NvBitFont.h File Reference

An OpenGL bitmap-font text rendering library Library for rendering text strings under Open GL and GL ES, using bitmap fonts alongside xml files with glyph data annotations. More...

#include <NvFoundation.h>
#include <NvUI/NvPackedColor.h>

Go to the source code of this file.

Classes

struct NvBftAlign

Alignment modes for text output. More...

struct NvBftStyle

BitFont supports 'styles' via embedded character codes and string literals. More...

Defines

Text Style String Literals

#define NVBF_STYLESTR_NORMAL   "\020"

BitFont string literal for style reset to 'normal'.

#define NVBF_STYLESTR_BOLD   "\021"

BitFont string literal to style further characters 'bold'.

Text Color String Literals

#define NVBF_COLORSTR_WHITE   "\001"

Embedded string literal to change text coloring to white.

#define NVBF_COLORSTR_GRAY   "\002"

Embedded string literal to change text coloring to gray.

#define NVBF_COLORSTR_BLACK   "\003"

Embedded string literal to change text coloring to black.

#define NVBF_COLORSTR_RED   "\004"

Embedded string literal to change text coloring to red.

#define NVBF_COLORSTR_GREEN   "\005"

Embedded string literal to change text coloring to green.

#define NVBF_COLORSTR_BLUE   "\006"

Embedded string literal to change text coloring to blue.

#define NVBF_COLORSTR_NORMAL   "\007"

Embedded string literal to restore text coloring to 'normal'.

Enumerations

enum NvBftColorCode {
  NVBF_COLORCODE_WHITE = 0, NVBF_COLORCODE_GRAY, NVBF_COLORCODE_BLACK, NVBF_COLORCODE_RED,
  NVBF_COLORCODE_GREEN, NVBF_COLORCODE_BLUE, NVBF_COLORCODE_MAX
}

BitFont supports specific color constants embedded in a string. More...

Functions

BitFont System Creation & Global Property Accessors

The high level functions for initializing and preparing the global state of the BitFont system on a per-app basis.

int32_t NVBFInitialize (uint8_t count, const char *filename[][2])

Base initialization of the font system, once per application.

void NVBFCleanup (void)

Clean up all BitFont resources.

uint8_t NVBFGetFontID (const char *filename)

Get the font ID for a named font file.

void NVBFSetScreenRes (float width, float height)

Set the destination size/scale to factor coords into.

void NVBFGetScreenRes (float *width, float *height)

Get current destination size/scale for safe save/restore.

void NVBFSetScreenRot (float degrees)

Set the rotation/orientation of text output (in 90-degree increments, preferably).

"BFText" String Creation & Property Accessors

BFText 'objects' are an abstraction of a 'text run' or drawable string, and contain all information and buffers necessary to quickly draw the text using GLES primitives.

BFText * NVBFTextAlloc (void)

Allocate a bftext 'object' (abstracted pointer/reference).

void NVBFTextFree (BFText *bftin)

Free an allocated bftext.

void NVBFTextSetVisibility (BFText *bftin, bool vis)

Set whether a given bftext should be visible or invisible for drawing.

void NVBFTextSetColor (BFText *bftin, NvPackedColor color)

Set the RGBA color (using an NvPackedColor) for a line of text.

void NVBFTextSetMultiplyColor (BFText *bftin, NvPackedColor color)

Set the RGBA color (an NvPackedColor) for a line of text.

void NVBFTextSetShadow (BFText *bftin, char offset, NvPackedColor color)

Set the drop-shadow for a bftext.

void NVBFSetDrawnChars (BFText *bftin, int32_t num)

Draw less than the full string.

void NVBFTextSetBox (BFText *bftin, float width, float height, int32_t lines, uint32_t dots)

Use a subrect of the screen for this bftext's raster operations.

void NVBFTextUpdateBox (BFText *bftin, float width, float height)

Helper to quickly update width and height of previously-set text box.

void NVBFTextSetFont (BFText *bftin, uint8_t font)

Select font 'face' to use for this bftext (font ID from NVBFGetFontID).

void NVBFTextSetSize (BFText *bftin, float size)

