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
There are also string literals for use directly in C quoted string composition.
- See also:
- NVBF_COLORSTR_WHITE
- Enumerator:
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.