FreeTypeGX Class Reference

Wrapper class for the FreeType library with GX rendering. More...

#include <FreeTypeGX.h>

Public Member Functions
	FreeTypeGX (uint8_t textureFormat=GX_TF_RGBA8, uint8_t vertexIndex=GX_VTXFMT1)
	~FreeTypeGX ()
bool	setKerningEnabled (bool enabled)
bool	getKerningEnabled ()
bool	setTextInfoCachingEnabled (bool enabled)
bool	getTextInfoCachingEnabled ()
void	clearTextInfoCache ()
void	setVertexFormat (uint8_t vertexIndex)
void	setCompatibilityMode (uint32_t compatibilityMode)
uint16_t	loadFont (uint8_t *fontBuffer, FT_Long bufferSize, FT_UInt pointSize, bool cacheAll=false)
uint16_t	loadFont (const uint8_t *fontBuffer, FT_Long bufferSize, FT_UInt pointSize, bool cacheAll=false)
uint16_t	drawText (int16_t x, int16_t y, wchar_t *text, GXColor color=ftgxWhite, uint16_t textStyling=FTGX_NULL)
uint16_t	drawText (int16_t x, int16_t y, wchar_t const *text, GXColor color=ftgxWhite, uint16_t textStyling=FTGX_NULL)
uint16_t	getWidth (wchar_t *text)
uint16_t	getWidth (wchar_t const *text)
uint16_t	getHeight (wchar_t *text)
uint16_t	getHeight (wchar_t const *text)
Static Public Member Functions
static wchar_t *	charToWideChar (char *p)
static wchar_t *	charToWideChar (const char *p)
static uint16_t	setMaxVideoWidth (uint16_t width)
Private Member Functions
uint16_t	getStyleOffsetWidth (uint16_t width, uint16_t format)
uint16_t	getStyleOffsetHeight (uint16_t format)
ftgxCharData *	getCharacter (wchar_t character)
void	unloadFont ()
ftgxCharData *	cacheGlyphData (wchar_t charCode)
uint16_t	cacheGlyphDataComplete ()
void	loadGlyphData (FT_Bitmap bmp, ftgxCharData charData)
void	setDefaultMode ()
void	drawTextFeature (int16_t x, int16_t y, uint16_t width, uint16_t format, GXColor color)
void	copyTextureToFramebuffer (GXTexObj *texObj, f32 texWidth, f32 texHeight, int16_t screenX, int16_t screenY, GXColor color)
void	copyFeatureToFramebuffer (f32 featureWidth, f32 featureHeight, int16_t screenX, int16_t screenY, GXColor color)
Static Private Member Functions
static uint16_t	adjustTextureWidth (uint16_t textureWidth, uint8_t textureFormat)
static uint16_t	adjustTextureHeight (uint16_t textureHeight, uint8_t textureFormat)
Private Attributes
FT_Library	ftLibrary
FT_Byte *	ftFontBuffer
FT_Long	ftFontBufferSize
FT_UInt	ftPointSize
FT_Short	ftAscender
FT_Short	ftDescender
FT_Short	ftMiddle
bool	ftKerningEnabled
FT_Face	ftFace
uint8_t	textureFormat
uint8_t	vertexIndex
uint32_t	compatibilityMode
std::map< wchar_t, ftgxCharData >	fontData
bool	infoCachingEnabled
std::map< const wchar_t *, ftgxTextInfo >	cacheTextInfo
Static Private Attributes
static uint16_t	maxVideoWidth = 0

Detailed Description

Wrapper class for the FreeType library with GX rendering.

Author:: Armin Tamzarian

Version:: 0.3.2

FreeTypeGX acts as a wrapper class for the FreeType library. It supports precaching of transformed glyph data into a specified texture format. Rendering of the data to the EFB is accomplished through the application of high performance GX texture functions resulting in high throughput of string rendering.

Constructor & Destructor Documentation

FreeTypeGX::FreeTypeGX	(	uint8_t	textureFormat = `GX_TF_RGBA8`,
		uint8_t	vertexIndex = `GX_VTXFMT1`
	)

