# C API Reference

This manual documents the API used by C and C++ programmers who want to write extension modules that use pycairo.

## Pycairo Compiler Flags

To compile a Python extension using Pycairo you need to know where Pycairo and cairo are located and what flags to pass to the compiler and linker.

1. Variant:

   > Only available since version 1.16.0.

   > While Pycairo installs a pkg-config file, in case of virtualenvs, installation to the user directory or when using wheels/eggs, pkg-config will not be able to locate the .pc file. The `get_include()` function should work in all cases, as long as Pycairo is in your Python search path.

   > Compiler Flags:
   >   - `python -c "import cairo; print(cairo.get_include())"`
   >   - `pkg-config --cflags cairo`
   > Linker Flags:
   >   - `pkg-config --libs cairo`

2. Variant:

   > This works with older versions, but with the limitations mentioned above. Use it as a fallback if you want to support older versions or if your module does not require virtualenv/pip support.

   > Compiler Flags:
   >   - `pkg-config --cflags pycairo` or `pkg-config --cflags py3cairo`
   > Linker Flags:
   >   - `pkg-config --libs pycairo` or `pkg-config --libs py3cairo`

## To access the Pycairo C API under Python 2

Edit the client module file to add the following lines:

    /* All function, type and macro definitions needed to use the Pycairo/C API
     * are included in your code by the following line
     */
    #include "pycairo.h"

    /* define a variable for the C API */
    static Pycairo_CAPI_t *Pycairo_CAPI;

    /* import pycairo - add to the init<module> function */
    Pycairo_IMPORT;

## To access the Pycairo C API under Python 3

Example showing how to import the pycairo API:

    #include "py3cairo.h"

    PyMODINIT_FUNC
    PyInit_client(void)
    {
      PyObject *m;

      m = PyModule_Create(&clientmodule);
      if (m == NULL)
          return NULL;
      if (import_cairo() < 0)
          return NULL;
      /* additional initialization can happen here */
      return m;
    }

## Misc Functions

int `Pycairo_Check_Status`(cairo_status_t status)

  Parameters:

  - status (cairo_status_t) –

  Returns: | -1 in case of an error, otherwise 0. Sets an exception in case of an error.

  Takes a status value and converts it to an exception if it represents an error status.

## Cairo Context

PyObject `PycairoContext`
  cairo_t* `PycairoContext.ctx`

    The wrapped `cairo_t`

PyTypeObject *`PycairoContext_Type`

cairo_t * `PycairoContext_GET`(PycairoContext *obj)

  Parameters:

  - obj (PycairoContext) –

  Returns: | `cairo_t` [transfer none]

  Get the `cairo_t` object out of the `PycairoContext`.

PyObject * `PycairoContext_FromContext`(cairo_t *ctx, PyTypeObject *type, PyObject *base)

  Parameters:

  - ctx (cairo_t) – a cairo_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoContext creation fails, or if the cairo_t has an error status. [transfer full]
  - type (PyTypeObject) – a pointer to the type to instantiate. It can be &PycairoContext_Type, or a PycairoContext_Type subtype. (cairo.Context or a cairo.Context subclass) [transfer none]
  - base (PyObject) – the base object used to create the context, or NULL. it is referenced to keep it alive while the cairo_t is being used [transfer none]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoContext from a `cairo_t`

## Cairo Font Face

PyObject `PycairoFontFace`
  cairo_font_face_t* `PycairoFontFace.font_face`

  The wrapped `cairo_font_face_t`

PyTypeObject *`PycairoFontFace_Type`

PyObject * `PycairoFontFace_FromFontFace`(cairo_font_face_t *font_face)

  Parameters:

  - font_face (cairo_font_face_t) – a cairo_font_face_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoFontFace creation fails [transfer full]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoFontFace from a cairo_font_face_t

PycairoFontFace `PycairoToyFontFace`

PyTypeObject *`PycairoToyFontFace_Type`

## Cairo Font Options

PyObject `PycairoFontOptions`
  cairo_font_options_t* `PycairoFontOptions.font_options`

PyTypeObject *`PycairoFontOptions_Type`

PyObject * `PycairoFontOptions_FromFontOptions`(cairo_font_options_t *font_options)

  Parameters:

  - font_options (cairo_font_options_t) – a cairo_font_options_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoFontOptions creation fails [transfer full]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoFontOptions from a cairo_font_options_t

## Cairo Matrix

PyObject `PycairoMatrix`
  cairo_matrix_t `PycairoMatrix.matrix`

PyTypeObject *`PycairoMatrix_Type`

PyObject * `PycairoMatrix_FromMatrix`(const cairo_matrix_t *matrix)

  Parameters:

  - matrix (cairo_matrix_t) – a cairo_matrix_t to ‘wrap’ into a Python object. the cairo_matrix_t values are copied. [transfer none]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoMatrix from a cairo_matrix_t

## Cairo Path

PyObject `PycairoPath`
  cairo_path_t* `PycairoPath.path`

PyTypeObject *`PycairoPath_Type`

PyObject * `PycairoPath_FromPath`(cairo_path_t *path)

  Parameters:

  - path (cairo_path_t) – a cairo_path_t to ‘wrap’ into a Python object. path is unreferenced if the PycairoPath creation fails, or if path is in an error status. [transfer full]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoPath from a cairo_path_t

