Image Surfaces

## 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);
    int         cairo_image_surface_get_width   (cairo_surface_t *surface);
    int         cairo_image_surface_get_height  (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_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_image_surface_create ()

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

Creates an image surface of the specified format and dimensions. The initial contents of the surface is undefined; you must explicitely clear the buffer, using, for example, `cairo_rectangle()` and `cairo_fill()` if you want it cleared.

`format` : | format of pixels in the surface to create
`width` : | width of the surface, in pixels
`height` : | height of the surface, in pixels
Returns : | a pointer to the newly created surface. The caller owns the surface and should call cairo_surface_destroy when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use `cairo_surface_status()` to check for this.

### 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);

Creates an image surface for the provided pixel data. The output buffer must be kept around until the cairo_surface_t is destroyed or `cairo_surface_finish()` is called on the surface. The initial contents of `buffer` will be used as the inital image contents; you must explicitely clear the buffer, using, for example, `cairo_rectangle()` and `cairo_fill()` if you want it cleared.

`data` : | a pointer to a buffer supplied by the application in which to write contents.
`format` : | the format of pixels in the buffer
`width` : | the width of the image to be stored in the buffer
`height` : | the height of the image to be stored in the buffer
`stride` : | the number of bytes between the start of rows in the buffer. Having this be specified separate from `width` allows for padding at the end of rows, or for writing to a subportion of a larger image.
Returns : | a pointer to the newly created surface. The caller owns the surface and should call cairo_surface_destroy when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use `cairo_surface_status()` to check for this.

### cairo_image_surface_get_width ()

    int         cairo_image_surface_get_width   (cairo_surface_t *surface);

Get the width of the image surface in pixels.

`surface` : | a cairo_image_surface_t
Returns : | the width of the surface in pixels.

### cairo_image_surface_get_height ()

    int         cairo_image_surface_get_height  (cairo_surface_t *surface);

Get the height of the image surface in pixels.

`surface` : | a cairo_image_surface_t
Returns : | the height of the surface in pixels.