Points, Rectangles and Regions

Points, Rectangles and Regions — Simple graphical data types

Synopsis


#include <gdk/gdk.h>


            GdkPoint;

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

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

            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

GdkPoint

typedef struct {
  gint x;
  gint y;
} GdkPoint;

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.

GdkRectangle

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

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

GdkRegion

typedef struct _GdkRegion 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

GdkSpan

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

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