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
  39 </para>
  40
  41 @x:
  42 @y:
  43
  44 <!-- ##### STRUCT GdkRectangle ##### -->
  45 <para>
  46
  47 </para>
  48
  49 @x:
  50 @y:
  51 @width:
  52 @height:
  53
  54 <!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
  55 <para>
  56
  57 </para>
  58
  59 @src1:
  60 @src2:
  61 @dest:
  62 @Returns:
  63
  64
  65 <!-- ##### FUNCTION gdk_rectangle_union ##### -->
  66 <para>
  67
  68 </para>
  69
  70 @src1:
  71 @src2:
  72 @dest:
  73
  74
  75 <!-- ##### STRUCT GdkRegion ##### -->
  76 <para>
  77 A GdkRegion represents a set of pixels on the screen.
  78 The only user-visible field of the structure is the user_data member, which
  79 can be used to attach arbitrary data to the #GdkRegion.
  80 </para>
  81
  82
  83 <!-- ##### FUNCTION gdk_region_new ##### -->
  84 <para>
  85 Creates a new empty #GdkRegion.
  86 </para>
  87
  88 @Returns: a new empty #GdkRegion.
  89
  90
  91 <!-- ##### FUNCTION gdk_region_polygon ##### -->
  92 <para>
  93 Creates a new #GdkRegion using the polygon defined by a number of points.
  94
  95 </para>
  96
  97 @points: an array of #GdkPoint structs.
  98 @npoints: the number of elements in the @points array.
  99 @fill_rule: specifies which pixels are included in the region when the polygon
 100 overlaps itself.
 101 @Returns: a new #GdkRegion based on the given polygon.
 102
 103
 104 <!-- ##### ENUM GdkFillRule ##### -->
 105 <para>
 106 The method for determining which pixels are included in a region, when
 107 creating a #GdkRegion from a polygon.
 108 The fill rule is only relevant for polygons which overlap themselves.
 109 </para>
 110
 111 @GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
 112 included in the region, while areas overlapped an even number of times are not.
 113 @GDK_WINDING_RULE: overlapping areas are always included.
 114
 115 <!-- ##### FUNCTION gdk_region_copy ##### -->
 116 <para>
 117
 118 </para>
 119
 120 @region:
 121 @Returns:
 122
 123
 124 <!-- ##### FUNCTION gdk_region_rectangle ##### -->
 125 <para>
 126
 127 </para>
 128
 129 @rectangle:
 130 @Returns:
 131
 132
 133 <!-- ##### FUNCTION gdk_region_destroy ##### -->
 134 <para>
 135 Destroys a #GdkRegion.
 136 </para>
 137
 138 @region: a #GdkRegion.
 139
 140
 141 <!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
 142 <para>
 143 Returns the smallest rectangle which includes the entire #GdkRegion.
 144 </para>
 145
 146 @region: a #GdkRegion.
 147 @rectangle: returns the smallest rectangle which includes all of @region.
 148
 149
 150 <!-- ##### FUNCTION gdk_region_empty ##### -->
 151 <para>
 152 Returns TRUE if the #GdkRegion is empty.
 153 </para>
 154
 155 @region: a #GdkRegion.
 156 @Returns: TRUE if @region is empty.
 157
 158
 159 <!-- ##### FUNCTION gdk_region_equal ##### -->
 160 <para>
 161 Returns TRUE if the two regions are the same.
 162 </para>
 163
 164 @region1: a #GdkRegion.
 165 @region2: a #GdkRegion.
 166 @Returns: TRUE if @region1 and @region2 are equal.
 167
 168
 169 <!-- ##### FUNCTION gdk_region_point_in ##### -->
 170 <para>
 171 Returns TRUE if a point is in a region.
 172 </para>
 173
 174 @region: a #GdkRegion.
 175 @x: the x coordinate of a point.
 176 @y: the y coordinate of a point.
 177 @Returns: TRUE if the point is in @region.
 178
 179
 180 <!-- ##### FUNCTION gdk_region_rect_in ##### -->
 181 <para>
 182 Tests whether a rectangle is within a region.
 183 </para>
 184
 185 @region: a #GdkRegion.
 186 @rect: a #GdkRectangle.
 187 @Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or
 188 GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
 189 outside, or partly inside the #GdkRegion, respectively.
 190
 191
 192 <!-- ##### ENUM GdkOverlapType ##### -->
 193 <para>
 194 Specifies the possible values returned by gdk_region_rect_in().
 195 </para>
 196
 197 @GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion.
 198 @GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion.
 199 @GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion.
 200
 201 <!-- ##### FUNCTION gdk_region_offset ##### -->
 202 <para>
 203 Moves a region the specified distance.
 204 </para>
 205
 206 @region: a #GdkRegion.
 207 @dx: the distance to move the region horizontally.
 208 @dy: the distance to move the region vertically.
 209
 210
 211 <!-- ##### FUNCTION gdk_region_shrink ##### -->
 212 <para>
 213 Resizes a region by the specified amount.
 214 Positive values shrink the region. Negative values expand it.
 215 </para>
 216
 217 @region: a #GdkRegion.
 218 @dx: the number of pixels to shrink the region horizontally.
 219 @dy: the number of pixels to shrink the region vertically.
 220
 221
 222 <!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
 223 <para>
 224 Returns the union of a region and a rectangle.
 225 </para>
 226
 227 @region: a #GdkRegion.
 228 @rect: a #GdkRectangle.
 229 <!-- # Unused Parameters # -->
 230 @Returns: the union of @region and @rect.
 231
 232
 233 <!-- ##### FUNCTION gdk_region_intersect ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @source1:
 239 @source2:
 240
 241
 242 <!-- ##### FUNCTION gdk_region_union ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @source1:
 248 @source2:
 249
 250
 251 <!-- ##### FUNCTION gdk_region_subtract ##### -->
 252 <para>
 253
 254 </para>
 255
 256 @source1:
 257 @source2:
 258
 259
 260 <!-- ##### FUNCTION gdk_region_xor ##### -->
 261 <para>
 262
 263 </para>
 264
 265 @source1:
 266 @source2:
 267
 268
 269 <!-- ##### STRUCT GdkSpan ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @x:
 275 @y:
 276 @width:
 277
 278 <!-- ##### USER_FUNCTION GdkSpanFunc ##### -->
 279 <para>
 280
 281 </para>
 282
 283 @span: The intersected part of the span.
 284 @data: Opaque data passed by user.
 285
 286
 287 <!-- ##### FUNCTION gdk_region_spans_intersect_foreach ##### -->
 288 <para>
 289 Intersects a set of spans with a region and call a user specified
 290 function for each resulting spanline. This function is a lot more effective
 291 if the spans are sorted.
 292 </para>
 293
 294 @region: The region to intersect against.
 295 @spans: Array of spans to intersect.
 296 @n_spans: Number of spans.
 297 @sorted: True if the spans are sorted in increasing y order.
 298 @function: The function to call for each intersected spanline.
 299 @data: Opaque user data passed to function.
 300
 301