TextShaper Class

Namespace: Meziantou.Framework.Fonts
Assembly: Meziantou.Framework.Fonts.dll
Package: Meziantou.Framework.Fonts 1.0.9
Source: TextShaper.cs
Available in package assets: net10.0net11.0

Shapes a run of text: turns its characters into the glyphs of a font and their positions, with the OpenType Layout tables of the font.

public static class TextShaper

Remarks

A run has one font, one script, one language and one direction. The steps are:

Characters. The characters that the font does not have are decomposed when it has their parts, marks are put in canonical order, and a character and its marks are composed when the font has the composed character: the text is in the form the font was made for, whatever form it was typed in.
Glyphs. Each character gets its glyph from the character map, variation sequences included.
Substitution. The lookups of the features of the GSUB table that apply to the run, in the order of the lookup list.
Positioning. The advances of the glyphs, then the lookups of the GPOS table; the legacy kerning table when the font has no kerning feature. The advance of a mark is removed.

The features applied to every run are the ones the OpenType specification asks a client to apply by default for horizontal text: ccmp, locl, rlig, calt, clig, liga, rclt, the direction features (ltra, ltrm, rtla, rtlm), the fraction features around a fraction slash, and for positioning abvm, blwm, mark, mkmk, curs, dist, kern.

A run of a vertical line whose glyphs are upright is shaped from the top to the bottom: each glyph advances by minus its advance height and is placed by minus its vertical origin, so that its origin is at the top of its advance, in the middle of its width. The feature of such a run is vert, with those that do not depend on the direction (ccmp, locl, rlig, abvm, blwm, mark, mkmk); the letters of the scripts that join are not joined, and neither the legacy kerning table nor the marks placed from the shapes of the glyphs are used.

Methods

Name	Description
AddText(GlyphBuffer, ReadOnlySpan<char>, int)	Adds the characters of a text to a buffer, each with the index of its first UTF-16 code unit as cluster.
IsSynthesizedSpace(int)	Determines whether a space character is drawn with the space of a font that has no glyph for it, with a width of its own (a fraction of the em, the width of a digit...): the spaces of the General Punctuation block, the no-break spaces and the ideographic space.
Shape(GlyphBuffer, FontFace, UnicodeScript, ReadOnlySpan<uint>, bool, ReadOnlySpan<ShapingFeature>, bool, GlyphScratch?, ShapingCache?, bool)	Shapes the characters of a buffer.

AddText(GlyphBuffer, ReadOnlySpan<char>, int)

TextShaper.cs

Adds the characters of a text to a buffer, each with the index of its first UTF-16 code unit as cluster.

public static void AddText(GlyphBuffer buffer, ReadOnlySpan<char> text, int clusterOffset = 0)

Parameters

buffer GlyphBuffer
text ReadOnlySpan<char>
clusterOffset int

IsSynthesizedSpace(int)

TextShaper.cs

Determines whether a space character is drawn with the space of a font that has no glyph for it, with a width of its own (a fraction of the em, the width of a digit...): the spaces of the General Punctuation block, the no-break spaces and the ideographic space.

public static bool IsSynthesizedSpace(int codePoint)

Parameters

codePoint int

Returns

bool

Shape(GlyphBuffer, FontFace, UnicodeScript, ReadOnlySpan<uint>, bool, ReadOnlySpan<ShapingFeature>, bool, GlyphScratch?, ShapingCache?, bool)

TextShaper.cs

Shapes the characters of a buffer.

public static void Shape(GlyphBuffer buffer, FontFace face, UnicodeScript script, ReadOnlySpan<uint> languages, bool isRightToLeft, ReadOnlySpan<ShapingFeature> features, bool isVertical = false, GlyphScratch? scratch = null, ShapingCache? cache = null, bool areCharactersMirrored = false)

Parameters

buffer GlyphBuffer: The characters of the run; it receives the glyphs and their positions.
face FontFace: The font.
script UnicodeScript: The script of the run.
languages ReadOnlySpan<uint>: The OpenType tags of the language of the run, by order of preference: the language system of the first one the font has for the script is used; empty for the default language system.
isRightToLeft bool: true when the run is laid out from right to left.
features ReadOnlySpan<ShapingFeature>: The features to turn on or off, besides the default ones.
isVertical bool: true when the run is laid out from top to bottom, its glyphs upright. The glyphs then have their vertical forms (the vert feature, wherever the font has it, in the place of the features of a horizontal line: calt, clig, curs, dist, kern, liga, rclt), a vertical advance (GlyphPosition.YAdvance, negative since the y axis of a font goes up) and no horizontal one, and an offset from the pen to their horizontal origin: the opposite of their vertical origin (FontFace.GetVerticalOrigin). A vertical run is never right to left. The rotated forms (vrt2) of a vertical run, and the forms of turned glyphs (vrtr) of a horizontal one, are found wherever the font has them too, when the caller asks for them.
scratch GlyphScratch?: The working storage that measures the outlines of a font without vertical origins, or null when the run is horizontal.
cache ShapingCache?: What the runs of a layout share about their fonts, or null when the run is shaped on its own.
areCharactersMirrored bool: true when the caller already replaced the characters of a right-to-left run by their mirrored forms (rule L4 of the Unicode Bidirectional Algorithm): they are not replaced again, and the mirrored characters that have no mirrored form still get the mirrored forms of the font (rtlm).

Exceptions

InvalidFontException: A layout table of the font is malformed.
FontResourceLimitException: The glyphs exceed FontResourceLimits.MaxTextGlyphs.