Next: , Previous: Transformations, Up: Top


5 Regions

Representing a pixel-aligned area

5.1 Overview

Regions are a simple graphical data type representing an area of integer-aligned rectangles. They are often used on raster surfaces to track areas of interest, such as change or clip areas.

5.2 Usage

— Function: cairo-region-create ⇒  (ret <cairo-region-t >)

Allocates a new empty region object.

ret
A newly allocated <cairo-region-t>. Free with cairo-region-destroy. This function always returns a valid pointer; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with cairo-region-status.

Since 1.10

— Function: cairo-region-copy (original <cairo-region-t>) ⇒  (ret <cairo-region-t >)

Allocates a new region object copying the area from original.

original
a <cairo-region-t>
ret
A newly allocated <cairo-region-t>. Free with cairo-region-destroy. This function always returns a valid pointer; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with cairo-region-status.

Since 1.10

— Function: cairo-region-get-extents (region <cairo-region-t>) (extents <cairo-rectangle-int-t>)

Gets the bounding rectangle of region as a <cairo-rectangle-int-t>

region
a <cairo-region-t>
extents
rectangle into which to store the extents

Since 1.10

— Function: cairo-region-is-empty (region <cairo-region-t>) ⇒  (ret <cairo-bool-t>)

Checks whether region is empty.

region
a <cairo-region-t>
ret
#t’ if region is empty, ‘#f’ if it isn't.

Since 1.10

— Function: cairo-region-contains-point (region <cairo-region-t>) (<int>) (<int>) ⇒  (ret <cairo-bool-t>)

Checks whether (x, y) is contained in region.

region
a <cairo-region-t>
x
the x coordinate of a point
y
the y coordinate of a point
ret
#t’ if (x, y) is contained in region, ‘#f’ if it is not.

Since 1.10

— Function: cairo-region-contains-rectangle (region <cairo-region-t>) (rectangle <cairo-rectangle-int-t>) ⇒  (ret <cairo-region-overlap-t>)

Checks whether rectangle is inside, outside or partially contained in region

region
a <cairo-region-t>
rectangle
a <cairo-rectangle-int-t>
ret
CAIRO_REGION_OVERLAP_IN’ if rectangle is entirely inside region, ‘CAIRO_REGION_OVERLAP_OUT’ if rectangle is entirely outside region, or ‘CAIRO_REGION_OVERLAP_PART’ if rectangle is partially inside and partially outside region.

Since 1.10

— Function: cairo-region-translate (region <cairo-region-t>) (dx <int>) (dy <int>)

Translates region by (dx, dy).

region
a <cairo-region-t>
dx
Amount to translate in the x direction
dy
Amount to translate in the y direction

Since 1.10

— Function: cairo-region-intersect (dst <cairo-region-t>) (other <cairo-region-t>) ⇒  (ret <cairo-status-t>)

Computes the intersection of dst with other and places the result in dst

dst
a <cairo-region-t>
other
another <cairo-region-t>
ret
CAIRO_STATUS_SUCCESS’ or ‘CAIRO_STATUS_NO_MEMORY

Since 1.10

— Function: cairo-region-subtract (dst <cairo-region-t>) (other <cairo-region-t>) ⇒  (ret <cairo-status-t>)

Subtracts other from dst and places the result in dst

dst
a <cairo-region-t>
other
another <cairo-region-t>
ret
CAIRO_STATUS_SUCCESS’ or ‘CAIRO_STATUS_NO_MEMORY

Since 1.10

— Function: cairo-region-union (dst <cairo-region-t>) (other <cairo-region-t>) ⇒  (ret <cairo-status-t>)

Computes the union of dst with other and places the result in dst

dst
a <cairo-region-t>
other
another <cairo-region-t>
ret
CAIRO_STATUS_SUCCESS’ or ‘CAIRO_STATUS_NO_MEMORY

Since 1.10

— Function: cairo-region-xor (dst <cairo-region-t>) (other <cairo-region-t>) ⇒  (ret <cairo-status-t>)

Computes the exclusive difference of dst with other and places the result in dst. That is, dst will be set to contain all areas that are either in dst or in other, but not in both.

dst
a <cairo-region-t>
other
another <cairo-region-t>
ret
CAIRO_STATUS_SUCCESS’ or ‘CAIRO_STATUS_NO_MEMORY

Since 1.10