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