Meziantou.Framework

Font Class

Namespace
Meziantou.Framework.Imaging.Typography
Assembly
Meziantou.Framework.Imaging.dll
Package
Meziantou.Framework.Imaging 1.2.11
Source
Font.cs
Available in package assets
net10.0net11.0

A font face loaded from a TrueType or OpenType file (.ttf, .otf), from a WOFF or WOFF2 file, or from a font collection (.ttc, .otc).

public sealed class Font

Remarks

A font is immutable and can be used by several threads at the same time. It keeps the bytes of its file in memory for its whole lifetime, within ImageResourceLimits.MaxFontBytes, and reads its tables from them: it holds no other resource and needs no disposal. The faces of a collection share the bytes.

A font file is untrusted input. What every use of the font needs is validated when it is loaded; the data of a glyph is validated when the glyph is first needed, and the work to produce one glyph is bounded by ImageResourceLimits.MaxGlyphComplexity.

Properties

NameDescription
ColorPalettesGets the palettes of a color font (the CPAL table). Empty for a font without palette.
FamilyNameGets the name of the family of the font, such as Noto Sans; empty when the font has no name.
GlyphCountGets the number of glyphs of the font.
HasColorGlyphsGets a value indicating whether the font has glyphs that are drawn with their own colors, such as emoji: layers of colors or graphs of paints (the COLR table).
IsItalicGets a value indicating whether the font is italic or oblique.
IsMonospacedGets a value indicating whether the font declares that all its glyphs have the same advance.
MetricsGets the vertical metrics of the font, in font units.
NamedInstancesGets the instances a variable font names, such as "Light" or "Bold Condensed". Empty for a font that names none.
PostScriptNameGets the PostScript name of the font, such as NotoSans-Bold, or null when the font has none.
SubfamilyNameGets the name of the style of the font within its family, such as Bold Italic; empty when the font has no name.
UnitsPerEmGets the number of font units per em: the scale of the coordinates of the font.
VariationAxesGets the axes of a variable font: what can vary, and in what range. Empty for a font that does not vary.
VariationsGets the value of each axis of a variable font for this font, in the order of Font.VariationAxes: the defaults for a font as it is loaded, the values of the instance for a font Font.WithVariations returned. Empty for a font that does not vary.
WeightGets the weight of the font, from 1 to 1000: 400 is regular, 700 is bold.

ColorPalettes

Font.cs

Gets the palettes of a color font (the CPAL table). Empty for a font without palette.

public IReadOnlyList<FontColorPalette> ColorPalettes { get; }

Property value

IReadOnlyList<FontColorPalette>

FamilyName

Font.cs

Gets the name of the family of the font, such as Noto Sans; empty when the font has no name.

public string FamilyName { get; }

Property value

string

Remarks

The typographic family name is used when the font has one: it groups every weight and style of the design.

GlyphCount

Font.cs

Gets the number of glyphs of the font.

public int GlyphCount { get; }

Property value

int

HasColorGlyphs

Font.cs

Gets a value indicating whether the font has glyphs that are drawn with their own colors, such as emoji: layers of colors or graphs of paints (the COLR table).

public bool HasColorGlyphs { get; }

Property value

bool

Remarks

DrawingCanvas.FillText draws these glyphs with their colors; the brush of the text is the color of the parts of a glyph the font leaves to it. Stroking a text, and its path, use the outlines of the glyphs.

IsItalic

Font.cs

Gets a value indicating whether the font is italic or oblique.

public bool IsItalic { get; }

Property value

bool

IsMonospaced

Font.cs

Gets a value indicating whether the font declares that all its glyphs have the same advance.

public bool IsMonospaced { get; }

Property value

bool

Metrics

Font.cs

Gets the vertical metrics of the font, in font units.

public FontMetrics Metrics { get; }

Property value

FontMetrics

Remarks

