```{index} single: Cairo::Region ``` # Cairo::Region ```{pperl-module-badges} Cairo::Region ``` `Cairo::Region` - a set of integer-aligned rectangles. Regions describe pixel-aligned areas: build one from rectangles, combine it with another using `intersect`, `union`, `subtract` or `xor`, move it with `translate`, and ask whether a point or a rectangle falls inside it. A region owns its cairo object and releases it when Perl destroys the Perl object, so nothing has to be freed by hand. ## Requires cairo >= 1.10 The region API arrived in cairo 1.10. If the installed libcairo is older, every method here croaks with `Cairo::Region requires cairo >= 1.10` when it is called. ## Rectangles are plain hashrefs Everywhere a rectangle is passed in or handed back it is an unblessed hashref with exactly the keys `x`, `y`, `width` and `height`, and the values are **integers** - a region is pixel-aligned, so there are no fractional coordinates. In a rectangle you pass in, a missing key or an `undef` value counts as 0; an argument that is not a hash reference croaks with `cairo_rectangle_int_t must be a hash reference`. ## Functions ### Other Functions #### [`create`](Region/create) Creates a region, dispatching on how many rectangles you pass: #### `status` Returns the region's error status as a nickname string, `success` when the region is usable. #### `get_extents` Returns the smallest rectangle containing the whole region, as a hashref `{x, y, width, height}`. #### `num_rectangles` Returns how many rectangles the region is made of. #### `get_rectangle` Returns the `$nth` rectangle of the region (counting from 0) as a hashref `{x, y, width, height}`. #### `is_empty` Returns true if the region covers nothing at all. #### `contains_point` Returns true if the integer point `($x, $y)` lies inside the region. #### `contains_rectangle` Reports how `$rect` sits relative to the region, as a nickname string: `in` when the rectangle is entirely inside, `out` when it is entirely outside, `part` when it is partly in. #### `equal` Returns true if `$region` and `$other` cover exactly the same area. #### `translate` Moves the region by the integer offset `($dx, $dy)`, in place. Returns nothing. ```{toctree} :hidden: :maxdepth: 1 Region/create ```