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 Getting and Putting Pixels
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  22
  23 link:get_put_pixel.html[getpixel() and putpixel()] are implemented in the
  24 library 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_hline_xxy(gp_pixmap *pixmap, gp_coord x0, gp_coord x1, gp_coord y, gp_pixel pixel);
  45
  46 void gp_hline(gp_pixmap *pixmap, gp_coord x0, gp_coord x1, gp_coord y, 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_hline_xxy()'.
  53
  54 [source,c]
  55 --------------------------------------------------------------------------------
  56 void gp_hline_xyw(gp_pixmap *pixmap, gp_coord x, gp_coord y, gp_size w, gp_pixel pixel);
  57 --------------------------------------------------------------------------------
  58
  59 Draws a horizontal line from (x, y) to (x+w-1, y), inclusive.
  60
  61
  62 [source,c]
  63 --------------------------------------------------------------------------------
  64 void gp_vline_xyy(gp_pixmap *pixmap, gp_coord x, gp_coord y0, gp_coord y1,
  65                   gp_pixel pixel);
  66
  67 void gp_vline(gp_pixmap *pixmap, gp_coord x, gp_coord y0, gp_coord y1,
  68               gp_pixel pixel);
  69 --------------------------------------------------------------------------------
  70
  71 Draws a vertical line from (x, y0) to (x, y1), inclusive. The coordinates
  72 y0, y1 can be specified in any order.
  73
  74 'gp_vline()' is an alias for 'gp_vline_xyy()'.
  75
  76 [source,c]
  77 --------------------------------------------------------------------------------
  78 void gp_vline_xyh(gp_pixmap *pixmap, gp_coord x, gp_coord y, gp_size h,
  79                   gp_pixel pixel);
  80
  81 --------------------------------------------------------------------------------
  82
  83 Draws a vertical line from (x, y) to (x, y+h-1), inclusive.
  84
  85 [source,c]
  86 --------------------------------------------------------------------------------
  87 void gp_line(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
  88              gp_coord x1, gp_coord y1, gp_pixel pixel);
  89 --------------------------------------------------------------------------------
  90
  91 Draws a line from (x0, y0) to (x1, y1), inclusive. The starting and ending
  92 point can be specified in any order (the implementation guarantees that
  93 exactly the same set of pixels will be drawn in both cases).
  94
  95 Circles
  96 ~~~~~~~
  97
  98 [source,c]
  99 --------------------------------------------------------------------------------
 100 void gp_circle(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
 101                gp_size r, gp_pixel pixel);
 102 --------------------------------------------------------------------------------
 103
 104 Draws a circle centered at (xcenter, ycenter) with radius 'r' (in pixels).
 105
 106 The circle is drawn so that all affected pixels will fit into a square
 107 specified by points (xcenter-r, ycenter-r, xcenter+r, ycenter+r), inclusive.
 108
 109 [source,c]
 110 --------------------------------------------------------------------------------
 111 void gp_fill_circle(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
 112                     gp_size r, gp_pixel pixel);
 113 --------------------------------------------------------------------------------
 114
 115 Draws a filled circle.
 116
 117 The set of pixels affected by 'gp_fill_circle()' is exactly the same as if
 118 drawing the circle boundary using 'gp_circle()' and then filling all pixels
 119 within the boundary with the same color.
 120
 121 Rings
 122 ~~~~~
 123 [source,c]
 124 --------------------------------------------------------------------------------
 125 void gp_ring(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
 126              gp_size r1, gp_size r2, gp_pixel pixel);
 127 --------------------------------------------------------------------------------
 128
 129 Draws a ring (two circles centered at (xcenter, ycenter) with radii 'r1' and 'r2').
 130
 131 The result is exactly the same as calling 'gp_circle()' with the same center
 132 and appropriate radii.
 133
 134 [source,c]
 135 --------------------------------------------------------------------------------
 136 void gp_fill_ring(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
 137                   gp_size r1, gp_size r2, gp_pixel pixel);
 138 --------------------------------------------------------------------------------
 139
 140 Draws a filled ring.
 141
 142 The smaller of r1 and r2 is used for inner radius and bigger one for outer
 143 radius.
 144
 145 Ellipses
 146 ~~~~~~~~
 147
 148 [source,c]
 149 --------------------------------------------------------------------------------
 150 void gp_ellipse(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
 151                 gp_size a, gp_size b, gp_pixel pixel);
 152 --------------------------------------------------------------------------------
 153
 154 Draws an axis-aligned ellipse.
 155
 156 The ellipse is drawn so that all affected pixels will fit into a rectangle
 157 specified by points (xcenter-a, ycenter-b, xcenter+a, ycenter+b), inclusive.
 158
 159 [source,c]
 160 --------------------------------------------------------------------------------
 161 void gp_fill_ellipse(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
 162                      gp_size a, gp_size b, gp_pixel pixel);
 163 --------------------------------------------------------------------------------
 164
 165 Draws a filled axis-aligned ellipse.
 166
 167 Triangles
 168 ~~~~~~~~~
 169
 170 [source,c]
 171 --------------------------------------------------------------------------------
 172 void gp_triangle(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 173                  gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
 174                  gp_pixel pixel);
 175 --------------------------------------------------------------------------------
 176
 177 Draws a triangle.
 178
 179 [source,c]
 180 --------------------------------------------------------------------------------
 181 void gp_fill_triangle(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 182                       gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
 183                       gp_pixel pixel);
 184 --------------------------------------------------------------------------------
 185
 186 Draws a filled triangle.
 187
 188 Rects
 189 ~~~~~
 190
 191 [source,c]
 192 --------------------------------------------------------------------------------
 193 void gp_rect_xyxy(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 194                   gp_coord x1, gp_coord y1, gp_pixel pixel);
 195
 196 void gp_rect_xywh(gp_pixmap *pixmap, gp_coord x, gp_coord y,
 197                   gp_size w, gp_size h, gp_pixel pixel);
 198
 199 void gp_rect(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 200              gp_coord x1, gp_coord y1, gp_pixel pixel);
 201 --------------------------------------------------------------------------------
 202
 203 Draws a rectangle.
 204
 205 The 'gp_rect_xyxy()' expects two corner points (x0, y0), and (x1, y1).
 206 The 'gp_rect_xywh()' expects a corner point (x0, y0), width and height.
 207 The 'gp_rect()' function is an alias for 'gp_rect_xyxy()'.
 208
 209 [source,c]
 210 --------------------------------------------------------------------------------
 211 void gp_fill_rect_xyxy(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 212                        gp_coord x1, gp_coord y1, gp_pixel pixel);
 213
 214 void gp_fill_rect_xywh(gp_pixmap *pixmap, gp_coord x, gp_coord y,
 215                        gp_size w, gp_size h, gp_pixel pixel);
 216
 217 void gp_fill_rect(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 218                   gp_coord x1, gp_coord y1, gp_pixel pixel);
 219 --------------------------------------------------------------------------------
 220
 221 Draws a filled rectangle.
 222
 223 The 'gp_rect_xyxy' fills an area between corner points (x0, y0) and (x1, y1),
 224 inclusive.
 225 The 'gp_rect_xywh' fills an area starting from (x0, y0) with specified width
 226 and height, i.e. from (x0, y0) to (x0 + w, x1 + y), NOT inclusive.
 227 The 'gp_fill_rect()' functions is an alias for 'gp_fill_rect_xyxy()'.
 228
 229 Tetragons
 230 ~~~~~~~~~
 231
 232 [source,c]
 233 --------------------------------------------------------------------------------
 234 void gp_tetragon(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 235                  gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
 236                  gp_coord x3, gp_coord y3, gp_pixel pixel);
 237 --------------------------------------------------------------------------------
 238
 239 Draws a tetragon.
 240
 241 [source,c]
 242 --------------------------------------------------------------------------------
 243 void gp_fill_tetragon(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
 244                      gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
 245                      gp_coord x3, gp_coord y3, gp_pixel pixel);
 246 --------------------------------------------------------------------------------
 247
 248 Draws a filled tetragon.
 249
 250 Polygons
 251 ~~~~~~~~
 252
 253 [source,c]
 254 --------------------------------------------------------------------------------
 255 void gp_polygon(gp_pixmap *pixmap, unsigned int vertex_count,
 256                 const gp_coord *xy, gp_pixel pixel);
 257 --------------------------------------------------------------------------------
 258
 259 Draws a polygon.
 260
 261 [source,c]
 262 --------------------------------------------------------------------------------
 263 void gp_fill_polygon(gp_pixmap *pixmap, unsigned int vertex_count,
 264                      const gp_coord *xy, gp_pixel pixel);
 265 --------------------------------------------------------------------------------
 266
 267 Draws a filled polygon.
 268
 269 The coordinages are passed in [x0, y0, x1, y1, ...] order, the vertex count
 270 describes a number of nodes, i.e. half of the size of the array.