Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
Classes | Public Member Functions | List of all members
gf::Font Class Reference

A character font. More...

#include <gf/Font.h>

Public Member Functions

 Font ()
 Default constructor. More...
 
 ~Font ()
 Destructor. More...
 
 Font (const Font &)=delete
 Deleted copy constructor. More...
 
Fontoperator= (const Font &)=delete
 Deleted copy assignement. More...
 
 Font (Font &&other)
 Move constructor. More...
 
Fontoperator= (Font &&other)
 Move assignement. More...
 
bool loadFromFile (const Path &filename)
 Load the font from a file. More...
 
bool loadFromStream (InputStream &stream)
 Load the font from a custom stream. More...
 
bool loadFromMemory (const uint8_t *data, std::size_t length)
 Load the font from a file in memory. More...
 
const GlyphgetGlyph (char32_t codepoint, unsigned characterSize, float outlineThickness=0.0f)
 Retrieve a glyph of the font. More...
 
float getKerning (char32_t left, char32_t right, unsigned characterSize)
 Get the kerning offset of two glyphs. More...
 
float getLineSpacing (unsigned characterSize)
 Get the line spacing. More...
 
const AlphaTexturegetTexture (unsigned characterSize)
 Retrieve the texture containing the loaded glyphs of a certain size. More...
 
void generateTexture (unsigned characterSize)
 Generate the texture for a given character size. More...
 

Detailed Description

A character font.

Fonts can be loaded from a file, from memory or from a custom stream, and supports the most common types of fonts. See the loadFromFile() function for the complete list of supported formats.

Once it is loaded, a gf::Font instance provides three types of information about the font:

Fonts alone are not very useful: they hold the font data but cannot make anything useful of it. To do so you need to use the gf::Text class, which is able to properly output text with several options such as character size, style, color, position, rotation, etc.

This separation allows more flexibility and better performances: indeed a gf::Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a gf::Text is a lightweight object which can combine the glyphs data and metrics of a gf::Font to display any text on a render target.

Note that it is also possible to bind several gf::Text instances to the same gf::Font.

It is important to note that the gf::Text instance doesn't copy the font that it uses, it only keeps a reference to it. Thus, a gf::Font must not be destructed while it is used by a gf::Text (i.e. never write a function that uses a local gf::Font instance for creating a text).

Usage example:

// Declare a new font
gf::Font font;
// Load it from a file
if (!font.loadFromFile("arial.ttf"))
{
// error...
}
// Create a text which uses our font
gf::Text text1;
text1.setString("Hello World!")
text1.setFont(font);
text1.setCharacterSize(30);
// Create another text using the same font, but with different parameters
gf::Text text2;
text2.setString("Goodbye world!");
text2.setFont(font);
text2.setCharacterSize(50);

Apart from loading font files, and passing them to instances of gf::Text, you should normally not have to deal directly with this class. However, it may be useful to access the font metrics or rasterized glyphs for advanced usage.

Constructor & Destructor Documentation

gf::Font::Font ( )

Default constructor.

This constructor defines an empty font.

gf::Font::~Font ( )

Destructor.

gf::Font::Font ( const Font )
delete

Deleted copy constructor.

gf::Font::Font ( Font &&  other)

Move constructor.

Member Function Documentation

void gf::Font::generateTexture ( unsigned  characterSize)

Generate the texture for a given character size.

After this call, the texture corresponding to the size is available through getTexture.

Parameters
characterSizeReference character size
const Glyph& gf::Font::getGlyph ( char32_t  codepoint,
unsigned  characterSize,
float  outlineThickness = 0.0f 
)

Retrieve a glyph of the font.

If the font is a bitmap font, not all character sizes might be available. If the glyph is not available at the requested size, an empty glyph is returned.

Parameters
codepointUnicode code point of the character to get
characterSizeReference character size
outlineThicknessThickness of outline (when != 0 the glyph will not be filled)
Returns
The corresponding glyph
float gf::Font::getKerning ( char32_t  left,
char32_t  right,
unsigned  characterSize 
)

Get the kerning offset of two glyphs.

The kerning is an extra offset (negative) to apply between two glyphs when rendering them, to make the pair look more "natural". For example, the pair "AV" have a special kerning to make them closer than other characters. Most of the glyphs pairs have a kerning offset of zero, though.

Parameters
leftUnicode code point of the left character
rightUnicode code point of the right character
characterSizeReference character size
Returns
Kerning value, in pixels
float gf::Font::getLineSpacing ( unsigned  characterSize)

Get the line spacing.

Line spacing is the vertical offset to apply between two consecutive lines of text.

Parameters
characterSizeReference character size
Returns
Line spacing, in pixels
const AlphaTexture* gf::Font::getTexture ( unsigned  characterSize)

Retrieve the texture containing the loaded glyphs of a certain size.

The contents of the returned texture changes as more glyphs are requested, thus it is not very relevant. It is mainly used internally by gf::Text.

Parameters
characterSizeReference character size
Returns
Texture containing the glyphs of the requested size
bool gf::Font::loadFromFile ( const Path filename)

Load the font from a file.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Note that this function know nothing about the standard fonts installed on the user's system, thus you can't load them directly.

Warning
gf cannot preload all the font data in this function, so the file has to remain accessible until the gf::Font object loads a new font or is destroyed.
Parameters
filenamePath of the font file to load
Returns
True if loading succeeded, false if it failed
See also
loadFromMemory(), loadFromStream()
bool gf::Font::loadFromMemory ( const uint8_t *  data,
std::size_t  length 
)

Load the font from a file in memory.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.

Warning
gf cannot preload all the font data in this function, so the stream has to remain accessible until the gf::Font object loads a new font or is destroyed.
Parameters
dataPointer to the file data in memory
lengthLength of the data to load, in bytes
Returns
True if loading succeeded, false if it failed
See also
loadFromFile(), loadFromStream()
bool gf::Font::loadFromStream ( InputStream stream)

Load the font from a custom stream.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.

Warning
gf cannot preload all the font data in this function, so the stream has to remain accessible until the gf::Font object loads a new font or is destroyed.
Parameters
streamSource stream to read from
Returns
True if loading succeeded, false if it failed
See also
loadFromFile(), loadFromMemory()
Font& gf::Font::operator= ( const Font )
delete

Deleted copy assignement.

Font& gf::Font::operator= ( Font &&  other)

Move assignement.