Points, Rectangles and Regions

## Points, Rectangles and Regions Points, Rectangles and Regions — Simple graphical data types |

## Synopsis

    #include <gdk/gdk.h>

    struct              GdkPoint;

    struct              GdkRectangle;
    gboolean            gdk_rectangle_intersect             (const GdkRectangle *src1,
                                                             const GdkRectangle *src2,
                                                             GdkRectangle *dest);
    void                gdk_rectangle_union                 (const GdkRectangle *src1,
                                                             const GdkRectangle *src2,
                                                             GdkRectangle *dest);

                        GdkRegion;
    GdkRegion *         gdk_region_new                      (void);
    GdkRegion *         gdk_region_polygon                  (const GdkPoint *points,
                                                             gint n_points,
                                                             GdkFillRule fill_rule);
    enum                GdkFillRule;
    GdkRegion *         gdk_region_copy                     (const GdkRegion *region);
    GdkRegion *         gdk_region_rectangle                (const GdkRectangle *rectangle);
    void                gdk_region_destroy                  (GdkRegion *region);

    void                gdk_region_get_clipbox              (const GdkRegion *region,
                                                             GdkRectangle *rectangle);
    void                gdk_region_get_rectangles           (const GdkRegion *region,
                                                             GdkRectangle **rectangles,
                                                             gint *n_rectangles);
    gboolean            gdk_region_empty                    (const GdkRegion *region);
    gboolean            gdk_region_equal                    (const GdkRegion *region1,
                                                             const GdkRegion *region2);
    gboolean            gdk_region_rect_equal               (const GdkRegion *region,
                                                             const GdkRectangle *rectangle);
    gboolean            gdk_region_point_in                 (const GdkRegion *region,
                                                             int x,
                                                             int y);
    GdkOverlapType      gdk_region_rect_in                  (const GdkRegion *region,
                                                             const GdkRectangle *rectangle);
    enum                GdkOverlapType;

    void                gdk_region_offset                   (GdkRegion *region,
                                                             gint dx,
                                                             gint dy);
    void                gdk_region_shrink                   (GdkRegion *region,
                                                             gint dx,
                                                             gint dy);
    void                gdk_region_union_with_rect          (GdkRegion *region,
                                                             const GdkRectangle *rect);
    void                gdk_region_intersect                (GdkRegion *source1,
                                                             const GdkRegion *source2);
    void                gdk_region_union                    (GdkRegion *source1,
                                                             const GdkRegion *source2);
    void                gdk_region_subtract                 (GdkRegion *source1,
                                                             const GdkRegion *source2);
    void                gdk_region_xor                      (GdkRegion *source1,
                                                             const GdkRegion *source2);

    struct              GdkSpan;
    void                (*GdkSpanFunc)                      (GdkSpan *span,
                                                             gpointer data);
    void                gdk_region_spans_intersect_foreach  (GdkRegion *region,
                                                             const GdkSpan *spans,
                                                             int n_spans,
                                                             gboolean sorted,
                                                             GdkSpanFunc function,
                                                             gpointer data);

## Description

GDK provides the GdkPoint, GdkRectangle, GdkRegion and GdkSpan data types for representing pixels and sets of pixels on the screen.

GdkPoint is a simple structure containing an x and y coordinate of a point.

GdkRectangle is a structure holding the position and size of a rectangle. The intersection of two rectangles can be computed with `gdk_rectangle_intersect()`. To find the union of two rectangles use `gdk_rectangle_union()`.

GdkRegion is an opaque data type holding a set of arbitrary pixels, and is usually used for clipping graphical operations (see `gdk_gc_set_clip_region()`).

GdkSpan is a structure holding a spanline. A spanline is a horizontal line that is one pixel wide. It is mainly used when rasterizing other graphics primitives. It can be intersected to regions by using `gdk_region_spans_intersect_foreach()`.

## Details

### struct GdkPoint

    struct GdkPoint {
      gint x;
      gint y;
    };

