GLttf: glttf::Font Class Reference

glttf::Font::Font	(	const std::string &	filename,
		unsigned int	size,
		FontStyle	style,
		unsigned long	faceIndex = `DEFAULT_FACE_INDEX`
	)

Create a new font from file and initialize FreeType 2 if required.

Initializes the FreeType 2 library if it isn't already initialized.

Loads a font face from file filename, sets character size to size (FT_Set_Char_Size) using the default screen resolution and sets up a transformation according to style. The style parameter can take PLAIN, BOLD or ITALIC as a parameter or an OR'd combination of the previous.

Strong exception safety. If font loading fails, the library is deinitialized (if appropriate). If setting the character size or style fails, the font face is freed and the library is deinitialized (if appropriate).

Parameters:

	filename	The file name to load
	size	the point size of the font
	style	the style of the font
	faceIndex	the index of the font face in the font file

Exceptions:

std::runtime_error

On library initialization failure, failure to load font or set font size

See also:: setTransformation(), PLAIN, BOLD, ITALIC

virtual glttf::Font::~Font ( ) [virtual]

Destroy this font and deinitialize FreeType 2 if appropriate.

Destroy all cached glyphs, deinitialize the font face and if no more instances of the font class exist, deinitialize the FreeType 2 library.

See also:: deleteCache()

void glttf::Font::setPixelSize	(	unsigned int	width,
		unsigned int	height = `0`
	)

Set font size in pixel units.

Set up font size to width by height in pixel units. If one of the parameters is zero, it will be set equal to the other parameter.

Destroys cached glyphs!

Strong exception safety. If setting the pixel size fails, cached glyphs will not be deleted.

Parameters:

	width	the font width in pixels
	height	the font height in pixels

Exceptions:

std::runtime_error

if setting font size fails

See also:: deleteCache(), FT_Set_Pixel_Sizes()

void glttf::Font::setCharSize	(	float	width,
		float	height,
		unsigned int	hres = `0`,
		unsigned int	vres = `0`
	)

Set font size in point units.

Sets the font size to width by height using resolution hres by vres. If either the horizontal or vertical resolution is zero, it is set to a default value of 72 dpi.

Destroys cached glyphs!

Strong exception safety. If setting the pixel size fails, cached glyphs will not be deleted.

Parameters:

	width
	height
	hres	The horizontal resolution in dpi
	vres	The vertical resolution in dpi

Exceptions:

std::runtime_error

if setting font size fails

See also:: deleteCache(), FT_Set_Char_Size()

void glttf::Font::setTransformation	(	float	weight,
		float	shear
	)

Set font transformation.

Sets up font transformation. The weight parameter is the scaling factor in the horizontal direction. The shear parameter is the shearing factor (horizontal displacement per height).

Parameters:

	weight	The horizontal scaling factor for the font
	shear	The shearing factor for the font

See also:: deleteCache(), FT_Set_Transform()

void glttf::Font::setStyle ( FontStyle style )

Set up font style.

The style parameter can take PLAIN, BOLD or ITALIC as a parameter or an OR'd combination of the previous.

Parameters:

style

The new font style

See also:: setTransformation()

Glyph& glttf::Font::getGlyph	(	unsigned long	ch,
		bool	cache
	)

Get a character glyph.

Finds the requested glyph from the glyph cache and returns it. If the glyph is not cached and the cache parameter is true, attempt to load the appropriate glyph. If the glyph couldn't be loaded or the cache parameter is false, attempt to find the "unknown" glyph, usually blank or a square with charcode = 0. If no glyph hasn't been found so far, throw an exception.

Strong exception safety. If no glyph is found and/or the glyph loading fails, this object is left unaltered.

Parameters:

	ch	the character code of the glyph to get
	cache	if `true`, attempt to load glyphs that aren't cached

Returns:: a reference to the requested glyph

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found

See also:: loadCharacter()

void glttf::Font::drawCharacter	(	unsigned long	ch,
		bool	cache = `true`
	)

Draw a character.

Sets up font drawing state, fetches a character glyph and draws it and then cleans up the drawing state.

Strong exception safety. If no glyph is found and/or the glyph loading fails or the glyph drawing fails, this object is left unaltered and cleanupState function is called.

Parameters:

	ch	the character code f the character to draw.
	cache	if `true`, attempt to load glyphs that aren't cached

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found or the glyph drawing fails

See also:: getGlyph(), setupState(), cleanupState()

template<typename Iterator>

void glttf::Font::drawString	(	Iterator	begin,
		Iterator	end,
		bool	cache = `true`
	)

Draw a string.

