Cairo - Perl interface to the cairo library

  use Cairo;

  my $surface = Cairo::ImageSurface->create ('argb32', 100, 100);
  my $cr = Cairo::Context->create ($surface);

  $cr->rectangle (10, 10, 40, 40);
  $cr->set_source_rgb (0, 0, 0);
  $cr->fill;

  $cr->rectangle (50, 50, 40, 40);
  $cr->set_source_rgb (1, 1, 1);
  $cr->fill;

  $cr->show_page;

  $surface->write_to_png ('output.png');

Cairo provides Perl bindings for the vector graphics library cairo. It supports multiple output targets, including PNG, PDF and SVG. Cairo produces identical output on all those targets.

This is a listing of the API Cairo provides. For more verbose information, refer to the cairo manual at http://cairographics.org/manual/.

Cairo::Context is the main object used when drawing with Cairo. To draw with Cairo, you create a Cairo::Context, set the target surface, and drawing options for the Cairo::Context, create shapes with methods like $cr->move_to and $cr->line_to, and then draw shapes with $cr->stroke or $cr->fill.

Cairo::Context's can be pushed to a stack via $cr->save. They may then safely be changed, without loosing the current state. Use $cr->restore to restore to the saved state.

$cr = Cairo::Context->create ($surface)

$surface: Cairo::Surface

$cr->save

$cr->restore

$status = $cr->status

$surface = $cr->get_target

$cr->push_group [1.2]

$cr->push_group_with_content ($content) [1.2]

$content: Cairo::Content

$pattern = $cr->pop_group [1.2]

$cr->pop_group_to_source [1.2]

$surface = $cr->get_group_target [1.2]

$cr->set_source_rgb ($red, $green, $blue)

$red: double

$green: double

$blue: double

$cr->set_source_rgba ($red, $green, $blue, $alpha)

$red: double

$green: double

$blue: double

$alpha: double

$cr->set_source ($source)

$source: Cairo::Pattern

$cr->set_source_surface ($surface, $x, $y)

$surface: Cairo::Surface

$x: double

$y: double

$source = $cr->get_source

$cr->set_antialias ($antialias)

$antialias: Cairo::Antialias

$antialias = $cr->get_antialias

$cr->set_dash ($offset, ...)

$offset: double

...: list of doubles

$cr->set_fill_rule ($fill_rule)

$fill_rule: Cairo::FillRule

$fill_rule = $cr->get_fill_rule

$cr->set_line_cap ($line_cap)

$line_cap: Cairo::LineCap

$line_cap = $cr->get_line_cap

$cr->set_line_join ($line_join)

$line_join: Cairo::LineJoin

$line_join = $cr->get_line_join

$cr->set_line_width ($width)

$width: double

$width = $cr->get_line_width

$cr->set_miter_limit ($limit)

$limit: double

($offset, @dashes) = $cr->get_dash [1.4]

$limit = $cr->get_miter_limit

$cr->set_operator ($op)

$op: Cairo::Operator

$op = $cr->get_operator

$cr->set_tolerance ($tolerance)

$tolerance: double

$tolerance = $cr->get_tolerance

$cr->clip

$cr->clip_preserve

($x1, $y1, $x2, $y2) = $cr->clip_extents [1.4]

@rectangles = $cr->copy_clip_rectangle_list [1.4]

$cr->reset_clip

$cr->fill

$cr->fill_preserve

($x1, $y1, $x2, $y2) = $cr->fill_extents

$bool = $cr->in_fill ($x, $y)

$x: double

$y: double

$cr->mask ($pattern)

$pattern: Cairo::Pattern

$cr->mask_surface ($surface, $surface_x, $surface_y)

$surface: Cairo::Surface

$surface_x: double

$surface_y: double

$cr->paint

$cr->paint_with_alpha ($alpha)

$alpha: double

$cr->stroke

$cr->stroke_preserve

($x1, $y1, $x2, $y2) = $cr->stroke_extents

$bool = $cr->in_stroke ($x, $y)

$x: double

$y: double

$cr->copy_page

$cr->show_page

  $path = [
    { type => "move-to", points => [[1, 2]] },
    { type => "line-to", points => [[3, 4]] },
    { type => "curve-to", points => [[5, 6], [7, 8], [9, 10]] },
    ...
    { type => "close-path", points => [] },
  ];

Cairo::Path is a data structure for holding a path. This data structure serves as the return value for $cr->copy_path_data and $cr->copy_path_data_flat as well the input value for $cr->append_path.

