Up: cl-cffi-gtk API documentation

Package gdk-pixbuf

GDK-Pixbuf is a library for image loading and manipulation. The GDK-Pixbuf documentation contains both the programmer's guide and the API reference. This is the API documentation of a Lisp binding to GDK-Pixbuf.

About This Package

Library version numbers
The GdkPixbuf Structure
File Loading
File Saving
Image Data in Memory
Module Interface

Library version numbers

These macros and variables let you check the version of GDK-Pixbuf you are linking against.

Contains the full version of the GDK-Pixbuf library as a string. This is the version currently in use by a running program. ...

The major version number of the GDK-Pixbuf library. (e.g. in GDK-Pixbuf version 1.2.5 this is 1.) ...

The minor version number of the GDK-Pixbuf library. (e.g. in GDK-Pixbuf version 1.2.5 this is 2.) ...

The micro version number of the GDK-Pixbuf library. (e.g. in GDK-Pixbuf version 1.2.5 this is 5.) ...

The GdkPixbuf Structure

Information that describes an image.

This is the main structure in the gdk-pixbuf library. It is used to represent images. It contains information about the 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). ...

This enumeration defines the color spaces that are supported by the GDK-Pixbuf library. Currently only RGB is supported. ...

These values can be passed to gdk_pixbuf_render_to_drawable_alpha() to control how the alpha channel of an image should be handled. ...

Queries the color space of a pixbuf. ...

Queries the number of channels of a pixbuf. ...

Queries whether a pixbuf has an alpha channel (opacity information). ...

Queries the number of bits per color sample in a pixbuf. ...

Queries a pointer to the pixel data of a pixbuf. ...

Queries the width of a pixbuf. ...

Queries the height of a pixbuf. ...

Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row and the start of the next row. ...

Returns the length of the pixel data, in bytes. ...

Looks up key in the list of options that may have been attached to the pixbuf when it was loaded, or that may have been attached by another function using gdk_pixbuf_set_option(). ...

File Loading

Loading a pixbuf from a file.

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 GdkPixbufLoader functionality instead.

Creates a new pixbuf by loading an image from a file. ...

File Saving

Saving a pixbuf to a file.

These functions allow to save a gdk-pixbuf object in a number of file formats. The formatted data can be written to a file or to a memory buffer. gdk-pixbuf 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.

Saves pixbuf to a file in format type. By default, "jpeg", "png", "ico" and "bmp" are possible file formats to save in, but more formats may be installed. ...

Image Data in Memory

Creating a pixbuf from image data that is already in memory.

The most basic way to create a pixbuf is to wrap an existing pixel buffer with a gdk-pixbuf structure. You can use the function gdk-pixbuf-new-from-data 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 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 function gdk-pixbuf-new 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 function gdk-pixbuf-new-from-data. The function gdk-pixbuf-new will compute an optimal rowstride so that rendering can be performed with an efficient algorithm.

As a special case, you can use the function gdk-pixbuf-new-from-xpm-data to create a pixbuf from inline XPM image data.

You can also copy an existing pixbuf with the function gdk-pixbuf-copy. This is not the same as just doing a g-object-ref on the old pixbuf; the copy function will actually duplicate the pixel data in memory and create a new gdk-pixbuf structure for it.

Creates a new gdk-pixbuf structure and allocates a buffer for it. The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself.

Creates a new pixbuf which represents a sub-region of src-pixbuf. ...

Creates a new gdk-pixbuf object with a copy of the information in the specified pixbuf.


Scaling pixbufs and scaling and compositing pixbufs.

The gdk-pixbuf 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 functions gdk-pixbuf-scale, gdk-pixbuf-composite, and gdk-pixbuf-composite-color are rather complex to use and have many arguments, two simple convenience functions are provided, gdk-pixbuf-scale-simple and gdk-pixbuf-composite-color-simple which create a new pixbuf of a given size, scale an original image to fit, and then return the new pixbuf.

Scaling and compositing functions take advantage of MMX hardware acceleration on systems where MMX is supported. If gdk-pixbuf 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 widget's window. 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 gdk-pixbuf-composite-color function has exactly the same effect as calling the function gdk-pixbuf-scale.

Example: Handling an expose event.
 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; }
This enumeration describes the different interpolation modes that can be used with the scaling functions. :nearest is the fastest scaling method, but has horrible quality when scaling down. :bilinear is the best choice if you are not sure what to choose, it has a good speed/quality balance. ...

Create a new gdk-pixbuf object containing a copy of src scaled to dest-width x dest-height. ...

Creates a transformation of the source image src by scaling by scale-x and scale-y then translating by offset-x and offset-y, then renders the rectangle (dest-x, dest-y, dest-width, dest-height) of the resulting image onto the destination image replacing the previous contents. ...

Creates a new gdk-pixbuf by scaling src to dest-width x dest-height and compositing the result with a checkboard of colors color1 and color2.

