Menu - Top - Home - Donate to Me

H3DU.TextFont

Back to documentation index.

H3DU.TextFont()

Represents a bitmap font, which supports drawing two-dimensional text. This class supports traditional bitmap fonts and signed distance field fonts.

Bitmap fonts consist of a font definition file and one or more textures containing the shape of each font glyph. The glyphs are packed so that the glyphs don't overlap each other.

In a signed distance field font, each pixel's alpha value depends on the distance from that location to the edge of the glyph. A pixel alpha less than 0.5 (127 in most image formats) means the pixel is outside the glyph, greater than 0.5 means the pixel is inside the glyph, and 0 (for outside the glyph) and 1 (for inside the glyph) means the pixel is outside a buffer zone formed by the glyph's outline. Each glyph is usually given extra space to accommodate the signed distance field information.

The font definition file formats supported are text (".fnt"), JSON (".json"), binary (".fnt" or ".bin"), and XML (".xml"). The text and binary file formats are specified at this page. The XML format is very similar to the text file format. The JSON format is described at this page.

See this page for a list of bitmap font generation tools. (No one tool is recommended over any other, and the mention of this link is not an endorsement or sponsorship of any particular tool.)

NOTE: The constructor should not be called directly by applications. Use the H3DU.TextFont.load method to get an H3DU.TextFont object. This constructor's parameters are undocumented and are subject to change.

This class is considered a supplementary class to the Public Domain HTML 3D Library and is not considered part of that library.

To use this class, you must include the script "extras/text.js"; the class is not included in the "h3du_min.js" file which makes up the HTML 3D Library. Example:

<script type="text/javascript" src="extras/text.js"></script>

Methods

(static) H3DU.TextFont.load(fontFileName)

Loads a bitmap font definition from a file. Note that this method only loads the font data and not the bitmaps used to represent the font.

Parameters

Return Value

A promise that is resolved when the font data is loaded successfully (the result will be an H3DU.TextFont object), and is rejected when an error occurs. (Type: Promise.<H3DU.TextFont>)

H3DU.TextFont#loadTextures(textureLoader)

Loads the texture files used by this font object.

Parameters

Return Value

A promise as described in H3DU.getPromiseResultsAll. If the promise resolves, each item in the resulting array will be a loaded H3DU.Texture object. (Type: Promise.<H3DU.Texture>)

(static) H3DU.TextFont.loadWithTextures(fontFileName, textureLoader)

Loads a bitmap font definition from a file along with the textures used by that font.

Parameters

Return Value

A promise that is resolved when the font data and textures are loaded successfully, and is rejected when an error occurs. If the promise is resolved, the result will be an object with the following keys:

(Type: Promise)

H3DU.TextFont#makeTextMeshes(str, params)

Creates an array of meshes containing the primitives needed to draw text with this font.

Parameters

Return Value

An array of meshes representing the text. There is one mesh for each texture page of the font. If none of the text uses a given page, the corresponding mesh will be null. (Type: Array.<Mesh>)

H3DU.TextFont#measure(str, params)

Calculates the width and height of a text string when drawn using this font.

Parameters

Return Value

An array of two numbers; the first is the width of the string, and the second is the height of the string (taking into account line feed characters, U+000A, that break lines). (Type: Array.<number>)

H3DU.TextFont#textShape(str, params)

Creates a group of shapes containing the primitives needed to draw text in the given position, size, and color. For the text to show upright, the coordinate system should have the X axis pointing right and the Y axis pointing down (for example, an orthographic projection where the left and top coordinates are less than the right and bottom coordinates, respectively).

Parameters

Return Value

The generated group of shapes. (Type: H3DU.ShapeGroup)

Back to documentation index.