Classes | Public Member Functions | List of all members
cpp3ds::Font Class Reference

Class for loading and manipulating character fonts. More...

#include <Font.hpp>

Classes

struct  Info
 Holds various information about a font. More...
 

Public Member Functions

 Font ()
 Default constructor. More...
 
 Font (const Font &copy)
 Copy constructor. More...
 
 ~Font ()
 Destructor. More...
 
bool loadFromFile (const std::string &filename)
 Load the font from a file. More...
 
bool loadFromMemory (const void *data, std::size_t sizeInBytes)
 Load the font from a file in memory. More...
 
bool loadFromStream (InputStream &stream)
 Load the font from a custom stream. More...
 
const InfogetInfo () const
 Get the font information. More...
 
const GlyphgetGlyph (Uint32 codePoint, unsigned int characterSize, bool bold) const
 Retrieve a glyph of the font. More...
 
int getKerning (Uint32 first, Uint32 second, unsigned int characterSize) const
 Get the kerning offset of two glyphs. More...
 
int getLineSpacing (unsigned int characterSize) const
 Get the line spacing. More...
 
const TexturegetTexture (unsigned int characterSize) const
 Retrieve the texture containing the loaded glyphs of a certain size. More...
 
Fontoperator= (const Font &right)
 Overload of assignment operator. More...
 

Detailed Description

Class for loading and manipulating character fonts.

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 cpp3ds::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 cpp3ds::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 cpp3ds::Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a cpp3ds::Text is a lightweight object which can combine the glyphs data and metrics of a cpp3ds::Font to display any text on a render target. Note that it is also possible to bind several cpp3ds::Text instances to the same cpp3ds::Font.

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

Usage example:

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

Apart from loading font files, and passing them to instances of cpp3ds::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.

See also
cpp3ds::Text

Definition at line 49 of file Font.hpp.

Constructor & Destructor Documentation

cpp3ds::Font::Font ( )

Default constructor.

This constructor defines an empty font

cpp3ds::Font::Font ( const Font copy)

Copy constructor.

Parameters
copyInstance to copy
cpp3ds::Font::~Font ( )

Destructor.

Cleans up all the internal resources used by the font

Member Function Documentation

const Glyph& cpp3ds::Font::getGlyph ( Uint32  codePoint,
unsigned int  characterSize,
bool  bold 
) const

Retrieve a glyph of the font.

Parameters
codePointUnicode code point of the character to get
characterSizeReference character size
boldRetrieve the bold version or the regular one?
Returns
The glyph corresponding to codePoint and characterSize
const Info& cpp3ds::Font::getInfo ( ) const

Get the font information.

Returns
A structure that holds the font information
int cpp3ds::Font::getKerning ( Uint32  first,
Uint32  second,
unsigned int  characterSize 
) const

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
firstUnicode code point of the first character
secondUnicode code point of the second character
characterSizeReference character size
Returns
Kerning value for first and second, in pixels
int cpp3ds::Font::getLineSpacing ( unsigned int  characterSize) const

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 Texture& cpp3ds::Font::getTexture ( unsigned int  characterSize) const

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 cpp3ds::Text.

Parameters
characterSizeReference character size
Returns
Texture containing the glyphs of the requested size
bool cpp3ds::Font::loadFromFile ( const std::string &  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.

Parameters
filenamePath of the font file to load
Returns
True if loading succeeded, false if it failed
See also
loadFromMemory, loadFromStream
bool cpp3ds::Font::loadFromMemory ( const void *  data,
std::size_t  sizeInBytes 
)

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: SFML cannot preload all the font data in this function, so the buffer pointed by data has to remain valid as long as the font is used.

Parameters
dataPointer to the file data in memory
sizeInBytesSize of the data to load, in bytes
Returns
True if loading succeeded, false if it failed
See also
loadFromFile, loadFromStream
bool cpp3ds::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: SFML cannot preload all the font data in this function, so the contents of stream have to remain valid as long as the font is used.

Parameters
streamSource stream to read from
Returns
True if loading succeeded, false if it failed
See also
loadFromFile, loadFromMemory
Font& cpp3ds::Font::operator= ( const Font right)

Overload of assignment operator.

Parameters
rightInstance to assign
Returns
Reference to self

The documentation for this class was generated from the following file: