Contents User Forum Source Index APIs by Task APIs by Level Data

G3D::GFont

G3D::GFont Class Reference

Font class for use with RenderDevice. More...

#include <GFont.h>

List of all members.

Public Types

typedef ReferenceCountedPointer<
class GFont > Ref

enum Spacing { PROPORTIONAL_SPACING, FIXED_SPACING }

enum XAlign { XALIGN_RIGHT, XALIGN_LEFT, XALIGN_CENTER }

enum YAlign { YALIGN_TOP, YALIGN_BASELINE, YALIGN_CENTER, YALIGN_BOTTOM }

Public Member Functions

Vector2 bounds (const std::string &s, float size=12, Spacing spacing=PROPORTIONAL_SPACING) const

void configureRenderDevice (RenderDevice *rd) const

Vector2 draw2D (RenderDevice *renderDevice, const std::string &s, const Vector2 &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

Vector2 draw3D (RenderDevice *renderDevice, const std::string &s, const CoordinateFrame &pos3D, float size=.1, const Color4 &color=Color3::black(), const Color4 &outline=Color4::clear(), XAlign xalign=XALIGN_LEFT, YAlign yalign=YALIGN_TOP, Spacing spacing=PROPORTIONAL_SPACING) const

void ReferenceCountedObject_zeroWeakPointers ()

Vector2 send2DQuads (RenderDevice *renderDevice, const std::string &s, const Vector2 &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

Vector2 texelSize () const

Texture::Ref texture () const

const float * textureMatrix () const

Static Public Member Functions

static GFontRef fromFile (const std::string &filename)

static GFontRef fromMemory (const std::string &name, const uint8 *bytes, const int size)

static void makeFont (int charsetSize, const std::string &infileBase, std::string outfile="")

Public Attributes

AtomicInt32 ReferenceCountedObject_refCount

_WeakPtrLinkedList * ReferenceCountedObject_weakPointer

Detailed Description

Font class for use with RenderDevice.

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

Font rendering is (inherently) slow-- you can achieve better performance for static text by creating bitmap textures with whole words and sentences on them.

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

Member Typedef Documentation

typedef ReferenceCountedPointer<class GFont> G3D::GFont::Ref

Member Enumeration Documentation

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

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

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

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

Useful for drawing centered text and boxes around text.

void G3D::GFont::configureRenderDevice ( RenderDevice * rd ) const

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

       rd->push2D();
          font->configureRenderDevice(rd);
          for (...) {
             font->send2DQuads(...);
          }
       rd->pop2D();

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

Vector2 G3D::GFont::draw2D	(	RenderDevice *	renderDevice,
		const std::string &	s,
		const Vector2 &	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();

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

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.

static GFontRef G3D::GFont::fromFile ( const std::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.

static GFontRef G3D::GFont::fromMemory	(	const std::string &	name,
		const uint8 *	bytes,
		const int	size
	)			`[static]`

see GFont::fromFile

static void G3D::GFont::makeFont	(	int	charsetSize,
		const std::string &	infileBase,
		std::string	outfile = `""`
	)			`[static]`

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

inFile should have no extension-- .raw and .ini will be appended to it. 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 RAW 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::convertRAWINItoPWF("c:/tmp/g3dfont/news",
	                            "d:/graphics3d/book/cpp/data/font/news.fnt");

Parameters:

	infileBase	The name of the raw/ini files
	outfile	Defaults to infileBase + ".fnt"
	charsetSize	Must be 128 or 256; indicates whether the "extended" characters should be represented in the final texture.

void G3D::ReferenceCountedObject::ReferenceCountedObject_zeroWeakPointers ( ) [inline, inherited]

Automatically called immediately before the object is deleted.

This is not called from the destructor because it needs to be invoked before the subclass destructor.

Vector2 G3D::GFont::send2DQuads	(	RenderDevice *	renderDevice,
		const std::string &	s,
		const Vector2 &	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