cairo(3) - Linux man page
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 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);
SurfacesCairo::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
- $cr->save