Package gdk-pixbuf

The GDK-Pixbuf library provides a simple mechanism for loading an image from a file in synchronous fashion. This means that the library takes control of the application while the file is being loaded. From the user's point of view, the application will block until the image is done loading.

This interface can be used by applications in which blocking is acceptable while an image is being loaded. It can also be used to load small images in general. Applications that need progressive loading can use the gdk-pixbuf:pixbuf-loader API functionality instead.

These functions allow to save a gdk-pixbuf:pixbuf object in a number of file formats. The formatted data can be written to a file or to a memory buffer. The gdk-pixbuf:pixbuf library can also call a user-defined callback on the data, which allows to write the image to a socket or store it in a database.

The most basic way to create a pixbuf is to wrap an existing pixel buffer with a gdk-pixbuf:pixbuf object. You can use the gdk-pixbuf:pixbuf-new-from-data function to do this. You need to specify the destroy notification function that will be called when the data buffer needs to be freed. This will happen when a gdk-pixbuf:pixbuf object is finalized by the reference counting functions If you have a chunk of static data compiled into your application, you can pass in nil as the destroy notification function so that the data will not be freed.

The gdk-pixbuf:pixbuf-new function can be used as a convenience to create a pixbuf with an empty buffer. This is equivalent to allocating a data buffer using malloc() and then wrapping it with the gdk-pixbuf:pixbuf-new-from-data function. The gdk-pixbuf:pixbuf-new function will compute an optimal rowstride so that rendering can be performed with an efficient algorithm.

You can also copy an existing pixbuf with the gdk-pixbuf:pixbuf-copy function. The copy function will actually duplicate the pixel data in memory and create a new gdk-pixbuf:pixbuf instance for it.

The gdk-pixbuf:pixbuf library contains functions to scale pixbufs, to scale pixbufs and composite against an existing image, and to scale pixbufs and composite against a solid color or checkerboard. Compositing a checkerboard is a common way to show an image with an alpha channel in image-viewing and editing software.

Since the full-featured gdk-pixbuf:pixbuf-scale, gdk-pixbuf:pixbuf-composite, and gdk-pixbuf:pixbuf-composite-color functions are rather complex to use and have many arguments, two simple convenience functions are provided, the gdk-pixbuf:pixbuf-scale-simple and gdk-pixbuf:pixbuf-composite-color-simple functions which create a new pixbuf of a given size, scale an original image to fit, and then return the new pixbuf.

If the destination pixbuf was created from a readonly source, these operations will force a copy into a mutable buffer.

Scaling and compositing functions take advantage of MMX hardware acceleration on systems where MMX is supported. If the gdk-pixbuf:pixbuf library is built with the Sun mediaLib library, these functions are instead accelerated using mediaLib, which provides hardware acceleration on Intel, AMD, and Sparc chipsets. If desired, mediaLib support can be turned off by setting the GDK_DISABLE_MEDIALIB environment variable.

The following example demonstrates handling an expose event by rendering the appropriate area of a source image, which is scaled to fit the widget, onto the window of the widget. The source image is rendered against a checkerboard, which provides a visual representation of the alpha channel if the image has one. If the image does not have an alpha channel, calling the gdk-pixbuf:pixbuf-composite-color function has exactly the same effect as calling the gdk-pixbuf:pixbuf-scale function.

Example: Handling an expose event.

gboolean
expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
{
  GdkPixbuf *dest;


  dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8,
                         event->area.width, event->area.height);


  gdk_pixbuf_composite_color (pixbuf, dest,
           0, 0,
           event->area.width, event->area.height,
           -event->area.x, -event->area.y,
           (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
           (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
           GDK_INTERP_BILINEAR, 255,
           event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);


  gdk_draw_pixbuf (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
                   dest, 0, 0,
                   event->area.x, event->area.y,
                   event->area.width, event->area.height,
                   GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);


  gdk_pixbuf_unref (dest);


  return TRUE;
}      

Utility and miscellaneous convenience functions. These functions provide miscellaneous utilities for manipulating pixbufs. The pixel data in pixbufs may of course be manipulated directly by applications, but several common operations can be performed by these functions instead.