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