Set the output size of text in destination-space pixels, dependent on input font size/scale.

void NVBFTextSetString (BFText *bftin, const char *str)

Set the text string for a given bftext.

float NVBFTextGetWidth (BFText *bftin)

Get the last calculated output width of the bftext string.

float NVBFTextGetHeight (BFText *bftin)

Get the last calculated output height of the bftext.

void NVBFTextCursorAlign (BFText *bftin, NvBftAlign::Enum horizontal, NvBftAlign::Enum vertical)

Set the bftext horizontal and vertical alignment.

void NVBFTextCursorPos (BFText *bftin, float horiz, float vert)

Set the bftext starting render position.

BitFont String (BFText) Rasterization Functions

void NVBFTextRenderPrep (void)

Prepare to render some bftext objects.

void NVBFTextRenderDone (void)

Conclude rendering of bftexts, making it safe to do other GLES calls.

void NVBFTextMatrix (const float *mtx)

Set a specific transformation matrix to be used for rendering all text strings, until the next call to NVBFTextRenderDone.

void NVBFTextRender (BFText *bftin)

The main call to actually render a bftext using stored properties.

void NVBFTextRebuildCache (BFText *bftin, bool internal)

Force a rebuilding of the cached vertex data for this bftext.

Detailed Description

An OpenGL bitmap-font text rendering library Library for rendering text strings under Open GL and GL ES, using bitmap fonts alongside xml files with glyph data annotations.

Fonts can be made using fairly-standard 'angelcode' output-format bitmap font rasterizers.

BitFont is able to:

Load multiple bitmap fonts simultaneously, from compressed/DDS files, with or without mipmaps
Handle extended ASCII character codes
Manage multi-style fonts, thus able to combine normal and bold 'runs' of text styling in a single string.
Render text aligned to screen edges or any sub-rect 'box' on the screen
Support multi-line output, including auto-wrapping
Apply a specific font, size, base color, and multiplied color to each string
Optionally apply drop-shadowing under the text for more 'pop'
Optionally embed special escape codes for on-the-fly color or style changes
Given screen size (and rotation), can automatically re-scale and rotate text output
Allow overriding the default shader to implement custom raster effects
Allow overriding the default matrix calc to apply custom transformations to text

Define Documentation

#define NVBF_COLORSTR_BLACK "\003"

Embedded string literal to change text coloring to black.

#define NVBF_COLORSTR_BLUE "\006"

Embedded string literal to change text coloring to blue.

#define NVBF_COLORSTR_GRAY "\002"

Embedded string literal to change text coloring to gray.

#define NVBF_COLORSTR_GREEN "\005"

Embedded string literal to change text coloring to green.

#define NVBF_COLORSTR_NORMAL "\007"

Embedded string literal to restore text coloring to 'normal'.

should be 'max' value.

#define NVBF_COLORSTR_RED "\004"

Embedded string literal to change text coloring to red.

#define NVBF_COLORSTR_WHITE "\001"

Embedded string literal to change text coloring to white.

#define NVBF_STYLESTR_BOLD "\021"

BitFont string literal to style further characters 'bold'.

#define NVBF_STYLESTR_NORMAL "\020"

BitFont string literal for style reset to 'normal'.

Enumeration Type Documentation

enum NvBftColorCode

BitFont supports specific color constants embedded in a string.

See also:: bftStyle

You can directly use the following as character values for switching color 'runs' in the text. Note that these embedded color changes will completely override the base color specified for a given string.

There are also string literals for use directly in C quoted string composition.

See also:: NVBF_COLORSTR_WHITE
NVBF_COLORSTR_BLACK

Enumerator:

NVBF_COLORCODE_WHITE	Sets further text to be white.
NVBF_COLORCODE_GRAY	Sets further text to be gray.
NVBF_COLORCODE_BLACK	Sets further text to be black.
NVBF_COLORCODE_RED	Sets further text to be red.
NVBF_COLORCODE_GREEN	Sets further text to be green.
NVBF_COLORCODE_BLUE	Sets further text to be blue.
NVBF_COLORCODE_MAX	Used for programmatic range checking of embedded codes.

