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