Cairo(3)

💖 Cairo(3) 💖 — part 1

Welcome to Cairo(3) from the User Contributed Perl Documentation, bestie 🫶 This is the Perl situation, and it's giving vector graphics main character energy.

---

🌸 NAME 🌸

Cairo — Perl interface to the cairo 2d vector graphics 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. Slay, consistency 💅

🌈 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. Iconic workflow, no cap ✨

You can push a Cairo::Context onto a stack with $cr->save. Then you can safely change stuff without losing 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->tag_begin($name, $atts) [1.16]
  • $name: string
  • $atts: string
• $cr->tag_end($name) [1.16]
  • $name: string

Predefined names, bestie:

• Cairo::TAG_DEST [1.16]
• Cairo::TAG_LINK [1.16]
• $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. Periodt ✨

⚠️ 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)
  • $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_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.

🍓 Regions -- Representing a pixel-aligned area

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

💫 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 — matrix getter moment, slay.
• $cr->identity_matrix — identity matrix, periodt.
• ($x, $y) = $cr->user_to_device ($x, $y) — args:
  • $x: double
  • $y: double
• ($dx, $dy) = $cr->user_to_device_distance ($dx, $dy) — args:
  • $dx: double
  • $dy: double
• ($x, $y) = $cr->device_to_user ($x, $y) — args:
  • $x: double
  • $y: double
• ($dx, $dy) = $cr->device_to_user_distance ($dx, $dy) — args:
  • $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) — font face selection, no notes 💅 args:
  • $family: string
  • $slant: Cairo::FontSlant
  • $weight: Cairo::FontWeight
• $cr->set_font_size ($size) — set the font size. Arg:
  • $size: double
• $cr->set_font_matrix ($matrix) — font matrix time. Arg:
  • $matrix: Cairo::Matrix
• $matrix = $cr->get_font_matrix — the font matrix getter.
• $cr->set_font_options ($options) — set those font options. Arg:
  • $options: Cairo::FontOptions
• $options = $cr->get_font_options — get those font options.
• $cr->set_scaled_font ($scaled_font) [1.2] — scaled font setter. Arg:
  • $scaled_font: Cairo::ScaledFont
• $scaled_font = $cr->get_scaled_font [1.4] — scaled font getter.
• $cr->show_text ($utf8) — show text. Arg:
  • $utf8: string
• $cr->show_glyphs (...) — show glyphs. Arg:
  • ...: list of glyphs
• $cr->show_text_glyphs ($utf8, $glyphs, $clusters, $cluster_flags) [1.8] — show text glyphs. Args:
  • $utf8: string
  • $glyphs: array ref of glyphs
  • $clusters: array ref of clusters
  • $cluster_flags: Cairo::TextClusterFlags
• $face = $cr->get_font_face — font face getter.
• $extents = $cr->font_extents — font extents.
• $cr->set_font_face ($font_face) — set the font face. Arg:
  • $font_face: Cairo::FontFace
• $cr->set_scaled_font ($scaled_font) — set the scaled font (again, no version tag this time). Arg:
  • $scaled_font: Cairo::ScaledFont
• $extents = $cr->text_extents ($utf8) — text extents. Arg:
  • $utf8: string
• $extents = $cr->glyph_extents (...) — glyph extents. Arg:
  • ...: list of glyphs
• $face = Cairo::ToyFontFace->create ($family, $slant, $weight) [1.8] — toy font face creation. Args:
  • $family: string
  • $slant: Cairo::FontSlant
  • $weight: Cairo::FontWeight
• $family = $face->get_family [1.8] — family getter.
• $slang = $face->get_slant [1.8] — slant getter (and yes, the variable is literally $slang, not $slant — keep it exactly, bestie 😭).
• $weight = $face->get_weight [1.8] — weight getter.

🦋 Fonts 🦋

Cairo::FontFace — base class for fonts, periodt.

• $status = $font_face->status — status check.
• $type = $font_face->get_type [1.2] — type getter.

