Points, Rectangles and Regions: GDK 2 Reference Manual

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

## Functions

gboolean | gdk_rectangle_intersect ()
void | gdk_rectangle_union ()
GdkRegion * | gdk_region_new ()
GdkRegion * | gdk_region_polygon ()
GdkRegion * | gdk_region_copy ()
GdkRegion * | gdk_region_rectangle ()
void | gdk_region_destroy ()
void | gdk_region_get_clipbox ()
void | gdk_region_get_rectangles ()
gboolean | gdk_region_empty ()
gboolean | gdk_region_equal ()
gboolean | gdk_region_rect_equal ()
gboolean | gdk_region_point_in ()
GdkOverlapType | gdk_region_rect_in ()
void | gdk_region_offset ()
void | gdk_region_shrink ()
void | gdk_region_union_with_rect ()
void | gdk_region_intersect ()
void | gdk_region_union ()
void | gdk_region_subtract ()
void | gdk_region_xor ()
void | (*GdkSpanFunc) ()
void | gdk_region_spans_intersect_foreach ()

## Types and Values

struct | GdkPoint
struct | GdkRectangle
| GdkRegion
enum | GdkFillRule
enum | GdkOverlapType
struct | GdkSpan

## Includes

    #include <gdk/gdk.h>

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

## Functions

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

#### Parameters

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

#### Parameters

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

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

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

#### Parameters

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

### gdk_region_copy ()

    GdkRegion *
    gdk_region_copy (const GdkRegion *region);

Copies `region` , creating an identical new region.

#### Parameters

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

#### Parameters

rectangle | a GdkRectangle |

#### Returns

a new region

### gdk_region_destroy ()

    void
    gdk_region_destroy (GdkRegion *region);

Destroys a GdkRegion.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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);

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

### gdk_region_offset ()

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

Moves a region the specified distance.

#### Parameters

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);

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

source1 | a GdkRegion |
source2 | another GdkRegion |

### GdkSpanFunc ()

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

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

#### Parameters

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);

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

#### Parameters

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

## Types and Values

### struct GdkPoint

    struct GdkPoint {
      gint x;
      gint y;
    };

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

Defines the x and y coordinates of a point.

#### Members

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.

#### Members

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

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

### enum GdkFillRule

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

#### Members

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

### enum GdkOverlapType

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

#### Members

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

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

#### Members

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