## cairo_surface_t

cairo_surface_t —

## Synopsis

    typedef     cairo_surface_t;
    cairo_surface_t* cairo_surface_create_similar
                                                (cairo_surface_t *other,
                                                 cairo_content_t content,
                                                 int width,
                                                 int height);
    void        cairo_surface_reference         (cairo_surface_t *surface);
    void        cairo_surface_destroy           (cairo_surface_t *surface);
    cairo_status_t cairo_surface_finish         (cairo_surface_t *surface);
    cairo_status_t cairo_surface_set_user_data  (cairo_surface_t *surface,
                                                 const cairo_user_data_key_t *key,
                                                 void *user_data,
                                                 cairo_destroy_func_t destroy);
    void*       cairo_surface_get_user_data     (cairo_surface_t *surface,
                                                 const cairo_user_data_key_t *key);
    void        cairo_surface_set_device_offset (cairo_surface_t *surface,
                                                 double x_offset,
                                                 double y_offset);

## Description

## Details

### cairo_surface_t

    typedef struct _cairo_surface cairo_surface_t;

A cairo_surface_t represents an image, either as the destination of a drawing operation or as source when drawing onto another surface. There are different subtypes of cairo_surface_t for different drawing backends; for example, `cairo_image_surface_create()` creates a bitmap image in memory.

Memory management of cairo_surface_t is done with `cairo_surface_reference()` and `cairo_surface_destroy()`.

### cairo_surface_create_similar ()

    cairo_surface_t* cairo_surface_create_similar
                                                (cairo_surface_t *other,
                                                 cairo_content_t content,
                                                 int width,
                                                 int height);

Create a new surface that is as compatible as possible with an existing surface. The new surface will use the same backend as `other` unless that is not possible for some reason.

`other` : | an existing surface used to select the backend of the new surface
`format` : |
`width` : | width of the new surface, (in device-space units)
`height` : | height of the new surface (in device-space units)
Returns : | a pointer to the newly allocated surface, or NULL in the case of errors. The caller owns the surface and should call cairo_surface_destroy when done with it.

### cairo_surface_reference ()

    void        cairo_surface_reference         (cairo_surface_t *surface);

`surface` : |

### cairo_surface_destroy ()

    void        cairo_surface_destroy           (cairo_surface_t *surface);

`surface` : |

### cairo_surface_finish ()

    cairo_status_t cairo_surface_finish         (cairo_surface_t *surface);

This function finishes the surface and drops all references to external resources. For example, for the Xlib backend it means that cairo will no longer access the drawable, which can be freed. After calling `cairo_surface_finish()` the only valid operations on a surface are getting and setting user data and referencing and destroying it. Further drawing the the surface will not affect the surface but set the surface status to CAIRO_STATUS_SURFACE_FINISHED.

When the last call to `cairo_surface_destroy()` decreases the reference count to zero, cairo will call `cairo_surface_finish()` if it hasn't been called already, before freeing the resources associated with the surface.

`surface` : | the cairo_surface_t to finish
Returns : | CAIRO_STATUS_SUCCESS if the surface was finished successfully, otherwise CAIRO_STATUS_NO_MEMORY or CAIRO_STATUS_WRITE_ERROR.

### cairo_surface_set_user_data ()

    cairo_status_t cairo_surface_set_user_data  (cairo_surface_t *surface,
                                                 const cairo_user_data_key_t *key,
                                                 void *user_data,
                                                 cairo_destroy_func_t destroy);

Attach user data to `surface`. To remove user data from a surface, call this function with the key that was used to set it and `NULL` for `data`.

`surface` : | a cairo_surface_t
`key` : | the address of a cairo_user_data_key_t to attach the user data to
`user_data` : | the user data to attach to the surface
`destroy` : | a cairo_destroy_func_t which will be called when the surface is destroyed or when new user data is attached using the same key.
Returns : | `CAIRO_STATUS_SUCCESS` or `CAIRO_STATUS_NO_MEMORY` if a slot could not be allocated for the user data.

### cairo_surface_get_user_data ()

    void*       cairo_surface_get_user_data     (cairo_surface_t *surface,
                                                 const cairo_user_data_key_t *key);

Return user data previously attached to `surface` using the specified key. If no user data has been attached with the given key this function returns `NULL`.

`surface` : | a cairo_surface_t
`key` : | the address of the cairo_user_data_key_t the user data was attached to
Returns : | the user data previously attached or `NULL`.

### cairo_surface_set_device_offset ()

    void        cairo_surface_set_device_offset (cairo_surface_t *surface,
                                                 double x_offset,
                                                 double y_offset);

Sets an offset that is added to the device coordinates determined by the CTM when drawing to `surface`. One use case for this function is when we want to create a cairo_surface_t that redirects drawing for a portion of an onscreen surface to an offscreen surface in a way that is completely invisible to the user of the cairo API. Setting a transformation via `cairo_translate()` isn't sufficient to do this, since functions like `cairo_device_to_user()` will expose the hidden offset.

Note that the offset only affects drawing to the surface, not using the surface in a surface pattern.

`surface` : | a cairo_surface_t
`x_offset` : | the offset in the X direction, in device units
`y_offset` : | the offset in the Y direction, in device units