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.

$cr = Cairo::Context->create ($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]

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

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

$cr->set_source ($source)

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

$source = $cr->get_source

$cr->set_antialias ($antialias)

$antialias = $cr->get_antialias

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

$cr->set_fill_rule ($fill_rule)

$fill_rule = $cr->get_fill_rule

$cr->set_line_cap ($line_cap)

$line_cap = $cr->get_line_cap

$cr->set_line_join ($line_join)

$line_join = $cr->get_line_join

$cr->set_line_width ($width)

$width = $cr->get_line_width

$cr->set_miter_limit ($limit)

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

$limit = $cr->get_miter_limit

$cr->set_operator ($op)

$op = $cr->get_operator

$cr->set_tolerance ($tolerance)

$tolerance = $cr->get_tolerance

$cr->clip

$cr->clip_preserve

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

$bool = $cr->in_clip ($x, $y) [1.10]

@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)

$cr->mask ($pattern)

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

$cr->paint

$cr->paint_with_alpha ($alpha)

$cr->stroke

$cr->stroke_preserve

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

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

$cr->tag_begin($name, $atts) [1.16]

$cr->tag_end($name) [1.16]

Predefined names:

$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" and "$cr->copy_path_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".

Note that the paths returned by Cairo are implemented as tied array references which do not support adding, removing or shuffling of path segments. For these operations, you need to make a shallow copy first:

  my @path_clone = @{$path};
  # now you can alter @path_clone which ever way you want

The points of a single path element can be changed directly, however, without the need for a shallow copy:

  $path->[$i]{points} = [[3, 4], [5, 6], [7, 8]];

$path = $cr->copy_path

$path = $cr->copy_path_flat

$cr->append_path ($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)

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

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

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

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

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

$cr->glyph_path (...)

$cr->text_path ($utf8)

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

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

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

Patterns -- Gradients and filtered sources

$status = $pattern->status

$type = $pattern->get_type [1.2]

$pattern->set_extend ($extend)

$extend = $pattern->get_extend

$pattern->set_filter ($filter)

$filter = $pattern->get_filter

$pattern->set_matrix ($matrix)

$matrix = $pattern->get_matrix

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

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

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

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

$surface = $pattern->get_surface [1.4]

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

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

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

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

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

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

@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.

Regions -- Representing a pixel-aligned area

$region = Cairo::Region->create (...) [1.10]

$status = $region->status [1.10]

$num = $region->num_rectangles [1.10]

$rect = $region->get_rectangle ($i) [1.10]

$bool = $region->is_empty [1.10]

$bool = $region->contains_point ($x, $y) [1.10]

$bool = $region_one->equal ($region_two) [1.10]

$region->translate ($dx, $dy) [1.10]

$status = $dst->intersect ($other) [1.10]

$status = $dst->intersect_rectangle ($rect) [1.10]

$status = $dst->subtract ($other) [1.10]

$status = $dst->subtract_rectangle ($rect) [1.10]

$status = $dst->union ($other) [1.10]

$status = $dst->union_rectangle ($rect) [1.10]

$status = $dst->xor ($other) [1.10]

$status = $dst->xor_rectangle ($rect) [1.10]

Transformations -- Manipulating the current transformation matrix

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

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

$cr->rotate ($angle)

$cr->transform ($matrix)

$cr->set_matrix ($matrix)

$matrix = $cr->get_matrix

$cr->identity_matrix

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

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

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

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

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)

$cr->set_font_size ($size)

$cr->set_font_matrix ($matrix)

$matrix = $cr->get_font_matrix

$cr->set_font_options ($options)

$options = $cr->get_font_options

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

$scaled_font = $cr->get_scaled_font [1.4]

$cr->show_text ($utf8)

$cr->show_glyphs (...)

$cr->show_text_glyphs ($utf8, $glyphs, $clusters, $cluster_flags) [1.8]

$face = $cr->get_font_face

$extents = $cr->font_extents

$cr->set_font_face ($font_face)

$cr->set_scaled_font ($scaled_font)

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

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

$face = Cairo::ToyFontFace->create ($family, $slant, $weight) [1.8]

$family = $face->get_family [1.8]

$slang = $face->get_slant [1.8]

$weight = $face->get_weight [1.8]

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)

$status = $scaled_font->status

$extents = $scaled_font->extents

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

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

($status, $glyphs, $clusters, $cluster_flags) = $scaled_font->text_to_glyphs ($x, $y, $utf8) [1.8]

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

$scale_matrix = $scaled_font->get_scale_matrix [1.8]

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

$hash = $font_options->hash

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

$font_options->set_antialias ($antialias)

$antialias = $font_options->get_antialias

$font_options->set_subpixel_order ($subpixel_order)

$subpixel_order = $font_options->get_subpixel_order

$font_options->set_hint_style ($hint_style)

$hint_style = $font_options->get_hint_style

$font_options->set_hint_metrics ($hint_metrics)

$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 Font::FreeType module.

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

  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

$similar = Cairo::Surface->create_similar ($other, $content, $width, $height)

  $similar = $other->create_similar ($content, $width, $height)

$new = Cairo::Surface->create_for_rectangle ($target, $x, $y, $width, $height) [1.10]

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

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

($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, $y_pixels_per_inch) = $surface->get_fallback_resolution [1.8]

$type = $surface->get_type [1.2]

$surface->set_mime_data ($mime_type, $mime_data) [1.10]

$mime_data = $surface->get_mime_data ($mime_type) [1.10]

$bool = $surface->supports_mime_type ($mime_type) [1.12]

$status = $surface->copy_page [1.6]

$status = $surface->show_page [1.6]

$boolean = $surface->has_show_text_glyphs [1.8]

Image Surfaces -- Rendering to memory buffers

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

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

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

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

PDF Surfaces -- Rendering PDF documents

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

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

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

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

@versions = Cairo::PdfSurface::get_versions [1.10]

$string = Cairo::PdfSurface::version_to_string ($version) [1.10]

$item_id = $surface->add_outline($parent_id, $name, $attributes, $flags) [1.16]

$surface->set_metadata($name, $value) [1.16]

$surface->set_page_label($label) [1.16]

$surface->set_thumbnail_size($width, $height) [1.16]

PNG Support -- Reading and writing PNG images

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

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

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

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

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

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

PostScript Surfaces -- Rendering PostScript documents

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

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

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

$surface->dsc_begin_setup [1.2]

$surface->dsc_begin_page_setup [1.2]

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

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

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

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

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

$eps = $surface->get_eps [1.6]

Recording Surfaces -- Records all drawing operations

$surface = Cairo::RecordingSurface->create ($content, $extents) [1.10]

($x0, $y0, $width, $height) = $surface->ink_extents [1.10]

$extents_ref = $surface->get_extents [1.12]

SVG Surfaces -- Rendering SVG documents

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

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

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

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

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

Utilities

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

$version_code = Cairo->lib_version

$version_string = Cairo->lib_version_string

These two functions return the version of libcairo that the program is currently running against.

$version_code = Cairo->LIB_VERSION

Returns the version of libcairo that Cairo was compiled against.

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