Sets up font drawing state, draws all the glyphs from begin to end and then cleans up the drawing state.

Strong exception safety. If any glyph is not found and/or the glyph loading fails or the glyph drawing fails or there is another kind of failure, this object is left unaltered and cleanupState function is called.

Parameters:

	begin	an iterator to the beginning of the string
	end	an iterator to the end of the string
	cache	if `true`, attempt to load glyphs that aren't cached

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found or the glyph drawing fails or if kerning data couldn't be loaded

See also:: getGlyph(), setupState(), cleanupState()

template<typename Iterator>

void glttf::Font::getBoundingBox	(	Iterator	begin,
		Iterator	end,
		float &	minX,
		float &	minY,
		float &	maxX,
		float &	maxY,
		bool	cache = `true`
	)

Calculates a string's bounding box.

Calculates the bounding box of a given string.

Whitespaces, tabs and newlines in the end of the string do not affect the size of the bounding box.

Strong exception safety. If any glyph is not found and/or the glyph loading fails or the glyph drawing fails or there is another kind of failure, this object is left unaltered.

Parameters:

	begin	an iterator to the beginning of the string
	end	an iterator to the end of the string
	minX	a reference to which the minimum X coordinate of the bounding box is save
	minY	a reference to which the minimum Y coordinate of the bounding box is save
	maxX	a reference to which the maximum X coordinate of the bounding box is save
	maxY	a reference to which the maximum Y coordinate of the bounding box is save
	cache	if `true`, attempt to load glyphs that aren't cached

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found or if kerning data couldn't be loaded

See also:: getGlyph()

void glttf::Font::drawString	(	std::string const &	str,
		bool	cache = `true`
	)

Draws a string.

An alternative entry point to drawString(Iterator, Iterator, bool).

Parameters:

	str	the string to draw
	cache	if `true`, attempt to load glyphs that aren't cached

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found or if kerning data couldn't be loaded

See also:: drawString(Iterator, Iterator, bool)

void glttf::Font::getBoundingBox	(	std::string const &	str,
		float &	minX,
		float &	minY,
		float &	maxX,
		float &	maxY,
		bool	cache = `true`
	)

Calculate a bounding box.

An alternative entry point to getBoundingBox(Iterator, Iterator, float&, float&, float&, float&, bool).

Parameters:

	str	the string
	minX	a reference to which the minimum X coordinate of the bounding box is save
	minY	a reference to which the minimum Y coordinate of the bounding box is save
	maxX	a reference to which the maximum X coordinate of the bounding box is save
	maxY	a reference to which the maximum Y coordinate of the bounding box is save
	cache	if `true`, attempt to load glyphs that aren't cached

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found or if kerning data couldn't be loaded

See also:: getBoundingBox(Iterator, Iterator, float&, float&, float&, float&, bool)

void glttf::Font::drawString	(	std::wstring const &	str,
		bool	cache = `true`
	)

Draws a string.

An alternative entry point to drawString(Iterator, Iterator, bool).

Parameters:

	str	the string to draw
	cache	if `true`, attempt to load glyphs that aren't cached

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found or if kerning data couldn't be loaded

See also:: drawString(Iterator, Iterator, bool)

void glttf::Font::getBoundingBox	(	std::wstring const &	str,
		float &	minX,
		float &	minY,
		float &	maxX,
		float &	maxY,
		bool	cache = `true`
	)

Calculate a bounding box.

An alternative entry point to getBoundingBox(Iterator, Iterator, float&, float&, float&, float&, bool).

Parameters:

	str	the string
	minX	a reference to which the minimum X coordinate of the bounding box is save
	minY	a reference to which the minimum Y coordinate of the bounding box is save
	maxX	a reference to which the maximum X coordinate of the bounding box is save
	maxY	a reference to which the maximum Y coordinate of the bounding box is save
	cache	if `true`, attempt to load glyphs that aren't cached

Exceptions:

std::runtime_error

if the glyph is not found, the glyph couldn't be loaded and the "unknown" glyph is not found or if kerning data couldn't be loaded

See also:: getBoundingBox(Iterator, Iterator, float&, float&, float&, float&, bool)

void glttf::Font::buildCache	(	unsigned long	from = `0`,
		unsigned long	to = `127`
	)

Load and cache glyphs.

Load and cache glyphs with character codes in range from - to (inclusive).

Parameters:

	from	the lower limit of the character codes of the glyphs to load
	to	the upper limit of the character codes of the glyphs to load

virtual void glttf::Font::setupState ( ) [virtual]

Set up drawing state.

