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_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.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

cairo_surface_status ()

cairo_status_t      cairo_surface_status                (cairo_surface_t *surface);

Checks whether an error has previously occurred for this surface.