cairo_device_t: Cairo: A Vector Graphics Library

+ + +

cairo_device_t

cairo_device_t — interface to underlying rendering system

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+cairo_device_t * +	+cairo_device_reference () +
+void +	+cairo_device_destroy () +
+cairo_status_t +	+cairo_device_status () +
+void +	+cairo_device_finish () +
+void +	+cairo_device_flush () +
+cairo_device_type_t +	+cairo_device_get_type () +
unsigned int +	+cairo_device_get_reference_count () +
+cairo_status_t +	+cairo_device_set_user_data () +
+void * +	+cairo_device_get_user_data () +
+cairo_status_t +	+cairo_device_acquire () +
+void +	+cairo_device_release () +
+double +	+cairo_device_observer_elapsed () +
+double +	+cairo_device_observer_fill_elapsed () +
+double +	+cairo_device_observer_glyphs_elapsed () +
+double +	+cairo_device_observer_mask_elapsed () +
+double +	+cairo_device_observer_paint_elapsed () +
+cairo_status_t +	+cairo_device_observer_print () +
+double +	+cairo_device_observer_stroke_elapsed () +

Types and Values

++++ + + + + + + + + + + +

typedef	cairo_device_t
enum	cairo_device_type_t

Description

Devices are the abstraction Cairo employs for the rendering system +used by a cairo_surface_t. You can get the device of a surface using +cairo_surface_get_device().

Devices are created using custom functions specific to the rendering +system you want to use. See the documentation for the surface types +for those functions.

An important function that devices fulfill is sharing access to the +rendering system between Cairo and your application. If you want to +access a device directly that you used to draw to with Cairo, you must +first call cairo_device_flush() to ensure that Cairo finishes all +operations on the device and resets it to a clean state.

Cairo also provides the functions cairo_device_acquire() and +cairo_device_release() to synchronize access to the rendering system +in a multithreaded environment. This is done internally, but can also +be used by applications.

Putting this all together, a function that works with devices should +look something like this:

+ + + + + + + +

1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20

void
+my_device_modifying_function (cairo_device_t *device)
+{
+  cairo_status_t status;
+
+  // Ensure the device is properly reset
+  cairo_device_flush (device);
+  // Try to acquire the device
+  status = cairo_device_acquire (device);
+  if (status != CAIRO_STATUS_SUCCESS) {
+    printf ("Failed to acquire the device: %s\n", cairo_status_to_string (status));
+    return;
+  }
+
+  // Do the custom operations on the device here.
+  // But do not call any Cairo functions that might acquire devices.
+  
+  // Release the device when done.
+  cairo_device_release (device);
+}

+ +

Please refer to the documentation of each backend for +additional usage requirements, guarantees provided, and +interactions with existing surface API of the device functions for +surfaces of that type. +

Functions

cairo_device_reference ()

cairo_device_t *
+cairo_device_reference (cairo_device_t *device);

Increases the reference count on device + by one. This prevents +device + from being destroyed until a matching call to +cairo_device_destroy() is made.

Use cairo_device_get_reference_count() to get the number of references +to a cairo_device_t.

Parameters

+++++ + + + + + +

device

a cairo_device_t

Returns

the referenced cairo_device_t.

Since: 1.10

cairo_device_destroy ()

void
+cairo_device_destroy (cairo_device_t *device);

Decreases the reference count on device + by one. If the result is +zero, then device + and all associated resources are freed. See +cairo_device_reference().

This function may acquire devices if the last reference was dropped.

Parameters

+++++ + + + + + +

device

a cairo_device_t

Since: 1.10

cairo_device_status ()

cairo_status_t
+cairo_device_status (cairo_device_t *device);

Checks whether an error has previously occurred for this +device.

Parameters

+++++ + + + + + +

device

a cairo_device_t

Returns

CAIRO_STATUS_SUCCESS on success or an error code if +the device is in an error state.

Since: 1.10

cairo_device_finish ()

void
+cairo_device_finish (cairo_device_t *device);

This function finishes the device and drops all references to +external resources. All surfaces, fonts and other objects created +for this device + will be finished, too. +Further operations on the device + will not affect the device + but +will instead trigger a CAIRO_STATUS_DEVICE_FINISHED error.

When the last call to cairo_device_destroy() decreases the +reference count to zero, cairo will call cairo_device_finish() if +it hasn't been called already, before freeing the resources +associated with the device.

This function may acquire devices.

Parameters

+++++ + + + + + +

device

the cairo_device_t to finish

Since: 1.10

cairo_device_flush ()

void
+cairo_device_flush (cairo_device_t *device);

Finish any pending operations for the device and also restore any +temporary modifications cairo has made to the device's state. +This function must be called before switching from using the +device with Cairo to operating on it directly with native APIs. +If the device doesn't support direct access, then this function +does nothing.

This function may acquire devices.

Parameters

+++++ + + + + + +

device

a cairo_device_t

Since: 1.10

cairo_device_get_type ()

cairo_device_type_t
+cairo_device_get_type (cairo_device_t *device);

This function returns the type of the device. See cairo_device_type_t +for available types.

Parameters

+++++ + + + + + +

device

a cairo_device_t

Returns

The type of device +.

Since: 1.10

cairo_device_get_reference_count ()

unsigned int
+cairo_device_get_reference_count (cairo_device_t *device);

Returns the current reference count of device +.

Parameters

+++++ + + + + + +

device

a cairo_device_t

Returns

the current reference count of device +. If the +object is a nil object, 0 will be returned.

Since: 1.10

cairo_device_set_user_data ()

cairo_status_t
+cairo_device_set_user_data (cairo_device_t *device,
+                            const cairo_user_data_key_t *key,
+                            void *user_data,
+                            cairo_destroy_func_t destroy);

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

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

