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.


struct GdkRectangle

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

Defines the position and size of a rectangle.


gdk_rectangle_intersect ()

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

Calculates the intersection of two rectangles.


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.


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.


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.


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_region_copy ()

GdkRegion*  gdk_region_copy                 (GdkRegion *region);

Copies region, creating an identical new region.


gdk_region_rectangle ()

GdkRegion*  gdk_region_rectangle            (GdkRectangle *rectangle);

Creates a new region containing the area rectangle.


gdk_region_destroy ()

void        gdk_region_destroy              (GdkRegion *region);

Destroys a GdkRegion.


gdk_region_get_clipbox ()

void        gdk_region_get_clipbox          (GdkRegion *region,
                                             GdkRectangle *rectangle);

Returns the smallest rectangle which includes the entire GdkRegion.


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().


gdk_region_empty ()

gboolean    gdk_region_empty                (GdkRegion *region);

Returns TRUE if the GdkRegion is empty.


gdk_region_equal ()

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

Returns TRUE if the two regions are the same.


gdk_region_point_in ()

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

Returns TRUE if a point is in a region.


gdk_region_rect_in ()

GdkOverlapType gdk_region_rect_in           (GdkRegion *region,
                                             GdkRectangle *rect);

Tests whether a rectangle is within a region.


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_region_offset ()

void        gdk_region_offset               (GdkRegion *region,
                                             gint dx,
                                             gint dy);

Moves a region the specified distance.


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.


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.


gdk_region_intersect ()

void        gdk_region_intersect            (GdkRegion *source1,
                                             GdkRegion *source2);

Converts source1 into the intersection between source1 and source2. That is, after calling this function source2 will be unchanged and source1 will be the areas the two regions have in common.

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.


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.


gdk_region_subtract ()

void        gdk_region_subtract             (GdkRegion *source1,
                                             GdkRegion *source2);

Subtracts any area in source2 from the area in source1.

Subtracts the area of source2 from the area source1. The resulting area is the set of pixels contained in source1 but not in source2.


gdk_region_xor ()

void        gdk_region_xor                  (GdkRegion *source1,
                                             GdkRegion *source2);

XORs the two regions, placing the result in source1. The XOR of two regions contains all areas which were not overlapping. That is, it's the union of the regions minus the intersection of the regions.

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.


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.


GdkSpanFunc ()

void        (*GdkSpanFunc)                  (GdkSpan *span,
                                             gpointer data);

This defines the type of the function 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.