Defines the x and y coordinates of a point.

gint `x`; | the x coordinate of the point.
gint `y`; | the y coordinate of the point.

### struct GdkRectangle

    struct GdkRectangle {
      gint x;
      gint y;
      gint width;
      gint height;
    };

Defines the position and size of a rectangle.

gint `x`; | the x coordinate of the left edge of the rectangle.
gint `y`; | the y coordinate of the top of the rectangle.
gint `width`; | the width of the rectangle.
gint `height`; | the height of the rectangle.

### gdk_rectangle_intersect ()

    gboolean            gdk_rectangle_intersect             (const GdkRectangle *src1,
                                                             const GdkRectangle *src2,
                                                             GdkRectangle *dest);

Calculates the intersection of two rectangles. It is allowed for `dest` to be the same as either `src1` or `src2`. If the rectangles do not intersect, `dest`'s width and height is set to 0 and its x and y values are undefined. If you are only interested in whether the rectangles intersect, but not in the intersecting area itself, pass `NULL` for `dest`.

`src1` : | a GdkRectangle
`src2` : | a GdkRectangle
`dest` : | return location for the intersection of `src1` and `src2`, or `NULL`. [out caller-allocates][allow-none]
Returns : | `TRUE` if the rectangles intersect.

### gdk_rectangle_union ()

    void                gdk_rectangle_union                 (const GdkRectangle *src1,
                                                             const GdkRectangle *src2,
                                                             GdkRectangle *dest);

Calculates the union of two rectangles. The union of rectangles `src1` and `src2` is the smallest rectangle which includes both `src1` and `src2` within it. It is allowed for `dest` to be the same as either `src1` or `src2`.

`src1` : | a GdkRectangle
`src2` : | a GdkRectangle
`dest` : | return location for the union of `src1` and `src2`. [out]

### GdkRegion

    typedef struct _GdkRegion GdkRegion;

A GdkRegion represents a set of pixels on the screen.

In GTK3, GdkRegion will be replaced by cairo_region_t. All the functions listed in this section will go away and you will have to use the relevant Cairo functions. The conversion can be done using simple serch and replace.

### gdk_region_new ()

    GdkRegion *         gdk_region_new                      (void);

Creates a new empty GdkRegion.

Returns : | a new empty GdkRegion

### gdk_region_polygon ()

    GdkRegion *         gdk_region_polygon                  (const GdkPoint *points,
                                                             gint n_points,
                                                             GdkFillRule fill_rule);

### Warning

`gdk_region_polygon` has been deprecated since version 2.22 and should not be used in newly-written code. There is no replacement. For working with paths, please use Cairo.

Creates a new GdkRegion using the polygon defined by a number of points.

`points` : | an array of GdkPoint structs
`n_points` : | the number of elements in the `points` array
`fill_rule` : | specifies which pixels are included in the region when the polygon overlaps itself.
Returns : | a new GdkRegion based on the given polygon

### enum GdkFillRule

    typedef enum {
      GDK_EVEN_ODD_RULE,
      GDK_WINDING_RULE
    } GdkFillRule;

### Warning

`GdkFillRule` is deprecated and should not be used in newly-written code.

The method for determining which pixels are included in a region, when creating a GdkRegion from a polygon. The fill rule is only relevant for polygons which overlap themselves.

`GDK_EVEN_ODD_RULE` | areas which are overlapped an odd number of times are included in the region, while areas overlapped an even number of times are not.
`GDK_WINDING_RULE` | overlapping areas are always included.

### gdk_region_copy ()

    GdkRegion *         gdk_region_copy                     (const GdkRegion *region);

Copies `region`, creating an identical new region.

`region` : | a GdkRegion
Returns : | a new region identical to `region`

### gdk_region_rectangle ()

    GdkRegion *         gdk_region_rectangle                (const GdkRectangle *rectangle);

Creates a new region containing the area `rectangle`.

