Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members

nglFontBase Class Reference

#include <nglFontBase.h>

Inheritance diagram for nglFontBase:

nglError nglFont List of all members.

Detailed Description

Base font class.

This base font class does not handle final rendering. It is intended to support all font services but rendering. Specific rendering methods are implemented atop this class using some advanced and specialized services (see the protected interface).

This class implementation is based on FreeType ( http://www.freetype.org ). It will load fonts of various formats (see nglFontBase()), expose global font as well as glyph specific informations and metrics, control scalable fonts rasterizing (hinting, anti-aliasing), manage charmaps and synthesize missing ones, calculate string layout (no BiDi or vertical support for now) and somehow contribute to the world's entropy.

Although this class is intented to handle transparently both scalable and bitmap fonts, there are some major design differences you ought to know :


Public Types

typedef GlyphData * GlyphHandle
typedef uint RenderMode
enum  GlyphType {
  eGlyphNative,
  eGlyphOutline,
  eGlyphBitmap
}

Public Member Functions

Life cycle
 nglFontBase ()
 nglFontBase (uint8 *pBuffer, uint32 BufferSize, uint Face=0)
 nglFontBase (const nglPath &rFontFile, uint Face=0)
 nglFontBase (const nglFontBase &rFont)
virtual ~nglFontBase ()
Global font info & metrics
bool GetInfo (nglFontInfo &rInfo, nglFontUnit Unit=eFontUnitPixel) const
nglString GetFamilyName () const
nglString GetStyleName () const
bool IsScalable () const
bool IsBold () const
bool IsItalic () const
float GetHeight (nglFontUnit Unit=eFontUnitPixel, float DefaultSpacing=1.f) const
uint GetGlyphCount () const
float EMToPixel (float Value) const
float EMToPoint (float Value) const
float PixelToPoint (float Value) const
float PointToPixel (float Value) const
Glyph metrics
float GetSize (nglFontUnit Unit=eFontUnitPixel) const
bool SetSize (float Size, nglFontUnit Unit=eFontUnitPixel)
float GetResolution () const
void SetResolution (float Resolution)
bool GetMetrics (nglGlyphInfo &rInfo, nglChar Char, GlyphType Type=eGlyphBitmap) const
virtual bool GetGlyphInfo (nglGlyphInfo &rInfo, uint Index, GlyphType Type) const
bool GetKerning (uint Left, uint Right, float &rX, float &rY) const
Character maps
int GetCharMapCount () const
int GetCharMap () const
bool SetCharMap (int Index)
const nglChar * GetCharMapName () const
const nglChar * GetCharMapName (int Index) const
int GetGlyphIndexes (const nglChar *pSource, int SourceLength, uint *pIndexes, int IndexesLength) const
Rendering/rasterizing (scalable fonts only)
RenderMode GetRenderMode () const
virtual bool SetRenderMode (RenderMode Mode)
Glyph metrics, contour and bitmap retrieval
GlyphHandle GetGlyph (uint Index, GlyphType Type) const
GlyphType GetGlyphType (GlyphHandle Glyph) const
bool GetGlyphBitmap (GlyphHandle Glyph, GlyphBitmap &rBitmap) const
bool GetBitmap8 (const GlyphBitmap &rSrc, GlyphBitmap &rDst) const

Static Public Attributes

static const RenderMode AntiAliasing
static const RenderMode Hinting
static float DefaultPixelSize

Protected Member Functions

virtual const nglChar * OnError (uint &rError) const

Friends

class nglFontInfo

Classes

class  GlyphBitmap
 Description of a glyph bitmap representation. More...

Member Typedef Documentation

typedef class GlyphData* nglFontBase::GlyphHandle
 

typedef uint nglFontBase::RenderMode
 

Rendering flags. See SetRenderMode() and GetRenderMode().

Member Enumeration Documentation

enum nglFontBase::GlyphType
 

Glyph fetching mode. See GetGlyphInfo() and GetGlyph().

Enumeration values:
eGlyphNative  Fetch native format (bitmap for fixed sizes fonts, outlines for scalable fonts).
eGlyphOutline  Fetch as outlines (only works for scalable fonts).
eGlyphBitmap  Fetch as a bitmap (always possible, might imply rendering).

Constructor & Destructor Documentation

nglFontBase::nglFontBase (   ) 
 

Create default font Create a font from an embedded description. It implements all ASCII characters using a monospace, lightly serifed, legible scalable font.

nglFontBase::nglFontBase (  uint8 *  pBuffer,
uint32  BufferSize,
uint  Face = 0
) 
 

Create font from memory. Create a font from a memory buffer.

nglFontBase::nglFontBase (  const nglPath &  rFontFile,
uint  Face = 0
) 
 

Create a font from a file

Parameters:
rFontFile path to font file
Face face index for multi-face fonts
This will load a font file using any of the FreeType's supported file formats, including TrueType, PostScript Type1, Type42, PCF and Windows' FON (among others).

nglFontBase::nglFontBase (  const nglFontBase &  rFont  ) 
 

Copy a font

Parameters:
rFont source font
Make a copy of the font ressource. Current metrics are also copied (size, resolution and kerning). The charmap is also preserved.

Note : this copy constructor is lightweight due to the cache infrastructure.

virtual nglFontBase::~nglFontBase (   )  [virtual]
 

Release the font ressource

Member Function Documentation

float nglFontBase::EMToPixel (  float  Value  )  const
 

Convert from EM to pixels (undefined for bitmap fonts).

float nglFontBase::EMToPoint (  float  Value  )  const
 

Convert from EM to points (undefined for bitmap fonts).

bool nglFontBase::GetBitmap8 (  const GlyphBitmap &  rSrc,
GlyphBitmap &  rDst
)  const
 

Convert a 1-bit monochrome bitmap to a 8-bit one

Parameters:
rSrc source bitmap, if not monochrome will fail
rDst destination bitmap, must have its pData buffer allocated
Returns:
true if the conversion was succesfull
GetBitmap8() can convert monochrome bitmaps into graylevel ones, simply expanding a set bit as a full byte (255).

int nglFontBase::GetCharMap (   )  const
 

Return the current charmap

Returns:
current charmap index, between 0 and GetCharMapCount()-1, or -1 if no charmap is selected

int nglFontBase::GetCharMapCount (   )  const
 

Returns the number of supported charmaps.

const nglChar* nglFontBase::GetCharMapName (  int  Index  )  const
 

Get charmap Index human readable name.

const nglChar* nglFontBase::GetCharMapName (   )  const
 

Get current charmap human readable name.

nglString nglFontBase::GetFamilyName (   )  const
 

Returns font family (ie. Helvetica, Geneva, etc).

GlyphHandle nglFontBase::GetGlyph (  uint  Index,
GlyphType  Type
)  const
 

Fetch a glyph description from a a given glyph index

Parameters:
Index glyph index
Type extraction mode (see GlyphType)
Returns:
a GlyphHandle of the type Type, NULL if an error occured
For scalable fonts, using the eGlyphBitmap type implies rendering. Rendering is controled by the current render mode (see SetRenderMode()).

GetGlyph() can return monochrome (1 bit) or graylevel (8 bit) bitmaps, check the pixel_mode field. See also GetBitmap8().

bool nglFontBase::GetGlyphBitmap (  GlyphHandle  Glyph,
GlyphBitmap &  rBitmap
)  const
 

Retrieve bitmap info from a glyph handle

Parameters:
Glyph glyph handle
rBitmap bitmap info holder
Returns:
true if rBitmap contains valid informations

uint nglFontBase::GetGlyphCount (   )  const
 

Returns the number of available glyphs.

int nglFontBase::GetGlyphIndexes (  const nglChar *  pSource,
int  SourceLength,
uint *  pIndexes,
int  IndexesLength
)  const
 

Retrieve a range of glyph indexes from a nglChar array (encoding aware)

Parameters:
pSource nglChar source array (zero terminal is not handled)
SourceLength pSource array length in nglChars
pIndexes target glyph indexes array
IndexesLength pIndexes array length (in uints)
Returns:
number of nglChars/glyph indexes converted, -1 if a fatal error occured
This method retrieves glyph indexes from nglChars using the current active charmap.

virtual bool nglFontBase::GetGlyphInfo (  nglGlyphInfo &  rInfo,
uint  Index,
GlyphType  Type
)  const [virtual]
 

Fetch a glyph description from a a given glyph index

Parameters:
rInfo information receptacle
Index glyph index
Type compute metrics from outline (if available) or bitmap
Returns:
rInfo contains valid informations if true
Metrics can be computed against outline (only available for scalable fonts), or from their bitmap representation. Due to the hinting and rounding process, the metrics may differ between the outline and bitmap computations. You should use the same glyph type for layout computing and rendering.

If Char does not have a corresponding glyph, returns false (see SetCharMap()). Output metrics are always in pixels. See nglGlyphInfo for more info.

To retrieve string metrics, use nglFontLayout::GetMetrics().

GlyphType nglFontBase::GetGlyphType (  GlyphHandle  Glyph  )  const
 

Returns the type (outline vs. bitmap) of a glyph handle

Parameters:
Glyph glyph handle
Returns:
glyph type

float nglFontBase::GetHeight (  nglFontUnit  Unit = eFontUnitPixel,
float  DefaultSpacing = 1.f
)  const
 

Return font height

Parameters:
Unit output unit
DefaultSpacing user specified interline spacing (or line gap) when the font does not define one using Unit as input unit)
Returns:
font height in Unit or zero when not applicable
The font height is the distance that should separate two successive (horizontal) baselines.

Most scalable fonts define their font height, a value specifically choosen by the font designer. In this case, the DefaultSpacing value is ignored and the original font height is returned.

Most bitmap fonts do not have a defined font height. If such a value is not present in the font ressource, the font height is computed as the sum of the current font size and the DefaultSpacing parameter. An interline spacing of 1 pixel is pretty common in this case.

Please note that the Height field of nglFontInfo only returns the designer's font height when it's defined, zero otherwise. GetHeight() is a higher level method which helps you to support fonts which do not define their height (mostly bitmap fonts).

bool nglFontBase::GetInfo (  nglFontInfo &  rInfo,
nglFontUnit  Unit = eFontUnitPixel
)  const
 

Fetch font informations and global metrics

Parameters:
rInfo information receptacle
Unit unit used in metric fields
Returns:
rInfo contains valid informations if true
Return a wealth of information about this font face. See nglFontInfo.

bool nglFontBase::GetKerning (  uint  Left,
uint  Right,
float &  rX,
float &  rY
)  const
 

Fetch kerning values from a glyph pair

Parameters:
Left Left glyph index
Right Right glyph index
rX horizontal advance return
rY vertical advance return
Returns:
true if rX and rY represent a valid kerning vector
This methods work on raw glyph indexes because it is expected to be called from a layout implementation (see nglFontLayout), where indexes are proper glyph handlers.

bool nglFontBase::GetMetrics (  nglGlyphInfo &  rInfo,
nglChar  Char,
GlyphType  Type = eGlyphBitmap
)  const
 

Fetch glyph metrics

Parameters:
rInfo information receptacle
Char character code of the inspected glyph
Type compute metrics from outline (if available) or bitmap
Returns:
rInfo contains valid informations if true
This is a frontend to GetGlyphInfo(), but with a character code (with respect to the curretn charmap) instead of a raw glyph index.

RenderMode nglFontBase::GetRenderMode (   )  const
 

Get current rendering mode.

float nglFontBase::GetResolution (   )  const
 

Get current resolution in DPI (dots per inch).

float nglFontBase::GetSize (  nglFontUnit  Unit = eFontUnitPixel  )  const
 

Returns current font size using Unit.

nglString nglFontBase::GetStyleName (   )  const
 

Returns font style (ie. Bold, Italic, Condensed, etc).

bool nglFontBase::IsBold (   )  const
 

Returns font weight, ie. bold or regular.

bool nglFontBase::IsItalic (   )  const
 

Returns font slant, ie. italic or regular.

bool nglFontBase::IsScalable (   )  const
 

Returns wether the font is scalable or not (ie. bitmap based).

virtual const nglChar* nglFontBase::OnError (  uint &  rError  )  const [protected, virtual]
 

Parameters:
rError error code
Returns:
error message, or NULL if rError is out of bounds
When the user invokes GetErrorStr() on an object, the OnError() callback is called with the given error code and should return the corresponding message. When several classes have different string error tables in the same hierarchy, the latest derivation's OnError() is called : it should then use a parent-first search. Example :

const nglChar** ChildErrorTable = {_T("no error"), _T("Bad luck"), NULL};

const nglChar* Child::OnError (uint& rError) const
{
  return FetchError(ChildErrorTable, Parent::OnError(rError), rError);
}

Implements nglError.

Reimplemented in nglFont.

float nglFontBase::PixelToPoint (  float  Value  )  const
 

Convert from pixels to points (font size independent).

float nglFontBase::PointToPixel (  float  Value  )  const
 

Convert from points to pixels (font size independent).

bool nglFontBase::SetCharMap (  int  Index  ) 
 

Select current charmap

Parameters:
Index charmap index, between 0 and GetCharMapCount()-1
If the font embeds several charmaps, you can choose one by yourself. At creation time, nglFontBase will search for a Unicode charmap, then fallback to the first available charmap, and finaly select none if none is available.

virtual bool nglFontBase::SetRenderMode (  RenderMode  Mode  )  [virtual]
 

Set rendering mode

Parameters:
Mode a bitmask of RenderMode constants
Returns:
true if the rendering mode was succesfully applied
The rendering mode affects the way scalable fonts are rendered as bitmap.

AntiAliasing will use an 8bit alpha channel to represent smooth edges. You can apply this mask to a texture or a plain color, blend this on the target surface, and thus obtain smoothed font contours. Anti-aliasing is turned on as a default for scalable fonts.

Most scalable fonts are hinted : the font designer added some information to help the renderer keep some font features consistant, such as stem width or spacing, serif control, and so on. These hints are especially important (and well tuned) for small sizes like 10-20 pixels. Hinting is turned on as a default.

void nglFontBase::SetResolution (  float  Resolution  ) 
 

Set current resolution

Parameters:
Resolution new resolution in DPI (dots per inch)
The resolution is the link between a pixel (being a screen pixel or a printer's ink bubble) and its physical size. A dot is a physical measure which is equal to a 72th of an inch (0.35 mm). This parameter is used when input or output metric values are given using eFontUnitPoint. The default is 72dpi (1 pixel = 1 dot).

You can fetch and use the physical resolution of the display device from a nglWindow instance with nglWindow::GetResolution().

bool nglFontBase::SetSize (  float  Size,
nglFontUnit  Unit = eFontUnitPixel
) 
 

Set current font size

Parameters:
Size new font size, using Unit
Unit input unit
Returns:
true if the new font size Size was succesfully applied
Changing the current font size for a scalable font is always possible, but is restricted to some discrete values for bitmap fonts. Bitmap fonts can embed several glyph sizes, they are described in pixels and can be selected using this method.

Friends And Related Function Documentation

friend class nglFontInfo [friend]
 

Member Data Documentation

const RenderMode nglFontBase::AntiAliasing [static]
 

Use anti-aliasing. See SetRenderMode().

float nglFontBase::DefaultPixelSize [static]
 

Default size (in pixels) for scalable fonts.

const RenderMode nglFontBase::Hinting [static]
 

Interpret font hints. See SetRenderMode().

Generated on Thu Feb 3 22:26:10 2005 for NGL by  doxygen 1.4.1