![]() |
![]() |
![]() |
Cairo: A Vector Graphics Library | ![]() |
---|
cairo_surface_tcairo_surface_t — |
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); 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);
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_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, or NULL in the case of errors. The caller owns the surface and should call cairo_surface_destroy when done with it. |
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. |
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_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. |
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. |
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_t | cairo_pattern_t >> |