|  |  |  | The gdk-pixbuf Library |  | 
|---|
This sections describes the actual changes you need to make in an Imlib program to make it use gdk-pixbuf instead.
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.
	
	  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.
	
	  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.
	
	  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.
| << Differences between Imlib and gdk-pixbuf | Appendix B. License >> |