Class Device
Devices are the abstraction Cairo employs for the rendering system used
by a Surface. You can get the device of a surface using
Surface.getDevice().
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 Device.flush() to ensure that Cairo finishes all operations
on the device and resets it to a clean state.
Cairo also provides the functions Device.acquire() and
Device.release() to synchronize access to the rendering system
in a multithreaded environment. This is done internally, but can also
be used by applications.
Constructors
| Name |
Description |
this
|
Create a Device from a existing cairo_device_t*.
Device is a garbage collected class. It will call cairo_pattern_destroy
when it gets collected by the GC or when dispose() is called.
|
Methods
| Name |
Description |
acquire
|
Acquires the device for the current thread. This function will
block until no other thread has acquired the device.
|
finish
|
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 exception.
|
flush
|
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.
|
getType
|
This function returns the C type of a Device. See DeviceType
for available types.
|
release
|
Releases a device previously acquired using Device.acquire().
See that function for details.
|
checkError
|
Method for use in subclasses.
Calls cairo_device_status(nativePointer) and throws
an exception if the status isn't CAIRO_STATUS_SUCCESS
|
Aliases
| Name |
Description |
type
|
Convenience alias
|
Note
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.
Examples
void my_device_modifying_function(Device device)
{
// Ensure the device is properly reset
device.flush();
try
{
// Try to acquire the device
device.acquire();
}
catch(CairoException e)
{
writeln("");
}
// Release the device when done.
scope(exit)
device.release();
// Do the custom operations on the device here.
// But do not call any Cairo functions that might acquire devices.
}
Authors
| Johannes Pfau | cairoD |
| Andrej Mitrovic | cairoD |
| cairo team | cairo |