Cairo::Path is represented as an array reference that contains path elements, represented by hash references with two keys: type and points. The value for type can be either of the following:

move-to

line-to

curve-to

close-path

The value for points is an array reference which contains zero or more points. Points are represented as array references that contain two doubles: x and y. The necessary number of points depends on the type of the path element:

move-to: 1 point

line_to: 1 point

curve-to: 3 points

close-path: 0 points

The semantics and ordering of the coordinate values are consistent with $cr->move_to, $cr->line_to, $cr->curve_to, and $cr->close_path.

$path = $cr->copy_path

$path = $cr->copy_path_flat

$cr->append_path ($path)

$path: Cairo::Path

$bool = $cr->has_current_point [1.6]

($x, $y) = $cr->get_current_point

$cr->new_path

$cr->new_sub_path [1.2]

$cr->close_path

($x1, $y1, $x2, $y2) = $cr->path_extents [1.6]

$cr->arc ($xc, $yc, $radius, $angle1, $angle2)

$xc: double

$yc: double

$radius: double

$angle1: double

$angle2: double

$cr->arc_negative ($xc, $yc, $radius, $angle1, $angle2)

$xc: double

$yc: double

$radius: double

$angle1: double

$angle2: double

$cr->curve_to ($x1, $y1, $x2, $y2, $x3, $y3)

$x1: double

$y1: double

$x2: double

$y2: double

$x3: double

$y3: double

$cr->line_to ($x, $y)

$x: double

$y: double

$cr->move_to ($x, $y)

$x: double

$y: double

$cr->rectangle ($x, $y, $width, $height)

$x: double

$y: double

$width: double

$height: double

$cr->glyph_path (...)

...: list of Cairo::Glyph's

$cr->text_path ($utf8)

$utf8: string in utf8 encoding

$cr->rel_curve_to ($dx1, $dy1, $dx2, $dy2, $dx3, $dy3)

$dx1: double

$dy1: double

$dx2: double

$dy2: double

$dx3: double

$dy3: double

$cr->rel_line_to ($dx, $dy)

$dx: double

$dy: double

$cr->rel_move_to ($dx, $dy)

$dx: double

$dy: double

$status = $pattern->status

$type = $pattern->get_type [1.2]

$pattern->set_matrix ($matrix)

$matrix: Cairo::Matrix

$matrix = $pattern->get_matrix

$pattern = Cairo::SolidPattern->create_rgb ($red, $green, $blue)

$red: double

$green: double

$blue: double

$pattern = Cairo::SolidPattern->create_rgba ($red, $green, $blue, $alpha)

$red: double

$green: double

$blue: double

$alpha: double

($r, $g, $b, $a) = $pattern->get_rgba [1.4]

$pattern = Cairo::SurfacePattern->create ($surface)

$surface: Cairo::Surface

$pattern->set_extend ($extend)

$extend: Cairo::Extend

$extend = $pattern->get_extend

$pattern->set_filter ($filter)

$filter: Cairo::Filter

$filter = $pattern->get_filter

$surface = $pattern->get_surface [1.4]

$pattern = Cairo::LinearGradient->create ($x0, $y0, $x1, $y1)

$x0: double

$y0: double

$x1: double

$y1: double

($x0, $y0, $x1, $y1) = $pattern->get_points [1.4]

$pattern = Cairo::RadialGradient->create ($cx0, $cy0, $radius0, $cx1, $cy1, $radius1)

$cx0: double

$cy0: double

$radius0: double

$cx1: double

$cy1: double

$radius1: double

($x0, $y0, $r0, $x1, $y1, $r1) = $pattern->get_circles [1.4]

$pattern->add_color_stop_rgb ($offset, $red, $green, $blue)

$offset: double

$red: double

$green: double

$blue: double

$pattern->add_color_stop_rgba ($offset, $red, $green, $blue, $alpha)

$offset: double

$red: double

$green: double

$blue: double

$alpha: double

@stops = $pattern->get_color_stops [1.4]

A color stop is represented as an array reference with five elements: offset, red, green, blue, and alpha.

$cr->translate ($tx, $ty)

$tx: double

$ty: double

$cr->scale ($sx, $sy)

$sx: double

$sy: double

$cr->rotate ($angle)

$angle: double

$cr->transform ($matrix)

$matrix: Cairo::Matrix

$cr->set_matrix ($matrix)

$matrix: Cairo::Matrix

$matrix = $cr->get_matrix

