Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members  

OGLFT::Face Class Reference

A face (aka font) used to render text with OpenGL. More...

#include <OGLFT.h>

Inheritance diagram for OGLFT::Face::

OGLFT::Polygonal OGLFT::Raster OGLFT::Texture OGLFT::Filled OGLFT::Outline OGLFT::Grayscale OGLFT::Monochrome OGLFT::Translucent OGLFT::GrayscaleTexture OGLFT::MonochromeTexture OGLFT::TranslucentTexture List of all members.

Public Types

enum  HorizontalJustification { LEFT, ORIGIN, CENTER, RIGHT }
 Thanks to the standard formerly known as PHIGS. Horizontal text justification constants. More...

enum  VerticalJustification { BOTTOM, BASELINE, MIDDLE, TOP }
 Thanks to the standard formerly known as PHIGS. Vertical text justification constants. More...

enum  GlyphCompileMode { COMPILE, IMMEDIATE }
 Control how OpenGL display lists are created for individual glyphs. The default mode is to create display lists for each glyph as it is requested. Therefore, the Face drawing routines cannot themselves be called from within an open display list. In IMMEDIATE mode, cached glyphs will be drawn if available, otherwise the FreeType data for a glyph is re-rendered each time. More...


Public Methods

 Face (const char *filename, float point_size=12, FT_UInt resolution=100)
 Face (FT_Face face, float point_size=12, FT_UInt resolution=100)
virtual ~Face (void)
bool isValid (void) const
bool addAuxiliaryFace (const char *filename)
bool addAuxiliaryFace (FT_Face face)
void setCompileMode (enum GlyphCompileMode compile_mode)
enum GlyphCompileMode compileMode (void) const
void setPointSize (float point_size)
float pointSize (void)
void setResolution (FT_UInt resolution)
FT_UInt resolution (void)
void setAdvance (bool advance)
bool advance (void) const
void setForegroundColor (GLfloat red=0.0, GLfloat green=0.0, GLfloat blue=0.0, GLfloat alpha=1.0)
void setForegroundColor (const GLfloat foreground_color[4])
void setForegroundColor (const QRgb foreground_color)
GLfloat foregroundRed (void) const
GLfloat foregroundGreen (void) const
GLfloat foregroundBlue (void) const
GLfloat foregroundAlpha (void) const
void setBackgroundColor (GLfloat red=1.0, GLfloat green=1.0, GLfloat blue=1.0, GLfloat alpha=0.0)
void setBackgroundColor (const GLfloat background_color[4])
void setBackgroundColor (const QRgb background_color)
GLfloat backgroundRed (void) const
GLfloat backgroundGreen (void) const
GLfloat backgroundBlue (void) const
GLfloat backgroundAlpha (void) const
virtual void setCharacterRotationZ (GLfloat character_rotation_z)=0
virtual GLfloat characterRotationZ (void) const=0
void setCharacterRotationReference (unsigned char c)
void setStringRotation (GLfloat string_rotation)
GLfloat stringRotation (void) const
void setHorizontalJustification (enum HorizontalJustification horizontal_justification)
enum HorizontalJustification horizontalJustification (void) const
void setVerticalJustification (enum VerticalJustification vertical_justification)
enum VerticalJustification verticaljustification (void) const
void setCharacterDisplayLists (const DisplayLists &character_display_lists)
DisplayLists& characterDisplayLists (void)
virtual double height (void) const=0
virtual BBox measure (unsigned char c)=0
virtual BBox measure (QChar c)=0
virtual BBox measure (const char *s)
virtual BBox measure (const QString s)
virtual BBox measure (const QString &format, double number)
GLuint compile (const char *s)
GLuint compile (const QString s)
GLuint compile (unsigned char c)
GLuint compile (const QChar c)
void draw (const char *s)
void draw (const QString s)
void draw (unsigned char c)
void draw (const QChar c)
void draw (GLfloat x, GLfloat y, unsigned char c)
void draw (GLfloat x, GLfloat y, QChar c)
void draw (GLfloat x, GLfloat y, const char *s)
void draw (GLfloat x, GLfloat y, const QString s)
void draw (GLfloat x, GLfloat y, const QString &format, double number)
int ascender (void)
int descender (void)