The ascent, the descent and the line gap are the typographic values of the font when it asks for them to be used (the USE_TYPO_METRICS flag); else the values of its horizontal header; else its typographic values; else its Windows values.

When the font does not declare an underline, it is 1/16 em thick with its top 1/8 em below the baseline; when it does not declare a strikethrough line, it is 1/16 em thick with its top 5/16 em above the baseline.

NamedInstances

Font.cs

Gets the instances a variable font names, such as "Light" or "Bold Condensed". Empty for a font that names none.

public IReadOnlyList<FontNamedInstance> NamedInstances { get; }

Property value

IReadOnlyList<FontNamedInstance>

PostScriptName

Font.cs

Gets the PostScript name of the font, such as NotoSans-Bold, or null when the font has none.

public string? PostScriptName { get; }

Property value

string?

SubfamilyName

Font.cs

Gets the name of the style of the font within its family, such as Bold Italic; empty when the font has no name.

public string SubfamilyName { get; }

Property value

string

UnitsPerEm

Font.cs

Gets the number of font units per em: the scale of the coordinates of the font.

public int UnitsPerEm { get; }

Property value

int

VariationAxes

Font.cs

Gets the axes of a variable font: what can vary, and in what range. Empty for a font that does not vary.

public IReadOnlyList<FontVariationAxis> VariationAxes { get; }

Property value

IReadOnlyList<FontVariationAxis>

Variations

Font.cs

Gets the value of each axis of a variable font for this font, in the order of Font.VariationAxes: the defaults for a font as it is loaded, the values of the instance for a font Font.WithVariations returned. Empty for a font that does not vary.

public IReadOnlyList<FontVariationSetting> Variations { get; }

Property value

IReadOnlyList<FontVariationSetting>

Weight

Font.cs

Gets the weight of the font, from 1 to 1000: 400 is regular, 700 is bold.

public int Weight { get; }

Property value

int

Remarks

For an instance of a variable font that has a weight axis (wght), the value of that axis, rounded.

Methods

NameDescription
ContainsGlyph(Rune)Determines whether the font has a glyph for a character.
GetMetrics(double)Gets the vertical metrics of the font at a size, in pixels.
Load(SystemFontDescriptor, FontLoadOptions?)Loads a face of a font installed on the machine, or of a font of the directories of a SystemFontCollection.
Load(Stream, FontLoadOptions?)Loads a font from a stream, read from its current position to its end. For a font collection, the first face is loaded.
Load(ReadOnlySpan<byte>, FontLoadOptions?)Loads a font from the bytes of a font file. For a font collection, the first face is loaded.
Load(string, FontLoadOptions?)Loads a font from a file. For a font collection, the first face is loaded.
LoadAsync(Stream, FontLoadOptions?, CancellationToken)Asynchronously loads a font from a stream, read from its current position to its end. For a font collection, the first face is loaded.
LoadAsync(string, FontLoadOptions?, CancellationToken)Asynchronously loads a font from a file, using asynchronous file I/O. For a font collection, the first face is loaded.
LoadInstalled(string, int, bool, SystemFontCollection?, FontLoadOptions?)Loads the installed font of a family that is the closest to a style: the face SystemFontCollection.Match chooses, at the instance of the style when it is a variable font.
WithVariations(FontNamedInstance)Gets a named instance of a variable font.
WithVariations(ReadOnlySpan<FontVariationSetting>)Gets an instance of a variable font: the same font with other values of its axes.

ContainsGlyph(Rune)

Font.cs

Determines whether the font has a glyph for a character.

public bool ContainsGlyph(Rune codePoint)

Parameters

codePoint Rune
The character.

Returns

bool true when the character map of the font gives the character a glyph other than the missing glyph.

GetMetrics(double)

Font.cs

Gets the vertical metrics of the font at a size, in pixels.

public FontMetrics GetMetrics(double size)

Parameters

size double
The size of the font, in pixels per em.

Returns

FontMetrics The metrics of Font.Metrics multiplied by size / Font.UnitsPerEm.