`rectangle` : | a GdkRectangle
Returns : | a new region

### gdk_region_destroy ()

    void                gdk_region_destroy                  (GdkRegion *region);

Destroys a GdkRegion.

`region` : | a GdkRegion

### gdk_region_get_clipbox ()

    void                gdk_region_get_clipbox              (const GdkRegion *region,
                                                             GdkRectangle *rectangle);

Obtains the smallest rectangle which includes the entire GdkRegion.

`region` : | a GdkRegion
`rectangle` : | return location for the clipbox

### gdk_region_get_rectangles ()

    void                gdk_region_get_rectangles           (const GdkRegion *region,
                                                             GdkRectangle **rectangles,
                                                             gint *n_rectangles);

Obtains the area covered by the region as a list of rectangles. The array returned in `rectangles` must be freed with `g_free()`.

`region` : | a GdkRegion
`rectangles` : | return location for an array of rectangles. [array length=n_rectangles][transfer container]
`n_rectangles` : | length of returned array

### gdk_region_empty ()

    gboolean            gdk_region_empty                    (const GdkRegion *region);

Finds out if the GdkRegion is empty.

`region` : | a GdkRegion
Returns : | `TRUE` if `region` is empty.

### gdk_region_equal ()

    gboolean            gdk_region_equal                    (const GdkRegion *region1,
                                                             const GdkRegion *region2);

Finds out if the two regions are the same.

`region1` : | a GdkRegion
`region2` : | a GdkRegion
Returns : | `TRUE` if `region1` and `region2` are equal.

### gdk_region_rect_equal ()

    gboolean            gdk_region_rect_equal               (const GdkRegion *region,
                                                             const GdkRectangle *rectangle);

### Warning

`gdk_region_rect_equal` has been deprecated since version 2.22 and should not be used in newly-written code. Use `gdk_region_new_rect()` and `gdk_region_equal()` to achieve the same effect.

Finds out if a regions is the same as a rectangle.

`region` : | a GdkRegion
`rectangle` : | a GdkRectangle
Returns : | `TRUE` if `region` and `rectangle` are equal.

Since 2.18

### gdk_region_point_in ()

    gboolean            gdk_region_point_in                 (const GdkRegion *region,
                                                             int x,
                                                             int y);

Finds out if a point is in a region.

`region` : | a GdkRegion
`x` : | the x coordinate of a point
`y` : | the y coordinate of a point
Returns : | `TRUE` if the point is in `region`.

### gdk_region_rect_in ()

    GdkOverlapType      gdk_region_rect_in                  (const GdkRegion *region,
                                                             const GdkRectangle *rectangle);

Tests whether a rectangle is within a region.

`region` : | a GdkRegion.
`rectangle` : | a GdkRectangle.
Returns : | `GDK_OVERLAP_RECTANGLE_IN`, `GDK_OVERLAP_RECTANGLE_OUT`, or `GDK_OVERLAP_RECTANGLE_PART`, depending on whether the rectangle is inside, outside, or partly inside the GdkRegion, respectively.

### enum GdkOverlapType

    typedef enum {
      GDK_OVERLAP_RECTANGLE_IN,
      GDK_OVERLAP_RECTANGLE_OUT,
      GDK_OVERLAP_RECTANGLE_PART
    } GdkOverlapType;

Specifies the possible values returned by `gdk_region_rect_in()`.

`GDK_OVERLAP_RECTANGLE_IN` | if the rectangle is inside the GdkRegion.
`GDK_OVERLAP_RECTANGLE_OUT` | if the rectangle is outside the GdkRegion.
`GDK_OVERLAP_RECTANGLE_PART` | if the rectangle is partly inside the GdkRegion.

### gdk_region_offset ()

    void                gdk_region_offset                   (GdkRegion *region,
                                                             gint dx,
                                                             gint dy);

Moves a region the specified distance.