Protected Types

typedef std::map< FT_UInt,
GLuint > 		GlyphDLists
 Type of the cache of defined glyph to display list mapping.

typedef GlyphDLists::const_iterator GDLCI
 A convenience definition of the iterator over the glyph to display list map.

typedef GlyphDLists::iterator GDLI
 A convenience definition of the iterator over the glyph to display list map.


Protected Methods

virtual GLuint compileGlyph (FT_Face face, FT_UInt glyph_index)=0
 Some styles, in particular the Texture, need specialized steps to compile a glyph into an OpenGL display list.
Parameters:
face   the FT_Face containing the glyph.
glyph_index   the index of the glyph in face.
Returns:
the display list of the compiled glyph.


virtual void renderGlyph (FT_Face face, FT_UInt glyph_index)=0
 Each style implements its own glyph rendering routine.
Parameters:
face   the FT_Face containing the glyph.
glyph_index   the index of the glyph in face.


virtual void setCharSize (void)=0
 There is a slight different between the way in which the polygonal and raster styles select the character size for FreeType to generate.

virtual void clearCaches (void)=0
 The different styles have different caching needs (well, really only the texture style currently has more than the display list cache).

virtual void setRotationOffset (void)=0
 The polygonal and raster styles compute different values for the Z rotation offset. (It's in integer pixels for the raster styles and in floating point pixels for the polygonal styles.).


Protected Attributes

std::vector< FaceData > faces_
 The FreeType face - experimentally, this is now an array of faces so that we can handle a wider range of UNICODE points in case a face doesn't cover the points of interest.

bool valid_
 Did a font load OK?

enum GlyphCompileMode compile_mode_
 Glyph display list creation mode.

float point_size_
 Nominal point size.

FT_UInt resolution_
 Display resolution in pixels per inch.

bool advance_
 Does rendering text affect the MODELVIEW matrix?

GLfloat foreground_color_ [4]
 Foreground color (I really wanted to avoid this, but not really possible without state queries, which you can't put into display lists. Anyway, you'll be able to get even more fancy by passing in a function to map the color with, so why balk at this?).

GLfloat background_color_ [4]
 Background color (what modes would use this?).

enum HorizontalJustification horizontal_justification_
 PHIGS-like horizontal positioning of text.

enum VerticalJustification vertical_justification_
 PHIGS-like vertical positioning of text.

GLfloat string_rotation_
 Rotate an entire string in the Z plane.

FT_UInt rotation_reference_glyph_
 Let the user decide which character to use as the rotation reference. Use "o" by default, I suppose.

FT_Face rotation_reference_face_
 The rotation reference character could be in any face.

GLfloat rotation_offset_y_
 These are the translation offsets provided by the rotation reference character; for whom, we've discovered, only the Y position is relevant.

GlyphDLists glyph_dlists_
 Cache of defined glyph display lists.

DisplayLists character_display_lists_
 The user can supply an array of display list which are invoked before each glyph is rendered.

Detailed Description

A face (aka font) used to render text with OpenGL.

This is an abstract class, but it does define most the functions that you are likely to call to manipulate the rendering of the text.

Member Enumeration Documentation

enum OGLFT::Face::GlyphCompileMode
 

Control how OpenGL display lists are created for individual glyphs. The default mode is to create display lists for each glyph as it is requested. Therefore, the Face drawing routines cannot themselves be called from within an open display list. In IMMEDIATE mode, cached glyphs will be drawn if available, otherwise the FreeType data for a glyph is re-rendered each time.

Enumeration values:
COMPILE   Compile new glyphs when seen for the first time.
IMMEDIATE   Do not create display lists for glyphs.

enum OGLFT::Face::HorizontalJustification
 

Thanks to the standard formerly known as PHIGS. Horizontal text justification constants.

Enumeration values:
LEFT   Left justified justification of text.
ORIGIN   Natural origin alignment of text (default).
CENTER   Center justified alignment of text.
RIGHT   Right justified alignment of text.

enum OGLFT::Face::VerticalJustification
 

Thanks to the standard formerly known as PHIGS. Vertical text justification constants.

Enumeration values:
BOTTOM   Descender alignment of text.
BASELINE   Baseline alignment of text (default).
MIDDLE   Centered alignment of text.
TOP   Ascender justification of text.

Constructor & Destructor Documentation

OGLFT::Face::Face ( const char * filename,
float point_size = 12,
FT_UInt resolution = 100 )
 

Construct a Face by loading a font from the given file.

Parameters:
file   the filename which contains the font face.
point_size   the initial point size of the font to generate. A point is essentially 1/72th of an inch. Defaults to 12.
resolution   the pixel density of the display in dots per inch (DPI). Defaults to 100 DPI.

OGLFT::Face::Face ( FT_Face face,
float point_size = 12,
FT_UInt resolution = 100 )
 

Alternatively, the user may have already opened a face and just wants to draw with it. This is useful for Multiple Master fonts or combining multiple files to increase UNICODE point coverage.

Parameters:
face   open Freetype FT_Face.
point_size   the initial point size of the font to generate. A point is essentially 1/72th of an inch. Defaults to 12.
resolution   the pixel density of the display in dots per inch (DPI). Defaults to 100 DPI.

OGLFT::Face::~Face ( void ) [virtual]
 

Deleting a Face frees its FreeType face (and anything else it's styles have allocated).

Member Function Documentation

bool OGLFT::Face::addAuxiliaryFace ( FT_Face face )
 

Add another FT_Face to the OGLFT Face. Generally used to add more coverage of UNICODE points (at least that's the plan). This routine takes an already open FT_Face. The user is responsible for clean up.

Parameters:
face   open FreeType FT_Face
Returns:
true if face was successfully added.

bool OGLFT::Face::addAuxiliaryFace ( const char * filename )
 

Add another FT_Face to the OGLFT Face. Generally used to add more coverage of UNICODE points (at least that's the plan). This routine takes a filename and takes ownership of the FT_Face.

Parameters:
filename   name of file containing font face data.
Returns:
true if face was successfully added.

bool OGLFT::Face::advance ( void ) const [inline]
 

Returns:
the advance value.

int OGLFT::Face::ascender ( void ) [inline]
 

Returns:
the nominal ascender from the face. This is in "notional" units.

GLfloat OGLFT::Face::backgroundAlpha ( void ) const [inline]
 

Returns:
the alpha component of the background color

GLfloat OGLFT::Face::backgroundBlue ( void ) const [inline]
 

Returns:
the blue component of the background color

GLfloat OGLFT::Face::backgroundGreen ( void ) const [inline]
 

Returns:
the green component of the background color

GLfloat OGLFT::Face::backgroundRed ( void ) const [inline]
 

Returns:
the red component of the background color

DisplayLists & OGLFT::Face::characterDisplayLists ( void ) [inline]
 

Returns:
a reference to the array of character display lists. This is the live list as stored in the Face.

GLfloat OGLFT::Face::characterRotationZ ( void ) const [pure virtual]
 

Returns:
the character rotation in the Z direction.

Reimplemented in OGLFT::Polygonal, OGLFT::Raster, and OGLFT::Texture.

GLuint OGLFT::Face::compile ( const QChar c )
 

Compile a single character (glyph) into an OpenGL display list for later rendering. The Face does keep track of these display lists, so do not delete them.

Parameters:
c   the (UNICODE) character to compile.
Returns:
the display list name for the character.

GLuint OGLFT::Face::compile ( unsigned char c )
 

Compile a single character (glyph) into an OpenGL display list for later rendering. The Face does keep track of these display lists, so do not delete them.

Parameters:
c   the (latin1) character to compile.
Returns:
the display list name for the character.

GLuint OGLFT::Face::compile ( const QString s )
 

Compile a string into an OpenGL display list for later rendering. Essentially, the string is rendered at the origin of the current MODELVIEW. Note: no other display lists should be open when this routine is called. Also, the Face does not keep track of these lists, so you must delete them in order to recover the memory.

Parameters:
s   the (UNICODE) string to compile.
Returns:
the display list name for the string.

GLuint OGLFT::Face::compile ( const char * s )
 

Compile a string into an OpenGL display list for later rendering. Essentially, the string is rendered at the origin of the current MODELVIEW. Note: no other display lists should be open when this routine is called. Also, the Face does not keep track of these lists, so you must delete them in order to recover the memory.

Parameters:
s   the (latin1) string to compile.
Returns:
the display list name for the string.

enum GlyphCompileMode OGLFT::Face::compileMode ( void ) const [inline]
 

Returns:
the current glyph compile mode.

int OGLFT::Face::descender ( void ) [inline]
 

Returns:
the nominal descender from the face. This is in "notional" units.

void OGLFT::Face::draw ( GLfloat x,
GLfloat y,
const QString & format,
double number )
 

Draw a real number per the given format at the given 2D point.

Parameters:
x   the X position.
y   the Y position.
format   Like a typical printf format. Regular text is printed while a '%' introduces the real number's format. Includes the following format flags:
  • %x.yf - floating point in field width x and precision y
  • %x.ye - scientific notation in field width x and precision y
  • %x.yg - pick best floating or scientific in field width x and precision y
  • %p - draw as a proper fraction, e.g. 1 1/2. Note: this currently requires a special font which encodes glyphs to be drawn for the numerator and demoninator in the UNICODE Private Area (0xE000).
number   the numeric value.

void OGLFT::Face::draw ( GLfloat x,
GLfloat y,
const QString s )
 

Draw a string at the given 2D point.

Parameters:
x   the X position.
y   the Y position.
s   the (UNICODE) string to draw.

void OGLFT::Face::draw ( GLfloat x,
GLfloat y,
const char * s )
 

Draw a string at the given 2D point.

Parameters:
x   the X position.
y   the Y position.
s   the (latin1) string to draw.

void OGLFT::Face::draw ( GLfloat x,
GLfloat y,
QChar c )
 

Draw the (UNICODE) character at the given 2D point. Note that the MODELVIEW matrix is modified by the glyph advance. Draw a string if you don't want the MODELVIEW matrix changed.

Parameters:
x   the X position.
y   the Y position.
c   the (UNICODE) character to draw.

void OGLFT::Face::draw ( GLfloat x,
GLfloat y,
unsigned char c )
 

Draw the (latin1) character at the given 2D point. Note that the MODELVIEW matrix is modified by the glyph advance. Draw a string if you don't want the MODELVIEW matrix changed.

Parameters:
x   the X position.
y   the Y position.
c   the (latin1) character to draw.

void OGLFT::Face::draw ( const QChar c )
 

Draw the character using the current MODELVIEW matrix. Note that the MODELVIEW matrix is modified by the glyph advance. Draw a string if you don't want the MODELVIEW matrix changed.

Parameters:
c   the (UNICODE) character to draw.

void OGLFT::Face::draw ( unsigned char c )
 

Draw the character using the current MODELVIEW matrix. Note that the MODELVIEW matrix is modified by the glyph advance. Draw a string if you don't want the MODELVIEW matrix changed.

Parameters:
c   the (latin1) character to draw.

void OGLFT::Face::draw ( const QString s )
 

Draw a (UNICODE) string using the current MODELVIEW matrix. If advance is true, then the final glyph advance changes to the MODELVIEW matrix are left in place.

Parameters:
s   the (UNICODE) string to draw.

void OGLFT::Face::draw ( const char * s )
 

Draw a (latin1) string using the current MODELVIEW matrix. If advance is true, then the final glyph advance changes to the MODELVIEW matrix are left in place.

Parameters:
s   the (latin1) string to draw.

GLfloat OGLFT::Face::foregroundAlpha ( void ) const [inline]
 

Returns:
the alpha component of the foreground color

GLfloat OGLFT::Face::foregroundBlue ( void ) const [inline]
 

Returns:
the blue component of the foreground color

GLfloat OGLFT::Face::foregroundGreen ( void ) const [inline]
 

Returns:
the green component of the foreground color

GLfloat OGLFT::Face::foregroundRed ( void ) const [inline]
 

Returns:
the red component of the foreground color

double OGLFT::Face::height ( void ) const [pure virtual]
 

Returns:
the height (i.e., line spacing) at the current character size.

Reimplemented in OGLFT::Polygonal, OGLFT::Raster, and OGLFT::Texture.

enum HorizontalJustification OGLFT::Face::horizontalJustification ( void ) const [inline]
 

Returns:
the horizontal justification.

bool OGLFT::Face::isValid ( void ) const [inline]
 

Let the user test to see if the font was loaded OK.

Returns:
true if the FT_Face was successfully created.

BBox OGLFT::Face::measure ( const QString & format,
double number ) [virtual]
 

Compute the bounding box info for a real number formatted as specified.

Parameters:
format   (see draw for valid formats)
value   real number.
Returns:
the bounding box of the formatted number.

Reimplemented in OGLFT::Polygonal, OGLFT::Raster, and OGLFT::Texture.

BBox OGLFT::Face::measure ( const QString s ) [virtual]
 

Compute the bounding box info for a string.

Parameters:
s   the (UNICODE) string to measure.
Returns:
the bounding box of s.

BBox OGLFT::Face::measure ( const char * s ) [virtual]
 

Compute the bounding box info for a string.

Parameters:
s   the (latin1) string to measure.
Returns:
the bounding box of s.

Reimplemented in OGLFT::Polygonal, OGLFT::Raster, and OGLFT::Texture.

BBox OGLFT::Face::measure ( QChar c ) [pure virtual]
 

Compute the bounding box info for a character.

Parameters:
c   the (UNICODE) character to measure.
Returns:
the bounding box of c.

Reimplemented in OGLFT::Polygonal, OGLFT::Raster, and OGLFT::Texture.

BBox OGLFT::Face::measure ( unsigned char c ) [pure virtual]
 

Compute the bounding box info for a character.

Parameters:
c   the (latin1) character to measure.
Returns:
the bounding box of c.

Reimplemented in OGLFT::Polygonal, OGLFT::Raster, and OGLFT::Texture.

float OGLFT::Face::pointSize ( void ) [inline]
 

Returns:
the current point size.

FT_UInt OGLFT::Face::resolution ( void ) [inline]
 

Returns:
the current raster resolution.

void OGLFT::Face::setAdvance ( bool advance ) [inline]
 

If advance is true, then the changes made to the MODELVIEW matrix to render a string are allowed to remain. Otherwise, the library pushes the current MODELVIEW matrix onto the matrix stack, renders the string and then pops it off again. Rendering a character always modifies the MODELVIEW matrix.

Parameters:
advance   whether or not the MODELVIEW matrix should be left translated by the advancement of a rendered string.

void OGLFT::Face::setBackgroundColor ( const QRgb background_color )
 

This is the nominal background color of the glyphs. A lot of other things can alter what you actually see! Note that changing the background color invalidates the glyph cache.

Parameters:
background_color   the background color as an unsigned int.

void OGLFT::Face::setBackgroundColor ( const GLfloat background_color[4] )
 

This is the nominal background color of the glyphs. A lot of other things can alter what you actually see! Note that changing the background color invalidates the glyph cache.

Parameters:
background_color   an array of 4 values corresponding to the red, green, blue and alpha components of the background color.

void OGLFT::Face::setBackgroundColor ( GLfloat red = 1.0,
GLfloat green = 1.0,
GLfloat blue = 1.0,
GLfloat alpha = 0.0 )
 

This is the nominal background color of the glyphs. A lot of other things can alter what you actually see! Note that changing the background color invalidates the glyph cache.

Parameters:
red   the red component of the background color.
green   the green component of the background color.
blue   the blue component of the background color.
alpha   the alpha component of the background color.

void OGLFT::Face::setCharacterDisplayLists ( const DisplayLists & character_display_lists ) [inline]
 

Specify an OpenGL display list to be invoked before each character in a string. Face makes a copy of the argument. Pass an empty DisplayLists to disable this feature.

Parameters:
character_display_lists   STL vector<GLuint> containing a display list to invoke before each glyph in a string is drawn.

void OGLFT::Face::setCharacterRotationReference ( unsigned char c )
 

The z rotation angle needs a center. Nominate a character whose center is to be the center of rotation. By default, use "o".

Parameters:
c   rotation reference character.

void OGLFT::Face::setCharacterRotationZ ( GLfloat character_rotation_z ) [pure virtual]
 

Set the individual character rotation in the Z direction.

Parameters:
character_rotation_z   angle in degrees of z rotation.

Reimplemented in OGLFT::Polygonal, OGLFT::Raster, and OGLFT::Texture.

void OGLFT::Face::setCompileMode ( enum GlyphCompileMode compile_mode ) [inline]
 

By default, each time a new character is seen, its glyph is rendered into a display list. This means that a display list cannot already be open (since OpenGL doesn't allow nested display list creation). Rendering can be set into immediate mode in which case glyphs are rendered from display lists if available, but are otherwise generated anew each time.

Parameters:
compile_mode   the new compile mode.

void OGLFT::Face::setForegroundColor ( const QRgb foreground_color )
 

This is the nominal color of the glyphs. A lot of other things can alter what you actually see! Note that changing the foreground color invalidates the glyph cache.

Parameters:
foreground_color   the foreground color as an unsigned int.

void OGLFT::Face::setForegroundColor ( const GLfloat foreground_color[4] )
 

This is the nominal color of the glyphs. A lot of other things can alter what you actually see! Note that changing the foreground color invalidates the glyph cache.

Parameters:
foreground_color   an array of 4 values corresponding to the red, green, blue and alpha components of the foreground color.

void OGLFT::Face::setForegroundColor ( GLfloat red = 0.0,
GLfloat green = 0.0,
GLfloat blue = 0.0,
GLfloat alpha = 1.0 )
 

This is the nominal color of the glyphs. A lot of other things can alter what you actually see! Note that changing the foreground color invalidates the glyph cache.

Parameters:
red   the red component of the foreground color.
green   the green component of the foreground color.
blue   the blue component of the foreground color.
alpha   the alpha component of the foreground color.

void OGLFT::Face::setHorizontalJustification ( enum HorizontalJustification horizontal_justification ) [inline]
 

Set the horizontal justification.

Parameters:
horizontal_justification   the new horizontal justification.

void OGLFT::Face::setPointSize ( float point_size )
 

For the rasterized styles (Monochrome, Grayscale, Translucent, Texture), glyphs are rendered at the pixel size given by:

point_size [pts] * / 72 [pts/in] * resolution [dots/in] = [dots].

For the polygon styles (Outline, Filled, Solid), the "nominal" size of the glyphs is:

point_size[pts] / 72 [pts/in] * resolution [dots/in] / units_per_EM [font unit/EM] = [dots * EM].

If the MODELVIEW and PROJECTION matrices are such that one screen pixel corresponds to one modeling unit, then polygonal Faces will be the same size as raster Faces.

Note that changing the point size after Face creation will invalidate the cache of OpenGL display lists and any other information which the individual styles have cached.

Parameters:
point_size   the new point size in points (1/72-th inch).

void OGLFT::Face::setResolution ( FT_UInt resolution )
 

For the rasterized styles (Monochrome, Grayscale, Translucent, Texture), the exact rendered size of the glyphs depends on the resolution of the display (as opposed to the polygon styles whose size is controlled by the viewing matrices). The Texture style is slightly different because the glyphs are texture-mapped onto an arbitrary rectangle; here, the resolution only controls how accurately the glyph is rendered.

Parameters:
resolution   the resolution in DPI (dots per inch).

void OGLFT::Face::setStringRotation ( GLfloat string_rotation )
 

Rotate an entire string through the given angle (in the Z plane only). (Somewhat pointless for the vector styles since you can do mostly the same thing with the MODELVIEW transform, however, for what its worth, this routine uses the FreeType rotation function to compute the "proper" metrics for glyph advance.)

Parameters:
string_rotation   angle in degrees of z rotation.

void OGLFT::Face::setVerticalJustification ( enum VerticalJustification vertical_justification ) [inline]
 

Set the vertical justification.

Parameters:
vertical_justification   the new vertical justification

GLfloat OGLFT::Face::stringRotation ( void ) const [inline]
 

Returns:
the (Z plane) string rotation angle.

enum VerticalJustification OGLFT::Face::verticaljustification ( void ) const [inline]
 

Returns:
the vertical justification.

The documentation for this class was generated from the following files:
Generated at Fri Jul 12 10:47:15 2002 for OGLFT by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001