GLttf Documentation

Installation

See INSTALL in the source tarball.

If you encounter the following error message, you should add --disable-freetypetest parameter to the configure script.

checking for FreeType -- version >= 7.0.1... no
configure: WARNING:

  The FreeType test program failed to run.  If your system uses
  shared libraries and they are installed outside the normal
  system library path, make sure the variable LD_LIBRARY_PATH
  (or whatever is appropiate for your system) is correctly set.

configure: error: *** FreeType >= 2.0.4 not found ***

$ ./configure --disable-freetypetest

Basic usage

To use glttf, you must include the OpenGL header file and glttf.h into your source file. You must include the OpenGL header before glttf.h.

#include <GL/gl.h> // include OpenGL header before glttf.h
#include "glttf.h"

glttf::OutlineFont font("arial.ttf");
font.drawString("hello world");

Advanced usage

Different font types

There are four different types of fonts in GLttf.

• glttf::OutlineFont - a simple font outline rendered with GL_LINE_LOOP
• glttf::PolygonFont - a solid font rendered with triangles
• glttf::BitmapFont - a solid font rendered with textured quadrilaterals
• glttf::ExtrudedFont - an extruded 3d font

Caching

GLttf loads new characters on demand (given that the cache parameter in the drawing functions is not explicitly set to false) and caches them for future use. The loading process may be rather time consuming and slow down your application. Using Font::buildCache() you can manually load characters for future use.

glttf::Font &font = ...;
font.buildCache(0, 0); // loads character 0, the "unknonwn" character
font.buildCache(); // loads the characters in range 0 to 127, inclusive (the ASCII characters)
font.buildCache(232, 246); // loads characters in range 232 to 246, inclusive

You should always load at least the character 0, which is the "unknown" character. In case a character you're trying to draw can't be found, it will be substituted with the unknown character. If the unknown character isn't loaded, an attempt to draw a character which can't be found will result in a std::runtime_error exception.

Rendering state

The GLttf fonts may need to do some changes in the current OpenGL state in order to get text rendered correctly. The rendering state is set up by Font::setupState() and cleaned up by Font::cleanupState(). They are called implicitly upon Font::drawString() and Font::drawCharacter().

If you draw a lot of text with the same font at once, you should explicitly set up and clean up the rendering state before and after rendering text. This will minimize the amount of OpenGL state changes.

glttf::Font &font = ...;
font.setupState();  // set up rendering state

font.drawString("hello"); // rendering state already set, don't attempt to re-set it
glTranslatef(0.0f, -font.getTextHeight(), 0.0f);
font.drawString("world");

font.cleanupState(); // clean up rendering state

Using std::wstring

The MinGW Windows port libstdc++ does not support std::wstring because of it's dependecies to POSIX-style locales. Because of this GLttf does not have std::wstring support included unless explicitly enabled with HAVE_WSTRING macro at compile time and whenever including glttf.h

If you want to use GLttf with std::wstring, you must enable the HAVE_WSTRING macro either with compiler arguments, a header file such as config.h or manually before including glttf.h.

If you are building GLttf using the standard installation procedure, the configure script enables/disables the HAVE_WSTRING macro if std::wstring is present in your system.

GLttf and alpha blending

It is adviced not to use GLttf with alpha blending. GLttf always renders strings left-to-right and ignores depth and camera position. It may be possible to draw text with alpha blending by first calculating the proper drawing order for the strings and then rendering the strings.

ExtrudedFont draws faces in an arbitrary order, not taking depth into account and thus can't be used with alpha blending.

Thread safety

GLttf is not thread safe. You should not try to use the fonts in different threads without using a mutex locking system. You should not try to render text with the same or different font in different threads simultaneously. GLttf text rendering alters the OpenGL state machine and simultaneous rendering may result in unexpected outcome and/or errors.

Licence

GLttf is licenced under the zlib/libpng licence.

This software is provided 'as-is', without any express or implied
warranty.  In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
        claim that you wrote the original software. If you use this software
        in a product, an acknowledgment in the product documentation would be
        appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
        misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.

Author:

Riku Salminen

---