Cairo(3pm) | User Contributed Perl Documentation | Cairo(3pm) |
NAME¶
Cairo - Perl interface to the cairo 2d vector graphics librarySYNOPSIS¶
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¶
This is a listing of the API Cairo provides. For more verbose information, refer to the cairo manual at <http://cairographics.org/manual/>.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)
- $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]
- $bool = $cr->in_clip ($x, $y) [1.10]
- $x: double
- $y: double
- @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" 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"
- "move-to": 1 point
- "line_to": 1 point
- "curve-to": 3 points
- "close-path": 0 points
my @path_clone = @{$path}; # now you can alter @path_clone which ever way you wantThe 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)
- $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_extend ($extend)
- $extend: Cairo::Extend
- $extend = $pattern->get_extend
- $pattern->set_filter ($filter)
- $filter: Cairo::Filter
- $filter = $pattern->get_filter
- $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
- $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.
- $region = Cairo::Region->create (...) [1.10]
- ...: zero or more Cairo::RectangleInt
- $status = $region->status [1.10]
- $num = $region->num_rectangles [1.10]
- $rect = $region->get_rectangle ($i) [1.10]
- $i: integer
- $bool = $region->is_empty [1.10]
- $bool = $region->contains_point ($x, $y) [1.10]
- $x: integer
- $y: integer
- $bool = $region_one->equal ($region_two) [1.10]
- $region_two: Cairo::Region
- $region->translate ($dx, $dy) [1.10]
- $dx: integer
- $dy: integer
- $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]
- $other: Cairo::Region
- $rect: Cairo::RectangleInt
- $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
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
- $cr->show_text_glyphs ($utf8, $glyphs, $clusters, $cluster_flags) [1.8]
- $utf8: string
- $glyphs: array ref of glyphs
- $clusters: array ref of clusters
- $cluster_flags: Cairo::TextClusterFlags
- $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
- $face = Cairo::ToyFontFace->create ($family, $slant, $weight) [1.8]
- $family: string
- $slant: Cairo::FontSlant
- $weight: Cairo::FontWeight
- $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_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
- ($status, $glyphs, $clusters, $cluster_flags) = $scaled_font->text_to_glyphs ($x, $y, $utf8) [1.8]
- $x: double
- $y: double
- $utf8: string
- $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 = 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
- 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- $similar = Cairo::Surface->create_similar ($other, $content, $width, $height)
- $other: Cairo::Surface
- $content: Cairo::Content
- $width: integer
- $height: integer
For hysterical reasons, you can also use the following syntax:
$similar = $other->create_similar ($content, $width, $height)
- $new = Cairo::Surface->create_for_rectangle ($target, $x, $y, $width, $height) [1.10]
- $target: Cairo::Surface
- $x: double
- $y: double
- $width: double
- $height: double
- $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
- ($x_pixels_per_inch, $y_pixels_per_inch) = $surface->get_fallback_resolution [1.8]
- $type = $surface->get_type [1.2]
- $status = $surface->copy_page [1.6]
- $status: Cairo::Status
- $status = $surface->show_page [1.6]
- $status: Cairo::Status
- $boolean = $surface->has_show_text_glyphs [1.8]
- $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]
- $stride = Cairo::Format::stride_for_width ($format, $width) [1.6]
- $format: Cairo::Format
- $width: integer
- $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->restrict_to_version ($version) [1.10]
- $version: Cairo::PdfVersion
- @versions = Cairo::PdfSurface::get_versions [1.10]
- $string = Cairo::PdfSurface::version_to_string ($version) [1.10]
- $version: Cairo::PdfVersion
- $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::RecordingSurface->create ($content, $extents) [1.10]
- $content: Cairo::Content
- $extents: Cairo::Rectangle
- ($x0, $y0, $width, $height) = $surface->ink_extents [1.10]
- $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
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)
- $major: integer
- $minor: integer
- $micro: integer
Encodes the version "$major.$minor.$micro" as an integer suitable for
comparison against "Cairo->lib_version" and
"Cairo->LIB_VERSION".
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-2013 by the cairo perl team2013-09-29 | perl v5.20.0 |