Cairo - Perl interface to the cairo library

NAME

Cairo - Perl interface to the cairo library

SYNOPSIS

  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');

ABSTRACT

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.

API DOCUMENTATION

Note that this listing still lacks entries for Cairo::Surfaces and some utility methods.

Drawing

Cairo::Context -- The cairo drawing context

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. =over

$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

Paths -- Creating paths and manipulating path data

  $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

Patterns -- Gradients and filtered sources

$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 (double offset, double red, double green, double blue)

$offset: double
$red: double
$green: double
$blue: double

$pattern->add_color_stop_rgba (double offset, double red, double green, double blue, double 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.

Transformations -- Manipulating the current transformation matrix

$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

Text -- Rendering text and sets of glyphs

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

Fonts

Cairo::FontFace -- Base class for fonts

$status = $font_face->status

$type = $font_face->get_type [1.2]

Scaled Fonts -- Caching metrics for a particular font size

$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 -- How a font should be rendered

$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

FreeType Fonts -- Font support for FreeType

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 the Font::FreeType manpage 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);

Surfaces

Cairo::Surface -- Base class for surfaces

$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

Image Surfaces -- Rendering to memory buffers

$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]

PDF Surfaces -- Rendering PDF documents

$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: the Cairo::WriteFunc manpage
$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

PNG Support -- Reading and writing PNG images

$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: the Cairo::ReadFunc manpage
$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: the Cairo::WriteFunc manpage
$callback_data: scalar

PostScript Surfaces -- Rendering PostScript documents

$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: the Cairo::WriteFunc manpage
$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]

SVG Surfaces -- Rendering SVG documents

$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: the Cairo::WriteFunc manpage
$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

Utilities

Version Information -- Run-time and compile-time version checks.

$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

SEE ALSO

http://cairographics.org/documentation

Lists many available resources including tutorials and examples

http://cairographics.org/manual/

Contains the reference manual

AUTHORS

Ross McFarland <rwmcfa1 at neces dot com>
Torsten Schoenfeld <kaffeetisch at gmx dot de>

COPYRIGHT

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