Font

Bitmap font used to draw text in canvas space.

A font pairs a texture atlas with the metrics needed to lay out text from it. Each Glyph names the region of the atlas holding one character and how far to move the pen after drawing it, and kerning pairs adjust the spacing between specific pairs of characters.

Fonts are typically loaded using a font loader rather than instantiated directly.

auto font = vglx::LoadFont("assets/fonts/futura_condensed.fnt");
if (font.has_value()) {
    // use font.value()
} else {
    std::println(stderr, "{}", font.error());
}

Currently, only single page bitmap fonts exported from BMFont are supported.

Construction

Factories preferred

Font::Create() std::shared_ptr<Font>

Creates a shared instance of Font.

static std::shared_ptr<Font> Font::Create();

Types

Font::Glyph struct

Metrics describing a single character of the font.

Parameter	Description
region Rect	Sub-region of page holding the character in pixels.
offset Vector2	Offset in pixels from the pen position to the region's top-left corner.
advance float	Distance in pixels to move the pen after drawing the character.

Properties

base float

Distance in pixels from the top of a line to the baseline.

Glyph offsets are measured from the top of the line so subtracting this value gives a glyph's position relative to the baseline.

float base {0.0f};

line_height float

Distance in pixels between the baselines of consecutive lines.

Move the pen down by this amount when starting a new line.

float line_height {0.0f};

page std::shared_ptr<Texture2D>

Texture atlas holding the rendered characters.

Glyph regions select rectangles of this texture with a top-left origin. Only a single atlas page is supported. Because canvas content is composited after tone mapping, load the atlas with ColorSpace::Linear so the pixel values are used as authored.

std::shared_ptr<Texture2D> page {nullptr};

size float

Font size in pixels the atlas was authored at.

float size {0.0f};

Functions

AddGlyph() void

Adds a character to the font.

Replaces the existing entry if a character with the same code point was already added.

void Font::AddGlyph(char32_t code, const Glyph& glyph);

Parameter	Description
code	Unicode code point of the character.
glyph	Metrics describing the character.

AddKerning() void

Adds a kerning adjustment between two characters.

Replaces the existing entry if the same pair was already added.

void Font::AddKerning(char32_t first, char32_t second, float amount);

Parameter	Description
first	Code point of the character on the left.
second	Code point of the character on the right.
amount	Adjustment in pixels added to the advance of the first character.

GetGlyph() std::optional<Glyph>

Returns the glyph for the given character.

std::optional<Glyph> Font::GetGlyph(char32_t code) const;

Parameter	Description
code	Unicode code point to look up.

GetKerning() float

Returns the kerning adjustment between two characters.

float Font::GetKerning(char32_t first, char32_t second) const;

Parameter	Description
first	Code point of the character on the left.
second	Code point of the character on the right.