Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/regions.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Points, Rectangles and Regions
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 simple graphical data types.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types
  10 for representing pixels and sets of pixels on the screen.
  11 </para>
  12 <para>
  13 #GdkPoint is a simple structure containing an x and y coordinate of a point.
  14 </para>
  15 <para>
  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().
  20 </para>
  21 <para>
  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()).
  24 </para>
  25 <para>
  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().
  29 </para>
  30
  31 <!-- ##### SECTION See_Also ##### -->
  32 <para>
  33
  34 </para>
  35
  36 <!-- ##### STRUCT GdkPoint ##### -->
  37 <para>
  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.
  41 </para>
  42
  43 @x: the x coordinate of the point.
  44 @y: the y coordinate of the point.
  45
  46 <!-- ##### STRUCT GdkRectangle ##### -->
  47 <para>
  48 Defines the position and size of a rectangle.
  49 </para>
  50
  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.
  55
  56 <!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
  57 <para>
  58 Calculates the intersection of two rectangles.
  59 </para>
  60
  61 @src1: a #GdkRectangle.
  62 @src2: a #GdkRectangle.
  63 @dest: the intersection of @src1 and @src2.
  64 @Returns: TRUE if the rectangles intersect.
  65
  66
  67 <!-- ##### FUNCTION gdk_rectangle_union ##### -->
  68 <para>
  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.
  72 </para>
  73
  74 @src1: a #GdkRectangle.
  75 @src2: a #GdkRectangle.
  76 @dest: the union of @src1 and @src2.
  77
  78
  79 <!-- ##### STRUCT GdkRegion ##### -->
  80 <para>
  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.
  84 </para>
  85
  86
  87 <!-- ##### FUNCTION gdk_region_new ##### -->
  88 <para>
  89 Creates a new empty #GdkRegion.
  90 </para>
  91
  92 @Returns: a new empty #GdkRegion.
  93
  94
  95 <!-- ##### FUNCTION gdk_region_polygon ##### -->
  96 <para>
  97 Creates a new #GdkRegion using the polygon defined by a number of points.
  98
  99 </para>
 100
 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
 104 overlaps itself.
 105 @Returns: a new #GdkRegion based on the given polygon.
 106
 107
 108 <!-- ##### ENUM GdkFillRule ##### -->
 109 <para>
 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.
 113 </para>
 114
 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.
 118
 119 <!-- ##### FUNCTION gdk_region_copy ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @region:
 125 @Returns:
 126
 127
 128 <!-- ##### FUNCTION gdk_region_rectangle ##### -->
 129 <para>
 130
 131 </para>
 132
 133 @rectangle:
 134 @Returns:
 135
 136
 137 <!-- ##### FUNCTION gdk_region_destroy ##### -->
 138 <para>
 139 Destroys a #GdkRegion.
 140 </para>
 141
 142 @region: a #GdkRegion.
 143
 144
 145 <!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
 146 <para>
 147 Returns the smallest rectangle which includes the entire #GdkRegion.
 148 </para>
 149
 150 @region: a #GdkRegion.
 151 @rectangle: returns the smallest rectangle which includes all of @region.
 152
 153
 154 <!-- ##### FUNCTION gdk_region_get_rectangles ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @region:
 160 @rectangles:
 161 @n_rectangles:
 162
 163
 164 <!-- ##### FUNCTION gdk_region_empty ##### -->
 165 <para>
 166 Returns TRUE if the #GdkRegion is empty.
 167 </para>
 168
 169 @region: a #GdkRegion.
 170 @Returns: TRUE if @region is empty.
 171
 172
 173 <!-- ##### FUNCTION gdk_region_equal ##### -->
 174 <para>
 175 Returns TRUE if the two regions are the same.
 176 </para>
 177
 178 @region1: a #GdkRegion.
 179 @region2: a #GdkRegion.
 180 @Returns: TRUE if @region1 and @region2 are equal.
 181
 182
 183 <!-- ##### FUNCTION gdk_region_point_in ##### -->
 184 <para>
 185 Returns TRUE if a point is in a region.
 186 </para>
 187
 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.
 192
 193
 194 <!-- ##### FUNCTION gdk_region_rect_in ##### -->
 195 <para>
 196 Tests whether a rectangle is within a region.
 197 </para>
 198
 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.
 204
 205
 206 <!-- ##### ENUM GdkOverlapType ##### -->
 207 <para>
 208 Specifies the possible values returned by gdk_region_rect_in().
 209 </para>
 210
 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.
 214
 215 <!-- ##### FUNCTION gdk_region_offset ##### -->
 216 <para>
 217 Moves a region the specified distance.
 218 </para>
 219
 220 @region: a #GdkRegion.
 221 @dx: the distance to move the region horizontally.
 222 @dy: the distance to move the region vertically.
 223
 224
 225 <!-- ##### FUNCTION gdk_region_shrink ##### -->
 226 <para>
 227 Resizes a region by the specified amount.
 228 Positive values shrink the region. Negative values expand it.
 229 </para>
 230
 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.
 234
 235
 236 <!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
 237 <para>
 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.
 241
 242 </para>
 243
 244 @region: a #GdkRegion.
 245 @rect: a #GdkRectangle.
 246
 247
 248 <!-- ##### FUNCTION gdk_region_intersect ##### -->
 249 <para>
 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.
 253 </para>
 254
 255 @source1: a #GdkRegion
 256 @source2: a #GdkRegion
 257
 258
 259 <!-- ##### FUNCTION gdk_region_union ##### -->
 260 <para>
 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.
 264
 265 </para>
 266
 267 @source1: a #GdkRegion
 268 @source2: a #GdkRegion
 269
 270
 271 <!-- ##### FUNCTION gdk_region_subtract ##### -->
 272 <para>
 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.
 275 </para>
 276
 277 @source1: a #GdkRegion
 278 @source2: a #GdkRegion
 279
 280
 281 <!-- ##### FUNCTION gdk_region_xor ##### -->
 282 <para>
 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.
 286 </para>
 287
 288 @source1: a #GdkRegion
 289 @source2: a #GdkRegion
 290
 291
 292 <!-- ##### STRUCT GdkSpan ##### -->
 293 <para>
 294 A GdkSpan represents a horizontal line of pixels starting
 295 at the pixel with coordinates @x, @y and ending before @x + @width, @y.
 296 </para>
 297
 298 @x: x coordinate of the first pixel.
 299 @y: y coordinate of the first pixel.
 300 @width: number of pixels in the span.
 301
 302 <!-- ##### USER_FUNCTION GdkSpanFunc ##### -->
 303 <para>
 304 This defines the type of the function passed to
 305 gdk_region_spans_intersect_foreach().
 306 </para>
 307
 308 @span: a #GdkSpan.
 309 @data: the user data passed to gdk_region_spans_intersect_foreach().
 310
 311
 312 <!-- ##### FUNCTION gdk_region_spans_intersect_foreach ##### -->
 313 <para>
 314 Calls a function on each span in the intersection of @region and
 315 @spans.
 316 </para>
 317
 318 @region: a #GdkRegion.
 319 @spans: an array of #GdkSpans.
 320 @n_spans: the length of @spans.
 321 @sorted: %TRUE if @spans is sorted wrt. the y coordinate.
 322 @function: function to call on each span in the intersection.
 323 @data: data to pass to @function.
 324
 325