Sets up everything necessary for rendering text with this font such as texture bindings, etc. If the state is already set up, do nothing.

If scaleTo1EM is enabled, this function enables GL_NORMALIZE.

All functions overriding this function should call this function.

Exceptions:

std::runtime_error

on errors

See also:: cleanupState()

Reimplemented in glttf::BasicFont< T >.

virtual void glttf::Font::cleanupState ( ) [virtual]

Clean up drawing state.

Clean up the state set up in setupState(). If the state has not been set up, do nothing.

All functions overriding this function should call this function.

Nothrow exception safety. This function should never throw any exceptions nor should any functions overriding this throw any exceptions.

See also:: setupState()

Reimplemented in glttf::BasicFont< T >.

void glttf::Font::setScaleTo1EM ( bool enable )

Scale font to 1 unit.

Scales text with factor 1/unitsPerEM.

If this function is called between setupState and cleanupState it does nothing.

Parameters:

enable true to enable scaling

bool glttf::Font::getScaleTo1EM ( ) const

Get font scaling state.

Returns:: true if scaleTo1EM is enabled

void glttf::Font::setFlipYAxis ( bool enable )

Invert the font horizontally.

If this function is called between setupState and cleanupState it does nothing.

Parameters:

enable true to enable flipping

bool glttf::Font::getFlipYAxis ( ) const

Get inverting state.

Returns:: true if flipping is enabled

void glttf::Font::setTopLeftOrigin ( bool enable )

Translate the origin to the top left corner of the text.

Translates the text down by ascent.

Parameters:

enable true to enable translation

bool glttf::Font::getTopLeftOrigin ( ) const

Get translation state.

Returns:: true if translation is enabled

Flags glttf::Font::getFlags ( ) const

Get the font flags.

Returns:: the font flags

void glttf::Font::setFlags ( Flags f )

Set the font flags.

Parameters:

f

the new font flags

float glttf::Font::getTextHeight ( ) const

Get the text height.

Returns:: the text height

float glttf::Font::getUnitsPerEM ( ) const

Get text size.

Returns:: the size of 1 EM unit

float glttf::Font::getAscender ( ) const

Get the ascender.

Returns:: the ascender of this font

float glttf::Font::getDescender ( ) const

Get the descender.

Returns:: the descender of this font

float glttf::Font::getMaxAdvanceX ( ) const

Get maximum horizontal advance of this font.

To get the actual maximum advance, you must multiply this by the weight factor.

Returns:: the maximum untransformed horizontal advance of this font

float glttf::Font::getMaxAdvanceY ( ) const

Get maximum vertical advance of this font.

Returns:: the maximum vertical advance of this font

float glttf::Font::getWeight ( ) const

Get the text weight.

Returns:: the weight (horizontal scaling factor) of this font

float glttf::Font::getShear ( ) const

Get the text shear.

Returns:: the shearing factor (horizontal displacement per height) of this font

unsigned int glttf::Font::getTabSize ( ) const

Get the tab size of this font.

Returns:: the tab size (number of whitespaces per tab) of this font

void glttf::Font::setTabSize ( unsigned int size )

Set the tab size of this font.

Parameters:

size

the new tab size (number of whitespaces per tab)

void glttf::Font::setTabWidth ( float width )

Set the tab width for this font.

If you set a negative width, the width will be (re)calculated based on the tab size in whitespace characters when needed.

Parameters:

width

the new tab width for this font

See also:: setTabSize(unsigned int), getTabWidth()

float glttf::Font::getTabWidth ( ) const

Get the tab width for this font.

Returns:: the tab width of this font. if negative the tab width is not calculated yet.

See also:: setTabSize(unsigned int),

float glttf::Font::getTabWidth ( bool cache = true )

Get the tab width for this font.

Calculate tab width if it isn't already calculated.

Parameters:

cache if true, attempt to load glyphs that aren't cached

Returns:: the tab width of this font.

Exceptions:

std::runtime_error

if the whitespace glyph is not found, the whitespace glyph couldn't be loaded and the "unknown" glyph is not found

See also:: setTabSize(unsigned int), setTabWidth(float)

void glttf::Font::deleteCache ( ) [protected]

Delete cached glyphs.

Delete all cached glyphs.

Nothrow exception safety. This function does not throw any exceptions and thus it's safe to call deleteCache() in destructors.

virtual Glyph* glttf::Font::makeGlyph ( FT_GlyphSlot glyph ) [protected, pure virtual]

Create a glyph.

Create a new glyph from FreeType 2 glyph data. The glyphs are created by subclasses of the Font class. When the glyphs are created, their ownership is changed to the caller of this function and the owner is responsible for destroying them.

