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

`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

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

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

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

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

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

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

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

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

`dst` : | a cairo_region_t
`rectangle` : | a cairo_rectangle_int_t
Returns : | `CAIRO_STATUS_SUCCESS` or `CAIRO_STATUS_NO_MEMORY`

Since 1.10