cairo_surface_t

## cairo_surface_t cairo_surface_t — Base class for surfaces |

## Synopsis

    typedef     cairo_surface_t;
    enum        cairo_content_t;
    cairo_surface_t* cairo_surface_create_similar
                                                (cairo_surface_t *other,
                                                 cairo_content_t content,
                                                 int width,
                                                 int height);
    void        cairo_surface_destroy           (cairo_surface_t *surface);
    void        cairo_surface_finish            (cairo_surface_t *surface);
    void        cairo_surface_flush             (cairo_surface_t *surface);
    void        cairo_surface_get_font_options  (cairo_surface_t *surface,
                                                 cairo_font_options_t *options);
    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_mark_dirty        (cairo_surface_t *surface);
    void        cairo_surface_mark_dirty_rectangle
                                                (cairo_surface_t *surface,
                                                 int x,
                                                 int y,
                                                 int width,
                                                 int height);
    cairo_surface_t* cairo_surface_reference    (cairo_surface_t *surface);
    void        cairo_surface_set_device_offset (cairo_surface_t *surface,
                                                 double x_offset,
                                                 double y_offset);
    cairo_status_t cairo_surface_status         (cairo_surface_t *surface);

## 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()`.

### enum cairo_content_t

    typedef enum _cairo_content {
        CAIRO_CONTENT_COLOR		= 0x1000,
        CAIRO_CONTENT_ALPHA		= 0x2000,
        CAIRO_CONTENT_COLOR_ALPHA	= 0x3000
    } cairo_content_t;

`cairo_content_t` is used to describe the content that a surface will contain, whether color information, alpha information (translucence vs. opacity), or both.

Note: The large values here are designed to keep cairo_content_t values distinct from cairo_format_t values so that the implementation can detect the error if users confuse the two types.

`CAIRO_CONTENT_COLOR` | The surface will hold color content only.
`CAIRO_CONTENT_ALPHA` | The surface will hold alpha content only.
`CAIRO_CONTENT_COLOR_ALPHA` | The surface will hold color and alpha content.

### 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
`content` : | the content for the new surface
`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. 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 `other` is already in an error state or any other error occurs.

### cairo_surface_destroy ()

    void        cairo_surface_destroy           (cairo_surface_t *surface);

Decreases the reference count on `surface` by one. If the result is zero, then `surface` and all associated resources are freed. See `cairo_surface_reference()`.

`surface` : | a cairo_t

### cairo_surface_finish ()

    void        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 to the surface will not affect the surface but will instead trigger a CAIRO_STATUS_SURFACE_FINISHED error.

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

### cairo_surface_flush ()

    void        cairo_surface_flush             (cairo_surface_t *surface);

Do any pending drawing for the surface and also restore any temporary modification's cairo has made to the surface's state. This function must be called before switching from drawing on the surface with cairo to drawing on it directly with native APIs. If the surface doesn't support direct access, then this function does nothing.

`surface` : | a cairo_surface_t

### cairo_surface_get_font_options ()

    void        cairo_surface_get_font_options  (cairo_surface_t *surface,
                                                 cairo_font_options_t *options);

Retrieves the default font rendering options for the surface. This allows display surfaces to report the correct subpixel order for rendering on them, print surfaces to disable hinting of metrics and so forth. The result can then be used with `cairo_scaled_font_create()`.

`surface` : | a cairo_surface_t
`options` : | a cairo_font_options_t object into which to store the retrieved options. All existing values are overwritten

### 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_mark_dirty ()

    void        cairo_surface_mark_dirty        (cairo_surface_t *surface);

Tells cairo that drawing has been done to surface using means other than cairo, and that cairo should reread any cached areas. Note that you must call `cairo_surface_flush()` before doing such drawing.

`surface` : | a cairo_surface_t

### cairo_surface_mark_dirty_rectangle ()

    void        cairo_surface_mark_dirty_rectangle
                                                (cairo_surface_t *surface,
                                                 int x,
                                                 int y,
                                                 int width,
                                                 int height);

Like `cairo_surface_mark_dirty()`, but drawing has been done only to the specified rectangle, so that cairo can retain cached contents for other parts of the surface.

`surface` : | a cairo_surface_t
`x` : | X coordinate of dirty rectangle
`y` : | Y coordinate of dirty rectangle
`width` : | width of dirty rectangle
`height` : | height of dirty rectangle

### cairo_surface_reference ()

    cairo_surface_t* cairo_surface_reference    (cairo_surface_t *surface);

Increases the reference count on `surface` by one. This prevents `surface` from being destroyed until a matching call to `cairo_surface_destroy()` is made.

`surface` : | a cairo_surface_t
Returns : | the referenced cairo_surface_t.

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

### cairo_surface_status ()

    cairo_status_t cairo_surface_status         (cairo_surface_t *surface);

Checks whether an error has previously occurred for this surface.

`surface` : | a cairo_surface_t
Returns : | `CAIRO_STATUS_SUCCESS`, `CAIRO_STATUS_NULL_POINTER`, `CAIRO_STATUS_NO_MEMORY`, `CAIRO_STATUS_READ_ERROR`, `CAIRO_STATUS_INVALID_CONTENT`, `CAIRO_STATUS_INVALUE_FORMAT`, or `CAIRO_STATUS_INVALID_VISUAL`.