# 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 `int`s `{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).