The
gdk-pixbuf
Library
x3715.html
<<< Previous Page
index.html
Home
a3696.html
Up
compiling.html
Next Page >>>
Converting Applications to
gdk-pixbuf
This sections describes the actual changes you need to make in
an
Imlib
program to make it use
gdk-pixbuf
instead.
Image loading and creation
The
gdk-pixbuf
library can load image files synchronously
(i.e. with a single function call), create images from RGB
data in memory, and as a convenience, it can also create
images from inline XPM data.
To load an image file in a single function call, simply use
gdk_pixbuf_new_from_file()
.  Note that
this will make the program block until the whole file has
been read.  This function effectively replaces
gdk_imlib_load_image()
.
If you have RGB data in memory, you can use
gdk_pixbuf_new_from_data()
to create a
pixbuf out of it; this is a replacement for
gdk_imlib_create_image_from_data()
.
gdk-pixbuf
does not copy the image data; it is up to you
to define the ownership policy by providing a destroy
notification function that will be called when the image
data needs to be freed.  The function you provide can then
free the data or do something else, as appropriate.
As a convenience, you can use the
gdk_pixbuf_new_from_xpm_data()
function
to create a pixbuf out of inline XPM data that was compiled
into your C program.  This is a replacement for
gdk_imlib_create_image_from_xpm_data()
.
After you have created a pixbuf, you can manipulate it in
any way you please and then finally call
gdk_pixbuf_unref()
when you are done
with it.  This can be thought of as a replacement for
gdk_imlib_destroy_image()
but with much
cleaner semantics.
Rendering Images
Applications that use
Imlib
must first call
gdk_imlib_render()
to render the whole
image data onto a pixmap that
Imlib
creates.  Then they
must copy that pixmap's data into the final destination for
the image.
In contrast,
gdk-pixbuf
provides convenience functions to
render arbitrary rectangular regions of an image onto a
drawable that your application provides.  You can use
gdk_pixbuf_render_to_drawable()
or
gdk_pixbuf_render_to_drawable_alpha()
to do this; having your application provide the destination
drawable and specify an arbitrary region means your
application has complete control over the way images are
rendered.
As a convenience,
gdk-pixbuf
also provides the
gdk_pixbuf_render_pixmap_and_mask()
function; this will create new pixmap and mask drawables for
a whole pixbuf and render the image data onto them.  Only
trivially simple applications should find a use for this
function, since usually you want finer control of how things
are rendered.
Scaling Images
Imlib
lets you render scaled image data at the time you
call
gdk_imlib_render()
.  Again, this
unfortunately scales and renders the whole image onto a new
pixmap.
gdk-pixbuf
provides a number of functions that do scaling
of arbitrary regions of a source pixbuf onto a destination
one.  These functions can also perform compositing
operations against the data in the destination pixbuf or
against a solid color or a colored checkerboard.
#FTN.AEN3810
[1]
Very simple applications may find it sufficient to use
gdk_pixbuf_scale_simple()
or
gdk_pixbuf_composite_color_simple()
.
These functions scale the whole source image at a time and
create a new pixbuf with the result.
More sophisticated applications will need to use
gdk_pixbuf_scale()
,
gdk_pixbuf_composite()
, or
gdk_pixbuf_composite_color()
instead.
These functions let you scale and composite an arbitrary
region of the source pixbuf onto a destination pixbuf that
you provide.
Getting Image Data from a Drawable
Imlib
lets you create an image by fetching a drawable's
contents from the X server and converting those into RGB
data.  This is done with the
gdk_imlib_create_image_from_drawable()
function.
gdk-pixbuf
provides the
gdk_pixbuf_get_from_drawable()
function
instead.  It lets you specify a destination pixbuf instead
of always creating a new one for you.
Notes
x3767.html#AEN3810
[1]
You can use a colored checkerboard as the background for
compositing when you want to provide a visual indication
that the image has partially opaque areas.  This is
normally used in image editing and viewing programs.
Compositing against a single solid color is actually a
special case of a checkerboard; it simply uses checks of
the same color.
x3715.html
<<< Previous Page
index.html
Home
a3696.html
Up
compiling.html
Next Page >>>
Differences between
Imlib
and
gdk-pixbuf
Compiling the
gdk-pixbuf
library