Default constructor for the FreeTypeGX class.

Parameters:

	textureFormat	Optional format (GX_TF_*) of the texture as defined by the libogc gx.h header file. If not specified default value is GX_TF_RGBA8.
	vertexIndex	Optional vertex format index (GX_VTXFMT*) of the glyph textures as defined by the libogc gx.h header file. If not specified default value is GX_VTXFMT1.

FreeTypeGX::~FreeTypeGX ( )

Default destructor for the FreeTypeGX class.

Member Function Documentation

uint16_t FreeTypeGX::adjustTextureHeight	(	uint16_t	textureHeight,
		uint8_t	textureFormat
	)			`[static, private]`

Adjusts the texture data buffer to necessary height for a given texture format.

This routine determines adjusts the given texture height into the required height to hold the necessary texture data for proper alignment.

Parameters:

	textureHeight	The initial guess for the texture height.
	textureFormat	The texture format to which the data is to be converted.

Returns:: The correctly adjusted texture height.

uint16_t FreeTypeGX::adjustTextureWidth	(	uint16_t	textureWidth,
		uint8_t	textureFormat
	)			`[static, private]`

Adjusts the texture data buffer to necessary width for a given texture format.

This routine determines adjusts the given texture width into the required width to hold the necessary texture data for proper alignment.

Parameters:

	textureWidth	The initial guess for the texture width.
	textureFormat	The texture format to which the data is to be converted.

Returns:: The correctly adjusted texture width.

ftgxCharData * FreeTypeGX::cacheGlyphData ( wchar_t charCode ) [private]

Caches the given font glyph in the instance font texture buffer.

This routine renders and stores the requested glyph's bitmap and relevant information into its own quickly addressable structure within an instance-specific map.

Parameters:

charCode

The requested glyph's character code.

Returns:: A pointer to the allocated font structure.

uint16_t FreeTypeGX::cacheGlyphDataComplete ( ) [private]

Locates each character in this wrapper's configured font face and process them.

This routine locates each character in the configured font face and renders the glyph's bitmap. Each bitmap and relevant information is loaded into its own quickly addressable structure within an instance-specific map.

wchar_t * FreeTypeGX::charToWideChar ( const char * strChar ) [static]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

wchar_t * FreeTypeGX::charToWideChar ( char * strChar ) [static]

Convert a short char string to a wide char string.

This routine converts a supplied shot character string into a wide character string. Note that it is the user's responsibility to clear the returned buffer once it is no longer needed.

Parameters:

strChar

Character string to be converted.

Returns:: Wide character representation of supplied character string.

void FreeTypeGX::clearTextInfoCache ( )

Clears the current cache of text infos.

This clears the cache of text infos regardless of the enabled state of the info caching flag.

void FreeTypeGX::copyFeatureToFramebuffer	(	f32	featureWidth,
		f32	featureHeight,
		int16_t	screenX,
		int16_t	screenY,
		GXColor	color
	)			`[private]`

Creates a feature quad to the EFB.

This function creates a simple quad for displaying stylized text.

Parameters:

	featureWidth	The pixel width of the quad.
	featureHeight	The pixel height of the quad.
	screenX	The screen X coordinate at which to output the quad.
	screenY	The screen Y coordinate at which to output the quad.
	color	Color to apply to the texture.

void FreeTypeGX::copyTextureToFramebuffer	(	GXTexObj *	texObj,
		f32	texWidth,
		f32	texHeight,
		int16_t	screenX,
		int16_t	screenY,
		GXColor	color
	)			`[private]`

Copies the supplied texture quad to the EFB.

This routine uses the in-built GX quad builder functions to define the texture bounds and location on the EFB target.

Parameters:

	texObj	A pointer to the glyph's initialized texture object.
	texWidth	The pixel width of the texture object.
	texHeight	The pixel height of the texture object.
	screenX	The screen X coordinate at which to output the rendered texture.
	screenY	The screen Y coordinate at which to output the rendered texture.
	color	Color to apply to the texture.

