Regions

Regions — Representing a pixel-aligned area

Functions

Types and Values

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

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 .

Parameters

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 .

Parameters

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.

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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