Decoding images with GDK-PixBuf

The ImageSurface.create_from_png() method can decode PNG images and provide a cairo surface, but what about other image formats?

The cairocffi.pixbuf module uses GDK-PixBuf to decode JPEG, GIF, and various other formats (depending on what is installed.) If you don’t import this module, it is possible to use the rest of cairocffi without having GDK-PixBuf installed. GDK-PixBuf is an independent package since version 2.22, but before that was part of GTK+.

This module also converts pixel data since the internal format in GDK-PixBuf (big-endian RGBA) is not the same as in cairo (native-endian ARGB). For this reason, although it is a “toy” API, ImageSurface.create_from_png() can be faster than decode_to_image_surface() if the format is known to be PNG. The pixel conversion is done by GTK+ if available, but a (slower) fallback method is used otherwise.

exception cairocffi.pixbuf.ImageLoadingError

PixBuf returned an error when loading an image.

The image data is probably corrupted.

cairocffi.pixbuf.decode_to_image_surface(image_data, width=None, height=None)

Decode an image from memory into a cairo surface. The file format is detected automatically.

Parameters:

  • image_data – A byte string

  • width – Integer width in pixels or None

  • height – Integer height in pixels or None

Returns:

A tuple of a new ImageSurface object and the name of the detected image format.

Raises:

ImageLoadingError if the image data is invalid or in an unsupported format.