1 <!-- ##### SECTION Title ##### -->
2 Points, Rectangles and Regions
4 <!-- ##### SECTION Short_Description ##### -->
5 simple graphical data types.
7 <!-- ##### SECTION Long_Description ##### -->
9 GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types
10 for representing pixels and sets of pixels on the screen.
13 #GdkPoint is a simple structure containing an x and y coordinate of a point.
16 #GdkRectangle is a structure holding the position and size of a rectangle.
17 The intersection of two rectangles can be computed with
18 gdk_rectangle_intersect(). To find the union of two rectangles use
19 gdk_rectangle_union().
22 #GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
23 usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
26 #GdkSpan is a structure holding a spanline. A spanline is a horizontal line that
27 is one pixel wide. It is mainly used when rasterizing other graphics primitives.
28 It can be intersected to regions by using gdk_region_spans_intersect_foreach().
31 <!-- ##### SECTION See_Also ##### -->
36 <!-- ##### STRUCT GdkPoint ##### -->
38 Defines the x and y coordinates of a point.
39 Note that both are defined as #gint16 values, so the coordinates are limited
40 to between -32,768 and 32,767.
43 @x: the x coordinate of the point.
44 @y: the y coordinate of the point.
46 <!-- ##### STRUCT GdkRectangle ##### -->
48 Defines the position and size of a rectangle.
51 @x: the x coordinate of the left edge of the rectangle.
52 @y: the y coordinate of the top of the rectangle.
53 @width: the width of the rectangle.
54 @height: the height of the rectangle.
56 <!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
58 Calculates the intersection of two rectangles.
61 @src1: a #GdkRectangle.
62 @src2: a #GdkRectangle.
63 @dest: the intersection of @src1 and @src2.
64 @Returns: TRUE if the rectangles intersect.
67 <!-- ##### FUNCTION gdk_rectangle_union ##### -->
69 Calculates the union of two rectangles.
70 The union of rectangles @src1 and @src2 is the smallest rectangle which
71 includes both @src1 and @src2 within it.
74 @src1: a #GdkRectangle.
75 @src2: a #GdkRectangle.
76 @dest: the union of @src1 and @src2.
79 <!-- ##### STRUCT GdkRegion ##### -->
81 A GdkRegion represents a set of pixels on the screen.
82 The only user-visible field of the structure is the user_data member, which
83 can be used to attach arbitrary data to the #GdkRegion.
87 <!-- ##### FUNCTION gdk_region_new ##### -->
89 Creates a new empty #GdkRegion.
92 @Returns: a new empty #GdkRegion.
95 <!-- ##### FUNCTION gdk_region_polygon ##### -->
97 Creates a new #GdkRegion using the polygon defined by a number of points.
101 @points: an array of #GdkPoint structs.
102 @npoints: the number of elements in the @points array.
103 @fill_rule: specifies which pixels are included in the region when the polygon
105 @Returns: a new #GdkRegion based on the given polygon.
108 <!-- ##### ENUM GdkFillRule ##### -->
110 The method for determining which pixels are included in a region, when
111 creating a #GdkRegion from a polygon.
112 The fill rule is only relevant for polygons which overlap themselves.
115 @GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
116 included in the region, while areas overlapped an even number of times are not.
117 @GDK_WINDING_RULE: overlapping areas are always included.
119 <!-- ##### FUNCTION gdk_region_copy ##### -->
128 <!-- ##### FUNCTION gdk_region_rectangle ##### -->
137 <!-- ##### FUNCTION gdk_region_destroy ##### -->
139 Destroys a #GdkRegion.
142 @region: a #GdkRegion.
145 <!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
147 Returns the smallest rectangle which includes the entire #GdkRegion.
150 @region: a #GdkRegion.
151 @rectangle: returns the smallest rectangle which includes all of @region.
154 <!-- ##### FUNCTION gdk_region_get_rectangles ##### -->
164 <!-- ##### FUNCTION gdk_region_empty ##### -->
166 Returns TRUE if the #GdkRegion is empty.
169 @region: a #GdkRegion.
170 @Returns: TRUE if @region is empty.
173 <!-- ##### FUNCTION gdk_region_equal ##### -->
175 Returns TRUE if the two regions are the same.
178 @region1: a #GdkRegion.
179 @region2: a #GdkRegion.
180 @Returns: TRUE if @region1 and @region2 are equal.
183 <!-- ##### FUNCTION gdk_region_point_in ##### -->
185 Returns TRUE if a point is in a region.
188 @region: a #GdkRegion.
189 @x: the x coordinate of a point.
190 @y: the y coordinate of a point.
191 @Returns: TRUE if the point is in @region.
194 <!-- ##### FUNCTION gdk_region_rect_in ##### -->
196 Tests whether a rectangle is within a region.
199 @region: a #GdkRegion.
200 @rect: a #GdkRectangle.
201 @Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or
202 GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
203 outside, or partly inside the #GdkRegion, respectively.
206 <!-- ##### ENUM GdkOverlapType ##### -->
208 Specifies the possible values returned by gdk_region_rect_in().
211 @GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion.
212 @GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion.
213 @GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion.
215 <!-- ##### FUNCTION gdk_region_offset ##### -->
217 Moves a region the specified distance.
220 @region: a #GdkRegion.
221 @dx: the distance to move the region horizontally.
222 @dy: the distance to move the region vertically.
225 <!-- ##### FUNCTION gdk_region_shrink ##### -->
227 Resizes a region by the specified amount.
228 Positive values shrink the region. Negative values expand it.
231 @region: a #GdkRegion.
232 @dx: the number of pixels to shrink the region horizontally.
233 @dy: the number of pixels to shrink the region vertically.
236 <!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
238 Sets the area of @region to the union of the areas of @region and
239 @rect. The resulting area is the set of pixels contained in
240 either @region or @rect.
244 @region: a #GdkRegion.
245 @rect: a #GdkRectangle.
248 <!-- ##### FUNCTION gdk_region_intersect ##### -->
250 Sets the area of @source1 to the intersection of the areas of @source1
251 and @source2. The resulting area is the set of pixels contained in
252 both @source1 and @source2.
255 @source1: a #GdkRegion
256 @source2: a #GdkRegion
259 <!-- ##### FUNCTION gdk_region_union ##### -->
261 Sets the area of @source1 to the union of the areas of @source1 and
262 @source2. The resulting area is the set of pixels contained in
263 either @source1 or @source2.
267 @source1: a #GdkRegion
268 @source2: a #GdkRegion
271 <!-- ##### FUNCTION gdk_region_subtract ##### -->
273 Subtracts the area of @source2 from the area @source1. The resulting
274 area is the set of pixels contained in @source1 but not in @source2.
277 @source1: a #GdkRegion
278 @source2: a #GdkRegion
281 <!-- ##### FUNCTION gdk_region_xor ##### -->
283 Sets the area of @source1 to the exclusive-OR of the areas of @source1
284 and @source2. The resulting area is the set of pixels contained in one
285 or the other of the two sources but not in both.
288 @source1: a #GdkRegion
289 @source2: a #GdkRegion
292 <!-- ##### STRUCT GdkSpan ##### -->
301 <!-- ##### USER_FUNCTION GdkSpanFunc ##### -->
310 <!-- ##### FUNCTION gdk_region_spans_intersect_foreach ##### -->