Skip to content

Latest commit

 

History

History
149 lines (94 loc) · 4.23 KB

cffi_api.rst

File metadata and controls

149 lines (94 loc) · 4.23 KB
Raw

CFFI API

cairocffi

cairocffi’s API <api> is made of a number of wrapper <wrappers> classes that provide a more Pythonic interface for various cairo objects. Functions that take a pointer as their first argument become methods, error statuses become exceptions, and reference counting <refcounting> is hidden away.

In order to use other C libraries that use integrate with cairo, or if cairocffi’s API is not sufficient (Consider making a pull request!) you can access cairo’s lower level C pointers and API through CFFI.

Module-level objects

ffi

A cffi.FFI instance with all of the cairo C API declared.

cairo

The libcairo library, pre-loaded with ffi.dlopen. All cairo functions are accessible as attributes of this object:

import cairocffi
from cairocffi import cairo as cairo_c, SURFACE_TYPE_XLIB

if cairo_c.cairo_surface_get_type(surface._pointer) == SURFACE_TYPE_XLIB:
    ...

See the cairo manual for details.

Reference counting in cairo

Most cairo objects are reference-counted, and freed when the count reaches zero. cairocffi’s Python wrapper will automatically decrease the reference count when they are garbage-collected. Therefore, care must be taken when creating a wrapper as to the reference count should be increased (for existing cairo objects) or not (for cairo objects that were just created with a refcount of 1.)

Wrappers

Surface._from_pointer

Pattern._from_pointer

FontFace._from_pointer

ScaledFont._from_pointer

Context._from_pointer

Surface._pointer

The underlying :ccairo_surface_t * cdata pointer.

Pattern._pointer

The underlying :ccairo_pattern_t * cdata pointer.

FontFace._pointer

The underlying :ccairo_font_face_t * cdata pointer.

ScaledFont._pointer

The underlying :ccairo_scaled_font_t * cdata pointer.

FontOptions._pointer

The underlying :ccairo_scaled_font_t * cdata pointer.

Matrix._pointer

The underlying :ccairo_matrix_t * cdata pointer.

Context._pointer

The underlying :ccairo_t * cdata pointer.

Converting pycairo wrappers to cairocffi

Some libraries such as PyGTK or PyGObject provide a pycairo ~cairo.Context object for you to draw on. It is possible to extract the underlying :ccairo_t * pointer and create a cairocffi wrapper for the same cairo context.

The follwing function does that with unsafe pointer manipulation. It only works on CPython.

../utils/pycairo_to_cairocffi.py

Converting other types of objects like surfaces is very similar, but left as an exercise to the reader.

Converting cairocffi wrappers to pycairo

The reverse conversion is also possible. Here we use ctypes rather than CFFI because Python’s C API is sensitive to the GIL.

../utils/cairocffi_to_pycairo.py

Example: using Pango through CFFI with cairocffi

The program below shows a fairly standard usage of CFFI to access Pango’s C API. The Context._pointer pointer can be used directly as an argument to CFFI functions that expect cairo_t *. The C definitions are copied from Pango’s and GLib’s documentation.

Using CFFI for accessing Pango (rather than the traditional bindings in PyGTK or PyGObject with introspection) is not only easiest for using together with cairocffi, but also means that all of Pango’s API is within reach, whereas bindings often only expose the high level API.

../utils/pango_example.py