🎀 Scaled Fonts -- Caching metrics for a particular font size 🎀

• $scaled_font = Cairo::ScaledFont->create ($font_face, $font_matrix, $ctm, $options) — scaled font creation. Args:
  • $font_face: Cairo::FontFace
  • $font_matrix: Cairo::Matrix
  • $ctm: Cairo::Matrix
  • $options: Cairo::FontOptions
• $status = $scaled_font->status — status.
• $extents = $scaled_font->extents — extents.
• $extents = $scaled_font->text_extents ($utf8) [1.2] — text extents. Arg:
  • $utf8: string
• $extents = $scaled_font->glyph_extents (...) — glyph extents. Arg:
  • ...: list of glyphs
• ($status, $glyphs, $clusters, $cluster_flags) = $scaled_font->text_to_glyphs ($x, $y, $utf8) [1.8] — text to glyphs. Args:
  • $x: double
  • $y: double
  • $utf8: string
• $font_face = $scaled_font->get_font_face [1.2] — font face getter.
• $options = $scaled_font->get_font_options [1.2] — font options getter.
• $font_matrix = $scaled_font->get_font_matrix [1.2] — font matrix getter.
• $ctm = $scaled_font->get_ctm [1.2] — ctm getter.
• $scale_matrix = $scaled_font->get_scale_matrix [1.8] — scale matrix getter.
• $type = $scaled_font->get_type [1.2] — type getter.

💖 Font Options -- How a font should be rendered 💖

• $font_options = Cairo::FontOptions->create — create those font options.
• $status = $font_options->status — status.
• $font_options->merge ($other) — merge. Arg:
  • $other: Cairo::FontOptions
• $hash = $font_options->hash — hash.
• $bools = $font_options->equal ($other) — equal check (yes, $bools is the variable). Arg:
  • $other: Cairo::FontOptions
• $font_options->set_antialias ($antialias) — set antialias. Arg:
  • $antialias: Cairo::AntiAlias
• $antialias = $font_options->get_antialias — get antialias.
• $font_options->set_subpixel_order ($subpixel_order) — set subpixel order. Arg:
  • $subpixel_order: Cairo::SubpixelOrder
• $subpixel_order = $font_options->get_subpixel_order — get subpixel order.
• $font_options->set_hint_style ($hint_style) — set hint style. Arg:
  • $hint_style: Cairo::HintStyle
• $hint_style = $font_options->get_hint_style — get hint style.
• $font_options->set_hint_metrics ($hint_metrics) — set hint metrics. Arg:
  • $hint_metrics: Cairo::HintMetrics
• $hint_metrics = $font_options->get_hint_metrics — get hint metrics.

🧚 FreeType Fonts -- Font support for FreeType 🧚

okay so if your cairo library supports it, the FreeType integration lets you load font faces from font files — yes bestie. 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) — FtFontFace create. Args:
  • $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, no cap.

• $similar = Cairo::Surface->create_similar ($other, $content, $width, $height) — create similar. Args:
  • $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] — create for rectangle. Args:
  • $target: Cairo::Surface
  • $x: double
  • $y: double
  • $width: double
  • $height: double
• $status = $surface->status — status.
• $surface->finish — finish.
• $surface->flush — flush.
• $font_options = $surface->get_font_options — font options getter.
• $content = $surface->get_content [1.2] — content getter.
• $surface->mark_dirty — mark dirty.
• $surface->mark_dirty_rectangle ($x, $y, $width, $height) — mark dirty rectangle. Args:
  • $x: integer
  • $y: integer
  • $width: integer
  • $height: integer
• $surface->set_device_offset ($x_offset, $y_offset) — set device offset. Args:
  • $x_offset: integer
  • $y_offset: integer
• ($x_offset, $y_offset) = $surface->get_device_offset [1.2] — get device offset.
• $surface->set_fallback_resolution ($x_pixels_per_inch, $y_pixels_per_inch) [1.2] — set fallback resolution. Args:
  • $x_pixels_per_inch: double
  • $y_pixels_per_inch: double