Parameters:

glyph

the FreeType glyph which the glyph is built from

Returns:: a pointer to a new Glyph object. The caller is responsible for destroying the new object.

Exceptions:

std::runtime_error

on errors

See also:: FT_GlyphSlot

Implemented in glttf::BasicFont< T >.

glttf::Font Class Reference

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation


Public Types
typedef unsigned char	FontStyle
	Type for defining font styles.
typedef unsigned char	Flags
	Type for font flags.
Public Member Functions
	Font (const std::string &filename, unsigned int size, FontStyle style, unsigned long faceIndex=DEFAULT_FACE_INDEX)
	Create a new font from file and initialize FreeType 2 if required.
virtual	~Font ()
	Destroy this font and deinitialize FreeType 2 if appropriate.
void	setPixelSize (unsigned int width, unsigned int height=0)
	Set font size in pixel units.
void	setCharSize (float width, float height, unsigned int hres=0, unsigned int vres=0)
	Set font size in point units.
void	setTransformation (float weight, float shear)
	Set font transformation.
void	setStyle (FontStyle style)
	Set up font style.
Glyph &	getGlyph (unsigned long ch, bool cache)
	Get a character glyph.
void	drawCharacter (unsigned long ch, bool cache=true)
	Draw a character.
template<typename Iterator>
void	drawString (Iterator begin, Iterator end, bool cache=true)
	Draw a string.
template<typename Iterator>
void	getBoundingBox (Iterator begin, Iterator end, float &minX, float &minY, float &maxX, float &maxY, bool cache=true)
	Calculates a string's bounding box.
void	drawString (std::string const &str, bool cache=true)
	Draws a string.
void	getBoundingBox (std::string const &str, float &minX, float &minY, float &maxX, float &maxY, bool cache=true)
	Calculate a bounding box.
void	drawString (std::wstring const &str, bool cache=true)
	Draws a string.
void	getBoundingBox (std::wstring const &str, float &minX, float &minY, float &maxX, float &maxY, bool cache=true)
	Calculate a bounding box.
void	buildCache (unsigned long from=0, unsigned long to=127)
	Load and cache glyphs.
virtual void	setupState ()
	Set up drawing state.
virtual void	cleanupState ()
	Clean up drawing state.
void	setScaleTo1EM (bool enable)
	Scale font to 1 unit.
bool	getScaleTo1EM () const
	Get font scaling state.
void	setFlipYAxis (bool enable)
	Invert the font horizontally.
bool	getFlipYAxis () const
	Get inverting state.
void	setTopLeftOrigin (bool enable)
	Translate the origin to the top left corner of the text.
bool	getTopLeftOrigin () const
	Get translation state.
Flags	getFlags () const
	Get the font flags.
void	setFlags (Flags f)
	Set the font flags.
float	getTextHeight () const
	Get the text height.
float	getUnitsPerEM () const
	Get text size.
float	getAscender () const
	Get the ascender.
float	getDescender () const
	Get the descender.
float	getMaxAdvanceX () const
	Get maximum horizontal advance of this font.
float	getMaxAdvanceY () const
	Get maximum vertical advance of this font.
float	getWeight () const
	Get the text weight.
float	getShear () const
	Get the text shear.
unsigned int	getTabSize () const
	Get the tab size of this font.
void	setTabSize (unsigned int size)
	Set the tab size of this font.
void	setTabWidth (float width)
	Set the tab width for this font.
float	getTabWidth () const
	Get the tab width for this font.
float	getTabWidth (bool cache=true)
	Get the tab width for this font.
Static Public Attributes
static const unsigned long	DEFAULT_FACE_INDEX = 0
	The default face index to load.
static const FontStyle	PLAIN = 0x0
	Plain font style, always equal to zero.
static const FontStyle	BOLD = 0x1
	Bold font style.
static const FontStyle	ITALIC = 0x2
	Italic font style.
static const Flags	FLIP_Y_AXIS = 0x1
	Flip Y Axis flag.
static const Flags	SCALE_TO_1EM = 0x2
	Scale to 1 EM flag.
static const Flags	TOP_LEFT_ORIGIN = 0x4
	Translate origin top left flag.
static const float	BOLD_WEIGHT
	A constant for scaling bold style fonts horizontally.
static const float	ITALIC_SHEAR
	A constant for shearing italic style fonts (horizontal displacement per height).
Protected Member Functions
void	deleteCache ()
	Delete cached glyphs.
virtual Glyph *	makeGlyph (FT_GlyphSlot glyph)=0
	Create a glyph.