$cr->identity_matrix

($x, $y) = $cr->user_to_device ($x, $y)

$x: double

$y: double

($dx, $dy) = $cr->user_to_device_distance ($dx, $dy)

$dx: double

$dy: double

($x, $y) = $cr->device_to_user ($x, $y)

$x: double

$y: double

($dx, $dy) = $cr->device_to_user_distance ($dx, $dy)

$dx: double

$dy: double

Glyphs are represented as anonymous hash references with three keys: index, x and y. Example:

  my @glyphs = ({ index => 1, x => 2, y => 3 },
                { index => 2, x => 3, y => 4 },
                { index => 3, x => 4, y => 5 });

$cr->select_font_face ($family, $slant, $weight)

$family: string

$slant: Cairo::FontSlant

$weight: Cairo::FontWeight

$cr->set_font_size ($size)

$size: double

$cr->set_font_matrix ($matrix)

$matrix: Cairo::Matrix

$matrix = $cr->get_font_matrix

$cr->set_font_options ($options)

$options: Cairo::FontOptions

$options = $cr->get_font_options

$cr->set_scaled_font ($scaled_font) [1.2]

$scaled_font: Cairo::ScaledFont

$scaled_font = $cr->get_scaled_font [1.4]

$cr->show_text ($utf8)

$utf8: string

$cr->show_glyphs (...)

...: list of glyphs

$face = $cr->get_font_face

$extents = $cr->font_extents

$cr->set_font_face ($font_face)

$font_face: Cairo::FontFace

$cr->set_scaled_font ($scaled_font)

$scaled_font: Cairo::ScaledFont

$extents = $cr->text_extents ($utf8)

$utf8: string

$extents = $cr->glyph_extents (...)

...: list of glyphs

$status = $font_face->status

$type = $font_face->get_type [1.2]

$scaled_font = Cairo::ScaledFont->create ($font_face, $font_matrix, $ctm, $options)

$font_face: Cairo::FontFace

$font_matrix: Cairo::Matrix

$ctm: Cairo::Matrix

$options: Cairo::FontOptions

$status = $scaled_font->status

$extents = $scaled_font->extents

$extents = $scaled_font->text_extents ($utf8) [1.2]

$utf8: string

$extents = $scaled_font->glyph_extents (...)

...: list of glyphs

$font_face = $scaled_font->get_font_face [1.2]

$options = $scaled_font->get_font_options [1.2]

$font_matrix = $scaled_font->get_font_matrix [1.2]

$ctm = $scaled_font->get_ctm [1.2]

$type = $scaled_font->get_type [1.2]

$font_options = Cairo::FontOptions->create

$status = $font_options->status

$font_options->merge ($other)

$other: Cairo::FontOptions

$hash = $font_options->hash

$bools = $font_options->equal ($other)

$other: Cairo::FontOptions

$font_options->set_antialias ($antialias)

$antialias: Cairo::AntiAlias

$antialias = $font_options->get_antialias

$font_options->set_subpixel_order ($subpixel_order)

$subpixel_order: Cairo::SubpixelOrder

$subpixel_order = $font_options->get_subpixel_order

$font_options->set_hint_style ($hint_style)

$hint_style: Cairo::HintStyle

$hint_style = $font_options->get_hint_style

$font_options->set_hint_metrics ($hint_metrics)

$hint_metrics: Cairo::HintMetrics

$hint_metrics = $font_options->get_hint_metrics

If your cairo library supports it, the FreeType integration allows you to load font faces from font files. You can query for this capability with Cairo::HAS_FT_FONT. To actually use this, you'll need the Font::FreeType module.

my $face = Cairo::FtFontFace->create ($ft_face, $load_flags=0)

$ft_face: Font::FreeType::Face

$load_flags: integer

This method allows you to create a Cairo::FontFace from a Font::FreeType::Face. To obtain the latter, you can for example load it from a file:

  my $file = '/usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf';
  my $ft_face = Font::FreeType->new->face ($file);
  my $face = Cairo::FtFontFace->create ($ft_face);

$new = $old->create_similar ($content, $width, $height)

$content: Cairo::Content

$width: integer

$height: integer

$status = $surface->status

$surface->finish

$surface->flush

$font_options = $surface->get_font_options

$content = $surface->get_content [1.2]

$surface->mark_dirty

$surface->mark_dirty_rectangle ($x, $y, $width, $height)

$x: integer

$y: integer

$width: integer

$height: integer

