## 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 `g_object_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_draw_pixbuf()` 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. [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.

[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.