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>) (x <int>) (y <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