Cairo: A Vector Graphics Library: Regions

## 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

## Object Hierarchy

## 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 |

#### 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