Class ShapedFont

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

A TrueType or OpenType font that shapes its text: letters take the forms their neighbours call for (Arabic’s joined forms, Indic conjuncts, ligatures), marks sit where the font places them, and right-to-left scripts (Arabic, Hebrew) run right to left. HarfBuzz chooses the glyphs and their positions; each glyph is rasterized the first time it is drawn at a size and kept in glyph pages (textures), so later frames only draw quads.

C#

public sealed class ShapedFont : IDisposable

Inheritance

object ← ShapedFont

Implements

IDisposable

Examples

C#

var font = ShapedFont.FromBytes(Graphics, Assets.Bytes("fonts/Inter-Regular.ttf"))
    .AddFallback(Assets.Bytes("fonts/NotoSansArabic-Regular.ttf"));
font.At(32).Draw(renderer, "مرحبا", new Vector2(24, 24), Color.White);

Remarks

Use it in place of a [ScalableFont](/docs/api/microengine.graphics.scalablefont/) for text in a script that needs shaping; [At](/docs/api/microengine.graphics.shapedfont/#MicroEngine_Graphics_ShapedFont_At_System_Single_) gives an [IFont](/docs/api/microengine.graphics.ifont/), so widgets, layout and wrapping work with it unchanged. Faces added with [AddFallback](/docs/api/microengine.graphics.shapedfont/#MicroEngine_Graphics_ShapedFont_AddFallback_System_Byte___System_String_) supply the letters the main face lacks, a run of text at a time, so a Latin face with an Arabic and a Hebrew one after it draws all three. Letters no face has draw as the last face's missing-glyph box.

Lines that mix directions follow Unicode's bidirectional algorithm (UAX #9): a line reads in the direction of its first letter that has one ([IsRightToLeft](/docs/api/microengine.graphics.shapedfontsize/#MicroEngine_Graphics_ShapedFontSize_IsRightToLeft_System_String_)), and runs of the other direction inside it, a name or a number in an Arabic sentence, read in theirs. Explicit direction marks (embeddings, overrides, isolates) are ignored and brackets are not paired across directions.

Properties

Faces

How many faces the font has: the main one, then its fallbacks in the order they were added.

C#

public int Faces { get; }

Property Value

int

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 (Kerning does not apply: the font’s own positioning always does).

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 for the letters the faces before it lack (another script, symbols). Text already shaped is shaped again, so add fallbacks while loading.

C#

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

Parameters

data byte[]

name string?

Returns

ShapedFont

Exceptions

InvalidDataException

The data is not a font the engine reads.

At(float)

The font at size (the same size as a ScalableFont’s), as an IFont; the same object for the same size.

C#

public ShapedFontSize At(float size)

Parameters

size float

Returns

ShapedFontSize

Exceptions

ArgumentOutOfRangeException

size is not positive.

Dispose()

Releases the glyph pages and the faces. Text cannot be drawn afterwards.

C#

public void Dispose()

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

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

C#

public static ShapedFont 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

ShapedFont

Exceptions

InvalidDataException

The data is not a font the engine reads.

Load(IGraphicsDevice, string, FontOptions?)

Opens a TTF or OTF file.

C#

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

Parameters

device IGraphicsDevice

path string

options FontOptions?

Returns

ShapedFont

Exceptions

FileNotFoundException

The file does not exist.

InvalidDataException

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

Reset()

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

C#

public void Reset()