jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: cairo_device_t: Cairo: A Vector Graphics Library jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68: jpayne@68: jpayne@68:
jpayne@68:

cairo_device_t

jpayne@68:

cairo_device_t — interface to underlying rendering system

jpayne@68:
jpayne@68:
jpayne@68:

Functions

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

Types and Values

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
typedefcairo_device_t
enumcairo_device_type_t
jpayne@68:
jpayne@68:
jpayne@68:

Description

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: 
1
jpayne@68: 2
jpayne@68: 3
jpayne@68: 4
jpayne@68: 5
jpayne@68: 6
jpayne@68: 7
jpayne@68: 8
jpayne@68: 9
jpayne@68: 10
jpayne@68: 11
jpayne@68: 12
jpayne@68: 13
jpayne@68: 14
jpayne@68: 15
jpayne@68: 16
jpayne@68: 17
jpayne@68: 18
jpayne@68: 19
jpayne@68: 20
void
jpayne@68: my_device_modifying_function (cairo_device_t *device)
jpayne@68: {
jpayne@68:   cairo_status_t status;
jpayne@68: 
jpayne@68:   // Ensure the device is properly reset
jpayne@68:   cairo_device_flush (device);
jpayne@68:   // Try to acquire the device
jpayne@68:   status = cairo_device_acquire (device);
jpayne@68:   if (status != CAIRO_STATUS_SUCCESS) {
jpayne@68:     printf ("Failed to acquire the device: %s\n", cairo_status_to_string (status));
jpayne@68:     return;
jpayne@68:   }
jpayne@68: 
jpayne@68:   // Do the custom operations on the device here.
jpayne@68:   // But do not call any Cairo functions that might acquire devices.
jpayne@68:   
jpayne@68:   // Release the device when done.
jpayne@68:   cairo_device_release (device);
jpayne@68: }
jpayne@68:
jpayne@68: jpayne@68:

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

jpayne@68:
jpayne@68:
jpayne@68:

Functions

jpayne@68:
jpayne@68:

cairo_device_reference ()

jpayne@68: 
cairo_device_t *
jpayne@68: cairo_device_reference (cairo_device_t *device);
jpayne@68:

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

jpayne@68:

Use cairo_device_get_reference_count() to get the number of references jpayne@68: to a cairo_device_t.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

the referenced cairo_device_t.

jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_destroy ()

jpayne@68: 
void
jpayne@68: cairo_device_destroy (cairo_device_t *device);
jpayne@68:

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

jpayne@68:

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

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_status ()

jpayne@68: 
cairo_status_t
jpayne@68: cairo_device_status (cairo_device_t *device);
jpayne@68:

Checks whether an error has previously occurred for this jpayne@68: device.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

CAIRO_STATUS_SUCCESS on success or an error code if jpayne@68: the device is in an error state.

jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_finish ()

jpayne@68: 
void
jpayne@68: cairo_device_finish (cairo_device_t *device);
jpayne@68:

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

jpayne@68:

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

jpayne@68:

This function may acquire devices.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

the cairo_device_t to finish

 
jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_flush ()

jpayne@68: 
void
jpayne@68: cairo_device_flush (cairo_device_t *device);
jpayne@68:

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

jpayne@68:

This function may acquire devices.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_get_type ()

jpayne@68: 
cairo_device_type_t
jpayne@68: cairo_device_get_type (cairo_device_t *device);
jpayne@68:

This function returns the type of the device. See cairo_device_type_t jpayne@68: for available types.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

The type of device jpayne@68: .

jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_get_reference_count ()

jpayne@68: 
unsigned int
jpayne@68: cairo_device_get_reference_count (cairo_device_t *device);
jpayne@68:

Returns the current reference count of device jpayne@68: .

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

the current reference count of device jpayne@68: . If the jpayne@68: object is a nil object, 0 will be returned.

jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_set_user_data ()

jpayne@68: 
cairo_status_t
jpayne@68: cairo_device_set_user_data (cairo_device_t *device,
jpayne@68:                             const cairo_user_data_key_t *key,
jpayne@68:                             void *user_data,
jpayne@68:                             cairo_destroy_func_t destroy);
jpayne@68:

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

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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 jpayne@68: cairo_t is destroyed or when new user data is attached using the jpayne@68: same key.

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a jpayne@68: slot could not be allocated for the user data.

jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_get_user_data ()

jpayne@68: 
void *
jpayne@68: cairo_device_get_user_data (cairo_device_t *device,
jpayne@68:                             const cairo_user_data_key_t *key);
jpayne@68:

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

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 

key

the address of the cairo_user_data_key_t the user data was jpayne@68: attached to

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

the user data previously attached or NULL.

jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_acquire ()

jpayne@68: 
cairo_status_t
jpayne@68: cairo_device_acquire (cairo_device_t *device);
jpayne@68:

Acquires the device jpayne@68: for the current thread. This function will block jpayne@68: until no other thread has acquired the device.

jpayne@68:

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

jpayne@68:

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

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

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

jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_release ()

jpayne@68: 
void
jpayne@68: cairo_device_release (cairo_device_t *device);
jpayne@68:

Releases a device jpayne@68: previously acquired using cairo_device_acquire(). See jpayne@68: that function for details.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

device

a cairo_device_t

 
jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_observer_elapsed ()

jpayne@68: 
double
jpayne@68: cairo_device_observer_elapsed (cairo_device_t *device);
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_observer_fill_elapsed ()

jpayne@68: 
double
jpayne@68: cairo_device_observer_fill_elapsed (cairo_device_t *device);
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_observer_glyphs_elapsed ()

jpayne@68: 
double
jpayne@68: cairo_device_observer_glyphs_elapsed (cairo_device_t *device);
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_observer_mask_elapsed ()

jpayne@68: 
double
jpayne@68: cairo_device_observer_mask_elapsed (cairo_device_t *device);
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_observer_paint_elapsed ()

jpayne@68: 
double
jpayne@68: cairo_device_observer_paint_elapsed (cairo_device_t *device);
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_observer_print ()

jpayne@68: 
cairo_status_t
jpayne@68: cairo_device_observer_print (cairo_device_t *device,
jpayne@68:                              cairo_write_func_t write_func,
jpayne@68:                              void *closure);
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_device_observer_stroke_elapsed ()

jpayne@68: 
double
jpayne@68: cairo_device_observer_stroke_elapsed (cairo_device_t *device);
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

Types and Values

jpayne@68:
jpayne@68:

cairo_device_t

jpayne@68: 
typedef struct _cairo_device cairo_device_t;
jpayne@68:
jpayne@68:

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

jpayne@68:

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

jpayne@68:

Memory management of cairo_device_t is done with jpayne@68: cairo_device_reference() and cairo_device_destroy().

jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

enum cairo_device_type_t

jpayne@68:

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

jpayne@68:

The device type can be queried with cairo_device_get_type()

jpayne@68:

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

jpayne@68:

The behavior of calling a type-specific function with a device of jpayne@68: the wrong type is undefined.

jpayne@68:

New entries may be added in future versions.

jpayne@68:
jpayne@68:

Members

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

CAIRO_DEVICE_TYPE_DRM

 jpayne@68:

The device is of type Direct Render Manager, since 1.10

jpayne@68: 		 

CAIRO_DEVICE_TYPE_GL

 jpayne@68:

The device is of type OpenGL, since 1.10

jpayne@68: 		 

CAIRO_DEVICE_TYPE_SCRIPT

 jpayne@68:

The device is of type script, since 1.10

jpayne@68: 		 

CAIRO_DEVICE_TYPE_XCB

 jpayne@68:

The device is of type xcb, since 1.10

jpayne@68: 		 

CAIRO_DEVICE_TYPE_XLIB

 jpayne@68:

The device is of type xlib, since 1.10

jpayne@68: 		 

CAIRO_DEVICE_TYPE_XML

 jpayne@68:

The device is of type XML, since 1.10

jpayne@68: 		 

CAIRO_DEVICE_TYPE_COGL

 jpayne@68:

The device is of type cogl, since 1.12

jpayne@68: 		 

CAIRO_DEVICE_TYPE_WIN32

 jpayne@68:

The device is of type win32, since 1.12

jpayne@68: 		 

CAIRO_DEVICE_TYPE_INVALID

 jpayne@68:

The device is invalid, since 1.10

jpayne@68: 		 
jpayne@68:
jpayne@68:

Since: 1.10

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

See Also

jpayne@68:

cairo_surface_t

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:
Generated by GTK-Doc V1.27
jpayne@68: jpayne@68: