Class ScalableFont

Namespace: MicroEngine.Graphics
Assembly: MicroEngine.Text.dll
Guide: Graphics

A TrueType or OpenType font (TTF, OTF with TrueType or CFF outlines) that draws text at any size. Glyphs are rasterized the first time they are drawn at a size and kept in shared glyph pages (textures), so later frames only draw quads; Prepare rasterizes ahead, so the first frames of play do no font work.

C#

public sealed class ScalableFont : IDisposable

Inheritance

object ← ScalableFont

Implements

IDisposable

Examples

C#

var font = ScalableFont.Load(Graphics, "Content/fonts/Inter-Regular.ttf");
font.Draw(renderer, "Score 120", new Vector2(24, 24), 32, Color.White);
var title = font.At(64);              // an IFont for widgets and layout
title.DrawCentered(renderer, "Paused", new Vector2(640, 360), Color.White);

Remarks

Built on FontStashSharp (StbTrueTypeSharp rasterizer). One ScalableFont serves every size; extra faces added with AddFallback supply characters the main face lacks (another script, symbols). Missing characters draw as ‘?’. Usually loaded and owned by Game.Assets; a font made here is disposed by its creator.

Fields

Ascii

Printable ASCII: letters, digits and punctuation, a good default for Prepare.

C#

public const string Ascii = " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"

Field Value

string

Properties

Filter

How the glyph pages are sampled; applies to existing and future pages.

C#

public TextureFilter Filter { get; set; }

Property Value

TextureFilter

GlyphsRasterized

Glyphs rasterized so far, across every size (a measure of font work done).

C#

public int GlyphsRasterized { get; }

Property Value

int

Name

The file name (or the name given), for messages.

C#

public string Name { get; }

Property Value

string

Options

The options the font was opened with.

C#

public FontOptions Options { get; }

Property Value

FontOptions

Pages

Glyph pages created so far (each PageSize squared, 4 bytes per pixel).

C#

public int Pages { get; }

Property Value

int

TextureBytes

Device memory of the glyph pages, in bytes.

C#

public long TextureBytes { get; }

Property Value

long

Methods

AddFallback(byte[], string?)

Adds another TTF/OTF face whose glyphs are used for characters this font lacks (accents, other scripts, icons). Faces are searched in the order they were added. Glyphs already rasterized are dropped (as by Reset), so add fallbacks while loading.

C#

public ScalableFont AddFallback(byte[] data, string? name = null)

Parameters

data byte[]

name string?

Returns

ScalableFont

Exceptions

InvalidDataException

The data is not a font the rasterizer reads.

At(float)

The font at size (pixels per em), as an IFont; the same object for the same size.

C#

public SizedFont At(float size)

Parameters

size float

Returns

SizedFont

Exceptions

ArgumentOutOfRangeException

size is not positive.

Dispose()

Releases the glyph pages. Text cannot be drawn afterwards.

C#

public void Dispose()

Draw(IRenderer, string, Vector2, float, Color)

Draws text at size with its top-left at position.

C#

public void Draw(IRenderer renderer, string text, Vector2 position, float size, Color color)

Parameters

renderer IRenderer

text string

position Vector2

size float

color Color

FromBytes(IGraphicsDevice, byte[], FontOptions?, string?)

Opens a font from the bytes of a TTF or OTF file.

C#

public static ScalableFont FromBytes(IGraphicsDevice device, byte[] data, FontOptions? options = null, string? name = null)

Parameters

device IGraphicsDevice

Creates the glyph pages.

data byte[]

The whole font file.

options FontOptions?

Rasterization and sampling; null for Default.

name string?

A name for messages and diagnostics.

Returns

ScalableFont

Exceptions

InvalidDataException

The data is not a font the rasterizer reads.

LineHeight(float)

Distance between the tops of two lines at size.

C#

public float LineHeight(float size)

Parameters

size float

Returns

float

Load(IGraphicsDevice, string, FontOptions?)

Opens a TTF or OTF file.

C#

public static ScalableFont Load(IGraphicsDevice device, string path, FontOptions? options = null)

Parameters

device IGraphicsDevice

path string

options FontOptions?

Returns

ScalableFont

Exceptions

FileNotFoundException

The file does not exist.

InvalidDataException

The file is not a font the rasterizer reads; the message names it.

Measure(string, float)

Size of text at size, in canvas pixels.

C#

public Vector2 Measure(string text, float size)

Parameters

text string

size float

Returns

Vector2

Prepare(string, params float[])

Rasterizes characters at each of sizes now, so drawing them later costs no font work. Call it while loading for the text a scene will show (digits for a score, the letters of a menu).

C#

public void Prepare(string characters, params float[] sizes)

Parameters

characters string

sizes float[]

Reset()

Drops every rasterized glyph and its pages (freeing their memory); glyphs drawn later are rasterized again.

C#

public void Reset()