Debian Codegraph @

Documentation/Overview/font_overview-1.xml

raw
1 <xml>
2 <head>
3 <title>Creating and using fonts</title>
4 </head>
5 <body>
6
7 <p>ClanLib makes it possible to create your own font in an image file or use
8 existing system fonts. You can then use the fonts to display text to the
9 player, such as FPS counters, dialog boxes, and other such information.
10 ClanLib gives you a great deal of control over how your text is
11 displayed.</p>
12
13 <h3>Creating fonts</h3>
14
15 <p>You can make your own font by drawing all the glyphs (or character
16 images) in an image file. Once that is done, you must tell ClanLib how to
17 separate the file into individual glyphs. The easiest way to do this is to
18 use alpha-cutting. To create an alpha-cut font, open up your favorite image
19 editor, and create a wide, short, transparent image:</p>
20
21 <img src="Images/font0.png" width="363" height="332" />
22
23 <p>Then type a long string of characters, which will become the characters
24 in your font. Usually this string will look something like this:</p>
25
26 <img src="Images/font1.png" width="551" height="358" />
27
28 <p>The example set of character glyphs above isn't very useful: usually, you
29 will want to include at least the entire alphabet, probably in upper and
30 lower case, all the numbers, and quite a few of the symbols. However, you do
31 not have to, and in some cases, you won't want to. For example, an LCD
32 numerals font might only include 0-9 and the colon.</p>
33
34 <p>Once you've typed the string in, you must clean up the image to make
35 certain that there's at least one column of transparency between each
36 character. A common problem is the double-quote character: you may need to
37 add a slightly-visible pixel between the two quote marks to make ClanLib
38 treat it as a single character. Here's a before and after example:</p>
39
40 <img src="Images/font2.png" width="236" height="251" />
41 <img src="Images/font3.png" width="236" height="251" />
42
43 <p>ClanLib uses the same mechanism to load bitmap font glyphs as it does to
44 separate the frames of a sprite from a single file. In fact, a
45 <codelink>CL_Sprite</codelink> is used for bitmap fonts: you can use any
46 sprite creation method to create the glyphs of a font, including
47 palette-cutting, grid-cutting, storing glyphs in individual files, or any
48 combination of the above. See the <a href="sprites_overview.html">sprites
49 overview</a> for more information.</p>
50
51 <h3>Font resources</h3>
52
53 <p>You should probably already have a resource file or two as part of your
54 game; if you don't, then you're missing out on a lot of flexibility. See the
55 <a href="resources-1.html">resource overview</a> for more info.</p>
56
57 <p>You will need two resources: one for the sprite containing all the
58 glyphs, and one for the font itself. The only one you use directly is the
59 font resource.</p>
60
61 <p>Assuming you'd like to create a font called FontA based on an alpha-cut
62 image called font_a.tga, containing the glyphs in the visual example above,
63 your should have some entries in your resources file that look like
64 this:</p>
65
66 <code>
67 &lt;sprite name="Font_glyphs"&gt;
68 &lt;image file="font.tga"&gt;&lt;alpha /&gt;&lt;/image&gt;
69 &lt;/sprite&gt;
70
71 &lt;font name="Font"&gt;
72 &lt;bitmap glyphs="Font_glyphs" letters="AaBb1234.,&amp;quot;" /&gt;
73 &lt;/font&gt;
74 </code>
75
76 <p>The following options for sprite-based font resources are supported:</p>
77
78 <ul>
79 <li>glyphs : Required. The name of the resource of the sprite to extract glyphs from.</li>
80 <li>letters : Required. The ASCII characters that are in the font, in the same order as they appear in the sprite.</li>
81 <li>spacelen : The width, in pixels, of a space. If this value is unspecified, it will use the average of the font's glyph widths.</li>
82 <li>monospace : If non-zero, causes all glyphs in the font to seem to be the width of the widest glyph. This results
83 in a typewriter-like font.</li>
84 </ul>
85
86 <p>You can also use resources for system fonts, with the following
87 options:</p>
88
89 <ul>
90 <li>font : Required. The name of the system font to use. What this precisely means depends on how your OS's font interface works.</li>
91 <li>height : Required. The requested height of the font in pixels. What this means depends on how the OS's font interface works.</li>
92 <li>width : The requested width of the font in pixels. If unspecified, attempts to find the best matching width for the given height. Again, what this means is dependent upon the details of the OS's font interface.</li>
93 <li>letters : The ASCII characters that should be in the font; if unspecified, it will put in all the characters it can find
94 in the font.</li>
95 <li>bold : If non-zero, requests bold text.</li>
96 <li>italic : If non-zero, requests italic text.</li>
97 <li>underline : If non-zero, requests underlined text.</li>
98 <li>strikeout : If non-zero, requests text with a horizontal line through the middle of the glyphs.</li>
99 </ul>
100
101 <p>And these options work for both sprite-based and system fonts:</p>
102
103 <ul>
104 <li>width_offset : This is used to apply an offset to the widths of all glyphs. You can set this
105 to a negative value to kern characters together (this may be useful, for example, for italic fonts), or
106 positive to spread characters apart. You can always change this value afterwards using
107 <codelink>CL_Font</codelink>::set_width_offset.</li>
108 <li>height_offset : This is an offset applied to the height of the font. ClanLib uses the
109 height of the tallest glyph to determine the height of the line: you can use this option to give it
110 a positive offset, spreading lines apart, or a negative offset, merging lines together. You can always
111 change this afterwards using <codelink>CL_Font</codelink>::set_height_offset.</li>
112 <li>delims : This string of characters is what separates words from each other when word wrapping. Do not include
113 the newline character here, since that is implicitly a delimiter. By default, the only delimiter is the space.</li>
114 </ul>
115
116 <h3>Using fonts</h3>
117
118 <p>If your resources file was named 'resources.xml', then you can load the
119 font into your program from the resource using the following C++ code:</p>
120
121 <code>
122 CL_ResourceManager manager("resources.xml");
123 CL_Font font_a("Font_A", &manager);
124 </code>
125
126 <p>Once you've done that, you can call
127 <codelink>CL_Font</codelink>::draw(int, int, std::string) to print arbitrary
128 text. For example:</p>
129
130 <code>
131 font_a.draw(150, 150,
132 "How many boards would the Mongols hoard,"
133 " if the Mongol hordes got bored?\n"
134 " --Calvin and Hobbes");
135 </code>
136
137 <p>You can also print into a <codelink>CL_Rect</codelink> using
138 <codelink>CL_Font</codelink>::draw(CL_Rect, std::string). If you do this,
139 the text will be word-wrapped to the width of the rectangle, and will not
140 exceed the rectangle's height:</p>
141
142 <code>
143 CL_Rect bounds_rect(50, 50, 300, 350);
144 font_a.draw(bounds_rect,
145 "Gau: There's treasure! It's shiny, shiny, shiny shiny shiny!\n"
146 "Sabin: Could anything be that shiny?"
147 );
148 </code>
149
150 <h3>CL_TextStyler</h3>
151
152 <p><codelink>CL_TextStyler</codelink> is a class which contains one or more <codelink>CL_Font</codelink>s. You can then
153 use a CL_TextStyler to draw strings with various effects (scaling,
154 justification, etc), and to change between fonts mid-string.</p>
155
156 <p><codelink>CL_TextStyler</codelink> keeps track of the fonts it contains by naming them with
157 strings. Every CL_TextStyler should have a font named "default", which is used when no particular font
158 is explicitly specified. You can name any other fonts in the CL_TextStyler whatever you like.</p>
159
160 <p>You can create a working <codelink>CL_TextStyler</codelink> by using its default constructor, then
161 using the add_font() method to copy fonts in:</p>
162
163 <code>
164 CL_TextStyler ts;
165 ts.add_font("default", some_font);
166 ts.add_font("bold", another_font);
167 </code>
168
169 <p>It's also possible to keep CL_TextStylers in your resource files. Here's
170 the same CL_TextStyler as above, in resource form, assuming that some_font
171 and another_font are in the resource file:</p>
172
173 <code>
174 &lt;text_styler name="ts"&gt;
175 &lt;font name="default" font="some_font" /&gt;
176 &lt;font name="bold" font="another_font" /&gt;
177 &lt;/text_styler&gt;
178 </code>
179
180 <h3>Using CL_TextStyler</h3>
181
182 <p><codelink>CL_TextStyler</codelink>'s interface is almost identical to <codelink>CL_Font</codelink>'s. The main
183 difference is in the strings you pass, which can contain curly-bracketed
184 tags to change the font:</p>
185
186 <code>
187 ts.draw(0, 0, "This text is in the default font. {bold}And this text is in another font.{/bold} Narf!");
188 </code>
189
190 <p>To draw a "{" character without starting a tag, you can simply put two in
191 a row, which is escaped to mean a single left curly-bracket (right
192 curly-brackets don't need need to be escaped):</p>
193
194 <code>
195 ts.draw(0, 0, "This {{ is a left curly brace. Only one of them will appear in the actual output.");
196 </code>
197
198 <p>You can also use square-bracket tags that change the justification, color, or
199 scale, or insert newlines:</p>
200
201 <code>
202 ts.draw(0, 0,
203 "This is a line that's at regular scale and is left justified.\n"
204 "[c red]Red[/c][c 0 255 0]Blue[/c][c 0 0 255 170]Green (slightly transparent)[/c].\n"
205 "[s 2.0][j center]Here's a line that's center justified and double-sized.\n"
206 "[s 2.0][j right]Here's a line that's quadruple-sized (2.0x2.0) and right justified.\n"
207 "[/j][/j][/s][/s]This line is back at regular size and left justification.\n"
208 "This text is on it's line.[n]This text is on a different line.[n]"
209 "There's no difference between using 'n' tags and regular ASCII newlines.\n"
210 "[[ Here is a literal left square bracket; only one will appear in the actual output.\n"
211 );
212 </code>
213
214 <p>The above example also demonstrates a handy little C trick: literal
215 strings that appear next to each other will be attached together into a single
216 string by the compiler.</p>
217
218 <h3>CL_GlyphBuffer</h3>
219
220 <p>For unusual text effects, you can use a <codelink>CL_GlyphBuffer</codelink> to
221 alter the details of <codelink>CL_Font</codelink>'s or <codelink>CL_TextStyler</codelink>'s output before it is drawn
222 to the screen. CL_Font and CL_TextStyler both have draw_to_gb() methods, which you
223 can use to send glyph information to a CL_GlyphBuffer instead of the
224 display. Then, you can modify the CL_GlyphBuffer's various data structures,
225 and use the CL_GlyphBuffer's draw() method to display your post-edited text.
226 For example, you can use CL_GlyphBuffer to change justification:</p>
227
228 <code>
229 CL_GlyphBuffer gb;
230 some_font.draw_to_gb("Eat\nFlaming\nDeath!", gb);
231 gb.justify_center(); //Applies to all text in the buffer by default
232 gb.draw(0,0); //Draws the upper left corner of the text bounding box at given pos
233 </code>
234
235 <p>You can also use the draw_to_gb() functions several times in a row with
236 different text and/or fonts, which causes the text to be combined in the
237 same way that <codelink>CL_TextStyler</codelink> combines text from several fonts. For example,
238 to duplicate the first CL_TextStyler example above
239 using only <codelink>CL_Font</codelink>s and <codelink>CL_GlyphBuffer</codelink>:</p>
240
241 <code>
242 CL_GlyphBuffer gb;
243 some_font.draw_to_gb("This text is in the default font. ", gb);
244 another_font.draw_to_gb("And this text is in another font.", gb);
245 some_font.draw_to_gb("Narf!", gb);
246 gb.draw(0, 0);
247 </code>
248
249 <p>Editing operations on a <codelink>CL_GlyphBuffer</codelink> have to occur in a specific
250 order, with any number of calls to either or both of
251 <codelink>CL_Font</codelink>::draw_to_gb() or <codelink>CL_TextStyler</codelink>::draw_to_gb() first, any number of
252 calls to CL_GlyphBuffer's justification methods second, and any manual
253 modification of the CL_GlyphBuffer's contents last. You can skip past any of
254 these steps, but you cannot go backwards in the list unless you clear the
255 CL_GlyphBuffer and start over again from scratch. </p>
256
257 </body>
258 </xml>