GDK Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Points, Rectangles and Regions

## Name

Points, Rectangles and Regions -- simple graphical data types.

## Synopsis

    #include <gdk/gdk.h>

    struct      GdkPoint;

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

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

    void        gdk_region_get_clipbox          (GdkRegion *region,
                                                 GdkRectangle *rectangle);
    void        gdk_region_get_rectangles       (GdkRegion *region,
                                                 GdkRectangle **rectangles,
                                                 gint *n_rectangles);
    gboolean    gdk_region_empty                (GdkRegion *region);
    gboolean    gdk_region_equal                (GdkRegion *region1,
                                                 GdkRegion *region2);
    gboolean    gdk_region_point_in             (GdkRegion *region,
                                                 int x,
                                                 int y);
    GdkOverlapType gdk_region_rect_in           (GdkRegion *region,
                                                 GdkRectangle *rect);
    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,
                                                 GdkRectangle *rect);
    void        gdk_region_intersect            (GdkRegion *source1,
                                                 GdkRegion *source2);
    void        gdk_region_union                (GdkRegion *source1,
                                                 GdkRegion *source2);
    void        gdk_region_subtract             (GdkRegion *source1,
                                                 GdkRegion *source2);
    void        gdk_region_xor                  (GdkRegion *source1,
                                                 GdkRegion *source2);

    struct      GdkSpan;
    void        (*GdkSpanFunc)                  (GdkSpan *span,
                                                 gpointer data);
    void        gdk_region_spans_intersect_foreach
                                                (GdkRegion *region,
                                                 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         (GdkRectangle *src1,
                                                 GdkRectangle *src2,
                                                 GdkRectangle *dest);

Calculates the intersection of two rectangles.

`src1` : | a GdkRectangle.
`src2` : | a GdkRectangle.
`dest` : | the intersection of `src1` and `src2`.
Returns : | `TRUE` if the rectangles intersect.

### gdk_rectangle_union ()

    void        gdk_rectangle_union             (GdkRectangle *src1,
                                                 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.

`src1` : | a GdkRectangle.
`src2` : | a GdkRectangle.
`dest` : | the union of `src1` and `src2`.

### struct GdkRegion

    struct GdkRegion;

A GdkRegion represents a set of pixels on the screen. The only user-visible field of the structure is the user_data member, which can be used to attach arbitrary data to the GdkRegion.

### 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              (GdkPoint *points,
                                                 gint npoints,
                                                 GdkFillRule fill_rule);

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

`points` : | an array of GdkPoint structs.
`npoints` : | 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;

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                 (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            (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          (GdkRegion *region,
                                                 GdkRectangle *rectangle);

Returns the smallest rectangle which includes the entire GdkRegion.

`region` : | a GdkRegion.
`rectangle` : | returns the smallest rectangle which includes all of `region`.

### gdk_region_get_rectangles ()

    void        gdk_region_get_rectangles       (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
`n_rectangles` : | length of returned array

### gdk_region_empty ()

    gboolean    gdk_region_empty                (GdkRegion *region);

Returns `TRUE` if the GdkRegion is empty.

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

### gdk_region_equal ()

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

Returns `TRUE` if the two regions are the same.

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

### gdk_region_point_in ()

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

Returns `TRUE` 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           (GdkRegion *region,
                                                 GdkRectangle *rect);

Tests whether a rectangle is within a region.

`region` : | a GdkRegion.
`rect` : | 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);

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

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,
                                                 GdkSpan *spans,
                                                 int n_spans,
                                                 gboolean sorted,
                                                 GdkSpanFunc function,
                                                 gpointer data);

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

<<< Previous Page | Home | Up | Next Page >>>
GdkScreen | Graphics Contexts