1
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
4
<title>FTGL User Guide</title>
8
<TABLE BORDER="0" WIDTH="70%" CELLSPACING="0" CELLPADDING="0" ALIGN="center">
14
<h2>(work in progress)
17
<IMG SRC="images/ftgldemo.jpg" ALT="FTGL Demo screen shot" WIDTH="480" HEIGHT="383" BORDER="0">
22
<LI><H3><a href="#INT">Introduction</a></H3></LI>
23
<LI><H3><a href="#CFT">Choosing a font type</a></H3></LI>
24
<LI><H3><a href="#CAT">Creating a font</a></H3></LI>
25
<LI><H3><a href="#MFC">More font commands</a></H3></LI>
26
<LI><H3><a href="#FAQ">FAQ</a></H3></LI>
27
<LI><H3><a href="#GLS">Glossary</a></H3></LI>
29
<HR ALIGN="center" SIZE="2" WIDTH="80%">
34
OpenGL doesn't provide direct font support, so the application must use any of OpenGL's other features for font rendering, such as drawing bitmaps or pixmaps, creating texture maps containing an entire character set, drawing character outlines, or creating 3D geometry for each character.
38
<P>http://www.opengl.org/developers/faqs/technical/fonts.htm</P>
39
<P>http://www.opengl.org/developers/code/features/fontsurvey/index.html</P>
41
?????One thing all of these systems have in comman is they require a pre-processing stage to take the native fonts and convert them into proprietry format.
45
FTGL was borne out of the need to treat fonts in OpenGL applications just like any other application. For example when using Adobe Photoshop or Microsoft Word you don't need an intermediate pre-processing step to use high quality scalable fonts.
48
<HR ALIGN="center" SIZE="2" WIDTH="80%">
50
<H2>Choosing a font type</H2>
52
FTGL supports 6 font output types in 3 groups, raster fonts, vector fonts and texure fonts which are a mixture of both. Each font type has it's advantages and disadvantages
54
The two raster types are
57
<LI>Antialiased pixmapped</LI>
66
<LI>Extruded polygon</LI>
73
<LI>Texture mapped</LI>
76
This is probably the most versatile type. It is fast, antialised and can be transformed just like any openGL primitive.
79
<HR ALIGN="center" SIZE="2" WIDTH="80%">
84
<font color="blue"><PRE>
87
font.Open( "Fonts:Arial");
90
font.render( "Hello World!");
92
FTFont::Open( string, cache);
97
<font color="blue"><PRE>
98
bool Open( fontname, preCache = true);
106
A side effect of this is you can specify a sub set of glyphs to be pre-loaded. This will let you use larger higher quality glyphs without consuming huge amounts of ram as you would if you loaded the entire font. For example if your application only needs numbers, eg for scores, you can use the following code to preload them.
109
<font color="blue"><PRE>
110
// Open the font with pre-cache set to false
111
font.Open( "Fonts:Arial", false);
116
// Cause the font to preload the number chars without rendering them.
117
font.Advance( "0123456789");
122
<HR ALIGN="center" SIZE="2" WIDTH="80%">
125
<H2>More font commands</H2>
126
<H3>Font Metrics</H3>
128
<IMG SRC="images/metrics.png" ALT="glyph metrics" WIDTH="388" HEIGHT="253" BORDER="0">
132
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.
135
<font color="blue"><PRE>
136
int FTFont::Ascender() const;
137
int FTFont::Descender() const;
139
float FTFont::Advance( string);
144
With these three functions an approximate bounding box can be calculated. For an exact bounding box use the FTFont::BBox function.
147
<font color="blue"><PRE>
148
void FTFont::BBox( string, llx, lly, llz, urx, ury, urz);
149
const char* string: String of text to be tested
150
float& llx: The bottom left near most ?? in the x axis
151
float& lly: The bottom left near most ?? in the y axis
152
float& llz: The bottom left near most ?? in the z axis
153
float& urx: The top right far most ?? in the x axis
154
float& ury: The top right far most ?? in the y axis
155
float& urz: The top right far most ?? in the z axis
159
This function returns the extent of the volume containing 'string'. 0.0 on the y axis will be aligned with the font baseline.
162
<H3>Specifying a character map encoding.
164
From the freetype docs...<br>
165
"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."
167
It then gives up. In this case FTGL will set the charmap to the first it finds in the fonts charmap list.
169
You can expilcitly set the char encoding with Charmap:
170
<font color="blue"><PRE>
171
bool FTFont::CharMap( encoding);
172
FT_Encoding encoding; Freetype code
175
Valid encodings as at Freetype 2.0.4
176
<font color="blue"><PRE>
186
ft_encoding_adobe_standard
187
ft_encoding_adobe_expert
188
ft_encoding_adobe_custom
189
ft_encoding_apple_roman
193
<font color="blue"><PRE>
194
font.CharMap( ft_encoding_apple_roman);
197
This will return an error if the requested encoding can't be found in the font.
201
<HR ALIGN="center" SIZE="2" WIDTH="80%">
206
WhenI try to compile FTGL it complains about a missing file from the include:
208
#include <ft2build.h>
210
FTGL relies on freetype 2 for opening and decoding font files. This include is the main include for freetype. You will need to download Freetype 2 and install it. Then make sure that the FTGL project that you are using points to your freetype installation.
213
2) Is it possible to map a font to a "unit" size? My application relies on
214
the fonts being a certain "physical" height (in OpenGL coordinate space)
215
rather than a point size in display space. Any thoughts/suggestions?
218
We can do anything:) It would be easy to allow you to set the size in pixels, though I'm not sure this is what you want. Setting the size to 'opengl units' may be a bit harder. What does 1.0 in opengl space mean and how does that relate to point size? For one person it might mean scaling the font up, for someone else it may mean scaling down. Plus bitmaps and pixmaps have a pixel to pixel relationship that you can't change.
220
Here's some guidelines for vector and texture fonts. Take note that I say 'should' a lot:)
221
One point in pixel space maps to 1 unit in opengl space, so a glyph that is 18 points high should be 18.0 units high.
222
If you set an ortho projection to the window size and draw a glyph it's screen size should be the correct physical size ie a 72 point glyph on a 72dpi screen will be 1 inch high. Also if you set a perspective projection that maps 0.0 in the z axis to screen size you will get the same eg...
223
gluPerspective( 90, window_height / 2 , small_number, large_number);
224
So basically it all depends on your projection matrix. Obviously you can use glScale but I understand if you don't want to.
225
Couple of extra things to note. The quality of vector glyphs will not change when you change the size. ie a really small polygon glyph up close will look exactly the same as a big one from far away. They both contain the same amount of data. This doesn't apply to texture fonts. Secondly there is a bug in the advance/ kerning code that will cause ugliness at really small point sizes. This is because the advance and kerning use ints so an advance of 0.4 will become zero. If this is going to be a probelm, I can fix this.
227
Early on I did a lot of head scratching over the opengl unit to font size thing because when I was first integrating FTGL into my engine the fonts weren't the size I was expecting. I was tempted to build in some scaling but I decided doing nothing was the best approach because you can't please everyone. Plus it's 'correct' as it is.
231
<H3>Sample font manager class.</H3>
234
<font color="blue"><pre>
235
FTGLTextureFont* myFont = FTGLFontManager::Instance().GetFont( "arial.ttf", 72);
238
#include <string>
239
#include "FTGLTextureFont.h"
243
typedef map< string, FTFont*> FontList;
244
typedef FontList::const_iterator FontIter;
246
class FTGLFontManager
250
// This is shown here for brevity. The implementation should be in the source
251
// file otherwise your compiler may inline the function resulting in
252
// multiple instances of FTGLFontManager
253
static FTGLFontManager& Instance()
255
static FTGLFontManager tm;
262
for( font = fonts.begin(); font != fonts.end(); font++)
264
delete (*font).second;;
271
FTFont* GetFont( const char *filename, int size)
274
sprintf(buf, "%s%i", filename, size);
275
string fontKey = string(buf);
277
FontIter result = fonts.find( fontKey);
278
if( result != fonts.end())
280
LOGMSG( "Found font %s in list", filename);
281
return result->second;
284
FTFont* font = new FTGLTextureFont;
286
string fullname = path + string( filename);
288
if( !font->Open( fullname.c_str()))
290
LOGERROR( "Font %s failed to open", fullname.c_str());
295
if( !font->FaceSize( size))
297
LOGERROR( "Font %s failed to set size %i", filename, size);
302
fonts[fontKey] = font;
310
// Hide these 'cause this is a singleton.
312
FTGLFontManager( const FTGLFontManager&){};
313
FTGLFontManager& operator = ( const FTGLFontManager&){ return *this;};
315
// container for fonts
322
<HR ALIGN="center" SIZE="2" WIDTH="80%">
added
removed
extern/bFTGL/docs/FTGL.html
