<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>FTGL: FTGL tutorial</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.3 -->
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">FTGL <span id="projectnumber">2.1.3~rc5</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">FTGL User Guide</a> </li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<h1>FTGL tutorial </h1> </div>
</div>
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="starting"></a>
Starting to use FTGL</h2>
<p>Only one header is required to use FTGL:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="ftgl_8h.html">FTGL/ftgl.h</a>></span>
</pre></div><h2><a class="anchor" id="type"></a>
Choosing a font type</h2>
<p>FTGL supports 6 font output types among 3 groups: raster fonts, vector fonts, and texture fonts which are a mixture of both. Each font type has its advantages and disadvantages.</p>
<h3><a class="anchor" id="raster"></a>
Raster fonts</h3>
<p>Raster fonts are made of pixels painted directly on the viewport's framebuffer. They cannot be directly rotated or scaled.</p>
<ul>
<li>Bitmap fonts use 1-bit (2-colour) rasterised glyphs.</li>
<li>Pixmap fonts use 8-bit (256 levels) rasterised glyphs.</li>
</ul>
<div align="center">
<img src="rasterfont.png" alt="rasterfont.png"/>
</div>
<h3><a class="anchor" id="vector"></a>
Vector fonts</h3>
<p>Vector fonts are 3D objects that are rendered at the current matrix location. All position, scale, texture and material effects apply to vector fonts.</p>
<ul>
<li>Polygon fonts use planar triangle meshes and can be texture-mapped.</li>
<li>Outline fonts use OpenGL lines.</li>
<li>Extruded fonts are extruded polygon fonts, with the front, back and side meshes renderable separately to apply different effects and materials.</li>
</ul>
<div align="center">
<img src="vectorfont.png" alt="vectorfont.png"/>
</div>
<h3><a class="anchor" id="texture"></a>
Textured fonts</h3>
<p>Textured fonts are probably the most versatile types. They are fast, antialiased, and can be transformed just like any OpenGL primitive.</p>
<ul>
<li>Texture fonts use one texture per glyph. They are fast because glyphs are stored permanently in the video card's memory.</li>
<li>Buffer fonts use one texture per line of text. They tend to be faster than texture fonts when the same line of text needs to be rendered for more than one frame.</li>
</ul>
<div align="center">
<img src="texturefont.png" alt="texturefont.png"/>
</div>
<h2><a class="anchor" id="creating"></a>
Create font objects</h2>
<p>Creating a font and displaying some text is really straightforward, be it in C or in C++.</p>
<h3><a class="anchor" id="c"></a>
in C</h3>
<div class="fragment"><pre class="fragment"><span class="comment">/* Create a pixmap font from a TrueType file. */</span>
<a class="code" href="FTFont_8h.html#af121f8e0374785b92e3155992d703b17">FTGLfont</a> *font = <a class="code" href="FTGLPixmapFont_8h.html#a74e7a832d440bfd68d1e67e1ad6a6657" title="Create a specialised FTGLfont object for handling pixmap (grey scale) fonts.">ftglCreatePixmapFont</a>(<span class="stringliteral">"/home/user/Arial.ttf"</span>);
<span class="comment">/* If something went wrong, bail out. */</span>
<span class="keywordflow">if</span>(!font)
<span class="keywordflow">return</span> -1;
<span class="comment">/* Set the font size and render a small text. */</span>
<a class="code" href="FTFont_8h.html#a00c8f893cbeb98b663f9755647a34e8c" title="Set the char size for the current face.">ftglSetFontFaceSize</a>(font, 72, 72);
<a class="code" href="FTFont_8h.html#a048872ff0cf567ef94884ee7ea4d16d9" title="Render a string of characters.">ftglRenderFont</a>(font, <span class="stringliteral">"Hello World!"</span>, FTGL_RENDER_ALL);
<span class="comment">/* Destroy the font object. */</span>
<a class="code" href="FTFont_8h.html#af0dc4b1c8987895d19e863416ae8d174" title="Destroy an FTGL font object.">ftglDestroyFont</a>(font);
</pre></div><h3><a class="anchor" id="cxx"></a>
in C++</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Create a pixmap font from a TrueType file.</span>
<a class="code" href="FTGLPixmapFont_8h.html#a956bde64ce9c81ab74bc8d5c0f059929">FTGLPixmapFont</a> font(<span class="stringliteral">"/home/user/Arial.ttf"</span>);
<span class="comment">// If something went wrong, bail out.</span>
<span class="keywordflow">if</span>(font.Error())
<span class="keywordflow">return</span> -1;
<span class="comment">// Set the font size and render a small text.</span>
font.FaceSize(72);
font.Render(<span class="stringliteral">"Hello World!"</span>);
</pre></div><p>The first 128 glyphs of the font (generally corresponding to the ASCII set) are preloaded. This means that usual text is rendered fast enough, but no memory is wasted loading glyphs that will not be used.</p>
<h2><a class="anchor" id="commands"></a>
More font commands</h2>
<h3><a class="anchor" id="metrics"></a>
Font metrics</h3>
<div align="center">
<img src="metrics.png" alt="metrics.png"/>
</div>
<p>If you ask a font to render at 0.0, 0.0 the bottom left most pixel or polygon may not be aligned to 0.0, 0.0. With <a class="el" href="classFTFont.html#ac4659028a0be30e8bc85814e7e53ee87" title="Get the global ascender height for the face.">FTFont::Ascender()</a>, <a class="el" href="classFTFont.html#aa72f172f4f9a39970913e176f38866bc" title="Gets the global descender height for the face.">FTFont::Descender()</a> and <a class="el" href="classFTFont.html#ae606eb0323341d1a521dae7a712f1b6e" title="Get the advance for a string.">FTFont::Advance()</a> an approximate bounding box can be calculated.</p>
<p>For an exact bounding box, use the <a class="el" href="classFTFont.html#a05b5c069ab8e958935096df78f8af16f" title="Get the bounding box for a string.">FTFont::BBox()</a> function. This function returns the extent of the volume containing 'string'. 0.0 on the y axis will be aligned with the font baseline.</p>
<h3><a class="anchor" id="charmap"></a>
Specifying a character map encoding</h3>
<p>From the FreeType documentation:</p>
<p>"By default, when a new face object is created, (FreeType) lists all the charmaps contained in the font face and selects the one that supports Unicode character codes if it finds one. Otherwise, it tries to find support for Latin-1, then ASCII."</p>
<p>It then gives up. In this case FTGL will set the charmap to the first it finds in the fonts charmap list. You can expilcitly set the char encoding with <a class="el" href="classFTFont.html#a64f7346221e90325220829eeaa238e93" title="Set the character map for the face.">FTFont::CharMap()</a>.</p>
<p>Valid encodings as of FreeType 2.0.4 are:</p>
<ul>
<li>ft_encoding_none</li>
<li>ft_encoding_unicode</li>
<li>ft_encoding_symbol</li>
<li>ft_encoding_latin_1</li>
<li>ft_encoding_latin_2</li>
<li>ft_encoding_sjis</li>
<li>ft_encoding_gb2312</li>
<li>ft_encoding_big5</li>
<li>ft_encoding_wansung</li>
<li>ft_encoding_johab</li>
<li>ft_encoding_adobe_standard</li>
<li>ft_encoding_adobe_expert</li>
<li>ft_encoding_adobe_custom</li>
<li>ft_encoding_apple_roman</li>
</ul>
<p>For instance:</p>
<div class="fragment"><pre class="fragment">font.CharMap(ft_encoding_apple_roman);
</pre></div><p>This will return an error if the requested encoding can't be found in the font.</p>
<p>If your application uses Latin-1 characters, you can preload this character set using the following code:</p>
<div class="fragment"><pre class="fragment"><span class="comment">// Create a pixmap font from a TrueType file.</span>
<a class="code" href="FTGLPixmapFont_8h.html#a956bde64ce9c81ab74bc8d5c0f059929">FTGLPixmapFont</a> font(<span class="stringliteral">"/home/user/Arial.ttf"</span>);
<span class="comment">// If something went wrong, bail out.</span>
<span class="keywordflow">if</span>(font.Error())
<span class="keywordflow">return</span> -1;
<span class="comment">// Set the face size and the character map. If something went wrong, bail out.</span>
font.FaceSize(72);
<span class="keywordflow">if</span>(!font.CharMap(ft_encoding_latin_1))
<span class="keywordflow">return</span> -1;
<span class="comment">// Create a string containing all characters between 128 and 255</span>
<span class="comment">// and preload the Latin-1 chars without rendering them.</span>
<span class="keywordtype">char</span> buf[129];
<span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 128; i < 256; i++)
{
buf[i] = (char)(<span class="keywordtype">unsigned</span> <span class="keywordtype">char</span>)i;
}
buf[128] = <span class="charliteral">'\0'</span>;
font.Advance(buf);
}
</pre></div><h2><a class="anchor" id="sample"></a>
Sample font manager class</h2>
<div class="fragment"><pre class="fragment"><a class="code" href="classFTTextureFont.html" title="FTTextureFont is a specialisation of the FTFont class for handling Texture mapped fonts...">FTTextureFont</a>* myFont = FTGLFontManager::Instance().GetFont(<span class="stringliteral">"arial.ttf"</span>, 72);
<span class="preprocessor">#include <map></span>
<span class="preprocessor">#include <string></span>
<span class="preprocessor">#include <<a class="code" href="ftgl_8h.html">FTGL/ftgl.h</a>></span>
<span class="keyword">using namespace </span>std;
<span class="keyword">typedef</span> map<string, FTFont*> FontList;
<span class="keyword">typedef</span> FontList::const_iterator FontIter;
<span class="keyword">class </span>FTGLFontManager
{
<span class="keyword">public</span>:
<span class="comment">// NOTE</span>
<span class="comment">// This is shown here for brevity. The implementation should be in the source</span>
<span class="comment">// file otherwise your compiler may inline the function resulting in</span>
<span class="comment">// multiple instances of FTGLFontManager</span>
<span class="keyword">static</span> FTGLFontManager& Instance()
{
<span class="keyword">static</span> FTGLFontManager tm;
<span class="keywordflow">return</span> tm;
}
~FTGLFontManager()
{
FontIter font;
<span class="keywordflow">for</span>(font = fonts.begin(); font != fonts.end(); font++)
{
<span class="keyword">delete</span> (*font).second;
}
fonts.clear();
}
<a class="code" href="classFTFont.html" title="FTFont is the public interface for the FTGL library.">FTFont</a>* GetFont(<span class="keyword">const</span> <span class="keywordtype">char</span> *filename, <span class="keywordtype">int</span> size)
{
<span class="keywordtype">char</span> buf[256];
sprintf(buf, <span class="stringliteral">"%s%i"</span>, filename, size);
<span class="keywordtype">string</span> fontKey = string(buf);
FontIter result = fonts.find(fontKey);
<span class="keywordflow">if</span>(result != fonts.end())
{
LOGMSG(<span class="stringliteral">"Found font %s in list"</span>, filename);
<span class="keywordflow">return</span> result->second;
}
<a class="code" href="classFTFont.html" title="FTFont is the public interface for the FTGL library.">FTFont</a>* font = <span class="keyword">new</span> <a class="code" href="classFTTextureFont.html" title="FTTextureFont is a specialisation of the FTFont class for handling Texture mapped fonts...">FTTextureFont</a>;
<span class="keywordtype">string</span> fullname = path + string(filename);
<span class="keywordflow">if</span>(!font->Open(fullname.c_str()))
{
LOGERROR(<span class="stringliteral">"Font %s failed to open"</span>, fullname.c_str());
<span class="keyword">delete</span> font;
<span class="keywordflow">return</span> NULL;
}
<span class="keywordflow">if</span>(!font-><a class="code" href="classFTFont.html#aae95510a733d6755bbbaf92d67796ff9" title="Set the char size for the current face.">FaceSize</a>(size))
{
LOGERROR(<span class="stringliteral">"Font %s failed to set size %i"</span>, filename, size);
<span class="keyword">delete</span> font;
<span class="keywordflow">return</span> NULL;
}
fonts[fontKey] = font;
<span class="keywordflow">return</span> font;
}
<span class="keyword">private</span>:
<span class="comment">// Hide these 'cause this is a singleton.</span>
FTGLFontManager(){}
FTGLFontManager(<span class="keyword">const</span> FTGLFontManager&){};
FTGLFontManager& operator = (<span class="keyword">const</span> FTGLFontManager&){ <span class="keywordflow">return</span> *<span class="keyword">this</span>; };
<span class="comment">// container for fonts</span>
FontList fonts;
};
</pre></div> </div></div>
<hr class="footer"/><address class="footer"><small>Generated on Wed Feb 9 2011 for FTGL by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.3 </small></address>
</body>
</html>