• ($x_pixels_per_inch, $y_pixels_per_inch) = $surface->get_fallback_resolution [1.8] — get fallback resolution.
• $type = $surface->get_type [1.2] — type getter.
• $surface->set_mime_data ($mime_type, $mime_data) [1.10] — set MIME data.
• $mime_data = $surface->get_mime_data ($mime_type) [1.10] — get MIME data.
• $bool = $surface->supports_mime_type ($mime_type) [1.12] — supports MIME type.

okay the arg deets for that MIME trio are:

• $mime_type: string
  • Predefined MIME types:
    • Cairo::Surface::MIME_TYPE_JP2 [1.10]
    • Cairo::Surface::MIME_TYPE_JPEG [1.10]
    • Cairo::Surface::MIME_TYPE_PNG [1.10]
    • Cairo::Surface::MIME_TYPE_URI [1.10]
    • Cairo::Surface::MIME_TYPE_UNIQUE_ID [1.12]
    • Cairo::Surface::MIME_TYPE_JBIG2 [1.14]
    • Cairo::Surface::MIME_TYPE_JBIG2_GLOBAL [1.14]
    • Cairo::Surface::MIME_TYPE_JBIG2_GLOBAL_PARAMS [1.14]
    • Cairo::Surface::MIME_TYPE_CCITT_FAX [1.16]
    • Cairo::Surface::MIME_TYPE_CCITT_FAX_PARAMS [1.16]
    • Cairo::Surface::MIME_TYPE_EPS [1.16]
    • Cairo::Surface::MIME_TYPE_EPS_PARAMS [1.16]
• $mime_data: binary data string
• $status = $surface->copy_page [1.6] — copy page. Arg:
  • $status: Cairo::Status
• $status = $surface->show_page [1.6] — show page. Arg:
  • $status: Cairo::Status
• $boolean = $surface->has_show_text_glyphs [1.8] — boolean check.

🍓 Image Surfaces -- Rendering to memory buffers 🍓

• $surface = Cairo::ImageSurface->create ($format, $width, $height) — create image surface. Args:
  • $format: Cairo::Format
  • $width: integer
  • $height: integer
• $surface = Cairo::ImageSurface->create_for_data ($data, $format, $width, $height, $stride) — create for data. Args:
  • $data: image data
  • $format: Cairo::Format
  • $width: integer
  • $height: integer
  • $stride: integer
• $data = $surface->get_data [1.2] — data getter.
• $format = $surface->get_format [1.2] — format getter.
• $width = $surface->get_width — width getter.
• $height = $surface->get_height — height getter.
• $stride = $surface->get_stride [1.2] — stride getter.
• $stride = Cairo::Format::stride_for_width ($format, $width) [1.6] — stride for width. Args:
  • $format: Cairo::Format
  • $width: integer

🌈 PDF Surfaces -- Rendering PDF documents 🌈

• $surface = Cairo::PdfSurface->create ($filename, $width_in_points, $height_in_points) [1.2] — PDF surface create. Args:
  • $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] — create for stream. Args:
  • $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] — set size. Args:
  • $width_in_points: double
  • $height_in_points: double
• $surface->restrict_to_version ($version) [1.10] — restrict to version. Arg:
  • $version: Cairo::PdfVersion
• @versions = Cairo::PdfSurface::get_versions [1.10] — get versions.
• $string = Cairo::PdfSurface::version_to_string ($version) [1.10] — version to string. Arg:
  • $version: Cairo::PdfVersion
• $item_id = $surface->add_outline($parent_id, $name, $attributes, $flags) [1.16] — add outline. Args:
  • $item_id: int, item ID
  • $parent_id: parent item id or Cairo::PdfSurface::OUTLINE_ROOT
  • $name: string, item display
  • $attributes: string, item attributes
  • $flags: list reference, item flags
• $surface->set_metadata($name, $value) [1.16] — set metadata. Args:
  • $name: string
  • $value: string
• $surface->set_page_label($label) [1.16] — set page label. Arg:
  • $label: string, page label