Function Documentation

void NVBFCleanup ( void )

Clean up all BitFont resources.

uint8_t NVBFGetFontID ( const char * filename )

Get the font ID for a named font file.

Look up the matching font ID for a given font filename previously loaded. This is then used as argument to NVBFTextSetFont. It gives us the ability to abstract the order of loaded fonts from the ID/index used to reference them later -- most useful when multiple, distinct systems in an app are talking to BitFont, and separately loading some same, some different fonts.

Parameters:

filename

one of the filenames used in previous NVBFInitialize call.

Returns:: byte (bfuchar) ID/index that will refer to that font until app exit.

void NVBFGetScreenRes	(	float *	width,
		float *	height
	)

Get current destination size/scale for safe save/restore.

int32_t NVBFInitialize	(	uint8_t	count,
		const char *	filename[][2]
	)

Base initialization of the font system, once per application.

Initialize the BitFont system with one or more on-disk fonts.

Parameters:

	count	total fonts to load
	filename	array of two char* .fnt font descriptor files. In case bold style is supported, second is the bold .fnt variant -- note that the bold.fnt file MUST refer to the same texture/bitmap files as the normal/base did (we only support when bold is embedded in same texture).

Returns:: zero if initialized fine, one if failed anywhere during init process.

void NVBFSetDrawnChars	(	BFText *	bftin,
		int32_t	num
	)

Draw less than the full string.

Switches bftext to draw only first num characters in a bftext string. Most useful for helping do simple 'type on' effects. Note that positioning on the screen is where the chars would be if entire text was rendered -- thus left and top alignment are best.

void NVBFSetScreenRes	(	float	width,
		float	height
	)

Set the destination size/scale to factor coords into.

void NVBFSetScreenRot ( float degrees )

Set the rotation/orientation of text output (in 90-degree increments, preferably).

BFText* NVBFTextAlloc ( void )

Allocate a bftext 'object' (abstracted pointer/reference).

void NVBFTextCursorAlign	(	BFText *	bftin,
		NvBftAlign::Enum	horizontal,
		NvBftAlign::Enum	vertical
	)

Set the bftext horizontal and vertical alignment.

Sets the alignment 'edges' for render offset calculation and direction.

See also:: NvBftAlign

void NVBFTextCursorPos	(	BFText *	bftin,
		float	horiz,
		float	vert
	)

Set the bftext starting render position.

Sets an inset/offset from the horizontal and vertical 'edges', as selected via NVBFTextCursorAlign, in possible combination with NVBFTextSetBox. That is, the borders to offset from are "screen edges", unless NVBFTextSetBox was called in which case that box/rect is used to determine the 'edges' instead to inset from.

void NVBFTextFree ( BFText * bftin )

Free an allocated bftext.

float NVBFTextGetHeight ( BFText * bftin )

Get the last calculated output height of the bftext.

float NVBFTextGetWidth ( BFText * bftin )

Get the last calculated output width of the bftext string.

void NVBFTextMatrix ( const float * mtx )

Set a specific transformation matrix to be used for rendering all text strings, until the next call to NVBFTextRenderDone.

void NVBFTextRebuildCache	(	BFText *	bftin,
		bool	internal
	)

Force a rebuilding of the cached vertex data for this bftext.

This function recalculates all cached data related to a given bftext object, including vertex data for optimized rendering. It does NOT normally need to be called by the programmer, but is useful in the specific case where you have a number of completely static strings, in which case calling this during the initialization process can allow the system to preallocate necessary structures and not need to recalc/allocate further at runtime.

Many BFText state-changing functions will flag that a given string requires its vertex data be rebuilt -- but the system waits until rendering is requested so that it only recomputes the cached data once, regardless of the number of states changed for that text since the previous render or rebuild call.

Parameters:

	bftin	the bftext to modify
	internal	should be set to false, unless being called by an internal BitFont function which has already established the VBOs for this bftext.

void NVBFTextRender ( BFText * bftin )

The main call to actually render a bftext using stored properties.

void NVBFTextRenderDone ( void )

