doc/drawing_api.txt

   1 Drawing primitives
   2 ------------------
   3
   4 Fill
   5 ~~~~
   6
   7 [source,c]
   8 --------------------------------------------------------------------------------
   9 void GP_Fill(GP_Context *context, GP_Pixel pixel);
  10 --------------------------------------------------------------------------------
  11
  12 Fills the whole context bitmap with the specified pixel value. This has the
  13 same effect as calling 'GP_FillRect(context, 0, 0, context->w, context->h, pixel)'.
  14
  15 Lines
  16 ~~~~~
  17
  18 [source,c]
  19 --------------------------------------------------------------------------------
  20 void GP_HLineXXY(GP_Context *context, GP_Coord x0, GP_Coord x1, GP_Coord y,
  21                  GP_Pixel pixel);
  22
  23 void GP_HLine(GP_Context *context, GP_Coord x0, GP_Coord x1, GP_Coord y,
  24               GP_Pixel pixel);
  25 --------------------------------------------------------------------------------
  26
  27 Draws a horizontal line from (x0, y) to (x1, y), inclusive. The coordinates
  28 x0, x1 can be specified in any order.
  29
  30 'GP_HLine()' is an alias for 'GP_HLineXXY()'.
  31
  32 [source,c]
  33 --------------------------------------------------------------------------------
  34 void GP_HLineXYW(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size w,
  35                  GP_Pixel pixel);
  36 --------------------------------------------------------------------------------
  37
  38 Draws a horizontal line from (x, y) to (x+w-1, y), inclusive.
  39
  40
  41 [source,c]
  42 --------------------------------------------------------------------------------
  43 void GP_VLineXYY(GP_Context *context, GP_Coord x, GP_Coord y0, GP_Coord y1,
  44                  GP_Pixel pixel);
  45
  46 void GP_VLine(GP_Context *context, GP_Coord x, GP_Coord y0, GP_Coord y1,
  47               GP_Pixel pixel);
  48 --------------------------------------------------------------------------------
  49
  50 Draws a vertical line from (x, y0) to (x, y1), inclusive. The coordinates
  51 y0, y1 can be specified in any order.
  52
  53 'GP_VLine()' is an alias for 'GP_VLineXYY()'.
  54
  55 [source,c]
  56 --------------------------------------------------------------------------------
  57 void GP_VLineXYH(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size h,
  58                  GP_Pixel pixel);
  59
  60 --------------------------------------------------------------------------------
  61
  62 Draws a vertical line from (x, y) to (x, y+h-1), inclusive.
  63
  64 [source,c]
  65 --------------------------------------------------------------------------------
  66 void GP_Line(GP_Context *context, GP_Coord x0, GP_Coord y0,
  67              GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
  68 --------------------------------------------------------------------------------
  69
  70 Draws a line from (x0, y0) to (x1, y1), inclusive. The starting and ending
  71 point can be specified in any order (the implementation guarantees that
  72 exactly the same set of pixels will be drawn in both cases).
  73
  74 Circles
  75 ~~~~~~~
  76
  77 [source,c]
  78 --------------------------------------------------------------------------------
  79 void GP_Circle(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter,
  80                GP_Size r, GP_Pixel pixel);
  81 --------------------------------------------------------------------------------
  82
  83 Draws a circle centered at (xcenter, ycenter) with radius 'r' (in pixels).
  84
  85 The circle is drawn so that all affected pixels will fit into a square
  86 specified by points (xcenter-r, ycenter-r, xcenter+r, ycenter+r), inclusive.
  87
  88 [source,c]
  89 --------------------------------------------------------------------------------
  90 void GP_FillCircle(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter,
  91                    GP_Size r, GP_Pixel pixel);
  92 --------------------------------------------------------------------------------
  93
  94 Draws a filled circle.
  95
  96 The set of pixels affected by 'GP_FillCircle()' is exactly the same as if
  97 drawing the circle boundary using GP_Circle() and then filling all pixels
  98 within the boundary with the same color.
  99
 100 Rings
 101 ~~~~~
 102 [source,c]
 103 --------------------------------------------------------------------------------
 104 void GP_Ring(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter,
 105              GP_Size r1, GP_Size r2, GP_Pixel pixel);
 106 --------------------------------------------------------------------------------
 107
 108 Draws a ring (two circles centered at (xcenter, ycenter) with radii 'r1' and 'r2').
 109
 110 The result is exactly the same as calling 'GP_Circle()' with the same center
 111 and appropriate radii.
 112
 113 [source,c]
 114 --------------------------------------------------------------------------------
 115 void GP_FillRing(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter,
 116                  GP_Size r1, GP_Size r2, GP_Pixel pixel);
 117 --------------------------------------------------------------------------------
 118
 119 Draws a filled ring.
 120
 121 The smaller of r1 and r2 is used for inner radius and bigger one for outer
 122 radius.
 123
 124 Ellipses
 125 ~~~~~~~~
 126
 127 [source,c]
 128 --------------------------------------------------------------------------------
 129 void GP_Ellipse(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter,
 130                 GP_Size a, GP_Size b, GP_Pixel pixel);
 131 --------------------------------------------------------------------------------
 132
 133 Draws an axis-aligned ellipse.
 134
 135 The ellipse is drawn so that all affected pixels will fit into a rectangle
 136 specified by points (xcenter-a, ycenter-b, xcenter+a, ycenter+b), inclusive.
 137
 138 [source,c]
 139 --------------------------------------------------------------------------------
 140 void GP_FillEllipse(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter,
 141                     GP_Size a, GP_Size b, GP_Pixel pixel);
 142 --------------------------------------------------------------------------------
 143
 144 Draws a filled axis-aligned ellipse.
 145
 146 Triangles
 147 ~~~~~~~~~
 148
 149 [source,c]
 150 --------------------------------------------------------------------------------
 151 void GP_Triangle(GP_Context *context, GP_Coord x0, GP_Coord y0,
 152                  GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 153                  GP_Pixel pixel);
 154 --------------------------------------------------------------------------------
 155
 156 Draws a triangle.
 157
 158 [source,c]
 159 --------------------------------------------------------------------------------
 160 void GP_FillTriangle(GP_Context *context, GP_Coord x0, GP_Coord y0,
 161                      GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 162                      GP_Pixel pixel);
 163 --------------------------------------------------------------------------------
 164
 165 Draws a filled triangle.
 166
 167 Rects
 168 ~~~~~
 169
 170 [source,c]
 171 --------------------------------------------------------------------------------
 172 void GP_RectXYXY(GP_Context *context, GP_Coord x0, GP_Coord y0,
 173                  GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 174
 175 void GP_RectXYWH(GP_Context *context, GP_Coord x, GP_Coord y,
 176                  GP_Size w, GP_Size h, GP_Pixel pixel);
 177
 178 void GP_Rect(GP_Context *context, GP_Coord x0, GP_Coord y0,
 179              GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 180 --------------------------------------------------------------------------------
 181
 182 Draws a rectangle.
 183
 184 The 'GP_RectXYXY()' expects two corner points (x0, y0), and (x1, y1).
 185 The 'GP_RectXYWH()' expects a corner point (x0, y0), width and height.
 186 The 'GP_Rect()' function is an alias for 'GP_RectXYXY()'.
 187
 188 [source,c]
 189 --------------------------------------------------------------------------------
 190 void GP_FillRectXYXY(GP_Context *context, GP_Coord x0, GP_Coord y0,
 191                      GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 192
 193 void GP_FillRectXYWH(GP_Context *context, GP_Coord x, GP_Coord y,
 194                      GP_Size w, GP_Size h, GP_Pixel pixel);
 195
 196 void GP_FillRect(GP_Context *context, GP_Coord x0, GP_Coord y0,
 197                  GP_Coord x1, GP_Coord y1, GP_Pixel pixel);
 198 --------------------------------------------------------------------------------
 199
 200 Draws a filled rectangle.
 201
 202 The 'GP_RectXYXY' fills an area between corner points (x0, y0) and (x1, y1),
 203 inclusive.
 204 The 'GP_RectXYWH' fills an area starting from (x0, y0) with specified width
 205 and height, i.e. from (x0, y0) to (x0 + w, x1 + y), NOT inclusive.
 206 The 'GP_FillRect()' functions is an alias for 'GP_FillRectXYXY()'.
 207
 208 Tetragons
 209 ~~~~~~~~~
 210
 211 [source,c]
 212 --------------------------------------------------------------------------------
 213 void GP_Tetragon(GP_Context *context, GP_Coord x0, GP_Coord y0,
 214                  GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 215                  GP_Coord x3, GP_Coord y3, GP_Pixel pixel);
 216 --------------------------------------------------------------------------------
 217
 218 Draws a tetragon.
 219
 220 [source,c]
 221 --------------------------------------------------------------------------------
 222 void GP_FillTetragon(GP_Context *context, GP_Coord x0, GP_Coord y0,
 223                      GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2,
 224                      GP_Coord x3, GP_Coord y3, GP_Pixel pixel);
 225 --------------------------------------------------------------------------------
 226
 227 Draws a filled tetragon.
 228
 229 Text
 230 ~~~~
 231
 232 Text drawing is controlled by the 'GP_TextStyle' structure defined in
 233 'core/GP_TextStyle.h'. This structure carries the information about font,
 234 letter spacing and pixel multiplication and spacing. (If no font is specified,
 235 the default monospace font is used.)
 236
 237 [source,c]
 238 --------------------------------------------------------------------------------
 239 /* Where the text should be drawn relatively to the specified point */
 240 typedef enum GP_TextAlign {
 241         GP_ALIGN_LEFT = 0x01,           /* to the left from the point */
 242         GP_ALIGN_CENTER = 0x02,         /* centered on the point */
 243         GP_ALIGN_RIGHT = 0x03,          /* to the right from the point */
 244         GP_VALIGN_ABOVE = 0x10,         /* above the point */
 245         GP_VALIGN_CENTER = 0x20,        /* centered on the point */
 246         GP_VALIGN_BASELINE = 0x30,      /* baseline is on the point */
 247         GP_VALIGN_BELOW = 0x40          /* below the point */
 248 } GP_TextAlign;
 249
 250 GP_RetCode GP_Text(GP_Context *context, const GP_TextStyle *style,
 251                    int x, int y, int align, const char *str, GP_Pixel pixel);
 252 --------------------------------------------------------------------------------
 253
 254 Draws text at the position x and y; the alignment of the text in relation
 255 to the point is specified by alignment flags.
 256 If the 'style' argument is NULL, a default style is used.
 257
 258 The text size can be computed by following functions:
 259
 260 [source,c]
 261 --------------------------------------------------------------------------------
 262 unsigned int GP_TextWidth(const GP_TextStyle *style, const char *str);
 263 --------------------------------------------------------------------------------
 264
 265 Returns the width (in pixels) that would be occupied by the string if rendered
 266 using the specified style.
 267
 268 [source,c]
 269 --------------------------------------------------------------------------------
 270 unsigned int GP_TextMaxWidth(const GP_TextStyle *style, unsigned int len);
 271 --------------------------------------------------------------------------------
 272
 273 Returns maximum text width, in pixels, for string with 'len' letters. This call
 274 is useful for variable letter size fonts.
 275
 276 [source,c]
 277 --------------------------------------------------------------------------------
 278 unsigned int GP_TextAscent(const GP_TextStyle *style);
 279 --------------------------------------------------------------------------------
 280
 281 The Ascent is the height in pixels from the top to the baseline.
 282
 283 [source,c]
 284 --------------------------------------------------------------------------------
 285 unsigned int GP_TextDescent(const GP_TextStyle *style);
 286 --------------------------------------------------------------------------------
 287
 288 The Descent is the height in pixels from baseline to the bottom.
 289
 290 [source,c]
 291 --------------------------------------------------------------------------------
 292 unsigned int GP_TextHeight(const GP_TextStyle *style);
 293 --------------------------------------------------------------------------------
 294
 295 The Height is size of the font from top to the bottom, eg. equals exactly to
 296 the sum of ascent and descent.
 297