Font class for use with RenderDevice. More...

Inherits G3D::ReferenceCountedObject.

Classes
struct	CPUCharVertex

Public Types
enum	Spacing { PROPORTIONAL_SPACING, FIXED_SPACING }
	Constant for draw2D. More...

enum	XAlign { XALIGN_RIGHT, XALIGN_LEFT, XALIGN_CENTER }
	Constant for draw2D. More...

enum	YAlign { YALIGN_TOP, YALIGN_BASELINE, YALIGN_CENTER, YALIGN_BOTTOM }
	Constant for draw2D. More...

Public Member Functions
Vector2	appendToCharVertexArray (Array< CPUCharVertex > &cpuCharArray, Array< int > &indexArray, RenderDevice *renderDevice, const String &s, const Point2 &pos2D, float size=12, const Color4 &color=Color3::black(), const Color4 &outline=Color4::clear(), XAlign xalign=XALIGN_LEFT, YAlign yalign=YALIGN_TOP, Spacing spacing=PROPORTIONAL_SPACING) const
	For high-performance rendering of substantial amounts of text. More...

Vector2	appendToCharVertexArrayWordWrap (Array< CPUCharVertex > &cpuCharArray, Array< int > &indexArray, RenderDevice *renderDevice, float wrapWidth, const String &s, const Point2 &pos2D, float size=12, const Color4 &color=Color3::black(), const Color4 &outline=Color4::clear(), XAlign xalign=XALIGN_LEFT, YAlign yalign=YALIGN_TOP, Spacing spacing=PROPORTIONAL_SPACING) const
	For high-performance rendering of substantial amounts of text. More...

Vector2	bounds (const String &s, float size=12, Spacing spacing=PROPORTIONAL_SPACING) const
	Computes the bounding extent of s at the given font size. More...

Vector2	boundsWordWrap (float maxWidth, const String &s, float size=12, Spacing spacing=PROPORTIONAL_SPACING) const

Vector2	draw2D (RenderDevice *renderDevice, const String &s, const Point2 &pos2D, float size=12, const Color4 &color=Color3::black(), const Color4 &outline=Color4::clear(), XAlign xalign=XALIGN_LEFT, YAlign yalign=YALIGN_TOP, Spacing spacing=PROPORTIONAL_SPACING) const
	Draws a proportional width font string. More...

Vector2	draw2DWordWrap (RenderDevice *renderDevice, float maxWidth, const String &s, const Point2 &pos2D, float size=12, const Color4 &color=Color3::black(), const Color4 &outline=Color4::clear(), XAlign xalign=XALIGN_LEFT, YAlign yalign=YALIGN_TOP, Spacing spacing=PROPORTIONAL_SPACING) const
	Wordwraps at maxWidth. More...

Vector2	draw3D (RenderDevice *renderDevice, const String &s, const CoordinateFrame &pos3D, float size=0.1f, const Color4 &color=Color3::black(), const Color4 &outline=Color4::clear(), XAlign xalign=XALIGN_LEFT, YAlign yalign=YALIGN_TOP, Spacing spacing=PROPORTIONAL_SPACING) const
	Renders flat text on a plane in 3D, obeying the z-buffer. More...

Vector2	draw3DBillboard (RenderDevice *renderDevice, const String &s, const Point3 &pos3D, float size=0.1f, const Color4 &color=Color3::black(), const Color4 &outline=Color4::clear(), XAlign xalign=XALIGN_CENTER, YAlign yalign=YALIGN_CENTER, Spacing spacing=PROPORTIONAL_SPACING) const
	Renders flat text on a plane in 3D that always faces the viewer, obeying the z-buffer. More...

String	name () const

float	nativeSize () const
	Font size at which there is no scaling. More...

void	renderCharVertexArray (RenderDevice *rd, const Array< CPUCharVertex > &cpuCharArray, Array< int > &indexArray) const
	For high performance when rendering substantial amounts of text, call: More...

Vector2	texelSize () const
	Returns the natural character width and height of this font. More...

shared_ptr< Texture >	texture () const
	Returns the underlying texture used by the font. More...

const float *	textureMatrix () const
	4x4 matrix transforming texel coordinates to the range [0,1]. More...

int	wordSplitByWidth (const float maxWidth, const String &s, float size=12, Spacing spacing=PROPORTIONAL_SPACING) const
	returns the number of leading charectors that can be rendered in less than maxWidth More...

int	wordWrapCut (float maxWidth, String &s, String &firstLine, float size=12, Spacing spacing=PROPORTIONAL_SPACING) const

Static Public Member Functions
static void	adjustINIWidths (const String &srcFile, const String &dstFile, float scale)
	Adjusts the pre-computed widths in an .INI file in preparation for invoking makeFont on a scaled image. More...

static shared_ptr< GFont >	fromFile (const String &filename)
	Load a new font from disk (fonts are be cached in memory, so repeatedly loading the same font is fast as long as the first was not garbage collected). More...

static shared_ptr< GFont >	fromMemory (const String &name, const uint8 *bytes, const int size)
	see GFont::fromFile More...

static void	makeFont (int charsetSize, const String &infileBase, String outfile="")
	Converts an 8-bit font texture and INI file as produced by the Bitmap Font Builder program to a G3D FNT font. More...

static void	recenterGlyphs (const shared_ptr< Image > &src, shared_ptr< Image > &dst)
	Copies blocks of src so that they are centered in the corresponding squares of dst. More...

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Detailed Description

Font class for use with RenderDevice.

Renders variable size and color fonts from high-resolution bitmaps.

Although GFont optimizes text rendering as much as possible for fully dynamic strings, text rendering is (inherently) slow. You can achieve better performance for static text by creating bitmap textures with whole words and sentences on them.

Some fonts are provided with G3D in the data/font directory. See the copyright.txt file in that directory for information about the source of these files and rules for distribution.

You can make new fonts with the GFont::makeFont static function.

Member Enumeration Documentation

◆ Spacing

enum G3D::GFont::Spacing

Constant for draw2D.

Proportional width (default) spaces characters based on their size. Fixed spacing gives uniform spacing regardless of character width.

Enumerator
PROPORTIONAL_SPACING
FIXED_SPACING

◆ XAlign

enum G3D::GFont::XAlign

Constant for draw2D.

Specifies the horizontal alignment of an entire string relative to the supplied x,y position

Enumerator
XALIGN_RIGHT
XALIGN_LEFT
XALIGN_CENTER

◆ YAlign

enum G3D::GFont::YAlign

Constant for draw2D.

Specifies the vertical alignment of the characters relative to the supplied x,y position.

Enumerator
YALIGN_TOP
YALIGN_BASELINE
YALIGN_CENTER
YALIGN_BOTTOM

Member Function Documentation

◆ adjustINIWidths()

static void G3D::GFont::adjustINIWidths	(	const String &	srcFile,
		const String &	dstFile,
		float	scale
	)

static

Adjusts the pre-computed widths in an .INI file in preparation for invoking makeFont on a scaled image.

See also: makeFont, recenterGlyphs

◆ appendToCharVertexArray()