• $surface->set_thumbnail_size($width, $height) [1.16] — set thumbnail size. Args:
  • $width: int, thumbnail width
  • $height: int, thumbnail height

💜 PNG Support -- Reading and writing PNG images 💜

• $surface = Cairo::ImageSurface->create_from_png ($filename) — create from PNG. Arg:
  • $filename: string
• Cairo::ReadFunc: $data = sub { my ($callback_data, $length) = @_; } — read callback. Args:
  • $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) — create from PNG stream. Args:
  • $callback: Cairo::ReadFunc
  • $callback_data: scalar
• $status = $surface->write_to_png ($filename) — write to PNG. Arg:
  • $filename: string
• Cairo::WriteFunc: sub { my ($callback_data, $data) = @_; } — write callback. Args:
  • $callback_data: scalar, user data
  • $data: binary image data, to be written
• $status = $surface->write_to_png_stream ($callback, $callback_data) — write to PNG stream. Args:
  • $callback: Cairo::WriteFunc
  • $callback_data: scalar

🎀 PostScript Surfaces -- Rendering PostScript documents 🎀

• $surface = Cairo::PsSurface->create ($filename, $width_in_points, $height_in_points) [1.2] — PS surface create. Args:
  • $filename: string
  • $width_in_points: double
  • $height_in_points: double

PostScript surfaces are still serving, and the stream flavor is right here — it’s giving callback energy:

       $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

The size-setting moment is literally right here:

• $surface->set_size ($width_in_points, $height_in_points) [1.2] — sets the size, with these two doubles:
  • $width_in_points: double
  • $height_in_points: double

Then the DSC trio, lowkey iconic:

• $surface->dsc_begin_setup [1.2] — the no-arg setup call, periodt.
• $surface->dsc_begin_page_setup [1.2] — the no-arg page-setup call.
• $surface->dsc_comment ($comment) [1.2] — takes $comment: string.

Level restriction and level-string stuff:

• $surface->restrict_to_level ($level) [1.6] — restricts to a level; $level: Cairo::PsLevel.
• @levels = Cairo::PsSurface::get_levels [1.6] — returns the levels into @levels.
• $string = Cairo::PsSurface::level_to_string ($level) [1.6] — turns a level into a string; $level: Cairo::PsLevel.

EPS toggle time:

• $surface->set_eps ($eps) [1.6] — sets EPS mode; $eps: boolean.
• $eps = $surface->get_eps [1.6] — gets EPS mode into $eps.

---

🎙️ Recording Surfaces — Records all drawing operations

Recording surfaces are literally recording every drawing operation, main character behavior:

• $surface = Cairo::RecordingSurface->create ($content, $extents) [1.10] — creates one; args are:
  • $content: Cairo::Content
  • $extents: Cairo::Rectangle
• ($x0, $y0, $width, $height) = $surface->ink_extents [1.10] — gives you back $x0, $y0, $width, $height.
• $extents_ref = $surface->get_extents [1.12] — returns an extents reference; $extents_ref: Cairo::Rectangle reference.

---

🎨 SVG Surfaces — Rendering SVG documents

SVG surfaces are here to render SVG documents, no cap:

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

• $filename: string
• $width_in_points: double
• $height_in_points: double

And the stream version, because we love a callback:

       $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

Version restriction and version-string stuff:

• $surface->restrict_to_version ($version) [1.2] — restricts to a version; $version: Cairo::SvgVersion.
• @versions = Cairo::SvgSurface::get_versions [1.2] — returns versions into @versions.
• $string = Cairo::SvgSurface::version_to_string ($version) [1.2] — turns a version into a string; $version: Cairo::SvgVersion.

---

⚙️ Utilities ⚙️

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

• $version_code = Cairo->lib_version and $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) — takes these integers:
  • $major: integer
  • $minor: integer
  • $micro: integer

It 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 team

---

That’s the whole Cairo(3) glow-up, bestie — source/version perl v5.42.0, dated 2021-01-21. 💖✨🎀