Conclude rendering of bftexts, making it safe to do other GLES calls.

void NVBFTextRenderPrep ( void )

Prepare to render some bftext objects.

This sets up necessary bits of the BitFont raster system. From this until calling NVBFRenderDone, do no other GL operations. It can/should be called once before rendering one or more bftexts, for instance looping over an array of text elements on screen.

void NVBFTextSetBox	(	BFText *	bftin,
		float	width,
		float	height,
		int32_t	lines,
		uint32_t	dots
	)

Use a subrect of the screen for this bftext's raster operations.

Sets a subrect in the given screen size, in which processes such as alignment, multi-line wrapping, will occur.

Parameters:

	bftin	the bftext to modify
	width	left/right alignment 'edges' (and wrap/clip boundary).
	height	top/bottom alignment 'edges'.
	lines	if greater than zero, specifies width is used to wrap text, and how many lines to wrap.
	dots	if greater than zero, specifies a character to repeat three times when needs wrap but out of lines.

void NVBFTextSetColor	(	BFText *	bftin,
		NvPackedColor	color
	)

Set the RGBA color (using an NvPackedColor) for a line of text.

Since colors are per-character (stored in vertex data), changing the global text color requires a rebuild of the string buffers. If your intent is trying to fade (alpha), or otherwise color-modulate a string on the fly, you can avoid rebuilding the cache by using NVBFTextSetMultiplyColor instead. NOTE: Embedded color literals/escapes inside the string data itself will take precedence over this string-global color value.

void NVBFTextSetFont	(	BFText *	bftin,
		uint8_t	font
	)

Select font 'face' to use for this bftext (font ID from NVBFGetFontID).

void NVBFTextSetMultiplyColor	(	BFText *	bftin,
		NvPackedColor	color
	)

Set the RGBA color (an NvPackedColor) for a line of text.

As this color is multiplied in hardware, it doesn't require recaching the optimized vertex data for the string, thus allows for easy per-bftext alpha-fades and color modulation.

void NVBFTextSetShadow	(	BFText *	bftin,
		char	offset,
		NvPackedColor	color
	)

Set the drop-shadow for a bftext.

Activates a drop-shadow effect on given bftext output.

Parameters:

	bftin	the bftext to modify
	offset	the +/- offset of the shadow from the base, in 'texels' (not pixels)
	color	the shadow color as an NvPackedColor

void NVBFTextSetSize	(	BFText *	bftin,
		float	size
	)

Set the output size of text in destination-space pixels, dependent on input font size/scale.

void NVBFTextSetString	(	BFText *	bftin,
		const char *	str
	)

Set the text string for a given bftext.

void NVBFTextSetVisibility	(	BFText *	bftin,
		bool	vis
	)

Set whether a given bftext should be visible or invisible for drawing.

void NVBFTextUpdateBox	(	BFText *	bftin,
		float	width,
		float	height
	)

Helper to quickly update width and height of previously-set text box.


Classes
struct	NvBftAlign
	Alignment modes for text output. More...
struct	NvBftStyle
	BitFont supports 'styles' via embedded character codes and string literals. More...
Defines
Text Style String Literals
#define	NVBF_STYLESTR_NORMAL "\020"
	BitFont string literal for style reset to 'normal'.
#define	NVBF_STYLESTR_BOLD "\021"
	BitFont string literal to style further characters 'bold'.
Text Color String Literals
#define	NVBF_COLORSTR_WHITE "\001"
	Embedded string literal to change text coloring to white.
#define	NVBF_COLORSTR_GRAY "\002"
	Embedded string literal to change text coloring to gray.
#define	NVBF_COLORSTR_BLACK "\003"
	Embedded string literal to change text coloring to black.
#define	NVBF_COLORSTR_RED "\004"
	Embedded string literal to change text coloring to red.
#define	NVBF_COLORSTR_GREEN "\005"
	Embedded string literal to change text coloring to green.
#define	NVBF_COLORSTR_BLUE "\006"
	Embedded string literal to change text coloring to blue.