uint16_t FreeTypeGX::drawText	(	int16_t	x,
		int16_t	y,
		wchar_t const *	text,
		GXColor	color = `ftgxWhite`,
		uint16_t	textStyle = `FTGX_NULL`
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

uint16_t FreeTypeGX::drawText	(	int16_t	x,
		int16_t	y,
		wchar_t *	text,
		GXColor	color = `ftgxWhite`,
		uint16_t	textStyle = `FTGX_NULL`
	)

Processes the supplied text string and prints the results at the specified coordinates.

This routine processes each character of the supplied text string, loads the relevant preprocessed bitmap buffer, a texture from said buffer, and loads the resultant texture into the EFB.

Parameters:

	x	Screen X coordinate at which to output the text.
	y	Screen Y coordinate at which to output the text. Note that this value corresponds to the text string origin and not the top or bottom of the glyphs.
	text	NULL terminated string to output.
	color	Optional color to apply to the text characters. If not specified default value is ftgxWhite: (GXColor){0xff, 0xff, 0xff, 0xff}
	textStyle	Flags which specify any styling which should be applied to the rendered string.

Returns:: The number of characters printed.

void FreeTypeGX::drawTextFeature	(	int16_t	x,
		int16_t	y,
		uint16_t	width,
		uint16_t	textStyle,
		GXColor	color
	)			`[private]`

Internal routine to draw the features for stylized text.

This routine creates a simple feature for stylized text.

Parameters:

	x	Screen X coordinate of the text baseline.
	y	Screen Y coordinate of the text baseline.
	width	Pixel width of the text string.
	textStyle	Flags which specify any styling which should be applied to the rendered string.
	color	Color to be applied to the text feature.

ftgxCharData * FreeTypeGX::getCharacter ( wchar_t character ) [private]

Returns the FreeTypeGX font character data structure.

This routine locates the currently cached FreeTypeGX ftgxCharData structure for the supplied wide character. If the structure has not been loaded and cached the routine initialized the loading and caching of the structure for that data chatracter.

Parameters:

character

Character whose information needs to be retrieved.

Returns:: The font structure for the supplied character.

uint16_t FreeTypeGX::getHeight ( wchar_t const * text )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

uint16_t FreeTypeGX::getHeight ( wchar_t * text )

Processes the supplied string and return the height of the string in pixels.

This routine processes each character of the supplied text string and calculates the height of the entire string. Note that if precaching of the entire font set is not enabled any uncached glyph will be cached after the call to this function.

Parameters:

text

NULL terminated string to calculate.

Returns:: The height of the text string in pixels.

bool FreeTypeGX::getKerningEnabled ( )

Gets the current enabled state of the font kerning mode.

This routine gets the current enabled state of the font kerning mode.

Returns:: The enabled state of the font kerning.

uint16_t FreeTypeGX::getStyleOffsetHeight ( uint16_t format ) [private]

Determines the y offset of the rendered string.

This routine calculates the y offset of the rendered string based off of a supplied positional format parameter.

Parameters:

format

Positional format of the string.

uint16_t FreeTypeGX::getStyleOffsetWidth	(	uint16_t	width,
		uint16_t	format
	)			`[private]`

Determines the x offset of the rendered string.

This routine calculates the x offset of the rendered string based off of a supplied positional format parameter.

Parameters:

	width	Current pixel width of the string.
	format	Positional format of the string.

bool FreeTypeGX::getTextInfoCachingEnabled ( )

Gets the current enabled state of the text info caching mode.

This routine gets the current enabled state of the text info caching mode.

Returns:: The enabled state of the text info caching.

uint16_t FreeTypeGX::getWidth ( wchar_t const * text )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

uint16_t FreeTypeGX::getWidth ( wchar_t * text )

Processes the supplied string and return the width of the string in pixels.

This routine processes each character of the supplied text string and calculates the width of the entire string. Note that if precaching of the entire font set is not enabled any uncached glyph will be cached after the call to this function.

Parameters:

text

NULL terminated string to calculate.

Returns:: The width of the text string in pixels.

uint16_t FreeTypeGX::loadFont	(	const uint8_t *	fontBuffer,
		FT_Long	bufferSize,
		FT_UInt	pointSize,
		bool	cacheAll = `false`
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

uint16_t FreeTypeGX::loadFont	(	uint8_t *	fontBuffer,
		FT_Long	bufferSize,
		FT_UInt	pointSize,
		bool	cacheAll = `false`
	)

Loads and processes a specified true type font buffer to a specific point size.

This routine takes a precompiled true type font buffer and loads the necessary processed data into memory. This routine should be called before drawText will succeed.

Parameters:

	fontBuffer	A pointer in memory to a precompiled true type font buffer.
	bufferSize	Size of the true type font buffer in bytes.
	pointSize	The desired point size this wrapper's configured font face.
	cacheAll	Optional flag to specify if all font characters should be cached when the class object is created. If specified as false the characters only become cached the first time they are used. If not specified default value is false.

void FreeTypeGX::loadGlyphData	(	FT_Bitmap *	bmp,
		ftgxCharData *	charData
	)			`[private]`

Loads the rendered bitmap into the relevant structure's data buffer.

This routine does a simple byte-wise copy of the glyph's rendered 8-bit grayscale bitmap into the structure's buffer. Each byte is converted from the bitmap's intensity value into the a uint32_t RGBA value.

Parameters:

	bmp	A pointer to the most recently rendered glyph's bitmap.
	charData	A pointer to an allocated ftgxCharData structure whose data represent that of the last rendered glyph.

void FreeTypeGX::setCompatibilityMode ( uint32_t compatibilityMode )

Sets the TEV and VTX rendering compatibility requirements for the class.

This sets up the default TEV operation and VTX descriptions rendering values for the class. This ensures that FreeTypeGX can remain compatible with external libraries or project code. Certain external libraries or code by design or lack of foresight assume that the TEV operation and VTX descriptions values will remain constant or are always returned to a certain value. This will enable compatibility with those libraries and any other code which cannot or will not be changed.

Parameters:

compatibilityMode

Compatibility descriptor (FTGX_COMPATIBILITY_*) as defined in FreeTypeGX.h

void FreeTypeGX::setDefaultMode ( ) [private]

Sets the TEV operation and VTX descriptor values after texture rendering it complete.

This function calls the GX_SetTevOp and GX_SetVtxDesc functions with the compatibility parameters specified in setCompatibilityMode.

bool FreeTypeGX::setKerningEnabled ( bool enabled )

Enables or disables kerning of the output text.

This routine enables or disables kerning of the output text only if kerning is supported by the font. Note that by default kerning is enabled if it is supported by the font.

Parameters:

enabled

The enabled state of the font kerning.

Returns:: The resultant enabled state of the font kerning.

uint16_t FreeTypeGX::setMaxVideoWidth ( uint16_t width ) [static]

bool FreeTypeGX::setTextInfoCachingEnabled ( bool enabled )

Enables or disables info value caching of the output text.

This routine enables or disables width value caching of the output text in order avoid a repeated possible calculation of textual width within the drawText function. If enabled FreeTypeGX will cache the values of all text strings drawn until such time that clearTextWidthCache is called in order clear the current cache. Font width caching may be enabled or disabled at any time by calling this function. Note that by default this option is disabled to conserve memory.

Parameters:

enabled

The desired enabled state of the text info caching.

Returns:: The resultant enabled state of the text info caching.

void FreeTypeGX::setVertexFormat ( uint8_t vertexIndex )

Setup the vertex attribute formats for the glyph textures.

This function sets up the vertex format for the glyph texture on the specified vertex format index. Note that this function should not need to be called except if the vertex formats are cleared or the specified vertex format index is modified.

Parameters:

vertexIndex

Vertex format index (GX_VTXFMT*) of the glyph textures as defined by the libogc gx.h header file.

void FreeTypeGX::unloadFont ( ) [private]

Clears all loaded font glyph data.

This routine clears all members of the font map structure and frees all allocated memory back to the system.