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