Devices — Pycairo documentation

# Devices

## class Device()

class cairo.Device

  A `Device` represents the driver interface for drawing operations to a `Surface`.

  New in version 1.14.

  Note

  New in version 1.17.0: `cairo.Device` can be used as a context manager:

      # device.finish() will be called on __exit__
      with cairo.ScriptDevice(f) as device:
          pass

  finish() → None

    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 `Status.DEVICE_FINISHED` error.

    This function may acquire devices.

    New in version 1.14.

  flush() → None

    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.

    New in version 1.14.

  acquire() → None
    Raises:

      cairo.Error – If the device is in an error state and could not be acquired.

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

    If the does not raise, 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.

    After a successful call to `acquire()`, a matching call to `release()` is required.

    Note

    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.

    New in version 1.14.

  release() → None

    Releases a device previously acquired using `acquire()`. See that function for details.

    New in version 1.14.

## class ScriptDevice(`Device`)

class cairo.ScriptDevice(fobj: cairo._FileLike | cairo._PathLike)

  New in version 1.14.

  __init__(fobj: cairo._FileLike | cairo._PathLike) → None
    Parameters:

      fobj – a filename or writable file object.

    Creates a output device for emitting the script, used when creating the individual surfaces.

  set_mode(mode: ScriptMode) → None
    Parameters:

      mode – the new mode

    Change the output mode of the script

  get_mode() → ScriptMode
    Returns:

      the current output mode of the script

    Queries the script for its current output mode.

  write_comment(comment: str) → None
    Parameters:

      comment – the string to emit

    Emit a string verbatim into the script.

  from_recording_surface(recording_surface: RecordingSurface) → None
    Parameters:

      recording_surface – the recording surface to replay

    Raises:

      cairo.Error –

    Converts the record operations in recording_surface into a script.