Image Surfaces

Image Surfaces — Rendering to memory buffers

Synopsis




enum        cairo_format_t;
cairo_surface_t* cairo_image_surface_create (cairo_format_t format,
                                             int width,
                                             int height);
cairo_surface_t* cairo_image_surface_create_for_data
                                            (unsigned char *data,
                                             cairo_format_t format,
                                             int width,
                                             int height,
                                             int stride);
unsigned char* cairo_image_surface_get_data (cairo_surface_t *surface);
cairo_format_t cairo_image_surface_get_format
                                            (cairo_surface_t *surface);
int         cairo_image_surface_get_width   (cairo_surface_t *surface);
int         cairo_image_surface_get_height  (cairo_surface_t *surface);
int         cairo_image_surface_get_stride  (cairo_surface_t *surface);

Description

Image surfaces provide the ability to render to memory buffers either allocated by cairo or by the calling code. The supported image formats are those defined in cairo_format_t.

Details

enum cairo_format_t

typedef enum _cairo_format {
    CAIRO_FORMAT_ARGB32,
    CAIRO_FORMAT_RGB24,
    CAIRO_FORMAT_A8,
    CAIRO_FORMAT_A1,
    CAIRO_FORMAT_RGB16_565
} cairo_format_t;

cairo_format_t is used to identify the memory format of image data.

CAIRO_FORMAT_ARGB32 each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then red, then green, then blue. The 32-bit quantities are stored native-endian. Pre-multiplied alpha is used. (That is, 50% transparent red is 0x80800000, not 0x80ff0000.)
CAIRO_FORMAT_RGB24 each pixel is a 32-bit quantity, with the upper 8 bits unused. Red, Green, and Blue are stored in the remaining 24 bits in that order.
CAIRO_FORMAT_A8 each pixel is a 8-bit quantity holding an alpha value.
CAIRO_FORMAT_A1 each pixel is a 1-bit quantity holding an alpha value. Pixels are packed together into 32-bit quantities. The ordering of the bits matches the endianess of the platform. On a big-endian machine, the first pixel is in the uppermost bit, on a little-endian machine the first pixel is in the least-significant bit.
CAIRO_FORMAT_RGB16_565 each pixel is a 16-bit quantity, with red in the upper 5 bits, then green in the next 6, then blue in the lowest 5 bits. (Since 1.2)

cairo_image_surface_create ()

cairo_surface_t* cairo_image_surface_create (cairo_format_t format,
                                             int width,
                                             int height);

cairo_image_surface_create_for_data ()

cairo_surface_t* cairo_image_surface_create_for_data
                                            (unsigned char *data,
                                             cairo_format_t format,
                                             int width,
                                             int height,
                                             int stride);

cairo_image_surface_get_data ()

unsigned char* cairo_image_surface_get_data (cairo_surface_t *surface);

Since 1.2


cairo_image_surface_get_format ()

cairo_format_t cairo_image_surface_get_format
                                            (cairo_surface_t *surface);

Since 1.2


cairo_image_surface_get_width ()

int         cairo_image_surface_get_width   (cairo_surface_t *surface);

cairo_image_surface_get_height ()

int         cairo_image_surface_get_height  (cairo_surface_t *surface);

cairo_image_surface_get_stride ()

int         cairo_image_surface_get_stride  (cairo_surface_t *surface);

Since 1.2