device	a cairo_device_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 cairo_device_t
destroy	a cairo_destroy_func_t which will be called when the +cairo_t 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.

Since: 1.10

cairo_device_get_user_data ()

void *
+cairo_device_get_user_data (cairo_device_t *device,
+                            const cairo_user_data_key_t *key);

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

Parameters

+++++ + + + + + + + + + + + + +

device	a cairo_device_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.

Since: 1.10

cairo_device_acquire ()

cairo_status_t
+cairo_device_acquire (cairo_device_t *device);

Acquires the device + for the current thread. This function will block +until no other thread has acquired the device.

If the return value is CAIRO_STATUS_SUCCESS, you successfully acquired the +device. From now on your thread owns the device and no other thread will be +able to acquire it until a matching call to cairo_device_release(). It is +allowed to recursively acquire the device multiple times from the same +thread.

You must never acquire two different devices at the same time +unless this is explicitly allowed. Otherwise the possibility of deadlocks +exist. + +As various Cairo functions can acquire devices when called, these functions +may also cause deadlocks when you call them with an acquired device. So you +must not have a device acquired when calling them. These functions are +marked in the documentation. +

Parameters

+++++ + + + + + +

device

a cairo_device_t

Returns

CAIRO_STATUS_SUCCESS on success or an error code if +the device is in an error state and could not be +acquired. After a successful call to cairo_device_acquire(), +a matching call to cairo_device_release() is required.

Since: 1.10

cairo_device_release ()

void
+cairo_device_release (cairo_device_t *device);

Releases a device + previously acquired using cairo_device_acquire(). See +that function for details.

Parameters

+++++ + + + + + +

device

a cairo_device_t

Since: 1.10

cairo_device_observer_elapsed ()

double
+cairo_device_observer_elapsed (cairo_device_t *device);

cairo_device_observer_fill_elapsed ()

double
+cairo_device_observer_fill_elapsed (cairo_device_t *device);

cairo_device_observer_glyphs_elapsed ()

double
+cairo_device_observer_glyphs_elapsed (cairo_device_t *device);

cairo_device_observer_mask_elapsed ()

double
+cairo_device_observer_mask_elapsed (cairo_device_t *device);

cairo_device_observer_paint_elapsed ()

double
+cairo_device_observer_paint_elapsed (cairo_device_t *device);

cairo_device_observer_print ()

cairo_status_t
+cairo_device_observer_print (cairo_device_t *device,
+                             cairo_write_func_t write_func,
+                             void *closure);

cairo_device_observer_stroke_elapsed ()

double
+cairo_device_observer_stroke_elapsed (cairo_device_t *device);

Types and Values

cairo_device_t

typedef struct _cairo_device cairo_device_t;
+

A cairo_device_t represents the driver interface for drawing +operations to a cairo_surface_t. There are different subtypes of +cairo_device_t for different drawing backends; for example, +cairo_egl_device_create() creates a device that wraps an EGL display and +context.

The type of a device can be queried with cairo_device_get_type().

Memory management of cairo_device_t is done with +cairo_device_reference() and cairo_device_destroy().

Since: 1.10

enum cairo_device_type_t

cairo_device_type_t is used to describe the type of a given +device. The devices types are also known as "backends" within cairo.

The device type can be queried with cairo_device_get_type()

The various cairo_device_t functions can be used with devices of +any type, but some backends also provide type-specific functions +that must only be called with a device of the appropriate +type. These functions have names that begin with +cairo_type_device such as +cairo_xcb_device_debug_cap_xrender_version().

The behavior of calling a type-specific function with a device of +the wrong type is undefined.

New entries may be added in future versions.

Members

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

CAIRO_DEVICE_TYPE_DRM	+ The device is of type Direct Render Manager, since 1.10 +
CAIRO_DEVICE_TYPE_GL	+ The device is of type OpenGL, since 1.10 +
CAIRO_DEVICE_TYPE_SCRIPT	+ The device is of type script, since 1.10 +
CAIRO_DEVICE_TYPE_XCB	+ The device is of type xcb, since 1.10 +
CAIRO_DEVICE_TYPE_XLIB	+ The device is of type xlib, since 1.10 +
CAIRO_DEVICE_TYPE_XML	+ The device is of type XML, since 1.10 +
CAIRO_DEVICE_TYPE_COGL	+ The device is of type cogl, since 1.12 +
CAIRO_DEVICE_TYPE_WIN32	+ The device is of type win32, since 1.12 +
CAIRO_DEVICE_TYPE_INVALID	+ The device is invalid, since 1.10 +

Since: 1.10

cairo_device_t

Functions

Types and Values

Description

Functions

cairo_device_reference ()

Parameters

Returns

cairo_device_destroy ()

Parameters

cairo_device_status ()

Parameters

Returns

cairo_device_finish ()

Parameters

cairo_device_flush ()

Parameters

cairo_device_get_type ()

Parameters

Returns

cairo_device_get_reference_count ()

Parameters

Returns

cairo_device_set_user_data ()

Parameters

Returns

cairo_device_get_user_data ()

Parameters

Returns

cairo_device_acquire ()

Parameters

Returns

cairo_device_release ()

Parameters

cairo_device_observer_elapsed ()

cairo_device_observer_fill_elapsed ()

cairo_device_observer_glyphs_elapsed ()

cairo_device_observer_mask_elapsed ()

cairo_device_observer_paint_elapsed ()

cairo_device_observer_print ()

cairo_device_observer_stroke_elapsed ()

Types and Values

cairo_device_t

enum cairo_device_type_t

Members

See Also