Exceptions

ArgumentOutOfRangeException
size is not a positive finite number, or is greater than 65536.

Load overloads

Load(SystemFontDescriptor, FontLoadOptions?)

Font.cs

Loads a face of a font installed on the machine, or of a font of the directories of a SystemFontCollection.

public static Font Load(SystemFontDescriptor face, FontLoadOptions? options = null)
Parameters
face SystemFontDescriptor
The face: one of SystemFontCollection.Fonts, or what SystemFontCollection.Match or SystemFontCollection.FindByName returns.
options FontLoadOptions?
The options, or null for FontLoadOptions.Default.
Returns

Font The font of the face at SystemFontDescriptor.FaceIndex of SystemFontDescriptor.FilePath, at the default instance of a variable font.

Exceptions
ArgumentNullException
face is null.
UnknownImageFormatException
The file is no longer a font.
InvalidImageContentException
The font is malformed or truncated, or the file no longer has the face.
UnsupportedImageFeatureException
The font uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.
IOException
An I/O error occurred, such as a file that was removed since the fonts were scanned.
Remarks

A file is read once while one of its fonts is in use: the faces of a font collection (.ttc) share its bytes, and a face loaded again with the same options is the same font. Once none of the fonts of a file is referenced, the file is read again the next time one of its faces is loaded.

Load(Stream, FontLoadOptions?)

Font.cs

Loads a font from a stream, read from its current position to its end. For a font collection, the first face is loaded.

public static Font Load(Stream stream, FontLoadOptions? options = null)
Parameters
stream Stream
The readable source stream. It is left open and is not retained after the method returns.
options FontLoadOptions?
The options, or null for FontLoadOptions.Default.
Returns

Font The font.

Exceptions
ArgumentNullException
stream is null.
ArgumentException
stream is not readable.
UnknownImageFormatException
The data is not a font.
InvalidImageContentException
The font is malformed or truncated.
UnsupportedImageFeatureException
The font uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.
IOException
An I/O error occurred.

Load(ReadOnlySpan<byte>, FontLoadOptions?)

Font.cs

Loads a font from the bytes of a font file. For a font collection, the first face is loaded.

public static Font Load(ReadOnlySpan<byte> data, FontLoadOptions? options = null)
Parameters
data ReadOnlySpan<byte>
The bytes of the file. They are copied: the font does not refer to the span after the method returns.
options FontLoadOptions?
The options, or null for FontLoadOptions.Default.
Returns

Font The font.

Exceptions
UnknownImageFormatException
The data is not a font.
InvalidImageContentException
The font is malformed or truncated.
UnsupportedImageFeatureException
The font uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.

Load(string, FontLoadOptions?)

Font.cs

Loads a font from a file. For a font collection, the first face is loaded.

public static Font Load(string path, FontLoadOptions? options = null)
Parameters
path string
The path of the file. The file is closed before the method returns.
options FontLoadOptions?
The options, or null for FontLoadOptions.Default.
Returns

Font The font.

Exceptions
ArgumentException
path is empty.
UnknownImageFormatException
The file is not a font.
InvalidImageContentException
The font is malformed or truncated.
UnsupportedImageFeatureException
The font uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.
IOException
An I/O error occurred.

LoadAsync overloads

LoadAsync(Stream, FontLoadOptions?, CancellationToken)

Font.cs

Asynchronously loads a font from a stream, read from its current position to its end. For a font collection, the first face is loaded.

public static Task<Font> LoadAsync(Stream stream, FontLoadOptions? options = null, CancellationToken cancellationToken = default)
Parameters
stream Stream
The readable source stream. It is left open.
options FontLoadOptions?
The options, or null for FontLoadOptions.Default.
cancellationToken CancellationToken
The token to monitor for cancellation requests.
Returns

Task<Font> The font.

Exceptions
ArgumentNullException
stream is null.
ArgumentException
stream is not readable.
OperationCanceledException
The operation was canceled.

