<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Cairo/mod.rs. Do not edit. -->

```{index} single: Cairo
```

# Cairo

```{pperl-module-badges} Cairo
```

Perl bindings for cairo, the 2D vector graphics library.

This is the `Cairo` module, version 1.109 of the CPAN API: the same
packages, methods, arguments and return values that Perl code written
against `Cairo` already expects. Drawing goes to the `libcairo.so.2`
installed on the machine, which is located when the module is first
used; if that library is absent, the first Cairo call dies with a
message naming the distribution package to install.

## Objects and their lifetime

A cairo object is an ordinary blessed reference. Nothing has to be
freed by hand: the underlying cairo resource is released when the last
Perl reference to it goes out of scope. An object obtained from a
getter - the pattern from `$cr->get_source`, the surface from
`$cr->get_target` - stays valid on its own and may outlive the context
it came from.

One class does not follow that shape: `Cairo::Path` is a tied array of
hashes rather than an object with methods, so the path returned by
`$cr->copy_path` is read with ordinary array and hash syntax.

```perl
use Cairo;

my $surface = Cairo::ImageSurface->create('argb32', 100, 50);
my $cr = Cairo::Context->create($surface);
$cr->set_source_rgb(0.2, 0.4, 0.8);
$cr->rectangle(10, 10, 80, 30);
$cr->fill;
$cr->set_source_rgb(1, 1, 1);
$cr->move_to(20, 32);
$cr->show_text("cairo");
printf "%dx%d %s, status %s\n", $surface->get_width, $surface->get_height,
    $surface->get_format, $cr->status;           # 100x50 argb32, status success
$surface->write_to_png('out.png');
```

Enumerations are their nicknames as strings (`'argb32'`, `'success'`),
as in the CPAN module. The classes are documented on the pages below:
`Cairo::Context`, the surfaces, patterns, fonts, matrices, paths and
regions.

## Differences from upstream

None.

## Modules

- [`Cairo::Context`](Cairo/Context) - `Cairo::Context` - the drawing context, cairo's central object.
- [`Cairo::Font`](Cairo/Font) - The `Cairo::Font` family: font faces, scaled fonts and font options.
- [`Cairo::FontFace`](Cairo/FontFace)
- [`Cairo::FontOptions`](Cairo/FontOptions)
- [`Cairo::Format`](Cairo/Format)
- [`Cairo::FtFontFace`](Cairo/FtFontFace)
- [`Cairo::Gradient`](Cairo/Gradient)
- [`Cairo::ImageSurface`](Cairo/ImageSurface)
- [`Cairo::LinearGradient`](Cairo/LinearGradient)
- [`Cairo::Matrix`](Cairo/Matrix) - `Cairo::Matrix` - the affine transform every drawing operation goes through.
- [`Cairo::Pattern`](Cairo/Pattern) - `Cairo::Pattern` and its subclasses - the sources a context paints with.
- [`Cairo::PdfSurface`](Cairo/PdfSurface)
- [`Cairo::PsSurface`](Cairo/PsSurface)
- [`Cairo::RadialGradient`](Cairo/RadialGradient)
- [`Cairo::RecordingSurface`](Cairo/RecordingSurface)
- [`Cairo::Region`](Cairo/Region) - `Cairo::Region` - a set of integer-aligned rectangles.
- [`Cairo::ScaledFont`](Cairo/ScaledFont)
- [`Cairo::SolidPattern`](Cairo/SolidPattern)
- [`Cairo::Surface`](Cairo/Surface) - `Cairo::Surface` and its subclasses - the things cairo draws onto.
- [`Cairo::SurfacePattern`](Cairo/SurfacePattern)
- [`Cairo::SvgSurface`](Cairo/SvgSurface)
- [`Cairo::ToyFontFace`](Cairo/ToyFontFace)

## Functions

### Library information

#### `version`

Returns the version of the cairo library in use, as a single integer encoded `major * 10000 + minor * 100 + micro`.

Also available as `Cairo::lib_version`.

#### `version_string`

Returns the version of the cairo library in use as a printable string, for example "1.18.4".

Also available as `Cairo::lib_version_string`.

#### [`VERSION_ENCODE`](Cairo/VERSION_ENCODE)

Encodes a cairo version triple into the single integer that `Cairo::LIB_VERSION` returns: `major * 10000 + minor * 100 + micro`.

Also available as `Cairo::LIB_VERSION_ENCODE`.

#### `HAS_PNG_FUNCTIONS`

Returns true if the cairo library in use can read and write PNG files, that is, if `Cairo::ImageSurface->create_from_png` and `$surface->write_to_png` will work.

#### `HAS_PS_SURFACE`

Returns true if the cairo library in use can write PostScript, that is, if `Cairo::PsSurface->create` will work.

#### `HAS_PDF_SURFACE`

Returns true if the cairo library in use can write PDF, that is, if `Cairo::PdfSurface->create` will work.

#### `HAS_SVG_SURFACE`

Returns true if the cairo library in use can write SVG, that is, if `Cairo::SvgSurface->create` will work.

#### `HAS_RECORDING_SURFACE`

Returns true if the cairo library in use has recording surfaces (`Cairo::RecordingSurface->create`).

#### `HAS_FT_FONT`

Returns true if the cairo library in use can take its fonts from FreeType (`Cairo::FtFontFace->create`).

```{toctree}
:hidden:
:maxdepth: 1

Cairo/Context
Cairo/Font
Cairo/FontFace
Cairo/FontOptions
Cairo/Format
Cairo/FtFontFace
Cairo/Gradient
Cairo/ImageSurface
Cairo/LinearGradient
Cairo/Matrix
Cairo/Pattern
Cairo/PdfSurface
Cairo/PsSurface
Cairo/RadialGradient
Cairo/RecordingSurface
Cairo/Region
Cairo/ScaledFont
Cairo/SolidPattern
Cairo/Surface
Cairo/SurfacePattern
Cairo/SvgSurface
Cairo/ToyFontFace
Cairo/VERSION_ENCODE
```