Next: cairo_surface_t, Previous: User Fonts, Up: Top [Index]
interface to underlying rendering system
Devices are the abstraction Cairo employs for the rendering system used
by a <cairo-surface>. 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:
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.
<cairo-device-t>)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.
the <cairo-device-t> to finish
Since 1.10
<cairo-device-t>)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.
a <cairo-device-t>
Since 1.10
<cairo-device-t>) ⇒ (ret <cairo-device-type-t>)This function returns the type of the device. See
<cairo-device-type-t> for available types.
a <cairo-device-t>
The type of device.
Since 1.10
<cairo-device-t>) ⇒ (ret <cairo-status-t>)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.
a <cairo-device-t>
‘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-t>)Releases a device previously acquired using
cairo-device-acquire. See that function for details.
a <cairo-device-t>
Since 1.10
Next: cairo_surface_t, Previous: User Fonts, Up: Top [Index]