Class MeshFont

Namespace

Stride.CommunityToolkit.Rendering.Text

Assembly

Stride.CommunityToolkit.dll

A font file opened for its glyph outlines: the vector shapes that solid 3D lettering is built from.

public sealed class MeshFont : IDisposable

Inheritance

object

MeshFont

Implements

IDisposable

Remarks

Stride's sprite fonts rasterise glyphs; this reads the same files for their curves instead, through the FreeType library the engine ships on every platform, so TrueType, OpenType (CFF) and font collections all work. Default is an Open Sans Regular embedded in the toolkit, so lettering works with no font file at hand; Load(string, int) opens any file, and FromFamily(string, FontStyle) finds an installed family through SystemFonts.

Outlines come back in EM units, baseline at y = 0, pen at x = 0, y up: a capital letter is about 0.7 high and a line of text is LineHeight apart. Scale them to the size wanted. Glyphs are read once and cached; a font is safe to share between threads.

Kerning is read from the font's legacy kern table only, which modern fonts no longer carry (they keep it in GPOS, which FreeType does not read without a shaping engine), so GetKerning(int, int) is 0 for most fonts, including Default.

Properties

Ascent

How far above the baseline the font reaches, in EM units.

public float Ascent { get; }

Property Value

float

Default

The font embedded in the toolkit, Open Sans Regular (Apache 2.0), so lettering works with no font file at hand. Shared: disposing it does nothing.

public static MeshFont Default { get; }

Property Value

MeshFont

Descent

How far below the baseline the font reaches, in EM units; negative.

public float Descent { get; }

Property Value

float

FaceCount

How many faces the file holds: 1 for a .ttf or .otf, more for a collection (.ttc), each opened by its index.

public int FaceCount { get; }

Property Value

int

LineHeight

The distance between two baselines, in EM units.

public float LineHeight { get; }

Property Value

float

Name

The font's family and style, as the file names them: "Open Sans", "Segoe UI Bold".

public string Name { get; }

Property Value

string

UnitsPerEm

The font's design grid: how many of its own units make one EM. Outlines are already divided by it.

public int UnitsPerEm { get; }

Property Value

int

Methods

Dispose()

Closes the font. Default stays open.

public void Dispose()

~MeshFont()

Closes the native face when the font was never disposed.

protected ~MeshFont()

FromFamily(string, FontStyle)

Opens an installed font by family name, found through FindFile(string, FontStyle).

public static MeshFont? FromFamily(string family, FontStyle style = FontStyle.Regular)

Parameters

family string

The family: "Segoe UI", "Arial", "DejaVu Sans".

style FontStyle

The weight and slant wanted.

Returns

MeshFont

The font, or null when no file of that family and style is installed.

Remarks

The lookup finds a file, and the first face of it: a style that a collection keeps as its second or third face (macOS stores some families that way) needs Load(string, int) with the face index.

Exceptions

ArgumentNullException

The family is null.

GetGlyph(char)

The outline of a character.

public GlyphOutline GetGlyph(char character)

Parameters

character char

The character.

Returns

GlyphOutline

Its outline; the font's "missing glyph" shape when it has none, see IsMissing.

GetGlyph(int)

The outline of a code point, which covers the characters beyond the basic plane that a char cannot.

public GlyphOutline GetGlyph(int codepoint)

Parameters

codepoint int

The Unicode code point.

Returns

GlyphOutline

Its outline; the font's "missing glyph" shape when it has none, see IsMissing.

Exceptions

InvalidDataException

The font's outline for the glyph breaks FreeType's conventions.

GetKerning(int, int)

How much closer the pen moves for a pair of characters, from the font's kern table: negative pulls them together (AV), positive pushes them apart. 0 for most modern fonts, see the remarks on the class.

public float GetKerning(int left, int right)

Parameters

left int

The code point on the left.

right int

The code point on the right.

Returns

float

The adjustment to the left glyph's advance, in EM units.

HasGlyph(int)

Whether the font has a glyph of its own for the code point, rather than only its "missing glyph" box.

public bool HasGlyph(int codepoint)

Parameters

codepoint int

Returns

bool

Load(byte[], string?, int)

Opens a font from its bytes: a file read elsewhere, an embedded resource, a download.

public static MeshFont Load(byte[] data, string? name = null, int faceIndex = 0)

Parameters

data byte[]

The whole font file. It is pinned for the font's lifetime, so do not change it.

name string

A name for error messages; the font's own family name is read from the file.

faceIndex int

Which face of a collection to open; 0, the first, for a single-face file.

Returns

MeshFont

The font; dispose it when its outlines are no longer needed.

Exceptions

ArgumentNullException

The data is null.

ArgumentOutOfRangeException

The face index is negative.

InvalidDataException

The bytes are not a font FreeType can open, have no such face, or the font has no outlines.

Load(string, int)

Opens a font file.

public static MeshFont Load(string path, int faceIndex = 0)

Parameters

path string

The path of a .ttf, .otf or .ttc file.

faceIndex int

Which face of a collection to open; 0, the first, for a single-face file. FaceCount says how many there are.

Returns

MeshFont

The font; dispose it when its outlines are no longer needed.

Exceptions

ArgumentNullException

The path is null.

ArgumentOutOfRangeException

The face index is negative.

FileNotFoundException

There is no file at the path.

InvalidDataException

The file is not a font FreeType can open, has no such face, or has no outlines.