Protocols

Modules supporting animations must derive a type from GdkPixbufAnimation, providing suitable implementations of the virtual functions.

The PixbufAnimationClassProtocol protocol exposes the methods and properties of an underlying GdkPixbufAnimationClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufAnimationClass. Alternatively, use PixbufAnimationClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

Modules supporting animations must derive a type from GdkPixbufAnimationIter, providing suitable implementations of the virtual functions.

The PixbufAnimationIterClassProtocol protocol exposes the methods and properties of an underlying GdkPixbufAnimationIterClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufAnimationIterClass. Alternatively, use PixbufAnimationIterClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkPixbufFormat contains information about the image format accepted by a module.

Only modules should access the fields directly, applications should use the gdk_pixbuf_format_* family of functions.

The PixbufFormatProtocol protocol exposes the methods and properties of an underlying GdkPixbufFormat instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufFormat. Alternatively, use PixbufFormatRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PixbufLoaderClassProtocol protocol exposes the methods and properties of an underlying GdkPixbufLoaderClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufLoaderClass. Alternatively, use PixbufLoaderClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkPixbufModule contains the necessary functions to load and save images in a certain file format.

If GdkPixbuf has been compiled with GModule support, it can be extended by modules which can load (and perhaps also save) new image and animation formats.

Implementing modules

The GdkPixbuf interfaces needed for implementing modules are contained in gdk-pixbuf-io.h (and gdk-pixbuf-animation.h if the module supports animations). They are not covered by the same stability guarantees as the regular GdkPixbuf API. To underline this fact, they are protected by the GDK_PIXBUF_ENABLE_BACKEND pre-processor symbol.

Each loadable module must contain a GdkPixbufModuleFillVtableFunc function named fill_vtable, which will get called when the module is loaded and must set the function pointers of the GdkPixbufModule.

In order to make format-checking work before actually loading the modules (which may require calling dlopen to load image libraries), modules export their signatures (and other information) via the fill_info function. An external utility, gdk-pixbuf-query-loaders, uses this to create a text file containing a list of all available loaders and their signatures. This file is then read at runtime by GdkPixbuf to obtain the list of available loaders and their signatures.

Modules may only implement a subset of the functionality available via GdkPixbufModule. If a particular functionality is not implemented, the fill_vtable function will simply not set the corresponding function pointers of the GdkPixbufModule structure. If a module supports incremental loading (i.e. provides begin_load, stop_load and load_increment), it doesn’t have to implement load, since GdkPixbuf can supply a generic load implementation wrapping the incremental loading.

Installing modules

Installing a module is a two-step process:

• copy the module file(s) to the loader directory (normally $libdir/gdk-pixbuf-2.0/$version/loaders, unless overridden by the environment variable GDK_PIXBUF_MODULEDIR)
• call gdk-pixbuf-query-loaders to update the module file (normally $libdir/gdk-pixbuf-2.0/$version/loaders.cache, unless overridden by the environment variable GDK_PIXBUF_MODULE_FILE)

The PixbufModuleProtocol protocol exposes the methods and properties of an underlying GdkPixbufModule instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufModule. Alternatively, use PixbufModuleRef as a lighweight, unowned reference if you already have an instance you just want to use.

The signature prefix for a module.

The signature of a module is a set of prefixes. Prefixes are encoded as pairs of ordinary strings, where the second string, called the mask, if not NULL, must be of the same length as the first one and may contain ‘ ’, ‘!’, ‘x’, ‘z’, and ‘n’ to indicate bytes that must be matched, not matched, “don’t-care”-bytes, zeros and non-zeros, respectively.

Each prefix has an associated integer that describes the relevance of the prefix, with 0 meaning a mismatch and 100 a “perfect match”.

Starting with gdk-pixbuf 2.8, the first byte of the mask may be ‘’, indicating an unanchored pattern that matches not only at the beginning, but also in the middle. Versions prior to 2.8 will interpret the ‘’ like an ‘x’.

The signature of a module is stored as an array of GdkPixbufModulePatterns. The array is terminated by a pattern where the prefix is NULL.

GdkPixbufModulePattern *signature[] = {
  { "abcdx", " !x z", 100 },
  { "bla", NULL,  90 },
  { NULL, NULL, 0 }
};

In the example above, the signature matches e.g. “auud\0” with relevance 100, and “blau” with relevance 90.

