Text layout
editA layout turns characters into positioned glyphs: it chooses a font for each character, orders mixed directions, breaks lines and shapes each run of text with the OpenType tables of its font. This page covers the options that change how that is done. For the basics, see Drawing text.
Fallback fonts
A TextStyle takes a FontStack: a primary font, then the fonts used for the characters the ones before it lack. Each character is drawn with the first font of the stack that has it:
public static void DrawFontStack(string latinFontPath, string japaneseFontPath, string emojiFontPath, string outputPath)
{
// Each character is drawn with the first font of the stack that has it. An emoji is looked for first in the
// fonts that have color glyphs, and is drawn with its own colors
var fonts = new FontStack(Font.Load(latinFontPath), Font.Load(japaneseFontPath), Font.Load(emojiFontPath));
var layout = TextLayout.Create("Tokyo 東京 \U0001F680", new TextStyle(fonts, 32));
using var image = new Image<Rgba32>((int)Math.Ceiling(layout.Width) + 20, (int)Math.Ceiling(layout.Height) + 20, new Rgba32(255, 255, 255));
image.Draw(canvas => canvas.FillText(new Rgba32(0, 0, 0), layout, new PointD(10, 10)));
image.Save(outputPath);
}
- A character and the marks and selectors that follow it are drawn with the first font that has all of them.
- An emoji is first looked for in the fonts that have color glyphs (a character that is an emoji by default, or that is followed by the emoji presentation selector U+FE0F), and a character followed by the text presentation selector U+FE0E in the fonts without them. When no font of that kind has it, the stack is searched in its order.
- A character no font of the stack has is drawn with the missing glyph of the primary font: nothing throws, and
layout.HasMissingGlyphssays so. Check it when the text comes from a user.
Installed fonts as fallback
A stack only has the fonts it is given, so a text is drawn the same way on every machine. WithInstalledFallback() also looks for a character that none of them has among the fonts installed on the machine:
public static void DrawWithInstalledFallback(string fontPath, string outputPath)
{
// Without fallback, a stack only has the fonts it is given, and a text is drawn the same way on every machine.
// With it, a character none of them has (an ideograph, an emoji) is drawn with an installed font that has it
var fonts = new FontStack(Font.Load(fontPath)).WithInstalledFallback();
var layout = TextLayout.Create("Hello, \u4E16\u754C \U0001F600", new TextStyle(fonts, 32));
using var image = new Image<Rgba32>((int)Math.Ceiling(layout.Width) + 20, (int)Math.Ceiling(layout.Height) + 20, new Rgba32(255, 255, 255));
image.Draw(canvas => canvas.FillText(new Rgba32(0, 0, 0), layout, new PointD(10, 10)));
image.Save(outputPath);
}The installed fonts are searched in this order: the families of InstalledFontFallbackOptions.PreferredFamilies; for an emoji, the color emoji font of the platform (Segoe UI Emoji, Apple Color Emoji, Noto Color Emoji); the families the platforms usually use for the script of the character; then every family that has it. In a family, the face is the one closest to the style of the primary font. The font found for a character is loaded once and kept by the stack. With fallback, the result depends on the fonts of the machine.
The Han ideographs have different forms in Chinese, Japanese and Korean, so their installed fonts are chosen by TextStyle.Language:
| Language | Families, then those of Simplified Chinese |
|---|---|
ja | Yu Gothic, Hiragino Sans, Noto Sans CJK JP |
ko | Malgun Gothic, Apple SD Gothic Neo, Noto Sans CJK KR |
zh-Hant, zh-TW, zh-MO | Microsoft JhengHei, PingFang TC, Noto Sans CJK TC |
zh-HK, yue | PingFang HK, Noto Sans CJK HK, then those of Traditional Chinese |
zh, zh-Hans, no language, any other language | Microsoft YaHei, PingFang SC, Noto Sans CJK SC |
The fonts of the stack itself are used in their order whatever the language, and PreferredFamilies still come first.
Right-to-left and mixed directions
Each paragraph is ordered by the Unicode Bidirectional Algorithm: left-to-right and right-to-left text can be mixed, mirrored characters such as parentheses are mirrored, and each line is put in display order:
public static void DrawMixedDirections(string latinFontPath, string hebrewFontPath, string outputPath)
{
var fonts = new FontStack(Font.Load(latinFontPath), Font.Load(hebrewFontPath));
const string Shalom = "\u05E9\u05DC\u05D5\u05DD"; // "shalom", in Hebrew letters
// Two paragraphs, each in the direction of its first letter: the first one is left-to-right with a Hebrew word
// in it, the second one right-to-left with an English word and a number in it. Its parentheses are mirrored
var text = $"The word {Shalom} means peace.\n{Shalom} (peace) 2026";
// Start is the left of a left-to-right paragraph and the right of a right-to-left one
var layout = TextLayout.Create(text, new TextStyle(fonts, 24), new TextLayoutOptions { MaxWidth = 340, Alignment = TextAlignment.Start });
using var image = new Image<Rgba32>(360, (int)Math.Ceiling(layout.Height) + 20, new Rgba32(255, 255, 255));
image.Draw(canvas => canvas.FillText(new Rgba32(0, 0, 0), layout, new PointD(10, 10)));
image.Save(outputPath);
}
- By default (TextDirection.Auto), the direction of a paragraph is the one of its first strong character. TextLayoutOptions.Direction imposes it on every paragraph.
- Alignment follows the direction: Start is the left of a left-to-right paragraph and the right of a right-to-left one, and End the other side.
- TextLine.IsRightToLeft gives the direction of the paragraph of a line.
- Arabic, Hebrew, Syriac and the other right-to-left scripts are shaped as their fonts are made for: the letters of Arabic and Syriac join, and marks are placed on their letters.
Vertical text
TextLayoutOptions.WritingMode sets the text in vertical lines, as Chinese, Japanese and Korean often are: VerticalRightToLeft lines follow each other to the left, VerticalLeftToRight to the right, as Mongolian is:
public static void DrawVerticalText(string fontPath, string outputPath)
{
var style = new TextStyle(Font.Load(fontPath), 24);
// Lines go down and follow each other to the left, and are wrapped at the height of the layout. The ideographs
// and the kana are upright, with the vertical forms the font has for the brackets and the punctuation; the
// Latin letters are on their side.
var layout = TextLayout.Create(
"「日本語」のテキスト。ABC 東京、日本。",
style,
new TextLayoutOptions { WritingMode = TextWritingMode.VerticalRightToLeft, MaxHeight = 160 });
// The layout is as wide as its columns: the first one is on its right
using var image = new Image<Rgba32>((int)Math.Ceiling(layout.Width) + 20, 180, new Rgba32(255, 255, 255));
image.Draw(canvas => canvas.FillText(new Rgba32(0, 0, 0), layout, new PointD(10, 10)));
image.Save(outputPath);
}
- What is said of the width of a horizontal line is said of the height of a vertical one: MaxHeight is where lines are wrapped and what they are aligned in, LineHeight is the width of a line, and FirstLineIndent moves the indented lines down. Width and Height stay the size of the layout on the image.
- Orientation says which characters are upright. By default (Mixed), each one is set as the Unicode Standard says: ideographs, kana, Hangul and emoji are upright, the letters of horizontal scripts are on their side, turned a quarter of a turn clockwise. Upright sets every character upright, and Sideways every character on its side.
- A few characters can be set across the line in the room of one (tate-chu-yoko): the text of a style whose IsCombinedUpright is set, and the runs of ASCII digits that are not longer than CombineUprightDigits (2, 3 or 4), such as a date or a number.
- The vertical metrics and forms of the font are used (
vhea,vmtx,VORG,vert). A font without vertical metrics, which is every font not made for vertical text, centers each glyph in an advance of its ascent and descent. - Punctuation is neither compressed nor hung. A vertical layout is hinted like a horizontal one, each glyph in its own orientation (hint small text), and a ruby annotation is on the right of its base (ruby).
Hyphenation and scripts without spaces
A word is broken at a soft hyphen (U+00AD) of the text, and the line then ends with a hyphen. That is the default (Hyphenation = Manual); None never breaks a word, not even at a soft hyphen.
With Hyphenation = Automatic, a word is also broken where the patterns of its style allow it: TextStyle.Hyphenator is a Hyphenator of Meziantou.Framework.Unicode, loaded from TeX hyphenation patterns for the language of the text. No patterns are provided with the library. HyphenCharacter replaces the hyphen drawn at the end of the line.
Thai, Lao, Khmer and Burmese are written without spaces between words, and the Unicode algorithm leaves their line breaks to a dictionary. A line of such text can end before each of its words, as ICU finds them: the library uses the word lists and the dictionary break engines of ICU, from Meziantou.Framework.Unicode.Dictionaries, and its breaks are those of the line break iterator of ICU, which the browsers use. The other scripts written without spaces, such as Tai Tham, are only broken at a space, or anywhere with OverflowWrap = Anywhere.
To use your own words, set TextLayoutOptions.LineBreakDictionary to a LineBreakDictionary of Meziantou.Framework.Unicode, loaded from a list of words: it replaces the word lists of ICU. A dictionary without words, LineBreakDictionary.Parse(""), only breaks such text at a space.
Optimal line breaking
By default, each line takes as much of the text as fits, then the next line starts (greedy breaking). With LineBreakStrategy set to Optimal, the breaks of a whole paragraph are chosen together (total fit, after Knuth and Plass, "Breaking Paragraphs into Lines"), so that its lines are evenly filled: a line can end before the text that would still fit, when this leaves less room at the end of the lines after it.
public static TextLayout LayOutEvenly(string fontPath, string text, double width)
{
var font = Font.Load(fontPath);
// A line can end before the text that would still fit, when this leaves less room at the end of the lines
// after it. The last line of a paragraph can be short: it costs nothing
return TextLayout.Create(text, new TextStyle(font, 16), new TextLayoutOptions
{
MaxWidth = width,
LineBreakStrategy = TextLineBreakStrategy.Optimal,
});
}The breaks minimize the sum of the costs of the lines of the paragraph:
| A line | Costs |
|---|---|
| The last line of the paragraph | Nothing |
| Another line | The square of the room left at its end, in ems of the text at the start of the paragraph |
| Another line of a justified paragraph | The square of the room left per place it is stretched at (its spaces, or its characters with Justification), in thirds of an em |
| A line that ends with a hyphen | 1 more, and 3 more again when the line before it ends with a hyphen too |
| A line wider than the width, because nothing shorter can end it | 1,000,000, plus the square of how much it is too wide, in ems |
- The places a line can end are those of greedy breaking: the break opportunities of the Unicode line breaking algorithm (with WordBreak, LineBreak and the dictionaries of the scripts without spaces), the soft hyphens, and the hyphenation points when Hyphenation is Automatic. A word wider than the line is cut or overflows as with greedy breaking.
- Right-to-left and mixed directions, several fonts and sizes, vertical lines, indents and tabulations are measured as greedy breaking measures them. A line never ends inside the base of a ruby.
- The result is deterministic: among breaks of the same cost, the earliest ones are kept.
- The breaks are found from the advances of the paragraph shaped as a whole. A line is shaped again once it is cut; when a kerning pair or a ligature across the break makes it wider than its width, the breaks of the rest of the paragraph are chosen again (up to 8 times, then greedily).
- The work is bounded: choosing the breaks may measure 256 characters per character of the paragraph, plus a million. A paragraph whose lines hold so many break opportunities that it would measure more, such as a long paragraph in a very wide box, is broken greedily from there.
- MaxLines and MaxHeight cut the lines afterwards: the breaks are not chosen to fit them. The spaces are not shrunk to fit more text on a line, and there are no fitness classes: a loose line can follow a tight one.
Optimal breaking costs more than greedy breaking, and the lines of a paragraph depend on the text after them: a word added at its end can move the breaks of its first lines. That is why greedy breaking stays the default.
Ruby
RichTextBuilder.AppendRuby adds a base with an annotation set beside it, such as the reading of Japanese words in kana (furigana):
public static void DrawRuby(string fontPath, string outputPath)
{
var font = Font.Load(fontPath);
var text = new TextStyle(font, size: 28);
var reading = new TextStyle(font, size: 14);
// The base is part of the text; the annotation is set beside it, at half the size, and a line never ends inside the base
var rubyText = new RichTextBuilder()
.AppendRuby("東京", text, "とうきょう", reading)
.Append("の", text)
.AppendRuby("日本語", text, "にほんご", reading)
.Build();
// Above the base in a horizontal layout, on its right in a vertical one
var horizontal = TextLayout.Create(rubyText);
var vertical = TextLayout.Create(rubyText, new TextLayoutOptions { WritingMode = TextWritingMode.VerticalRightToLeft });
var width = (int)Math.Ceiling(horizontal.Width + vertical.Width) + 40;
var height = (int)Math.Ceiling(Math.Max(horizontal.Height, vertical.Height)) + 20;
using var image = new Image<Rgba32>(width, height, new Rgba32(255, 255, 255));
image.Draw(canvas =>
{
canvas.FillText(new Rgba32(0, 0, 0), horizontal, new PointD(10, 10));
canvas.FillText(new Rgba32(0, 0, 0), vertical, new PointD(horizontal.Width + 30, 10));
});
image.Save(outputPath);
}
- The base is text of the layout, with its style: it is measured, hit and selected like the rest of the text. A line never ends inside it, and it is never hyphenated.
- The annotation is laid out on its own, with its style, in the writing mode and orientation of the layout, and centered on the base: above it in a horizontal line, on its right in a vertical line. The line is as tall as the base and its annotation need.
- A base shorter than its annotation gets the difference as room, half before it and half after it: the annotation never runs over the text around it. Japanese typesetting lets it overhang neighboring kana; this layout does not.
- The annotation is drawn and is part of ToPath, but not of the positions of the text: HitTest, the carets and the selections are those of the base.
Synthetic bold and oblique
When you only have the regular font of a family, TextStyle.Synthesis imitates its bold and its italic from the outlines:
public static void DrawSyntheticStyles(string fontPath, string outputPath)
{
// Only the regular font is available: the bold thickens its glyphs and the oblique slants them. A bold or an
// italic font, or an instance of a variable font, looks better when there is one
var font = Font.Load(fontPath);
var text = new RichTextBuilder()
.Append("Regular\n", new TextStyle(font, 28))
.Append("Synthetic bold\n", new TextStyle(font, 28) { Synthesis = FontSynthesis.Bold })
.Append("Synthetic oblique\n", new TextStyle(font, 28) { Synthesis = FontSynthesis.Oblique })
.Append("Bold and oblique", new TextStyle(font, 28) { Synthesis = FontSynthesis.Bold | FontSynthesis.Oblique })
.Build();
var layout = TextLayout.Create(text);
using var image = new Image<Rgba32>((int)Math.Ceiling(layout.Width) + 20, (int)Math.Ceiling(layout.Height) + 20, new Rgba32(255, 255, 255));
image.Draw(canvas => canvas.FillText(new Rgba32(0, 0, 0), layout, new PointD(10, 10)));
image.Save(outputPath);
}
- Oblique slants every outline to the right around the baseline, by about 14 degrees. The advances do not change, marks follow their letter, and decorations stay straight.
- Bold thickens each glyph by a stroke of its outline 1/24 of the size wide, and each glyph takes 1/24 of the size more room. It is a way to fill: StrokeText and TextLayout.ToPath use the outlines of the font, slanted but not thickened.
- Glyphs a font draws with its own colors, such as emoji, are drawn as they are.
- A real bold or italic font, or an instance of a variable font, always looks better.
Language
TextStyle.Language is the language of the text, as a BCP 47 tag ("sr", "tr", "zh-Hant"). A font can draw the same characters differently for different languages: the Cyrillic letters of Serbian and Bulgarian, the ideographs of Chinese, Japanese and Korean, the ligatures around the dotless i of Turkish. The language selects the forms the font has for it, or the default ones when the font has none.
- The script, the region and the variants of the tag count where a language has several written forms:
zh-Hansandzh-Hant,zh-HK,el-polyton. - The language selects these forms, and the installed fonts of the Han ideographs of a stack with installed fallback. It does not change where lines break.
- A language the font has no forms for changes nothing.
Shaping
Each run of one script, direction and font is shaped with the OpenType Layout tables of its font: the GSUB table substitutes glyphs (ligatures, contextual forms, the forms of joining scripts) and the GPOS table positions them (kerning, marks). A font without GPOS kerning is kerned by its kern table. A font made for Apple systems is shaped with its own tables (Apple Advanced Typography): morx instead of GSUB, kerx instead of GPOS, and the tracking of its trak table at the size of the text (see Shaping).
| Scripts | Shaping |
|---|---|
| Latin, Greek, Cyrillic, Han, kana and the other scripts that need no analysis | The default features of the font |
| Arabic, Syriac, N'Ko, Mongolian, Adlam and the other joining scripts | Each letter takes the form its neighbors ask for |
| Hebrew, Thai, Lao, Hangul, Khmer, Myanmar, and the Indic scripts (Devanagari, Bengali, Tamil, …) | A model of their own: reordering, syllables, marks |
| Tibetan, Javanese, Balinese, Sinhala and the other scripts of the universal model | The Universal Shaping Engine model |
- The default features are those a client applies to horizontal text:
ccmp,locl,rlig,calt,clig,liga,kern,mark,mkmkand the others the scripts need. TextStyle.Features turns other features on (smcp,tnum,ss01) or turns default ones off (new FontFeature("liga", 0)). - A character typed as one code point or as a letter and a combining mark gives the same result: the text is put in the form the font has glyphs for.
- Control characters are not drawn, and end the emoji sequence that a zero width joiner before them would continue. Format characters (joiners, variation selectors, a soft hyphen where the line is not broken) are invisible.
- The glyphs and positions are compared with those of HarfBuzz, a reference shaper, on the fonts of every script that has a model.
What layout does not do yet: letter spacing is added between the letters of every script, including those that join; justification does not lengthen Arabic words (kashida), and shares its room equally between its places instead of by priority. A line without a place to stretch stays start-aligned.