Peta::FFI::Cairo::Region#

📦 std

Cairo::Region package plug-in.

A region (cairo_region_t) is a set of integer-aligned rectangles. The ENTIRE Region API is cairo >= 1.10 (CairoRegion.xs is guarded by CAIRO_VERSION >= 1.10), so every method here is dlsym-gated: if cairo_region_create is absent the constructor croaks with a version hint. The system cairo (1.18.4) has all of it, so on this host every symbol resolves.

This module owns the region cairo symbols, resolving them itself via super::cairo_dlsym over the shared handle so the foundation’s symbol table never carries region entries.

Refcount contract (census section 4): a region is a cairo-refcounted object. cairo_region_create* all return +1, so create blesses the pointer directly into Cairo::Region; DESTROY drops exactly one reference via cairo_region_destroy.

rectangle_int hashref convention (Cairo.xs newSVCairoRectangleInt /#

SvCairoRectangleInt)

cairo_rectangle_int_t is four C ints {x, y, width, height}. On the Perl side it is a plain (unblessed) hashref with exactly those keys, whose values are INTEGERS (newSViv, not newSVnv). super::nv_hashref builds float hashrefs (extents/rectangle), so it does NOT fit here; we use a local iv_hashref helper (newHV + hv_store of newSViv) for the int case. Reading a rectangle mirrors SvCairoRectangleInt: the struct is zeroed, then each of the four keys is read with SvIV only if present and defined (alloc_temp gives a zeroed struct, so unset/undef keys stay 0).

Functions#

Other Functions#

region_create#

Cairo::Region->create(...). Variadic ctor dispatching on arg count, mirroring CairoRegion.xs cairo_region_create(class, ...): items == 1 (class only) -> cairo_region_create() items == 2 -> cairo_region_create_rectangle($rect) items > 2 -> cairo_region_create_rectangles(@rects) All three cairo ctors return +1, so we bless the pointer directly.

region_destroy#

$region->DESTROY -> cairo_region_destroy, dropping the one reference.

region_status#

$region->status -> status nickname (enum-string return).

region_get_extents#

$region->get_extents -> {x,y,width,height} hashref. Mirrors the XS PREINIT rect + cairo_region_get_extents(region, &rect) -> RETVAL.

region_num_rectangles#

$region->num_rectangles -> int.

region_get_rectangle#

$region->get_rectangle($nth) -> {x,y,width,height} hashref.

region_is_empty#

$region->is_empty -> bool. cairo_bool_t is an int (0/1) surfaced as T_UV.

region_contains_point#

$region->contains_point($x, $y) -> bool.

region_contains_rectangle#

$region->contains_rectangle($rect) -> overlap nickname (in/out/part).

region_equal#

$region->equal($other) -> bool.

region_translate#

$region->translate($dx, $dy) (void).