The PixbufModulePatternProtocol protocol exposes the methods and properties of an underlying GdkPixbufModulePattern instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufModulePattern. Alternatively, use PixbufModulePatternRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PixbufSimpleAnimClassProtocol protocol exposes the methods and properties of an underlying GdkPixbufSimpleAnimClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufSimpleAnimClass. Alternatively, use PixbufSimpleAnimClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A pixel buffer.

GdkPixbuf contains information about an image’s pixel data, its color space, bits per sample, width and height, and the rowstride (the number of bytes between the start of one row and the start of the next).

Creating new GdkPixbuf

The most basic way to create a pixbuf is to wrap an existing pixel buffer with a [classGdkPixbuf.Pixbuf] instance. You can use the [ctorGdkPixbuf.Pixbuf.new_from_data``] function to do this.

Every time you create a new GdkPixbuf instance for some data, you will need to specify the destroy notification function that will be called when the data buffer needs to be freed; this will happen when a GdkPixbuf is finalized by the reference counting functions. If you have a chunk of static data compiled into your application, you can pass in NULL as the destroy notification function so that the data will not be freed.

The [ctorGdkPixbuf.Pixbuf.new] constructor function can be used as a convenience to create a pixbuf with an empty buffer; this is equivalent to allocating a data buffer usingmalloc()and then wrapping it withgdk_pixbuf_new_from_data(). Thegdk_pixbuf_new()“ function will compute an optimal rowstride so that rendering can be performed with an efficient algorithm.

As a special case, you can use the [ctorGdkPixbuf.Pixbuf.new_from_xpm_data”] function to create a pixbuf from inline XPM image data.

You can also copy an existing pixbuf with the [methodPixbuf.copy] function. This is not the same as just acquiring a reference to the old pixbuf instance: the copy function will actually duplicate the pixel data in memory and create a new [classPixbuf] instance for it.

Reference counting

GdkPixbuf structures are reference counted. This means that an application can share a single pixbuf among many parts of the code. When a piece of the program needs to use a pixbuf, it should acquire a reference to it by calling g_object_ref(); when it no longer needs the pixbuf, it should release the reference it acquired by calling g_object_unref(). The resources associated with a GdkPixbuf will be freed when its reference count drops to zero. Newly-created GdkPixbuf instances start with a reference count of one.

Image Data

Image data in a pixbuf is stored in memory in an uncompressed, packed format. Rows in the image are stored top to bottom, and in each row pixels are stored from left to right.

There may be padding at the end of a row.

The “rowstride” value of a pixbuf, as returned by [methodGdkPixbuf.Pixbuf.get_rowstride``], indicates the number of bytes between rows.

NOTE: If you are copying raw pixbuf data with memcpy() note that the last row in the pixbuf may not be as wide as the full rowstride, but rather just as wide as the pixel data needs to be; that is: it is unsafe to do memcpy (dest, pixels, rowstride * height) to copy a whole pixbuf. Use [methodGdkPixbuf.Pixbuf.copy] instead, or compute the width in bytes of the last row as:

last_row = width * ((n_channels * bits_per_sample + 7) / 8);

The same rule applies when iterating over each row of a GdkPixbuf pixels array.

The following code illustrates a simple put_pixel() function for RGB pixbufs with 8 bits per channel with an alpha channel.

static void
put_pixel (GdkPixbuf *pixbuf,
           int x,
       int y,
       guchar red,
       guchar green,
       guchar blue,
       guchar alpha)
{
  int n_channels = gdk_pixbuf_get_n_channels (pixbuf);

  // Ensure that the pixbuf is valid
  g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
  g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
  g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
  g_assert (n_channels == 4);

  int width = gdk_pixbuf_get_width (pixbuf);
  int height = gdk_pixbuf_get_height (pixbuf);

  // Ensure that the coordinates are in a valid range
  g_assert (x >= 0 && x < width);
  g_assert (y >= 0 && y < height);

  int rowstride = gdk_pixbuf_get_rowstride (pixbuf);

  // The pixel buffer in the GdkPixbuf instance
  guchar *pixels = gdk_pixbuf_get_pixels (pixbuf);

  // The pixel we wish to modify
  guchar *p = pixels + y * rowstride + x * n_channels;
  p[0] = red;
  p[1] = green;
  p[2] = blue;
  p[3] = alpha;
}

Loading images

The GdkPixBuf class provides a simple mechanism for loading an image from a file in synchronous and asynchronous fashion.

