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_RULEareas 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_RULEoverlapping 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_INif the rectangle is inside the GdkRegion.
GDK_OVERLAP_RECTANGLE_OUTif the rectangle is outside the GdkRegion.
GDK_OVERLAP_RECTANGLE_PARTif 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.