Regions

Regions — Representing a pixel-aligned area

Synopsis

typedef             cairo_region_t;
cairo_region_t *    cairo_region_create                 (void);
cairo_region_t *    cairo_region_create_rectangle       (const cairo_rectangle_int_t *rectangle);
cairo_region_t *    cairo_region_create_rectangles      (const cairo_rectangle_int_t *rects,
                                                         int count);
cairo_region_t *    cairo_region_copy                   (const cairo_region_t *original);
cairo_region_t *    cairo_region_reference              (cairo_region_t *region);
void                cairo_region_destroy                (cairo_region_t *region);
cairo_status_t      cairo_region_status                 (const cairo_region_t *region);
void                cairo_region_get_extents            (const cairo_region_t *region,
                                                         cairo_rectangle_int_t *extents);
int                 cairo_region_num_rectangles         (const cairo_region_t *region);
void                cairo_region_get_rectangle          (const cairo_region_t *region,
                                                         int nth,
                                                         cairo_rectangle_int_t *rectangle);
cairo_bool_t        cairo_region_is_empty               (const cairo_region_t *region);
cairo_bool_t        cairo_region_contains_point         (const cairo_region_t *region,
                                                         int x,
                                                         int y);
enum                cairo_region_overlap_t;
cairo_region_overlap_t  cairo_region_contains_rectangle (const cairo_region_t *region,
                                                         const cairo_rectangle_int_t *rectangle);
cairo_bool_t        cairo_region_equal                  (const cairo_region_t *a,
                                                         const cairo_region_t *b);
void                cairo_region_translate              (cairo_region_t *region,
                                                         int dx,
                                                         int dy);
cairo_status_t      cairo_region_intersect              (cairo_region_t *dst,
                                                         const cairo_region_t *other);
cairo_status_t      cairo_region_intersect_rectangle    (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);
cairo_status_t      cairo_region_subtract               (cairo_region_t *dst,
                                                         const cairo_region_t *other);
cairo_status_t      cairo_region_subtract_rectangle     (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);
cairo_status_t      cairo_region_union                  (cairo_region_t *dst,
                                                         const cairo_region_t *other);
cairo_status_t      cairo_region_union_rectangle        (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);
cairo_status_t      cairo_region_xor                    (cairo_region_t *dst,
                                                         const cairo_region_t *other);
cairo_status_t      cairo_region_xor_rectangle          (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);

Description

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.

Details

cairo_region_t

typedef struct _cairo_region cairo_region_t;

A cairo_region_t represents a set of integer-aligned rectangles.

It allows set-theoretical operations like cairo_region_union() and cairo_region_intersect() to be performed on them.

Memory management of cairo_region_t is done with cairo_region_reference() and cairo_region_destroy().

Since 1.10


cairo_region_create ()

cairo_region_t *    cairo_region_create                 (void);

Allocates a new empty region object.

Returns :

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


cairo_region_create_rectangle ()

cairo_region_t *    cairo_region_create_rectangle       (const cairo_rectangle_int_t *rectangle);

Allocates a new region object containing rectangle.

rectangle :

a cairo_rectangle_int_t

Returns :

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


cairo_region_create_rectangles ()

cairo_region_t *    cairo_region_create_rectangles      (const cairo_rectangle_int_t *rects,
                                                         int count);

Allocates a new region object containing the union of all given rects.

rects :

an array of count rectangles

count :

number of rectangles

Returns :

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


cairo_region_copy ()

cairo_region_t *    cairo_region_copy                   (const cairo_region_t *original);

Allocates a new region object copying the area from original.

original :

a cairo_region_t

Returns :

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


cairo_region_reference ()

cairo_region_t *    cairo_region_reference              (cairo_region_t *region);

Increases the reference count on region by one. This prevents region from being destroyed until a matching call to cairo_region_destroy() is made.

region :

a cairo_region_t

Returns :

the referenced cairo_region_t.

Since 1.10


cairo_region_destroy ()

void                cairo_region_destroy                (cairo_region_t *region);

Destroys a cairo_region_t object created with cairo_region_create(), cairo_region_copy(), or or cairo_region_create_rectangle().

region :

a cairo_region_t

Since 1.10


cairo_region_status ()

cairo_status_t      cairo_region_status                 (const cairo_region_t *region);

Checks whether an error has previous occured for this region object.