LoadAsync(string, FontLoadOptions?, CancellationToken)

Font.cs

Asynchronously loads a font from a file, using asynchronous file I/O. For a font collection, the first face is loaded.

public static Task<Font> LoadAsync(string path, FontLoadOptions? options = null, CancellationToken cancellationToken = default)
Parameters
path string
The path of the file.
options FontLoadOptions?
The options, or null for FontLoadOptions.Default.
cancellationToken CancellationToken
The token to monitor for cancellation requests.
Returns

Task<Font> The font.

Exceptions
ArgumentException
path is empty.
OperationCanceledException
The operation was canceled.

LoadInstalled(string, int, bool, SystemFontCollection?, FontLoadOptions?)

Font.cs

Loads the installed font of a family that is the closest to a style: the face SystemFontCollection.Match chooses, at the instance of the style when it is a variable font.

public static Font? LoadInstalled(string familyName, int weight = 400, bool isItalic = false, SystemFontCollection? fonts = null, FontLoadOptions? options = null)

Parameters

familyName string
A typographic family name or a family name, in any language of the fonts, compared without case.
weight int
The weight, from 1 to 1000: 400 is normal, 700 is bold.
isItalic bool
Whether an italic face is preferred; an oblique face, then an upright face, are used when the family has none.
fonts SystemFontCollection?
The fonts to look in, or null for SystemFontCollection.Default, the fonts installed on the machine.
options FontLoadOptions?
The options, or null for FontLoadOptions.Default.

Returns

Font? The font, or null when no font has the family: another family is never used instead.

Exceptions

ArgumentNullException
familyName is null.
ArgumentOutOfRangeException
weight is not between 1 and 1000.
UnknownImageFormatException
The file of the face is no longer a font.
InvalidImageContentException
The font is malformed or truncated, or the file no longer has the face.
UnsupportedImageFeatureException
The font uses a feature that is not supported.
ImageResourceLimitException
A configured limit is exceeded.
IOException
An I/O error occurred, such as a file that was removed since the fonts were scanned.

Remarks

When the face is a variable font, its wght axis is set to weight, its ital axis to the italic, or, without an ital axis, its slnt axis to an oblique angle of 14 degrees for an italic; a value outside the range of its axis is brought to its nearest end. A face that is not variable is used as it is: a family without a bold face gives its closest weight, which TextStyle.Synthesis can embolden.

The fonts of a machine differ from one machine to another: so does the font this method returns. The file is read as Font.Load reads it.

WithVariations overloads

WithVariations(FontNamedInstance)

Font.cs

Gets a named instance of a variable font.

public Font WithVariations(FontNamedInstance instance)
Parameters
instance FontNamedInstance
An instance of Font.NamedInstances.
Returns

Font The font of the instance.

Exceptions
ArgumentNullException
instance is null.

WithVariations(ReadOnlySpan<FontVariationSetting>)

Font.cs

Gets an instance of a variable font: the same font with other values of its axes.

public Font WithVariations(params scoped ReadOnlySpan<FontVariationSetting> settings)
Parameters
settings ReadOnlySpan<FontVariationSetting>
The values of the axes. An axis that is not named has its default value, whatever its value in this font; a value outside the range of its axis is brought to the nearest end of the range; a tag that is not one of the axes of the font is ignored; when an axis is named several times, its last value is used.
Returns

Font A font that shares the data of this one: its outlines, its advances, its metrics and the positions of its layout tables are the ones of the instance. For a font that does not vary, the font itself.

Remarks

Creating an instance reads no glyph: it normalizes the values (with the avar table of the font) and computes how much of each region of the variation data applies. The glyphs are varied when they are needed: their points are not rounded, so an instance is as smooth as the default one. The advances and the metrics of an instance are whole font units.

The instances of a font are different fonts for text layout: a text that uses two of them is shaped in two runs.