#define	NVBF_COLORSTR_NORMAL "\007"
	Embedded string literal to restore text coloring to 'normal'.
Enumerations
enum	NvBftColorCode { NVBF_COLORCODE_WHITE = 0, NVBF_COLORCODE_GRAY, NVBF_COLORCODE_BLACK, NVBF_COLORCODE_RED, NVBF_COLORCODE_GREEN, NVBF_COLORCODE_BLUE, NVBF_COLORCODE_MAX }
	BitFont supports specific color constants embedded in a string. More...
Functions
BitFont System Creation & Global Property Accessors
The high level functions for initializing and preparing the global state of the BitFont system on a per-app basis.
int32_t	NVBFInitialize (uint8_t count, const char *filename[][2])
	Base initialization of the font system, once per application.
void	NVBFCleanup (void)
	Clean up all BitFont resources.
uint8_t	NVBFGetFontID (const char *filename)
	Get the font ID for a named font file.
void	NVBFSetScreenRes (float width, float height)
	Set the destination size/scale to factor coords into.
void	NVBFGetScreenRes (float width, float height)
	Get current destination size/scale for safe save/restore.
void	NVBFSetScreenRot (float degrees)
	Set the rotation/orientation of text output (in 90-degree increments, preferably).
"BFText" String Creation & Property Accessors
BFText 'objects' are an abstraction of a 'text run' or drawable string, and contain all information and buffers necessary to quickly draw the text using GLES primitives.
BFText *	NVBFTextAlloc (void)
	Allocate a bftext 'object' (abstracted pointer/reference).
void	NVBFTextFree (BFText *bftin)
	Free an allocated bftext.
void	NVBFTextSetVisibility (BFText *bftin, bool vis)
	Set whether a given bftext should be visible or invisible for drawing.
void	NVBFTextSetColor (BFText *bftin, NvPackedColor color)
	Set the RGBA color (using an NvPackedColor) for a line of text.
void	NVBFTextSetMultiplyColor (BFText *bftin, NvPackedColor color)
	Set the RGBA color (an NvPackedColor) for a line of text.
void	NVBFTextSetShadow (BFText *bftin, char offset, NvPackedColor color)
	Set the drop-shadow for a bftext.
void	NVBFSetDrawnChars (BFText *bftin, int32_t num)
	Draw less than the full string.
void	NVBFTextSetBox (BFText *bftin, float width, float height, int32_t lines, uint32_t dots)
	Use a subrect of the screen for this bftext's raster operations.
void	NVBFTextUpdateBox (BFText *bftin, float width, float height)
	Helper to quickly update width and height of previously-set text box.
void	NVBFTextSetFont (BFText *bftin, uint8_t font)
	Select font 'face' to use for this bftext (font ID from NVBFGetFontID).
void	NVBFTextSetSize (BFText *bftin, float size)
	Set the output size of text in destination-space pixels, dependent on input font size/scale.
void	NVBFTextSetString (BFText bftin, const char str)
	Set the text string for a given bftext.
float	NVBFTextGetWidth (BFText *bftin)
	Get the last calculated output width of the bftext string.
float	NVBFTextGetHeight (BFText *bftin)
	Get the last calculated output height of the bftext.
void	NVBFTextCursorAlign (BFText *bftin, NvBftAlign::Enum horizontal, NvBftAlign::Enum vertical)
	Set the bftext horizontal and vertical alignment.
void	NVBFTextCursorPos (BFText *bftin, float horiz, float vert)
	Set the bftext starting render position.
BitFont String (BFText) Rasterization Functions
void	NVBFTextRenderPrep (void)
	Prepare to render some bftext objects.
void	NVBFTextRenderDone (void)
	Conclude rendering of bftexts, making it safe to do other GLES calls.
void	NVBFTextMatrix (const float *mtx)
	Set a specific transformation matrix to be used for rendering all text strings, until the next call to NVBFTextRenderDone.
void	NVBFTextRender (BFText *bftin)
	The main call to actually render a bftext using stored properties.
void	NVBFTextRebuildCache (BFText *bftin, bool internal)
	Force a rebuilding of the cached vertex data for this bftext.