Since 1.10


cairo_region_get_extents ()

void                cairo_region_get_extents            (const cairo_region_t *region,
                                                         cairo_rectangle_int_t *extents);

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


cairo_region_num_rectangles ()

int                 cairo_region_num_rectangles         (const cairo_region_t *region);

Returns the number of rectangles contained in region.

region :

a cairo_region_t

Returns :

The number of rectangles contained in region.

Since 1.10


cairo_region_get_rectangle ()

void                cairo_region_get_rectangle          (const cairo_region_t *region,
                                                         int nth,
                                                         cairo_rectangle_int_t *rectangle);

Stores the nth rectangle from the region in rectangle.

region :

a cairo_region_t

nth :

a number indicating which rectangle should be returned

rectangle :

return location for a cairo_rectangle_int_t

Since 1.10


cairo_region_is_empty ()

cairo_bool_t        cairo_region_is_empty               (const cairo_region_t *region);

Checks whether region is empty.

region :

a cairo_region_t

Returns :

TRUE if region is empty, FALSE if it isn't.

Since 1.10


cairo_region_contains_point ()

cairo_bool_t        cairo_region_contains_point         (const cairo_region_t *region,
                                                         int x,
                                                         int y);

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

Returns :

TRUE if (x, y) is contained in region, FALSE if it is not.

Since 1.10


enum cairo_region_overlap_t

typedef enum _cairo_region_overlap {
    CAIRO_REGION_OVERLAP_IN,		/* completely inside region */
    CAIRO_REGION_OVERLAP_OUT,		/* completely outside region */
    CAIRO_REGION_OVERLAP_PART		/* partly inside region */
} cairo_region_overlap_t;

Used as the return value for cairo_region_contains_rectangle().

CAIRO_REGION_OVERLAP_IN

The contents are entirely inside the region

CAIRO_REGION_OVERLAP_OUT

The contents are entirely outside the region

CAIRO_REGION_OVERLAP_PART

The contents are partially inside and partially outside the region.

cairo_region_contains_rectangle ()

cairo_region_overlap_t  cairo_region_contains_rectangle (const cairo_region_t *region,
                                                         const cairo_rectangle_int_t *rectangle);

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

region :

a cairo_region_t

rectangle :

a cairo_rectangle_int_t

Returns :

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


cairo_region_equal ()

cairo_bool_t        cairo_region_equal                  (const cairo_region_t *a,
                                                         const cairo_region_t *b);

Compares whether region_a is equivalent to region_b. NULL as an argument is equal to itself, but not to any non-NULL region.

a :

a cairo_region_t or NULL

b :

a cairo_region_t or NULL

Returns :

TRUE if both regions contained the same coverage, FALSE if it is not or any region is in an error status.

Since 1.10


cairo_region_translate ()

void                cairo_region_translate              (cairo_region_t *region,
                                                         int dx,
                                                         int dy);

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


cairo_region_intersect ()

cairo_status_t      cairo_region_intersect              (cairo_region_t *dst,
                                                         const cairo_region_t *other);

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

Since 1.10


cairo_region_intersect_rectangle ()

cairo_status_t      cairo_region_intersect_rectangle    (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);

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

Since 1.10


cairo_region_subtract ()

cairo_status_t      cairo_region_subtract               (cairo_region_t *dst,
                                                         const cairo_region_t *other);

Subtracts other from dst and places the result in dst

Since 1.10


cairo_region_subtract_rectangle ()

cairo_status_t      cairo_region_subtract_rectangle     (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);

Subtracts rectangle from dst and places the result in dst

Since 1.10


cairo_region_union ()

cairo_status_t      cairo_region_union                  (cairo_region_t *dst,
                                                         const cairo_region_t *other);

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

Since 1.10


cairo_region_union_rectangle ()

cairo_status_t      cairo_region_union_rectangle        (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);

Computes the union of dst with rectangle and places the result in dst.

Since 1.10


cairo_region_xor ()

cairo_status_t      cairo_region_xor                    (cairo_region_t *dst,
                                                         const cairo_region_t *other);

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.

Since 1.10


cairo_region_xor_rectangle ()

cairo_status_t      cairo_region_xor_rectangle          (cairo_region_t *dst,
                                                         const cairo_rectangle_int_t *rectangle);

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

Since 1.10