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);
void        cairo_surface_finish            (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_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
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_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 ()

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