cairomm: Cairo::Device Class Reference

cairomm 1.18.1

Classes | Public Types | Public Member Functions | Protected Attributes | List of all members
Cairo::Device Class Reference

Devices are the abstraction Cairo employs for the rendering system used by a cairo_surface_t. More...

`#include <cairomm/device.h>`

## Classes
class | Lock
| A convenience class for acquiring a Device object in an exception-safe manner. More...

## Public Types
enum class | DeviceType { DRM = CAIRO_DEVICE_TYPE_DRM , GL = CAIRO_DEVICE_TYPE_GL , SCRIPT = CAIRO_DEVICE_TYPE_SCRIPT , XCB = CAIRO_DEVICE_TYPE_XCB , XLIB = CAIRO_DEVICE_TYPE_XLIB , XML = CAIRO_DEVICE_TYPE_XML }
typedef cairo_device_t | cobject

## Public Member Functions
| Device (cairo_device_t * cobjectcobject, bool has_reference=false)
| Create a C++ wrapper for the C instance.
virtual | ~Device ()
DeviceType | get_type () const
| This function returns the type of the device.
void | flush ()
| Finish any pending operations for the device and also restore any temporary modifications cairo has made to the device's state.
void | finish ()
| This function finishes the device and drops all references to external resources.
void | acquire ()
| Acquires the device for the current thread.
void | release ()
| Releases a device previously acquired using acquire().
cobject * | cobj ()
const cobject * | cobj () const
void | reference () const
void | unreference () const

## Protected Attributes
cobject * | m_cobject

## Detailed 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 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 flush() to ensure that Cairo finishes all operations on the device and resets it to a clean state.

Cairo also provides the functions acquire() and release() to synchronize access to the rendering system in a multithreaded environment. This is done internally, but can also be used by applications. There is also a Device::Lock convenience class that allows the device to be acquired and released in an exception-safe manner.

This is a reference-counted object that should be used via Cairo::RefPtr.

Since
  1.10

## Member Typedef Documentation

## ◆ cobject

typedef cairo_device_t Cairo::Device::cobject

## Member Enumeration Documentation

## ◆ DeviceType

enum class Cairo::Device::DeviceType
| strong

Since
  1.10

Enumerator
DRM |
GL |
SCRIPT |
XCB |
XLIB |
XML |

## Constructor & Destructor Documentation

## ◆ Device()

Cairo::Device::Device | ( | cairo_device_t * | cobject,
|  | bool | has_reference = false )
| explicit

Create a C++ wrapper for the C instance.

This C++ instance should then be given to a RefPtr.

Parameters

  cobject | The C instance.
  has_reference | Whether we already have a reference. Otherwise, the constructor will take an extra reference.

## ◆ ~Device()

virtual Cairo::Device::~Device | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ acquire()

void Cairo::Device::acquire | ( |  | ) |

Acquires the device for the current thread.

This function will block until no other thread has acquired the device.

If no exception is thrown, 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 release(). It is allowed to recursively acquire the device multiple times from the same thread.

Note
  It is recommended to use Device::Lock to acquire devices in an exception-safe manner, rather than acquiring and releasing the device manually.

Warning
  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.

## ◆ cobj() [1/2]

cobject * Cairo::Device::cobj | ( |  | ) |
| inline

## ◆ cobj() [2/2]

const cobject * Cairo::Device::cobj | ( |  | ) | const
| inline

## ◆ finish()

void Cairo::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 DEVICE_FINISHED error.

When the last reference to the device is dropped, cairo will call finish() if it hasn't been called already, before freeing the resources associated with the device.

This function may acquire devices.

## ◆ flush()

void Cairo::Device::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.

This function may acquire devices.

## ◆ get_type()

DeviceType Cairo::Device::get_type | ( |  | ) | const

This function returns the type of the device.

## ◆ reference()

void Cairo::Device::reference | ( |  | ) | const

## ◆ release()

void Cairo::Device::release | ( |  | ) |

Releases a device previously acquired using acquire().

## ◆ unreference()

void Cairo::Device::unreference | ( |  | ) | const

## Member Data Documentation

## ◆ m_cobject

cobject* Cairo::Device::m_cobject
| protected

The documentation for this class was generated from the following file:

- cairomm/device.h