$surface->set_device_offset ($x_offset, $y_offset)

$x_offset: integer

$y_offset: integer

($x_offset, $y_offset) = $surface->get_device_offset [1.2]

$surface->set_fallback_resolution ($x_pixels_per_inch, $y_pixels_per_inch) [1.2]

$x_pixels_per_inch: double

$y_pixels_per_inch: double

$type = $surface->get_type [1.2]

$status = $surface->copy_page [1.6]

$status: Cairo::Status

$status = $surface->show_page [1.6]

$status: Cairo::Status

$surface = Cairo::ImageSurface->create ($format, $width, $height)

$format: Cairo::Format

$width: integer

$height: integer

$surface = Cairo::ImageSurface->create_for_data ($data, $format, $width, $height, $stride)

$data: image data

$format: Cairo::Format

$width: integer

$height: integer

$stride: integer

$data = $surface->get_data [1.2]

$format = $surface->get_format [1.2]

$width = $surface->get_width

$height = $surface->get_height

$stride = $surface->get_stride [1.2]

$surface = Cairo::PdfSurface->create ($filename, $width_in_points, $height_in_points) [1.2]

$filename: string

$width_in_points: double

$height_in_points: double

$surface = Cairo::PdfSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2]

$callback: Cairo::WriteFunc

$callback_data: scalar

$width_in_points: double

$height_in_points: double

$surface->set_size ($width_in_points, $height_in_points) [1.2]

$width_in_points: double

$height_in_points: double

$surface = Cairo::ImageSurface->create_from_png ($filename)

$filename: string

Cairo::ReadFunc: $data = sub { my ($callback_data, $length) = @_; }

$data: binary image data, of length $length

$callback_data: scalar, user data

$length: integer, bytes to read

$surface = Cairo::ImageSurface->create_from_png_stream ($callback, $callback_data)

$callback: Cairo::ReadFunc

$callback_data: scalar

$status = $surface->write_to_png ($filename)

$filename: string

Cairo::WriteFunc: sub { my ($callback_data, $data) = @_; }

$callback_data: scalar, user data

$data: binary image data, to be written

$status = $surface->write_to_png_stream ($callback, $callback_data)

$callback: Cairo::WriteFunc

$callback_data: scalar

$surface = Cairo::PsSurface->create ($filename, $width_in_points, $height_in_points) [1.2]

$filename: string

$width_in_points: double

$height_in_points: double

$surface = Cairo::PsSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2]

$callback: Cairo::WriteFunc

$callback_data: scalar

$width_in_points: double

$height_in_points: double

$surface->set_size ($width_in_points, $height_in_points) [1.2]

$width_in_points: double

$height_in_points: double

$surface->dsc_begin_setup [1.2]

$surface->dsc_begin_page_setup [1.2]

$surface->dsc_comment ($comment) [1.2]

$comment: string

$surface->restrict_to_level ($level) [1.6]

$level: Cairo::PsLevel

@levels = Cairo::PsSurface::get_levels [1.6]

$string = Cairo::PsSurface::level_to_string ($level) [1.6]

$level: Cairo::PsLevel

$surface->set_eps ($eps) [1.6]

$eps: boolean

$eps = $surface->get_eps [1.6]

$surface = Cairo::SvgSurface->create ($filename, $width_in_points, $height_in_points) [1.2]

$filename: string

$width_in_points: double

$height_in_points: double

$surface = Cairo::SvgSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2]

$callback: Cairo::WriteFunc

$callback_data: scalar

$width_in_points: double

$height_in_points: double

$surface->restrict_to_version ($version) [1.2]

$version: Cairo::SvgVersion

@versions = Cairo::SvgSurface::get_versions [1.2]

$string = Cairo::SvgSurface::version_to_string ($version) [1.2]

$version: Cairo::SvgVersion

$version = Cairo->version

$string = Cairo->version_string

$version_code = Cairo->VERSION

$version_code = Cairo->VERSION_ENCODE ($major, $minor, $micro)

$major: integer

$minor: integer

$micro: integer

$stride = Cairo::Format::stride_for_width ($format, $width) [1.6]

$format: Cairo::Format

$width: integer

http://cairographics.org/documentation

Lists many available resources including tutorials and examples

http://cairographics.org/manual/

Contains the reference manual

Ross McFarland <rwmcfa1 at neces dot com>

Torsten Schoenfeld <kaffeetisch at gmx dot de>

Copyright (C) 2004-2011 by the cairo perl team