Creates a transformation of the source image src by scaling by scale-x and scale-y then translating by offset-x and offset-y. This gives an image in the coordinates of the destination pixbuf. The rectangle (dest-x, dest-y, dest-width, dest-height) is then composited onto the corresponding rectangle of the original destination image. ...

Creates a transformation of the source image src by scaling by scale-x and scale-y then translating by offset-x and offset-y, then composites the rectangle (dest-x, dest-y, dest-width, dest-height) of the resulting image with a checkboard of the colors color1 and color2 and renders it onto the destination image. ...


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.

Takes an existing pixbuf and adds an alpha channel to it. If the existing pixbuf already had an alpha channel, the channel values are copied from the original; otherwise, the alpha channel is initialized to 255 (full opacity). ...

Copies a rectangular area from src-pixbuf to dest-pixbuf. Conversion of pixbuf formats is done automatically. ...

Clears a pixbuf to the given RGBA value, converting the RGBA value into the pixbuf's pixel format. ...


Animated images.

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 do not need to understand its representation, however; you just ask gdk-pixbuf what should be displayed at a given point in time. ...

Creates a new animation by loading it from a file. ...

If an animation is really just a plain image, has only one frame, this function returns that image. ...


Application-driven progressive image loading.

gdk-pixbuf-loader 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 the functions 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. ...

Creates a new pixbuf loader object.

This will cause a pixbuf loader to parse the next count bytes of an image. ...

Causes the image to be scaled while it is loaded. ...

Queries the gdk-pixbuf object that a pixbuf loader is currently creating. ...

Informs a pixbuf loader that no further writes with the function gdk-pixbuf-loader-write will occur, so that it can free its internal loading structures. ...

Module Interface

Extending GdkPixBuf.

A gdk-pixbuf-format contains information about the image format accepted by a module. ...

Flags which allow a module to specify further details about the supported operations. ...

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. Each prefix has an associated integer that describes the relevance of the prefix, with 0 meaning a mismatch and 100 a "perfect match". ...

Exported Symbol Index

+gdk-pixbuf-major-version+, Constant
+gdk-pixbuf-micro-version+, Constant
+gdk-pixbuf-minor-version+, Constant
+gdk-pixbuf-version+, Constant
copy-gdk-pixbuf-format, Function
gdk-colorspace, Enum
gdk-interp-type, Enum
gdk-pixbuf, Class
gdk-pixbuf-add-alpha, Function
gdk-pixbuf-alpha-mode, Enum
gdk-pixbuf-animation, Class
gdk-pixbuf-animation-get-static-image, Function
gdk-pixbuf-animation-loop, Accessor
gdk-pixbuf-animation-new-from-file, Function
gdk-pixbuf-bits-per-sample, Accessor
gdk-pixbuf-colorspace, Accessor
gdk-pixbuf-composite, Function
gdk-pixbuf-composite-color, Function
gdk-pixbuf-composite-color-simple, Function
gdk-pixbuf-copy, Function
gdk-pixbuf-copy-area, Function
gdk-pixbuf-fill, Function
gdk-pixbuf-format, CStruct
gdk-pixbuf-format-description, Accessor
gdk-pixbuf-format-disabled, Accessor
gdk-pixbuf-format-domain, Accessor
gdk-pixbuf-format-extensions, Accessor
gdk-pixbuf-format-flags, Accessor
gdk-pixbuf-format-flags, Bitfield
gdk-pixbuf-format-license, Accessor
gdk-pixbuf-format-mime-types, Accessor
gdk-pixbuf-format-name, Accessor
gdk-pixbuf-format-signature, Accessor
gdk-pixbuf-get-bits-per-sample, Function
gdk-pixbuf-get-byte-length, Function
gdk-pixbuf-get-colorspace, Function
gdk-pixbuf-get-has-alpha, Function
gdk-pixbuf-get-height, Function
gdk-pixbuf-get-n-channels, Function
gdk-pixbuf-get-option, Function
gdk-pixbuf-get-pixels, Function
gdk-pixbuf-get-rowstride, Function
gdk-pixbuf-get-width, Function
gdk-pixbuf-has-alpha, Accessor
gdk-pixbuf-height, Accessor
gdk-pixbuf-load-get-animation, Symbol
gdk-pixbuf-loader, Class
gdk-pixbuf-loader-close, Function
gdk-pixbuf-loader-get-pixbuf, Function
gdk-pixbuf-loader-new, Function
gdk-pixbuf-loader-set-size, Function
gdk-pixbuf-loader-write, Function
gdk-pixbuf-module-pattern, CStruct
gdk-pixbuf-n-channels, Accessor
gdk-pixbuf-new, Function
gdk-pixbuf-new-from-file, Function
gdk-pixbuf-new-subpixbuf, Function
gdk-pixbuf-pixels, Accessor
gdk-pixbuf-rowstride, Accessor
gdk-pixbuf-save, Function
gdk-pixbuf-scale, Function
gdk-pixbuf-scale-simple, Function
gdk-pixbuf-width, Accessor
make-gdk-pixbuf-format, Function