doc/gfx.txt

   1 Drawing primitives
   2 ------------------
   3
   4 Drawing primitives implements algorithms to draw basic geometric shapes such
   5 as lines, circles, etc.
   6
   7 You may want to see the link:coordinate_system.html[coordinate system] first.
   8
   9 See also RGB tripplet to pixel link:convert.html[conversions].
  10
  11 Rotation Flags
  12 ~~~~~~~~~~~~~~
  13
  14 Drawing orientation is affected by the link:pixmap.html[pixmap rotation
  15 flags]. The parameters passed to the functions are transformed accordingly to
  16 the flags before the drawing, which allows for fast and transparent rotated or
  17 mirrored rendering.
  18
  19
  20 GetPixel and PutPixel
  21 ~~~~~~~~~~~~~~~~~~~~~
  22
  23 link:get_put_pixel.html[GetPixel and PutPixel] are implemented in the library
  24 Core.
  25
  26 Fill
  27 ~~~~
  28
  29 [source,c]
  30 --------------------------------------------------------------------------------
  31 void GP_Fill(GP_Pixmap *pixmap, GP_Pixel pixel);
  32 --------------------------------------------------------------------------------
  33
  34 Fills the whole pixmap bitmap with the specified pixel value.
  35
  36 NOTE: GP_Fill is implemented in the library Core rather than in GFX so that
  37       it's available to all library parts.
  38
  39 Lines
  40 ~~~~~
  41
  42 [source,c]
  43 --------------------------------------------------------------------------------
  44 void GP_HLineXXY(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord x1, GP_Coord y,
  45                  GP_Pixel pixel);
  46
  47 void GP_HLine(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord x1, GP_Coord y,
  48               GP_Pixel pixel);
  49 --------------------------------------------------------------------------------
  50
  51 Draws a horizontal line from (x0, y) to (x1, y), inclusive. The coordinates
  52 x0, x1 can be specified in any order.
  53
  54 'GP_HLine()' is an alias for 'GP_HLineXXY()'.
  55
  56 [source,c]
  57 --------------------------------------------------------------------------------
  58 void GP_HLineXYW(GP_Pixmap *pixmap, GP_Coord x, GP_Coord y, GP_Size w,
  59                  GP_Pixel pixel);
  60 --------------------------------------------------------------------------------
  61
  62 Draws a horizontal line from (x, y) to (x+w-1, y), inclusive.
  63
  64
  65 [source,c]
  66 --------------------------------------------------------------------------------
  67 void GP_VLineXYY(GP_Pixmap *pixmap, GP_Coord x, GP_Coord y0, GP_Coord y1,
  68                  GP_Pixel pixel);
  69
  70 void GP_VLine(GP_Pixmap *pixmap, GP_Coord x, GP_Coord y0, GP_Coord y1,
  71               GP_Pixel pixel);
  72 --------------------------------------------------------------------------------
  73
  74 Draws a vertical line from (x, y0) to (x, y1), inclusive. The coordinates
  75 y0, y1 can be specified in any order.
  76
  77 'GP_VLine()' is an alias for 'GP_VLineXYY()'.
  78
  79 [source,c]
  80 --------------------------------------------------------------------------------
  81 void GP_VLineXYH(GP_Pixmap *pixmap, GP_Coord x, GP_Coord y, GP_Size h,
  82                  GP_Pixel pixel);
  83
  84 --------------------------------------------------------------------------------
  85
  86 Draws a vertical line from (x, y) to (x, y+h-1), inclusive.
  87
  88 [source,c]
  89 --------------------------------------------------------------------------------
  90 void GP_Line(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
  91              GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
  92 --------------------------------------------------------------------------------
  93
  94 Draws a line from (x0, y0) to (x1, y1), inclusive. The starting and ending
  95 point can be specified in any order (the implementation guarantees that
  96 exactly the same set of pixels will be drawn in both cases).
  97
  98 Circles
  99 ~~~~~~~
 100
 101 [source,c]
 102 --------------------------------------------------------------------------------
 103 void GP_Circle(GP_Pixmap *pixmap, GP_Coord xcenter, GP_Coord ycenter,
 104                GP_Size r, GP_Pixel pixel);
 105 --------------------------------------------------------------------------------
 106
 107 Draws a circle centered at (xcenter, ycenter) with radius 'r' (in pixels).
 108
 109 The circle is drawn so that all affected pixels will fit into a square
 110 specified by points (xcenter-r, ycenter-r, xcenter+r, ycenter+r), inclusive.
 111
 112 [source,c]
 113 --------------------------------------------------------------------------------
 114 void GP_FillCircle(GP_Pixmap *pixmap, GP_Coord xcenter, GP_Coord ycenter,
 115                    GP_Size r, GP_Pixel pixel);
 116 --------------------------------------------------------------------------------
 117
 118 Draws a filled circle.
 119
 120 The set of pixels affected by 'GP_FillCircle()' is exactly the same as if
 121 drawing the circle boundary using 'GP_Circle()' and then filling all pixels
 122 within the boundary with the same color.
 123
 124 Rings
 125 ~~~~~
 126 [source,c]
 127 --------------------------------------------------------------------------------
 128 void GP_Ring(GP_Pixmap *pixmap, GP_Coord xcenter, GP_Coord ycenter,
 129              GP_Size r1, GP_Size r2, GP_Pixel pixel);
 130 --------------------------------------------------------------------------------
 131
 132 Draws a ring (two circles centered at (xcenter, ycenter) with radii 'r1' and 'r2').
 133
 134 The result is exactly the same as calling 'GP_Circle()' with the same center
 135 and appropriate radii.
 136
 137 [source,c]
 138 --------------------------------------------------------------------------------
 139 void GP_FillRing(GP_Pixmap *pixmap, GP_Coord xcenter, GP_Coord ycenter,
 140                  GP_Size r1, GP_Size r2, GP_Pixel pixel);
 141 --------------------------------------------------------------------------------
 142
 143 Draws a filled ring.
 144
 145 The smaller of r1 and r2 is used for inner radius and bigger one for outer
 146 radius.
 147
 148 Ellipses
 149 ~~~~~~~~
 150
 151 [source,c]
 152 --------------------------------------------------------------------------------
 153 void GP_Ellipse(GP_Pixmap *pixmap, GP_Coord xcenter, GP_Coord ycenter,
 154                 GP_Size a, GP_Size b, GP_Pixel pixel);
 155 --------------------------------------------------------------------------------
 156
 157 Draws an axis-aligned ellipse.
 158
 159 The ellipse is drawn so that all affected pixels will fit into a rectangle
 160 specified by points (xcenter-a, ycenter-b, xcenter+a, ycenter+b), inclusive.
 161
 162 [source,c]
 163 --------------------------------------------------------------------------------
 164 void GP_FillEllipse(GP_Pixmap *pixmap, GP_Coord xcenter, GP_Coord ycenter,
 165                     GP_Size a, GP_Size b, GP_Pixel pixel);
 166 --------------------------------------------------------------------------------
 167
 168 Draws a filled axis-aligned ellipse.
 169
 170 Triangles
 171 ~~~~~~~~~
 172
 173 [source,c]
 174 --------------------------------------------------------------------------------
 175 void GP_Triangle(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 176                  GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 177                  GP_Pixel pixel);
 178 --------------------------------------------------------------------------------
 179
 180 Draws a triangle.
 181
 182 [source,c]
 183 --------------------------------------------------------------------------------
 184 void GP_FillTriangle(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 185                      GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 186                      GP_Pixel pixel);
 187 --------------------------------------------------------------------------------
 188
 189 Draws a filled triangle.
 190
 191 Rects
 192 ~~~~~
 193
 194 [source,c]
 195 --------------------------------------------------------------------------------
 196 void GP_RectXYXY(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 197                  GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 198
 199 void GP_RectXYWH(GP_Pixmap *pixmap, GP_Coord x, GP_Coord y,
 200                  GP_Size w, GP_Size h, GP_Pixel pixel);
 201
 202 void GP_Rect(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 203              GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 204 --------------------------------------------------------------------------------
 205
 206 Draws a rectangle.
 207
 208 The 'GP_RectXYXY()' expects two corner points (x0, y0), and (x1, y1).
 209 The 'GP_RectXYWH()' expects a corner point (x0, y0), width and height.
 210 The 'GP_Rect()' function is an alias for 'GP_RectXYXY()'.
 211
 212 [source,c]
 213 --------------------------------------------------------------------------------
 214 void GP_FillRectXYXY(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 215                      GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 216
 217 void GP_FillRectXYWH(GP_Pixmap *pixmap, GP_Coord x, GP_Coord y,
 218                      GP_Size w, GP_Size h, GP_Pixel pixel);
 219
 220 void GP_FillRect(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 221                  GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 222 --------------------------------------------------------------------------------
 223
 224 Draws a filled rectangle.
 225
 226 The 'GP_RectXYXY' fills an area between corner points (x0, y0) and (x1, y1),
 227 inclusive.
 228 The 'GP_RectXYWH' fills an area starting from (x0, y0) with specified width
 229 and height, i.e. from (x0, y0) to (x0 + w, x1 + y), NOT inclusive.
 230 The 'GP_FillRect()' functions is an alias for 'GP_FillRectXYXY()'.
 231
 232 Tetragons
 233 ~~~~~~~~~
 234
 235 [source,c]
 236 --------------------------------------------------------------------------------
 237 void GP_Tetragon(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 238                  GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 239                  GP_Coord x3, GP_Coord y3, GP_Pixel pixel);
 240 --------------------------------------------------------------------------------
 241
 242 Draws a tetragon.
 243
 244 [source,c]
 245 --------------------------------------------------------------------------------
 246 void GP_FillTetragon(GP_Pixmap *pixmap, GP_Coord x0, GP_Coord y0,
 247                      GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 248                      GP_Coord x3, GP_Coord y3, GP_Pixel pixel);
 249 --------------------------------------------------------------------------------
 250
 251 Draws a filled tetragon.
 252
 253 Polygons
 254 ~~~~~~~~
 255
 256 [source,c]
 257 --------------------------------------------------------------------------------
 258 void GP_Polygon(GP_Pixmap *pixmap, unsigned int vertex_count,
 259                 const GP_Coord *xy, GP_Pixel pixel);
 260 --------------------------------------------------------------------------------
 261
 262 Draws a polygon.
 263
 264 [source,c]
 265 --------------------------------------------------------------------------------
 266 void GP_FillPolygon(GP_Pixmap *pixmap, unsigned int vertex_count,
 267                     const GP_Coord *xy, GP_Pixel pixel);
 268 --------------------------------------------------------------------------------
 269
 270 Draws a filled polygon.
 271
 272 The coordinages are passed in [x0, y0, x1, y1, ...] order, the vertex count
 273 describes a number of nodes, i.e. half of the size of the array.