# Peta::FFI::Cairo::Surface

📦 std

`Cairo::Surface` family package plug-in. One file per the seven-file fan-out plan covers the whole surface family, because every concrete surface (`Cairo::ImageSurface`, `Cairo::PdfSurface`, `Cairo::PsSurface`, `Cairo::SvgSurface`, `Cairo::RecordingSurface`) is a `Cairo::Surface` subclass blessed by the SAME type-dispatch table (`cairo_surface_get_type`), and they share the surface-family cairo symbols. This module resolves those symbols itself via `super::cairo_dlsym` over the shared handle, so the foundation’s symbol table never carries surface entries and parallel package agents never contend on it. Refcount contract (census section 4): every `create*` constructor and `create_similar` / `create_for_rectangle` return a +1 surface, blessed directly (`_noinc`). `DESTROY` drops exactly one reference via `cairo_surface_destroy`. Enum-returning methods (`status`, `get_type`, `get_content`, `get_format`) surface the cairo int as its string nickname. Version scope (census top block): the 1.109 phenotype is the floor; we bind it 1:1 against the loaded libcairo 1.18.4. Backend-specific ctors and the > =1.16 PDF metadata/outline methods are dlsym-gated: on a feature-stripped > libcairo the symbol resolves to `None` and the method croaks with a > targeted ”built without X support“ message rather than dereferencing null. Deferred (later dedicated pass, census section 5 hard-parts 1 and 4): the stream ctors and `write_to_png_stream` / `create_from_png_stream` need a Perl write/read callback re-entered from inside libcairo through a C trampoline; `set_mime_data` / `get_mime_data` cross an SV lifetime into libcairo. These are registered as croaking stubs so the API surface is present but flags the unimplemented path explicitly. ## Functions ### Other Functions #### `image_surface_create` `Cairo::ImageSurface->create($format, $width, $height)` -> blessed surface. Mirrors cairo_image_surface_create; C_ARGS drops the leading class. The constructor owns +1, so we type-dispatch bless without an extra reference. #### `image_surface_create_for_data` `Cairo::ImageSurface->create_for_data($data, $format, $width, $height, $stride)`. Mirrors cairo_image_surface_create_for_data: the raw bytes are borrowed by cairo (not copied), so the SV must outlive the surface - matching the XS, which passes the SV’s PV pointer straight through. #### `image_get_data` `$image_surface->get_data` -> SV string of height\*stride bytes, or undef. Mirrors the XS which reads height and stride to size the SV. #### `image_get_format` `$image_surface->get_format` -> format nickname (enum-string return). #### `image_create_from_png` `Cairo::ImageSurface->create_from_png($filename)` -> blessed surface. PNG is a build option; the symbol is dlsym-gated (census runtime-env note). #### `surface_destroy` `$surface->DESTROY` -> cairo_surface_destroy, dropping the one reference this wrapper owns (census section 4). #### `surface_status` `$surface->status` -> status nickname (enum-string return). #### `surface_get_type` `$surface->get_type` -> surface-type nickname (enum-string return). #### `surface_get_content` `$surface->get_content` -> content nickname (enum-string return). #### `surface_write_to_png` `$surface->write_to_png($filename)` -> status nickname. PNG is dlsym-gated. #### `surface_create_similar` `create_similar` in its dual class/instance form (CairoSurface.xs L313): Cairo::Surface->create_similar($other, $content, $w, $h) (items==5) $other->create_similar($content, $w, $h) (items==4) The extra leading class shifts the arg offset by one. content is an enum string; the result is a +1 surface blessed type-dispatched. #### `surface_set_device_offset` `$surface->set_device_offset($x, $y)`. #### `surface_get_device_offset` `$surface->get_device_offset` -> ($x_offset, $y_offset) (OUTLIST list). #### `surface_set_fallback_resolution` `$surface->set_fallback_resolution($x_ppi, $y_ppi)`. #### `surface_get_fallback_resolution` `$surface->get_fallback_resolution` -> ($x_ppi, $y_ppi) (OUTLIST list). #### `surface_get_font_options` `$surface->get_font_options` -> blessed Cairo::FontOptions. Mirrors the XS CODE block: allocate a fresh options with cairo_font_options_create, fill it via cairo_surface_get_font_options, then bless the +1 pointer directly (font options are their own object owned by the Font package). #### `surface_mark_dirty_rectangle` `$surface->mark_dirty_rectangle($x, $y, $width, $height)` (four ints). #### `surface_has_show_text_glyphs` `$surface->has_show_text_glyphs` -> bool (0/1). #### `surface_create_for_rectangle` `Cairo::Surface->create_for_rectangle($target, $x, $y, $width, $height)`. Mirrors the XS `class, target, x, y, w, h` with C_ARGS dropping class; the result is a +1 surface blessed type-dispatched. #### `surface_supports_mime_type` `$surface->supports_mime_type($mime_type)` -> bool (0/1). #### `pdf_restrict_to_version` `$pdf->restrict_to_version($version)` (enum string arg). #### `pdf_set_metadata` `$pdf->set_metadata($metadata, $utf8)` (>=1.16). metadata is an enum string. #### `pdf_set_page_label` `$pdf->set_page_label($utf8)` (>=1.16). #### `pdf_set_thumbnail_size` `$pdf->set_thumbnail_size($width, $height)` (>=1.16). #### `pdf_add_outline` `$pdf->add_outline($parent_id, $utf8, $link_attribs, $flags)` -> int (>=1.16). flags is the outline-flags enum as an integer bitmask (not a nickname in the XS - it is a plain int typemap for this method). #### `pdf_outline_root` `Cairo::PdfSurface::OUTLINE_ROOT` -> 0 (CAIRO_PDF_OUTLINE_ROOT constant). #### `ps_dsc_comment` `$ps->dsc_comment($comment)`. #### `ps_restrict_to_level` `$ps->restrict_to_level($level)` (enum string arg). #### `ps_set_eps` `$ps->set_eps($bool)`. #### `ps_get_eps` `$ps->get_eps` -> bool (0/1). #### `svg_restrict_to_version` `$svg->restrict_to_version($version)` (enum string arg). #### `recording_create` `Cairo::RecordingSurface->create($content, $extents_or_undef)`. Mirrors the XS `class, content, cairo_rectangle_t_ornull *extents`: content is an enum string; extents is either an unblessed {x,y,width,height} hashref (a bounded recording surface) or undef/absent (unbounded, NULL rectangle). #### `recording_ink_extents` `$recording->ink_extents` -> ($x0, $y0, $width, $height) (OUTLIST list). #### `recording_get_extents` `$recording->get_extents` -> {x,y,width,height} hashref, or undef when the surface is unbounded. Mirrors the XS: the cairo_bool_t return gates whether the filled rectangle is returned at all. #### `format_stride_for_width` `Cairo::Format::stride_for_width($format, $width)` -> int. Mirrors cairo_format_stride_for_width; format is an enum string. Called as a plain function (not a method), so the format is ST(0). #### `write_to_png_stream` `$surface->write_to_png_stream($closure [, $data])` -> status nickname. One-shot write_func: the closure lives only for the call, so we free it immediately afterwards (no set_user_data). Mirrors CairoSurface.xs cairo_surface_write_to_png_stream. PNG is dlsym-gated. #### `create_from_png_stream` `Cairo::ImageSurface->create_from_png_stream($closure [, $data])` -> blessed surface. read_func ctor; +1 surface blessed type-dispatched. The closure is consumed only during the ctor call, so free it immediately after. PNG gated. #### `set_mime_data` `$surface->set_mime_data($mime_type, $data)` -> status nickname (>=1.10). Mirrors CairoSurface.xs: SvREFCNT_inc the passed $data SV (NOT a copy), hand its raw bytes to cairo, and register data_destroy (SvREFCNT_dec) so cairo owns exactly one reference until it drops the buffer. The SV’s PV must stay valid for the surface’s life, which the retained reference guarantees. #### `get_mime_data` `$surface->get_mime_data($mime_type)` -> SV string, or undef if the surface carries no data for that MIME type (>=1.10). cairo writes an out double- pointer + length; the XS builds newSVpvn(data, length). We return undef when cairo reports a null data pointer (no attached blob) rather than an empty string, since a genuine zero-length blob is indistinguishable and undef is the more useful phenotype for ”absent“.