For GUI applications, it is recommended to use the asynchronous stream API to avoid blocking the control flow of the application.

Additionally, GdkPixbuf provides the [classGdkPixbuf.PixbufLoader`] API for progressive image loading.

Saving images

The GdkPixbuf class provides methods for saving image data in a number of file formats. The formatted data can be written to a file or to a memory buffer. GdkPixbuf can also call a user-defined callback on the data, which allows to e.g. write the image to a socket or store it in a database.

The PixbufProtocol protocol exposes the methods and properties of an underlying GdkPixbuf instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Pixbuf. Alternatively, use PixbufRef as a lighweight, unowned reference if you already have an instance you just want to use.

An opaque object representing an animation.

The GdkPixBuf library provides a simple mechanism to load and represent animations. An animation is conceptually a series of frames to be displayed over time.

The animation may not be represented as a series of frames internally; for example, it may be stored as a sprite and instructions for moving the sprite around a background.

To display an animation you don’t need to understand its representation, however; you just ask GdkPixbuf what should be displayed at a given point in time.

The PixbufAnimationProtocol protocol exposes the methods and properties of an underlying GdkPixbufAnimation instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufAnimation. Alternatively, use PixbufAnimationRef as a lighweight, unowned reference if you already have an instance you just want to use.

An opaque object representing an iterator which points to a certain position in an animation.

The PixbufAnimationIterProtocol protocol exposes the methods and properties of an underlying GdkPixbufAnimationIter instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufAnimationIter. Alternatively, use PixbufAnimationIterRef as a lighweight, unowned reference if you already have an instance you just want to use.

Incremental image loader.

GdkPixbufLoader provides a way for applications to drive the process of loading an image, by letting them send the image data directly to the loader instead of having the loader read the data from a file. Applications can use this functionality instead of gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file() when they need to parse image data in small chunks. For example, it should be used when reading an image from a (potentially) slow network connection, or when loading an extremely large file.

To use GdkPixbufLoader to load an image, create a new instance, and call [methodGdkPixbuf.PixbufLoader.write] to send the data to it. When done, [methodGdkPixbuf.PixbufLoader.close] should be called to end the stream and finalize everything.

The loader will emit three important signals throughout the process:

• [signalGdkPixbuf.PixbufLoader::size-prepared] will be emitted as soon as the image has enough information to determine the size of the image to be used. If you want to scale the image while loading it, you can call [methodGdkPixbuf.PixbufLoader.set_size] in response to this signal.
• [signalGdkPixbuf.PixbufLoader::area-prepared] will be emitted as soon as the pixbuf of the desired has been allocated. You can obtain the GdkPixbuf instance by calling [methodGdkPixbuf.PixbufLoader.get_pixbuf]. If you want to use it, simply acquire a reference to it. You can also call gdk_pixbuf_loader_get_pixbuf() later to get the same pixbuf.
• [signalGdkPixbuf.PixbufLoader::area-updated] will be emitted every time a region is updated. This way you can update a partially completed image. Note that you do not know anything about the completeness of an image from the updated area. For example, in an interlaced image you will need to make several passes before the image is done loading.

Loading an animation

Loading an animation is almost as easy as loading an image. Once the first [signalGdkPixbuf.PixbufLoader::area-prepared] signal has been emitted, you can call [methodGdkPixbuf.PixbufLoader.get_animation] to get the [classGdkPixbuf.PixbufAnimation] instance, and then call and [methodGdkPixbuf.PixbufAnimation.get_iter] to get a [classGdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the desired time stamp.

The PixbufLoaderProtocol protocol exposes the methods and properties of an underlying GdkPixbufLoader instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufLoader. Alternatively, use PixbufLoaderRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PixbufNonAnimProtocol protocol exposes the methods and properties of an underlying GdkPixbufNonAnim instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufNonAnim. Alternatively, use PixbufNonAnimRef as a lighweight, unowned reference if you already have an instance you just want to use.

An opaque struct representing a simple animation.

The PixbufSimpleAnimProtocol protocol exposes the methods and properties of an underlying GdkPixbufSimpleAnim instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufSimpleAnim. Alternatively, use PixbufSimpleAnimRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PixbufSimpleAnimIterProtocol protocol exposes the methods and properties of an underlying GdkPixbufSimpleAnimIter instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PixbufSimpleAnimIter. Alternatively, use PixbufSimpleAnimIterRef as a lighweight, unowned reference if you already have an instance you just want to use.