doc/text.txt

   1 Text
   2 ----
   3 Text drawing is controlled by the <<TextStyle,GP_TextStyle>> structure. This
   4 structure carries information about font, letter spacing and pixel
   5 multiplication and spacing. (If no font is specified, the default mono-space
   6 font is used.)
   7
   8 You may want to see the link:coordinate_system.html[coordinate system] first.
   9
  10 [source,c]
  11 --------------------------------------------------------------------------------
  12 #include <GP.h>
  13 /* or */
  14 #include <text/GP_Text.h>
  15
  16 /* Where the text should be drawn relatively to the specified point */
  17 typedef enum GP_TextAlign {
  18         GP_ALIGN_LEFT = 0x01,           /* to the left from the point */
  19         GP_ALIGN_CENTER = 0x02,         /* centered on the point */
  20         GP_ALIGN_RIGHT = 0x03,          /* to the right from the point */
  21         GP_VALIGN_ABOVE = 0x10,         /* above the point */
  22         GP_VALIGN_CENTER = 0x20,        /* centered on the point */
  23         GP_VALIGN_BASELINE = 0x30,      /* baseline is on the point */
  24         GP_VALIGN_BELOW = 0x40          /* below the point */
  25 } GP_TextAlign;
  26
  27 void GP_Text(GP_Context *context, const GP_TextStyle *style,
  28              int x, int y, int align, const char *str, GP_Pixel pixel);
  29
  30
  31 GP_Size GP_Print(GP_Context *context, const GP_TextStyle *style,
  32                  GP_Coord x, GP_Coord y, int align,
  33                  GP_Pixel fg_color, GP_Pixel bg_color, const char *fmt, ...);
  34
  35 GP_Size GP_VPrint(GP_Context *context, const GP_TextStyle *style,
  36                   GP_Coord x, GP_Coord y, int align,
  37                   GP_Pixel fg_color, GP_Pixel bg_color,
  38                   const char *fmt, va_list va);
  39 --------------------------------------------------------------------------------
  40
  41 Draws text at the position x and y; the alignment of the text in relation
  42 to the point is specified by alignment flags.
  43
  44 If the 'style' argument is 'NULL', a default style is used.
  45
  46 The text size can be computed by following functions:
  47
  48 [source,c]
  49 --------------------------------------------------------------------------------
  50 #include <GP.h>
  51 /* or */
  52 #include <text/GP_TextMetric.h>
  53
  54 unsigned int GP_TextWidth(const GP_TextStyle *style, const char *str);
  55 --------------------------------------------------------------------------------
  56
  57 Returns the width (in pixels) that would be occupied by the string if rendered
  58 using the specified style.
  59
  60 Computing a length of a given string is more complicated than it appears to
  61 be. The first letter needs 'advance - bearing' pixels, the middle letters
  62 needs 'advance' pixels and the last letter needs 'bearing + width' pixel. See
  63 link:images/fonts/glyph_metrics.png[Glyph Metrics] for a description of the
  64 terms used in this paragraph.
  65
  66 [source,c]
  67 --------------------------------------------------------------------------------
  68 #include <GP.h>
  69 /* or */
  70 #include <text/GP_TextMetric.h>
  71
  72 unsigned int GP_TextMaxWidth(const GP_TextStyle *style, unsigned int len);
  73 --------------------------------------------------------------------------------
  74
  75 Returns maximum text width, in pixels, for string with 'len' letters.
  76
  77 This call simply computes width of a string rendered with 'len' largest glyphs
  78 (letters) in the font. Because of this the resulting size is often much larger
  79 than needed.
  80
  81 [source,c]
  82 --------------------------------------------------------------------------------
  83 #include <GP.h>
  84 /* or */
  85 #include <text/GP_TextMetric.h>
  86
  87 GP_Size GP_TextMaxStrWidth(const GP_TextStyle *style, const char *str,
  88                            unsigned int len);
  89 --------------------------------------------------------------------------------
  90
  91 Returns maximum text width, in pixels, for a string with 'len' letters that
  92 are composed only of letters from 'str'.
  93
  94 This call simply computes width of a string rendered with largest letter from
  95 'str' and with 'len' characters.
  96
  97 [source,c]
  98 --------------------------------------------------------------------------------
  99 #include <GP.h>
 100 /* or */
 101 #include <text/GP_TextMetric.h>
 102
 103 unsigned int GP_TextAscent(const GP_TextStyle *style);
 104 --------------------------------------------------------------------------------
 105
 106 The Ascent is the height in pixels from the top to the baseline.
 107
 108 The baseline is imaginary line that letters are positioned upon and the ascent
 109 is usually height of capital letter, but it may be larger for certain fonts.
 110
 111 [source,c]
 112 --------------------------------------------------------------------------------
 113 #include <GP.h>
 114 /* or */
 115 #include <text/GP_TextMetric.h>
 116
 117 unsigned int GP_TextDescent(const GP_TextStyle *style);
 118 --------------------------------------------------------------------------------
 119
 120 The Descent is the height in pixels from baseline to the bottom.
 121
 122 The baseline is imaginary line that letters are positioned upon and the
 123 descent is usually height of upper part of the letter y that goes under the
 124 baseline, but it may be larger for certain fonts.
 125
 126 [source,c]
 127 --------------------------------------------------------------------------------
 128 #include <GP.h>
 129 /* or */
 130 #include <text/GP_TextMetric.h>
 131
 132 unsigned int GP_TextHeight(const GP_TextStyle *style);
 133 --------------------------------------------------------------------------------
 134
 135 The Height is size of the font from top to the bottom, i.e. equals exactly to
 136 the sum of ascent and descent.
 137
 138 This simply returns height that is needed to draw a line of a text using a
 139 certain font style (without the spacing between the lines).
 140
 141 [[TextStyle]]
 142 TextStyle
 143 ~~~~~~~~~
 144
 145 [source,c]
 146 --------------------------------------------------------------------------------
 147 #include <GP.h>
 148 /* or */
 149 #include <text/GP_TextStyle.h>
 150
 151 typedef struct GP_TextStyle {
 152         const struct GP_FontFace *font;
 153
 154         /* Spacing between pixels (0 is the default, no spacing). */
 155         int pixel_xspace, pixel_yspace;
 156
 157         /* Multiplier of pixel width/height (1 is default). */
 158         int pixel_xmul, pixel_ymul;
 159
 160         /* Extra spacing (in pixels) between characters. */
 161         int char_xspace;
 162
 163 } GP_TextStyle;
 164 --------------------------------------------------------------------------------
 165
 166 The TextStyle structure describes the parameters for text rendering.
 167
 168 The first parameter is font being used.
 169 TODO: link to font format and description.
 170
 171 The 'xspace' and 'yspace' parameters controls spacing between the pixels and
 172 the 'xmul' and 'ymul' describes pixel multiplication in respective directions.
 173
 174 The 'char_xspace' is used to add additional space between letters.
 175
 176 .Default Console Font xmul=ymul=1 xspace=yspace=0
 177 image::images/fonts/default_console_font.png["Default Console Font"]
 178
 179 .Default Console Font xmul=ymul=2 xspace=yspace=-1
 180 image::images/fonts/default_console_font_embolding.png["Default Console Font"]
 181
 182 .Default Console Font xmul=ymul=2 xspace=yspace=1
 183 image::images/fonts/default_console_font_big.png["Default Console Font"]
 184
 185
 186 Compiled-in Fonts
 187 ~~~~~~~~~~~~~~~~~
 188
 189 There is a global constant pointer to each compiled-in font structure, see
 190 'include/text/GP_Fonts.h'.
 191
 192 .Default Console Font
 193 image::images/fonts/default_console_font.png["Default Console Font"]
 194
 195 .Default Proportional Font
 196 image::images/fonts/default_proportional_font.png["Default Proportional Font"]
 197
 198 .Font Tiny Mono (GP_FontTinyMono)
 199 image::images/fonts/font_tiny_mono.png["Font Tiny Mono"]
 200
 201 .Font Tiny (GP_FontTiny)
 202 image::images/fonts/font_tiny.png["Font Tiny"]
 203
 204 TrueType Fonts
 205 ~~~~~~~~~~~~~~
 206
 207 [source,c]
 208 --------------------------------------------------------------------------------
 209 /*
 210  * Load font face from file.
 211  */
 212 GP_FontFace *GP_FontFaceLoad(const char *path, uint32_t width, uint32_t height);
 213
 214 /*
 215  * Free the font face.
 216  */
 217 void GP_FontFaceFree(GP_FontFace *self);
 218 --------------------------------------------------------------------------------
 219
 220 Renders TrueType font using link:http://www.freetype.org[FreeType] (currently
 221 printable ASCII only) into GFXprim font structures.
 222
 223 One of the 'width' or 'height' may be zero, which means that the second value
 224 should be computed accordingly.
 225
 226 NOTE: If you pass both 'width' and 'height' non-zero the resulting font may
 227       look strange as this action forced unnatural aspect ratio.
 228
 229
 230 TIP: For Font and TextStyle handling see link:example_fonts.html[examples].