Vector2 G3D::GFont::appendToCharVertexArray	(	Array< CPUCharVertex > &	cpuCharArray,
		Array< int > &	indexArray,
		RenderDevice *	renderDevice,
		const String &	s,
		const Point2 &	pos2D,
		float	size = `12`,
		const Color4 &	color = `Color3::black()`,
		const Color4 &	outline = `Color4::clear()`,
		XAlign	xalign = `XALIGN_LEFT`,
		YAlign	yalign = `YALIGN_TOP`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

For high-performance rendering of substantial amounts of text.

◆ appendToCharVertexArrayWordWrap()

Vector2 G3D::GFont::appendToCharVertexArrayWordWrap	(	Array< CPUCharVertex > &	cpuCharArray,
		Array< int > &	indexArray,
		RenderDevice *	renderDevice,
		float	wrapWidth,
		const String &	s,
		const Point2 &	pos2D,
		float	size = `12`,
		const Color4 &	color = `Color3::black()`,
		const Color4 &	outline = `Color4::clear()`,
		XAlign	xalign = `XALIGN_LEFT`,
		YAlign	yalign = `YALIGN_TOP`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

For high-performance rendering of substantial amounts of text.

◆ bounds()

Vector2 G3D::GFont::bounds	(	const String &	s,
		float	size = `12`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

Computes the bounding extent of s at the given font size.

Useful for drawing centered text and boxes around text.

◆ boundsWordWrap()

Vector2 G3D::GFont::boundsWordWrap	(	float	maxWidth,
		const String &	s,
		float	size = `12`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ draw2D()

Vector2 G3D::GFont::draw2D	(	RenderDevice *	renderDevice,
		const String &	s,
		const Point2 &	pos2D,
		float	size = `12`,
		const Color4 &	color = `Color3::black()`,
		const Color4 &	outline = `Color4::clear()`,
		XAlign	xalign = `XALIGN_LEFT`,
		YAlign	yalign = `YALIGN_TOP`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

Draws a proportional width font string.

Assumes device->push2D() has been called. Leaves all rendering state as it was, except for the texture coordinate on unit 0.

Parameters

size	The distance between successive lines of text. Specify texelSize().y / 1.5 to get 1:1 texel to pixel
outline	If this color has a non-zero alpha, a 1 pixel border of this color is drawn about the text.
spacing	Fixed width fonts are spaced based on the width of the 'M' character.

Returns: Returns the x and y bounds (ala get2DStringBounds) of the printed string.

You can draw rotated text by setting the RenderDevice object to world matrix manually. The following example renders the word "ANGLE" on a 45-degree angle at (100, 100).

app->renderDevice->push2D();
    CoordinateFrame cframe(
        Matrix3::fromAxisAngle(Vector3::unitZ(), toRadians(45)),
        Vector3(100, 100, 0));
    app->renderDevice->setObjectToWorldMatrix(cframe);
    app->debugFont->draw2D("ANGLE", Vector2(0, 0), 20);
app->renderDevice->pop2D();

◆ draw2DWordWrap()

Vector2 G3D::GFont::draw2DWordWrap	(	RenderDevice *	renderDevice,
		float	maxWidth,
		const String &	s,
		const Point2 &	pos2D,
		float	size = `12`,
		const Color4 &	color = `Color3::black()`,
		const Color4 &	outline = `Color4::clear()`,
		XAlign	xalign = `XALIGN_LEFT`,
		YAlign	yalign = `YALIGN_TOP`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

Wordwraps at maxWidth.

◆ draw3D()

Vector2 G3D::GFont::draw3D	(	RenderDevice *	renderDevice,
		const String &	s,
		const CoordinateFrame &	pos3D,
		float	size = `0.1f`,
		const Color4 &	color = `Color3::black()`,
		const Color4 &	outline = `Color4::clear()`,
		XAlign	xalign = `XALIGN_LEFT`,
		YAlign	yalign = `YALIGN_TOP`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

Renders flat text on a plane in 3D, obeying the z-buffer.

Text is visible from behind. The text is oriented so that it reads "forward" when the pos3D z-axis points towards the viewer.

Note that text, like all transparent objects, should be rendered in back to front sorted order to achieve proper alpha blending.

Parameters

size	In meters of the height of a line of text.

This doesn't follow the same optimized rendering path as draw2D and is intended mainly for debugging.

◆ draw3DBillboard()

Vector2 G3D::GFont::draw3DBillboard	(	RenderDevice *	renderDevice,
		const String &	s,
		const Point3 &	pos3D,
		float	size = `0.1f`,
		const Color4 &	color = `Color3::black()`,
		const Color4 &	outline = `Color4::clear()`,
		XAlign	xalign = `XALIGN_CENTER`,
		YAlign	yalign = `YALIGN_CENTER`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

Renders flat text on a plane in 3D that always faces the viewer, obeying the z-buffer.

Note that text, like all transparent objects, should be rendered in back to front sorted order to achieve proper alpha blending.

Parameters

pos3D	In object space
size	In meters of the height of a line of text.

◆ fromFile()

static shared_ptr<GFont> G3D::GFont::fromFile ( const String & filename )

static

Load a new font from disk (fonts are be cached in memory, so repeatedly loading the same font is fast as long as the first was not garbage collected).

The filename must be a G3D .fnt file.

If a font file is not found, an assertion will fail, an exception will be thrown, and texelSize() will return (0, 0).

Several fonts in this format at varying resolutions are available in the font of the G3D data module.

See GFont::makeFont for creating new fonts in the FNT format.

◆ fromMemory()

static shared_ptr<GFont> G3D::GFont::fromMemory	(	const String &	name,
		const uint8 *	bytes,
		const int	size
	)

static

see GFont::fromFile

◆ makeFont()

static void G3D::GFont::makeFont	(	int	charsetSize,
		const String &	infileBase,
		String	outfile = `""`
	)

static

Converts an 8-bit font texture and INI file as produced by the Bitmap Font Builder program to a G3D FNT font.

outfile should end with ".fnt" or be "" for the default.

The Bitmap Font Builder program can be downloaded from http://www.lmnopc.com/bitmapfontbuilder/

Use the full ASCII character set; the conversion will strip infrequently used characters automatically. Write out TGA files with characters CENTER aligned and right side up using this program. Then, also write out an INI file; this contains the width of each character in the font. Example:

 GFont::makeFont(256,
                 "c:/tmp/g3dfont/news",
                 "d:/graphics3d/book/cpp/data/font/news.fnt");

Parameters

charsetSize	Must be 128 or 256; indicates whether the "extended" characters should be represented in the final texture.
infileBase	The name of the texture and font metrics files, with no extension. The texture filename must be .tga. The font metrics filename must end in .ini. The input texture must be a power of two in each dimension. Intensity is treated as the alpha value in this image. The input texture must be a 16x16 or 16x8 grid of characters
outfile	Defaults to infileBase + ".fnt"

See also: adjustINIWidths, recenterGlyphs

◆ name()

String G3D::GFont::name ( ) const

inline

◆ nativeSize()

float G3D::GFont::nativeSize ( ) const

inline

Font size at which there is no scaling.

Fonts will appear sharpest at power-of-two multiples of this size.

◆ recenterGlyphs()

static void G3D::GFont::recenterGlyphs	(	const shared_ptr< Image > &	src,
		shared_ptr< Image > &	dst
	)

static

Copies blocks of src so that they are centered in the corresponding squares of dst.

Assumes each is a 16x16 grid. Useful when you have shrunk a font texture prior to invoking makeFont and want to use the original resolution to obtain good MIP-boundaries.

◆ renderCharVertexArray()

void G3D::GFont::renderCharVertexArray	(	RenderDevice *	rd,
		const Array< CPUCharVertex > &	cpuCharArray,
		Array< int > &	indexArray
	)		const

For high performance when rendering substantial amounts of text, call:

rd->pushState();
   Array<CPUCharVertex> cpuCharArray;
   for (...) {
      font->appendToCharVertexArray(cpuCharArray, ...);
   }
   font->renderCharVertexArray(rd, cpuCharArray);
rd->popState();

This amortizes the cost of the font setup across multiple calls.

◆ texelSize()

Vector2 G3D::GFont::texelSize ( ) const

Returns the natural character width and height of this font.

◆ texture()

shared_ptr<Texture> G3D::GFont::texture ( ) const

inline

Returns the underlying texture used by the font.

This is rarely needed by applications

◆ textureMatrix()

const float* G3D::GFont::textureMatrix ( ) const

inline

4x4 matrix transforming texel coordinates to the range [0,1].

Rarely needed by applications.

◆ wordSplitByWidth()

int G3D::GFont::wordSplitByWidth	(	const float	maxWidth,
		const String &	s,
		float	size = `12`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

returns the number of leading charectors that can be rendered in less than maxWidth

◆ wordWrapCut()

int G3D::GFont::wordWrapCut	(	float	maxWidth,
		String &	s,
		String &	firstLine,
		float	size = `12`,
		Spacing	spacing = `PROPORTIONAL_SPACING`
	)		const

Parameters

s	The original string. This will be modified to contain the remainder after word wrapping, with leading and trailing whitespace removed.
firstLine	This will be filled with the first line of text. It is guaranteed to have width less than maxWidth.
maxWidth	In pixels

Returns: The character in the original s where the cut occured.

See also: G3D::wordWrap, G3D::TextOutput::Settings::WordWrapMode

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ Spacing

◆ XAlign

◆ YAlign

Member Function Documentation

◆ adjustINIWidths()

◆ appendToCharVertexArray()

◆ appendToCharVertexArrayWordWrap()

◆ bounds()

◆ boundsWordWrap()

◆ createShared()

◆ draw2D()

◆ draw2DWordWrap()

◆ draw3D()

◆ draw3DBillboard()

◆ fromFile()

◆ fromMemory()

◆ makeFont()

◆ name()

◆ nativeSize()

◆ recenterGlyphs()

◆ renderCharVertexArray()

◆ texelSize()

◆ texture()

◆ textureMatrix()

◆ wordSplitByWidth()

◆ wordWrapCut()