Regions: Cairo: A Vector Graphics Library

+ + +

Regions

Regions — Representing a pixel-aligned area

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+cairo_region_t * +	+cairo_region_create () +
+cairo_region_t * +	+cairo_region_create_rectangle () +
+cairo_region_t * +	+cairo_region_create_rectangles () +
+cairo_region_t * +	+cairo_region_copy () +
+cairo_region_t * +	+cairo_region_reference () +
+void +	+cairo_region_destroy () +
+cairo_status_t +	+cairo_region_status () +
+void +	+cairo_region_get_extents () +
+int +	+cairo_region_num_rectangles () +
+void +	+cairo_region_get_rectangle () +
+cairo_bool_t +	+cairo_region_is_empty () +
+cairo_bool_t +	+cairo_region_contains_point () +
+cairo_region_overlap_t +	+cairo_region_contains_rectangle () +
+cairo_bool_t +	+cairo_region_equal () +
+void +	+cairo_region_translate () +
+cairo_status_t +	+cairo_region_intersect () +
+cairo_status_t +	+cairo_region_intersect_rectangle () +
+cairo_status_t +	+cairo_region_subtract () +
+cairo_status_t +	+cairo_region_subtract_rectangle () +
+cairo_status_t +	+cairo_region_union () +
+cairo_status_t +	+cairo_region_union_rectangle () +
+cairo_status_t +	+cairo_region_xor () +
+cairo_status_t +	+cairo_region_xor_rectangle () +

Types and Values

++++ + + + + + + + + + + +

typedef	cairo_region_t
enum	cairo_region_overlap_t

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.

Functions

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 +.

Parameters

+++++ + + + + + +

rectangle

a cairo_rectangle_int_t

Returns

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 +.

Parameters

+++++ + + + + + + + + + + + + +

rects	an array of `count` +rectangles
count	number of rectangles

Returns

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 +.

Parameters

+++++ + + + + + +

original

a cairo_region_t

Returns

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.

Parameters

+++++ + + + + + +

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().

Parameters

+++++ + + + + + +

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 occurred for this +region object.

Parameters

+++++ + + + + + +

region

a cairo_region_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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

Parameters

+++++ + + + + + + + + + + + + +

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 +.

Parameters

+++++ + + + + + +

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 +.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

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.

Parameters

+++++ + + + + + +

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 +.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

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

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 +

Parameters

+++++ + + + + + + + + + + + + +

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.

Parameters

+++++ + + + + + + + + + + + + +

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 +).

Parameters

+++++ + + + + + + + + + + + + + + + + + +

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 +

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
other	another cairo_region_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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 +

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
rectangle	a cairo_rectangle_int_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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 +

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
other	another cairo_region_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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 +

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
rectangle	a cairo_rectangle_int_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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 +

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
other	another cairo_region_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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 +.

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
rectangle	a cairo_rectangle_int_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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.

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
other	another cairo_region_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

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.

Parameters

+++++ + + + + + + + + + + + + +

dst	a cairo_region_t
rectangle	a cairo_rectangle_int_t

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

Since: 1.10

Types and Values

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

enum cairo_region_overlap_t

Used as the return value for cairo_region_contains_rectangle().

Members

+++++ + + + + + + + + + + + + + + + + + +

CAIRO_REGION_OVERLAP_IN	+ The contents are entirely inside the region. (Since 1.10) +
CAIRO_REGION_OVERLAP_OUT	+ The contents are entirely outside the region. (Since 1.10) +
CAIRO_REGION_OVERLAP_PART	+ The contents are partially inside and + partially outside the region. (Since 1.10) +

Since: 1.10