Points, Rectangles and Regions

Name

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

Synopsis


#include <gdk/gdk.h>


struct      GdkPoint;

struct      GdkRectangle;
gint        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;
void        gdk_region_destroy              (GdkRegion *region);

GdkRegion*  gdk_regions_intersect           (GdkRegion *source1,
                                             GdkRegion *source2);
GdkRegion*  gdk_regions_union               (GdkRegion *source1,
                                             GdkRegion *source2);
GdkRegion*  gdk_regions_subtract            (GdkRegion *source1,
                                             GdkRegion *source2);
GdkRegion*  gdk_regions_xor                 (GdkRegion *source1,
                                             GdkRegion *source2);
GdkRegion*  gdk_region_union_with_rect      (GdkRegion *region,
                                             GdkRectangle *rect);
void        gdk_region_offset               (GdkRegion *region,
                                             gint dx,
                                             gint dy);
void        gdk_region_shrink               (GdkRegion *region,
                                             gint dx,
                                             gint dy);

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

Description

GDK provides the GdkPoint, GdkRectangle and GdkRegion 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()).

Details

struct GdkPoint

struct GdkPoint
{
  gint16 x;
  gint16 y;
};

Defines the x and y coordinates of a point. Note that both are defined as gint16 values, so the coordinates are limited to between -32,768 and 32,767.

gint16 xthe x coordinate of the point.
gint16 ythe y coordinate of the point.


struct GdkRectangle

struct GdkRectangle
{
  gint16 x;
  gint16 y;
  guint16 width;
  guint16 height;
};

Defines the position and size of a rectangle.

gint16 xthe x coordinate of the left edge of the rectangle.
gint16 ythe y coordinate of the top of the rectangle.
guint16 widththe width of the rectangle.
guint16 heightthe height of the rectangle.


gdk_rectangle_intersect ()

gint        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
{
  gpointer user_data;
};

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.

gpointer user_dataarbitrary data attached 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_destroy ()

void        gdk_region_destroy              (GdkRegion *region);

Destroys a GdkRegion.

region :a GdkRegion.


gdk_regions_intersect ()

GdkRegion*  gdk_regions_intersect           (GdkRegion *source1,
                                             GdkRegion *source2);

Returns the intersection of two regions.

source1 :a GdkRegion.
source2 :a GdkRegion.
Returns :the intersection of source1 and source2.


gdk_regions_union ()

GdkRegion*  gdk_regions_union               (GdkRegion *source1,
                                             GdkRegion *source2);

Returns the union of two regions. This is all pixels in either of source1 or source2.

source1 :a GdkRegion.
source2 :a GdkRegion.
Returns :the union of source1 and source2.


gdk_regions_subtract ()

GdkRegion*  gdk_regions_subtract            (GdkRegion *source1,
                                             GdkRegion *source2);

Subtracts one region from another. The result is a region containing all the pixels which are in source1, but which are not in source2.

source1 :a GdkRegion.
source2 :a GdkRegion to subtract from source1.
Returns :source1 - source2.


gdk_regions_xor ()

GdkRegion*  gdk_regions_xor                 (GdkRegion *source1,
                                             GdkRegion *source2);

Returns the difference between the union and the intersection of two regions. This is a region containing the pixels that are in one of the source regions, but which are not in both.

source1 :a GdkRegion.
source2 :a GdkRegion.
Returns :the difference between the union and the intersection of source1 and source2.


gdk_region_union_with_rect ()

GdkRegion*  gdk_region_union_with_rect      (GdkRegion *region,
                                             GdkRectangle *rect);

Returns the union of a region and a rectangle.

region :a GdkRegion.
rect :a GdkRectangle.
Returns :the union of region and rect.


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