Points, Rectangles and Regions

Points, Rectangles and Regions — Simple graphical data types

Synopsis


#include <gdk/gdk.h>

                    GdkPoint;

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

                    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

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

GdkRegion

typedef struct _GdkRegion GdkRegion;

A GdkRegion represents a set of pixels on the screen.

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

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;

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

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

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

			GDK Reference Manual
Top \| Description