<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Creating and using fonts - ClanLib Game SDK</title>
<link rel="stylesheet" type="text/css" href="../../default.css">
</head>
<body style="background-color: #a4daea; color: black; margin: 1em 3em 1em 3em;">
<div style="border-style: solid; border-width:thin; border-color: black;">
<div style="background-color: white; color: black; padding: .3em 1em .3em 1em; border-bottom-style: dotted; border-bottom-width: 2px;">
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td align="center">
<h1>
<a href="http://www.clanlib.org"><img style="border-style: none; padding-right: 130px;" src="../../gfx/clanlib.png" alt="ClanLib"></a>
</h1>
</td>
</tr>
</table>
<!--<div class="menu">
<a href="index.html">News</a>
<a href="intro.html">About</a>
<a href="download.html">Download</a>
<a href="cvs.html">CVS</a>
<a class="active" href="docs.html">Docs</a>
<a href="games.html">Games</a>
<a href="contact.html">Contact</a>
<a href="links.html">Links</a>
</div>-->
</div>
<div style="background-color: white; padding: 1em 3em 1em 3em;">
<!-- clanlib header end -->
<div style="border-bottom-style: dotted; border-bottom-width: 1px; margin-bottom: 1em;"><h2>Creating and using fonts</h2></div>
<p>ClanLib makes it possible to create your own font in an image file or use
existing system fonts. You can then use the fonts to display text to the
player, such as FPS counters, dialog boxes, and other such information.
ClanLib gives you a great deal of control over how your text is
displayed.</p>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Creating fonts</h3></div>
<p>You can make your own font by drawing all the glyphs (or character
images) in an image file. Once that is done, you must tell ClanLib how to
separate the file into individual glyphs. The easiest way to do this is to
use alpha-cutting. To create an alpha-cut font, open up your favorite image
editor, and create a wide, short, transparent image:</p>
<img src="Images/font0.png" width="363" height="332" />
<p>Then type a long string of characters, which will become the characters
in your font. Usually this string will look something like this:</p>
<img src="Images/font1.png" width="551" height="358" />
<p>The example set of character glyphs above isn't very useful: usually, you
will want to include at least the entire alphabet, probably in upper and
lower case, all the numbers, and quite a few of the symbols. However, you do
not have to, and in some cases, you won't want to. For example, an LCD
numerals font might only include 0-9 and the colon.</p>
<p>Once you've typed the string in, you must clean up the image to make
certain that there's at least one column of transparency between each
character. A common problem is the double-quote character: you may need to
add a slightly-visible pixel between the two quote marks to make ClanLib
treat it as a single character. Here's a before and after example:</p>
<img src="Images/font2.png" width="236" height="251" />
<img src="Images/font3.png" width="236" height="251" />
<p>ClanLib uses the same mechanism to load bitmap font glyphs as it does to
separate the frames of a sprite from a single file. In fact, a
<a href="../Reference/html/CL_Sprite.html">CL_Sprite</a> is used for bitmap fonts: you can use any
sprite creation method to create the glyphs of a font, including
palette-cutting, grid-cutting, storing glyphs in individual files, or any
combination of the above. See the <a href="sprites_overview.html">sprites
overview</a> for more information.</p>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Font resources</h3></div>
<p>You should probably already have a resource file or two as part of your
game; if you don't, then you're missing out on a lot of flexibility. See the
<a href="resources-1.html">resource overview</a> for more info.</p>
<p>You will need two resources: one for the sprite containing all the
glyphs, and one for the font itself. The only one you use directly is the
font resource.</p>
<p>Assuming you'd like to create a font called FontA based on an alpha-cut
image called font_a.tga, containing the glyphs in the visual example above,
your should have some entries in your resources file that look like
this:</p>
<ul><pre><font face="Arial,Courier New,Courier"><sprite name="Font_glyphs">
<image file="font.tga"><alpha /></image>
</sprite>
<font name="Font">
<bitmap glyphs="Font_glyphs" letters="AaBb1234.,&quot;" />
</font>
</font></pre></ul>
<p>The following options for sprite-based font resources are supported:</p>
<ul>
<li>glyphs : Required. The name of the resource of the sprite to extract glyphs from.</li>
<li>letters : Required. The ASCII characters that are in the font, in the same order as they appear in the sprite.</li>
<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>
<li>monospace : If non-zero, causes all glyphs in the font to seem to be the width of the widest glyph. This results
in a typewriter-like font.</li>
</ul>
<p>You can also use resources for system fonts, with the following
options:</p>
<ul>
<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>
<li>height : Required. The requested height of the font in pixels. What this means depends on how the OS's font interface works.</li>
<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>
<li>letters : The ASCII characters that should be in the font; if unspecified, it will put in all the characters it can find
in the font.</li>
<li>bold : If non-zero, requests bold text.</li>
<li>italic : If non-zero, requests italic text.</li>
<li>underline : If non-zero, requests underlined text.</li>
<li>strikeout : If non-zero, requests text with a horizontal line through the middle of the glyphs.</li>
</ul>
<p>And these options work for both sprite-based and system fonts:</p>
<ul>
<li>width_offset : This is used to apply an offset to the widths of all glyphs. You can set this
to a negative value to kern characters together (this may be useful, for example, for italic fonts), or
positive to spread characters apart. You can always change this value afterwards using
<a href="../Reference/html/CL_Font.html">CL_Font</a>::set_width_offset.</li>
<li>height_offset : This is an offset applied to the height of the font. ClanLib uses the
height of the tallest glyph to determine the height of the line: you can use this option to give it
a positive offset, spreading lines apart, or a negative offset, merging lines together. You can always
change this afterwards using <a href="../Reference/html/CL_Font.html">CL_Font</a>::set_height_offset.</li>
<li>delims : This string of characters is what separates words from each other when word wrapping. Do not include
the newline character here, since that is implicitly a delimiter. By default, the only delimiter is the space.</li>
</ul>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Using fonts</h3></div>
<p>If your resources file was named 'resources.xml', then you can load the
font into your program from the resource using the following C++ code:</p>
<ul><pre><font face="Arial,Courier New,Courier"> CL_ResourceManager manager("resources.xml");
CL_Font font_a("Font_A", &manager);
</font></pre></ul>
<p>Once you've done that, you can call
<a href="../Reference/html/CL_Font.html">CL_Font</a>::draw(int, int, std::string) to print arbitrary
text. For example:</p>
<ul><pre><font face="Arial,Courier New,Courier"> font_a.draw(150, 150,
"How many boards would the Mongols hoard,"
" if the Mongol hordes got bored?\n"
" --Calvin and Hobbes");
</font></pre></ul>
<p>You can also print into a <a href="../Reference/html/CL_Rect.html">CL_Rect</a> using
<a href="../Reference/html/CL_Font.html">CL_Font</a>::draw(CL_Rect, std::string). If you do this,
the text will be word-wrapped to the width of the rectangle, and will not
exceed the rectangle's height:</p>
<ul><pre><font face="Arial,Courier New,Courier"> CL_Rect bounds_rect(50, 50, 300, 350);
font_a.draw(bounds_rect,
"Gau: There's treasure! It's shiny, shiny, shiny shiny shiny!\n"
"Sabin: Could anything be that shiny?"
);
</font></pre></ul>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>CL_TextStyler</h3></div>
<p><a href="../Reference/html/CL_TextStyler.html">CL_TextStyler</a> is a class which contains one or more <a href="../Reference/html/CL_Font.html">CL_Font</a>s. You can then
use a CL_TextStyler to draw strings with various effects (scaling,
justification, etc), and to change between fonts mid-string.</p>
<p><a href="../Reference/html/CL_TextStyler.html">CL_TextStyler</a> keeps track of the fonts it contains by naming them with
strings. Every CL_TextStyler should have a font named "default", which is used when no particular font
is explicitly specified. You can name any other fonts in the CL_TextStyler whatever you like.</p>
<p>You can create a working <a href="../Reference/html/CL_TextStyler.html">CL_TextStyler</a> by using its default constructor, then
using the add_font() method to copy fonts in:</p>
<ul><pre><font face="Arial,Courier New,Courier">CL_TextStyler ts;
ts.add_font("default", some_font);
ts.add_font("bold", another_font);
</font></pre></ul>
<p>It's also possible to keep CL_TextStylers in your resource files. Here's
the same CL_TextStyler as above, in resource form, assuming that some_font
and another_font are in the resource file:</p>
<ul><pre><font face="Arial,Courier New,Courier"><text_styler name="ts">
<font name="default" font="some_font" />
<font name="bold" font="another_font" />
</text_styler>
</font></pre></ul>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Using CL_TextStyler</h3></div>
<p><a href="../Reference/html/CL_TextStyler.html">CL_TextStyler</a>'s interface is almost identical to <a href="../Reference/html/CL_Font.html">CL_Font</a>'s. The main
difference is in the strings you pass, which can contain curly-bracketed
tags to change the font:</p>
<ul><pre><font face="Arial,Courier New,Courier">ts.draw(0, 0, "This text is in the default font. {bold}And this text is in another font.{/bold} Narf!");
</font></pre></ul>
<p>To draw a "{" character without starting a tag, you can simply put two in
a row, which is escaped to mean a single left curly-bracket (right
curly-brackets don't need need to be escaped):</p>
<ul><pre><font face="Arial,Courier New,Courier">ts.draw(0, 0, "This {{ is a left curly brace. Only one of them will appear in the actual output.");
</font></pre></ul>
<p>You can also use square-bracket tags that change the justification, color, or
scale, or insert newlines:</p>
<ul><pre><font face="Arial,Courier New,Courier">ts.draw(0, 0,
"This is a line that's at regular scale and is left justified.\n"
"[c red]Red[/c][c 0 255 0]Blue[/c][c 0 0 255 170]Green (slightly transparent)[/c].\n"
"[s 2.0][j center]Here's a line that's center justified and double-sized.\n"
"[s 2.0][j right]Here's a line that's quadruple-sized (2.0x2.0) and right justified.\n"
"[/j][/j][/s][/s]This line is back at regular size and left justification.\n"
"This text is on it's line.[n]This text is on a different line.[n]"
"There's no difference between using 'n' tags and regular ASCII newlines.\n"
"[[ Here is a literal left square bracket; only one will appear in the actual output.\n"
);
</font></pre></ul>
<p>The above example also demonstrates a handy little C trick: literal
strings that appear next to each other will be attached together into a single
string by the compiler.</p>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>CL_GlyphBuffer</h3></div>
<p>For unusual text effects, you can use a <a href="../Reference/html/CL_GlyphBuffer.html">CL_GlyphBuffer</a> to
alter the details of <a href="../Reference/html/CL_Font.html">CL_Font</a>'s or <a href="../Reference/html/CL_TextStyler.html">CL_TextStyler</a>'s output before it is drawn
to the screen. CL_Font and CL_TextStyler both have draw_to_gb() methods, which you
can use to send glyph information to a CL_GlyphBuffer instead of the
display. Then, you can modify the CL_GlyphBuffer's various data structures,
and use the CL_GlyphBuffer's draw() method to display your post-edited text.
For example, you can use CL_GlyphBuffer to change justification:</p>
<ul><pre><font face="Arial,Courier New,Courier">CL_GlyphBuffer gb;
some_font.draw_to_gb("Eat\nFlaming\nDeath!", gb);
gb.justify_center(); //Applies to all text in the buffer by default
gb.draw(0,0); //Draws the upper left corner of the text bounding box at given pos
</font></pre></ul>
<p>You can also use the draw_to_gb() functions several times in a row with
different text and/or fonts, which causes the text to be combined in the
same way that <a href="../Reference/html/CL_TextStyler.html">CL_TextStyler</a> combines text from several fonts. For example,
to duplicate the first CL_TextStyler example above
using only <a href="../Reference/html/CL_Font.html">CL_Font</a>s and <a href="../Reference/html/CL_GlyphBuffer.html">CL_GlyphBuffer</a>:</p>
<ul><pre><font face="Arial,Courier New,Courier">CL_GlyphBuffer gb;
some_font.draw_to_gb("This text is in the default font. ", gb);
another_font.draw_to_gb("And this text is in another font.", gb);
some_font.draw_to_gb("Narf!", gb);
gb.draw(0, 0);
</font></pre></ul>
<p>Editing operations on a <a href="../Reference/html/CL_GlyphBuffer.html">CL_GlyphBuffer</a> have to occur in a specific
order, with any number of calls to either or both of
<a href="../Reference/html/CL_Font.html">CL_Font</a>::draw_to_gb() or <a href="../Reference/html/CL_TextStyler.html">CL_TextStyler</a>::draw_to_gb() first, any number of
calls to CL_GlyphBuffer's justification methods second, and any manual
modification of the CL_GlyphBuffer's contents last. You can skip past any of
these steps, but you cannot go backwards in the list unless you clear the
CL_GlyphBuffer and start over again from scratch. </p>
<!-- clanlib footer begin -->
<div style="margin-top: 0em; text-align: center; color: #a0a0a0; border-top-style: dotted; border-top-width: 1px;">
Questions or comments, write to the <a href="http://clanlib.org/contact.html">ClanLib mailing list</a>.
</div>
</div>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
a2116f36018873d572acbcadddb8e994
>
files
>
24