`region` : | a GdkRegion
`dx` : | the distance to move the region horizontally
`dy` : | the distance to move the region vertically

### gdk_region_shrink ()

    void                gdk_region_shrink                   (GdkRegion *region,
                                                             gint dx,
                                                             gint dy);

### Warning

`gdk_region_shrink` has been deprecated since version 2.22 and should not be used in newly-written code. There is no replacement for this function.

Resizes a region by the specified amount. Positive values shrink the region. Negative values expand it.

`region` : | a GdkRegion
`dx` : | the number of pixels to shrink the region horizontally
`dy` : | the number of pixels to shrink the region vertically

### gdk_region_union_with_rect ()

    void                gdk_region_union_with_rect          (GdkRegion *region,
                                                             const GdkRectangle *rect);

Sets the area of `region` to the union of the areas of `region` and `rect`. The resulting area is the set of pixels contained in either `region` or `rect`.

`region` : | a GdkRegion.
`rect` : | a GdkRectangle.

### gdk_region_intersect ()

    void                gdk_region_intersect                (GdkRegion *source1,
                                                             const GdkRegion *source2);

Sets the area of `source1` to the intersection of the areas of `source1` and `source2`. The resulting area is the set of pixels contained in both `source1` and `source2`.

`source1` : | a GdkRegion
`source2` : | another GdkRegion

### gdk_region_union ()

    void                gdk_region_union                    (GdkRegion *source1,
                                                             const GdkRegion *source2);

Sets the area of `source1` to the union of the areas of `source1` and `source2`. The resulting area is the set of pixels contained in either `source1` or `source2`.

`source1` : | a GdkRegion
`source2` : | a GdkRegion

### gdk_region_subtract ()

    void                gdk_region_subtract                 (GdkRegion *source1,
                                                             const GdkRegion *source2);

Subtracts the area of `source2` from the area `source1`. The resulting area is the set of pixels contained in `source1` but not in `source2`.

`source1` : | a GdkRegion
`source2` : | another GdkRegion

### gdk_region_xor ()

    void                gdk_region_xor                      (GdkRegion *source1,
                                                             const GdkRegion *source2);

Sets the area of `source1` to the exclusive-OR of the areas of `source1` and `source2`. The resulting area is the set of pixels contained in one or the other of the two sources but not in both.

`source1` : | a GdkRegion
`source2` : | another GdkRegion

### struct GdkSpan

    struct GdkSpan {
      gint x;
      gint y;
      gint width;
    };

A GdkSpan represents a horizontal line of pixels starting at the pixel with coordinates `x`, `y` and ending before `x` + `width`, `y`.

gint `x`; | x coordinate of the first pixel.
gint `y`; | y coordinate of the first pixel.
gint `width`; | number of pixels in the span.

### GdkSpanFunc ()

    void                (*GdkSpanFunc)                      (GdkSpan *span,
                                                             gpointer data);

### Warning

`GdkSpanFunc` is deprecated and should not be used in newly-written code.

This defines the type of the function passed to `gdk_region_spans_intersect_foreach()`.

`span` : | a GdkSpan.
`data` : | the user data passed to `gdk_region_spans_intersect_foreach()`.

### gdk_region_spans_intersect_foreach ()

    void                gdk_region_spans_intersect_foreach  (GdkRegion *region,
                                                             const GdkSpan *spans,
                                                             int n_spans,
                                                             gboolean sorted,
                                                             GdkSpanFunc function,
                                                             gpointer data);

### Warning

`gdk_region_spans_intersect_foreach` has been deprecated since version 2.22 and should not be used in newly-written code. There is no replacement.

Calls a function on each span in the intersection of `region` and `spans`.

`region` : | a GdkRegion
`spans` : | an array of GdkSpans
`n_spans` : | the length of `spans`
`sorted` : | `TRUE` if `spans` is sorted wrt. the y coordinate
`function` : | function to call on each span in the intersection
`data` : | data to pass to `function`