## Cairo Pattern

PyObject `PycairoPattern`
  cairo_pattern_t* `PycairoPattern.pattern`

PyTypeObject *`PycairoPattern_Type`

PycairoPattern `PycairoSolidPattern`

PyTypeObject *`PycairoSolidPattern_Type`

PycairoPattern `PycairoSurfacePattern`

PyTypeObject *`PycairoSurfacePattern_Type`

PycairoPattern `PycairoGradient`

PyTypeObject *`PycairoGradient_Type`

PycairoGradient `PycairoLinearGradient`

PyTypeObject *`PycairoLinearGradient_Type`

PycairoGradient `PycairoRadialGradient`

PyTypeObject *`PycairoRadialGradient_Type`

PyObject * `PycairoPattern_FromPattern`(cairo_pattern_t *pattern, PyObject *base)

  Parameters:

  - pattern (cairo_pattern_t) – a cairo_pattern_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoPattern creation fails, or if the pattern has an error status. [transfer full]
  - base (PyObject) – the base object used to create the pattern, or NULL. It is referenced to keep it alive while the cairo_pattern_t is being used. [transfer none]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoSolidPattern, PycairoSurfacePattern, PycairoLinearGradient, or PycairoRadialGradient from a cairo_pattern_t.

## Cairo Region

PyObject `PycairoRegion`
  cairo_region_t* `PycairoRegion.region`

PyTypeObject *`PycairoRegion_Type`

PyObject * `PycairoRegion_FromRegion`(cairo_region_t *region)

  Parameters:

  - region (cairo_region_t) – a cairo_region_t to ‘wrap’ into a Python object. region is unreferenced if the PycairoRegion creation fails, or if region is in an error status.

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoRegion from a cairo_region_t

## Cairo RectangleInt

PyObject `PycairoRectangleInt`
  cairo_rectangle_int_t* `PycairoRectangleInt.rectangle_int`

PyTypeObject *`PycairoRectangleInt_Type`

PyObject * `PycairoRectangleInt_FromRectangleInt`(const cairo_rectangle_int_t *rectangle_int)

  Parameters:

  - rectangle_int (cairo_rectangle_int_t) – a cairo_rectangle_int_t to ‘wrap’ into a Python object. rectangle_int is unreferenced if the PycairoRectangleInt creation fails. [transfer none]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoRectangleInt from a cairo_rectangle_int_t

## Scaled Font

PyObject `PycairoScaledFont`
  cairo_scaled_font_t* `PycairoScaledFont.scaled_font`

PyTypeObject *`PycairoScaledFont_Type`

PyObject * `PycairoScaledFont_FromScaledFont`(cairo_scaled_font_t *scaled_font)

  Parameters:

  - scaled_font (cairo_scaled_font_t) – a cairo_scaled_font_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoScaledFont creation fails [transfer full]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoScaledFont from a cairo_scaled_font_t

## Cairo Surface

PyObject `PycairoSurface`
  cairo_surface_t* `PycairoSurface.surface`

PyTypeObject *`PycairoSurface_Type`

PycairoSurface `PycairoImageSurface`

PyTypeObject *`PycairoImageSurface_Type`

PycairoSurface `PycairoPDFSurface`

PyTypeObject *`PycairoPDFSurface_Type`

PycairoSurface `PycairoPSSurface`

PyTypeObject *`PycairoPSSurface_Type`

PycairoSurface `PycairoRecordingSurface`

PyTypeObject *`PycairoRecordingSurface_Type`

PycairoSurface `PycairoSVGSurface`

PyTypeObject *`PycairoSVGSurface_Type`

PycairoSurface `PycairoWin32Surface`

PyTypeObject *`PycairoWin32Surface_Type`

PycairoSurface `PycairoXCBSurface`

PyTypeObject *`PycairoXCBSurface_Type`

PycairoSurface `PycairoXlibSurface`

PyTypeObject *`PycairoXlibSurface_Type`

PyObject * `PycairoSurface_FromSurface`(cairo_surface_t *surface, PyObject *base)

  Parameters:

  - surface (cairo_surface_t) – a cairo_surface_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoSurface creation fails, or if the cairo_surface_t has an error status. [transfer full]
  - base (PyObject) – the base object used to create the surface, or NULL. It is referenced to keep it alive while the cairo_surface_t is being used. [transfer none]

  Returns: | New reference or NULL on failure and sets an exception [transfer full]

  Create a new PycairoImageSurface, PycairoPDFSurface, PycairoPSSurface, PycairoRecordingSurface, PycairoSVGSurface, PycairoWin32Surface, PycairoWin32PrintingSurface, PycairoXCBSurface, or PycairoXlibSurface from a cairo_surface_t.

## Cairo Types

These are only listed here so they can be referenced in the documentation.

See https://www.cairographics.org/manual/ for details.

`cairo_t`
`cairo_status_t`
`cairo_surface_t`
`cairo_scaled_font_t`
`cairo_rectangle_int_t`
`cairo_region_t`
`cairo_pattern_t`
`cairo_matrix_t`
`cairo_font_options_t`
`cairo_path_t`
`cairo_font_face_t`