glttf::Font Class Reference

The font base class. More...

#include <font.h>

Inheritance diagram for glttf::Font:

glttf::BasicFont< T > List of all members.

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.
GlyphgetGlyph (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 GlyphmakeGlyph (FT_GlyphSlot glyph)=0
 Create a glyph.

Detailed Description

The font base class.

The Font class is an abstract (pure virtual) base class to all GLttf fonts. All Fonts in GLttf inherit this class. The font class provides basic functionality shared by all fonts, including drawing characters and strings and calculating font metrics.

The Font class' instances cannot be copied, you will have to pass them by references.

Todo:
different character encodings
Todo:
optimizations for std::string
Todo:
optimizations for fixed width (monospace) fonts
Author:
Riku Salminen


Constructor & Destructor Documentation

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()


Member Function Documentation

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 >.


The documentation for this class was generated from the following file:
Generated on Mon Jan 8 12:08:37 2007 for GLttf by  doxygen 1.5.1