Meziantou.FrameworkFontFace Class
One face of a font file: its table directory and what its fixed-size tables declare.
public sealed class FontFaceRemarks
A face is immutable and holds no cache: it can be used by several threads at the same time, each with its own GlyphScratch.
What every use of the font needs is validated when the face is created: the table directory, the required tables, the headers, the sizes of the metrics and location tables, the structure of the character map. The data of a glyph is validated when the glyph is decoded.
Properties
| Name | Description |
|---|---|
| AverageCharWidth | Gets OS/2.xAvgCharWidth, in font units; 0 when the font has no OS/2 table. |
| Axes | Gets the axes of a variable font; empty for a font that does not vary. |
| CapHeight | Gets OS/2.sCapHeight: the height of the uppercase letters, in font units. |
| Data | Gets the bytes of the font file the face comes from. |
| FamilyName | Gets the family name of the face, from the name table. |
| GdefData | Gets the bytes of the GDEF table; empty when the face has none. |
| GlyphCount | Gets the number of glyphs of the face (maxp.numGlyphs). |
| GposData | Gets the bytes of the GPOS table; empty when the face has none. |
| Gsub | Gets the glyph substitution table, or null. |
| GsubData | Gets the bytes of the GSUB table; empty when the face has none. |
| HasColorGlyphs | Gets a value indicating whether the font has glyphs that are drawn with their own colors. |
| HasColorLayers | Gets a value indicating whether the font has color glyphs made of layers (version 0 of the COLR table). |
| HasLegacyKerning | Gets a value indicating whether the font has pair adjustments in its legacy kerning table. |
| HasMathConstants | Gets a value indicating whether the MATH table of the font has constants. |
| HasMathTable | Gets a value indicating whether the font has a MATH table. |
| HasOs2 | Gets a value indicating whether the face has an OS/2 table. |
| HasPost | Gets a value indicating whether the face has a post table. |
| HasVerticalMetrics | Gets a value indicating whether the font has vertical metrics of its own (vhea and vmtx). |
| HeadFlags | Gets head.flags. |
| HorizontalAscender | Gets hhea.ascender, in font units. |
| HorizontalDescender | Gets hhea.descender, in font units, negative below the baseline. |
| HorizontalLineGap | Gets hhea.lineGap, in font units. |
| Instance | Gets the instance of a variable font the face is, or null for the default instance. |
| IsItalic | Gets a value indicating whether the face is italic or oblique. |
| IsMonospaced | Gets a value indicating whether all the glyphs of the face have the same advance width. |
| ItalicAngle | Gets post.italicAngle, in degrees counterclockwise from the vertical; 0 for an upright font. |
| MacStyle | Gets head.macStyle: bit 0 is bold, bit 1 is italic. |
| MathMinConnectorOverlap | Gets how much two parts of the assembly of a glyph of mathematical layout overlap at least, in font units. |
| NamedInstances | Gets the named instances of a variable font. |
| Os2Version | Gets the version of the OS/2 table; 0 when the font has none. |
| Outlines | Gets the kind of outlines of the face. |
| PaletteCount | Gets the number of palettes of colors of the font. |
| PaletteEntryCount | Gets the number of colors of each palette. |
| PostScriptName | Gets the PostScript name of the face, or null when the font has none. |
| Selection | Gets OS/2.fsSelection; 0 when the font has no OS/2 table. |
| StrikeoutPosition | Gets OS/2.yStrikeoutPosition: the top of the strikeout above the baseline, in font units. |
| StrikeoutSize | Gets OS/2.yStrikeoutSize: the thickness of the strikeout, in font units. |
| SubfamilyName | Gets the subfamily name of the face, such as Bold Italic, from the name table. |
| SubscriptYOffset | Gets OS/2.ySubscriptYOffset: how far below the baseline subscripts are, in font units, positive downward. |
| SuperscriptYOffset | Gets OS/2.ySuperscriptYOffset: how far above the baseline superscripts are, in font units. |
| TableTags | Gets the tags of the tables of the face, in increasing order. |
| TypoAscender | Gets OS/2.sTypoAscender, in font units. |
| TypoDescender | Gets OS/2.sTypoDescender, in font units, negative below the baseline. |
| TypoLineGap | Gets OS/2.sTypoLineGap, in font units. |
| UnderlinePosition | Gets post.underlinePosition: the top of the underline, in font units, negative below the baseline. |
| UnderlineThickness | Gets post.underlineThickness: the thickness of the underline, in font units. |
| UnitsPerEm | Gets the number of font units in the em square (head.unitsPerEm). |
| UseTypoMetrics | Gets a value indicating whether the font asks that the typographic metrics of the OS/2 table are used for the line spacing (USE_TYPO_METRICS). |
| VariesAdvancesWithOutlines | Gets a value indicating whether the advances of the glyphs come from their outlines: an instance of a variable font with TrueType outlines and without HVAR table, whose advance is the one of the phantom points of a glyph. |
| VerticalAscender | Gets vhea.vertTypoAscender, in font units; 0 when the font has no vertical metrics. |
| VerticalDescender | Gets vhea.vertTypoDescender, in font units; 0 when the font has no vertical metrics. |
| VerticalLineGap | Gets vhea.vertTypoLineGap, in font units; 0 when the font has no vertical metrics. |
| Weight | Gets the weight of the face, from 1 to 1000 (400 is regular, 700 is bold). |
| WidthClass | Gets OS/2.usWidthClass, from 1 (ultra-condensed) to 9 (ultra-expanded); 5 when the font has no OS/2 table. |
| WinAscent | Gets OS/2.usWinAscent, in font units. |
| WinDescent | Gets OS/2.usWinDescent, in font units, positive below the baseline. |
| XHeight | Gets OS/2.sxHeight: the height of the lowercase letters, in font units. |
| XMax | Gets the right of the box of all the glyphs of the font (head.xMax), in font units. |
| XMin | Gets the left of the box of all the glyphs of the font (head.xMin), in font units. |
| YMax | Gets the top of the box of all the glyphs of the font (head.yMax), in font units. |
| YMin | Gets the bottom of the box of all the glyphs of the font (head.yMin), in font units. |
AverageCharWidth
FontFace.csAxes
FontFace.csGets the axes of a variable font; empty for a font that does not vary.
public ReadOnlySpan<FontAxisRecord> Axes { get; }Property value
CapHeight
FontFace.csData
FontFace.csFamilyName
FontFace.csGdefData
FontFace.csGets the bytes of the GDEF table; empty when the face has none.
public ReadOnlyMemory<byte> GdefData { get; }Property value
GlyphCount
FontFace.csGposData
FontFace.csGets the bytes of the GPOS table; empty when the face has none.
public ReadOnlyMemory<byte> GposData { get; }Property value
Gsub
FontFace.csGsubData
FontFace.csGets the bytes of the GSUB table; empty when the face has none.
public ReadOnlyMemory<byte> GsubData { get; }Property value
HasColorGlyphs
FontFace.csHasColorLayers
FontFace.csHasLegacyKerning
FontFace.csHasMathConstants
FontFace.csHasMathTable
FontFace.csHasOs2
FontFace.csHasPost
FontFace.csHasVerticalMetrics
FontFace.csHeadFlags
FontFace.csHorizontalAscender
FontFace.csHorizontalDescender
FontFace.csHorizontalLineGap
FontFace.csInstance
FontFace.csGets the instance of a variable font the face is, or null for the default instance.
public FontInstance? Instance { get; }Property value
IsItalic
FontFace.csIsMonospaced
FontFace.csItalicAngle
FontFace.csMacStyle
FontFace.csMathMinConnectorOverlap
FontFace.csGets how much two parts of the assembly of a glyph of mathematical layout overlap at least, in font units.
public int MathMinConnectorOverlap { get; }NamedInstances
FontFace.csGets the named instances of a variable font.
public ReadOnlySpan<FontInstanceRecord> NamedInstances { get; }Property value
Os2Version
FontFace.csOutlines
FontFace.csPaletteCount
FontFace.csPaletteEntryCount
FontFace.csPostScriptName
FontFace.csSelection
FontFace.csStrikeoutPosition
FontFace.csStrikeoutSize
FontFace.csSubfamilyName
FontFace.csSubscriptYOffset
FontFace.csSuperscriptYOffset
FontFace.csTableTags
FontFace.csGets the tags of the tables of the face, in increasing order.
public ReadOnlySpan<uint> TableTags { get; }Property value
TypoAscender
FontFace.csTypoDescender
FontFace.csTypoLineGap
FontFace.csUnderlinePosition
FontFace.csUnderlineThickness
FontFace.csUnitsPerEm
FontFace.csUseTypoMetrics
FontFace.csVariesAdvancesWithOutlines
FontFace.csVerticalAscender
FontFace.csVerticalDescender
FontFace.csVerticalLineGap
FontFace.csWeight
FontFace.csWidthClass
FontFace.csWinAscent
FontFace.csWinDescent
FontFace.csXHeight
FontFace.csXMax
FontFace.csXMin
FontFace.csYMax
FontFace.csYMin
FontFace.csMethods
| Name | Description |
|---|---|
| BuildColorGlyph(int, int, GlyphScratch, GlyphBudget) | Builds the display list of a color glyph, which validates what the glyph refers to. |
| DecodeOutline(int, OutlineSink, GlyphScratch, GlyphBudget) | Decodes the outline of a glyph into a sink. A glyph without outline, such as a space, emits nothing. |
| DecodeOutline(int, double, OutlineSink, GlyphScratch, GlyphBudget) | Decodes the outline of a glyph as it is drawn at a size: the outline of the glyph, or, when the font was loaded to use its bitmaps without colors and has one for the glyph at exactly this size, the squares of its pixels. |
| GetAdvanceHeight(int) | Gets the advance height of a glyph, in font units: how far the pen moves down after it in a vertical line. |
| GetAdvanceWidth(int) | Gets the advance width of a glyph, in font units. |
| GetColorLayers(int) | Gets the layers of a color glyph of version 0 of the COLR table, from the bottom one: the glyph whose outline each layer fills and the index of its color in the palette. |
| GetLayoutDelta(int, int) | Gets the delta of a value of the layout tables for the instance, from the item variation store of the GDEF table, rounded to a font unit; 0 for the default instance. |
| GetLeftSideBearing(int) | Gets the left side bearing of a glyph in the hmtx table, in font units: the one of the default instance of a variable font. |
| GetLegacyKerning(int, int) | Gets the adjustment the legacy kerning table gives to the advance of a glyph when another glyph follows it, in font units; 0 when the font has no such table or no adjustment for the pair. |
| GetLigatureCarets(int, Span<int>) | Gets the positions of the carets inside a ligature glyph, in font units along its advance, from the GDEF table. |
| GetMathConstant(MathConstant) | Gets a constant of mathematical layout, with the delta of the instance of a variable font; 0 when the font has none. |
| GetMathGlyphConstruction(int, bool) | Gets how a glyph of mathematical layout grows along a direction: its larger forms and its assembly. |
| GetName(int) | Gets a name of the font by its identifier in the name table. |
| GetNames(int) | Gets the values a name of the font has in every language of the name table, each one once. |
| GetPaletteType(int, bool, bool) | Tells the backgrounds a palette is made for. |
| GetTopSideBearing(int) | Gets the top side bearing of a glyph in the vmtx table, in font units: the one of the default instance of a variable font; 0 when the font has no vertical metrics. |
| GetVerticalOrigin(int, GlyphScratch?, int, int) | Gets the vertical origin of a glyph, in font units from its horizontal origin: the point of the glyph that is on the pen in a vertical line, at the top of its advance height and in the middle of its width. |
| IsColorGlyph(int) | Tells whether a glyph is drawn with its own colors. |
| IsLayeredColorGlyph(int) | Tells whether a glyph is a color glyph made of layers (version 0 of the COLR table). |
| IsMathExtendedShape(int) | Tells whether a glyph of mathematical layout is an extended shape, such as a large operator. |
| MapCodePoint(int) | Gets the glyph of a character, or 0 when the font has none. |
| MapVariation(int, int, int) | Gets the glyph of a variation sequence. |
| TryGetBaseline(bool, ReadOnlySpan<uint>, uint, int) | Gets a baseline of a script, in font units: along the y axis of the glyphs for horizontal lines, along their x axis for vertical lines. |
| TryGetBitmapGlyph(int, double, BitmapGlyph) | Finds the image of a glyph the font gives as a bitmap, in the strike that suits a size. |
| TryGetGlyphBounds(int, GlyphScratch, GlyphBox) | Gets the box of the outline of a glyph, in font units: the box the glyf table declares for the glyph in a font with TrueType outlines that does not vary them, otherwise the box of the points of its outline, rounded outward. |
| TryGetIdeographicCenter(bool, ReadOnlySpan<uint>, double) | Gets the middle of the ideographic em box of a script, in font units: halfway between the bottom and the top of the box (the ideo and idtp baselines), one em apart when the table only gives one of them. |
| TryGetMathItalicsCorrection(int, int) | Gets the italics correction of a glyph of mathematical layout, in font units. |
| TryGetMathTopAccentAttachment(int, int) | Gets where an accent above a glyph of mathematical layout is centered, in font units from its origin. |
| TryGetPaletteColor(int, int, int, int, int, int) | Gets a color of a palette: its red, green, blue and alpha components, from 0 to 255. |
| TryGetTable(uint, ReadOnlyMemory<byte>) | Gets a table of the face. |
| WithCoordinates(ReadOnlySpan<int>) | Gets the face of an instance of a variable font. |
BuildColorGlyph(int, int, GlyphScratch, GlyphBudget)
FontFace.csBuilds the display list of a color glyph, which validates what the glyph refers to.
public ColorGlyph? BuildColorGlyph(int glyphId, int palette, GlyphScratch scratch, ref GlyphBudget budget)Parameters
glyphIdint- The glyph.
paletteint- The palette its colors come from; a palette the font does not have is its first one.
scratchGlyphScratch- The working storage of the outlines.
budgetGlyphBudget- The complexity budget of the glyph.
Returns
ColorGlyph? The display list, or null when the glyph has no colors of its own.
Exceptions
InvalidFontException- The data of the glyph is malformed.
FontResourceLimitException- The glyph exceeds the complexity limit or the allocation limit.
DecodeOutline overloads
DecodeOutline(int, OutlineSink, GlyphScratch, GlyphBudget)
FontFace.csDecodes the outline of a glyph into a sink. A glyph without outline, such as a space, emits nothing.
public void DecodeOutline(int glyphId, OutlineSink sink, GlyphScratch scratch, ref GlyphBudget budget)Parameters
glyphIdintsinkOutlineSinkscratchGlyphScratchbudgetGlyphBudget
Exceptions
InvalidFontException- The data of the glyph is malformed.
UnsupportedFontFeatureException- The outlines of the font are in a format that is not supported.
FontResourceLimitException- The glyph exceeds the complexity limit or the allocation limit.
DecodeOutline(int, double, OutlineSink, GlyphScratch, GlyphBudget)
FontFace.csDecodes the outline of a glyph as it is drawn at a size: the outline of the glyph, or, when the font was loaded to use its bitmaps without colors and has one for the glyph at exactly this size, the squares of its pixels.
public void DecodeOutline(int glyphId, double size, OutlineSink sink, GlyphScratch scratch, ref GlyphBudget budget)Parameters
glyphIdint- The glyph.
sizedouble- The size the glyph is drawn at, in pixels per em.
sinkOutlineSink- The sink.
scratchGlyphScratch- The working storage of the outlines.
budgetGlyphBudget- The budget of the glyph.
Exceptions
InvalidFontException- The data of the glyph is malformed.
UnsupportedFontFeatureException- The outlines of the font are in a format that is not supported.
FontResourceLimitException- The glyph exceeds the complexity limit or the allocation limit.
GetAdvanceHeight(int)
FontFace.csGets the advance height of a glyph, in font units: how far the pen moves down after it in a vertical line.
GetAdvanceWidth(int)
FontFace.csGets the advance width of a glyph, in font units.
GetColorLayers(int)
FontFace.csGets the layers of a color glyph of version 0 of the COLR table, from the bottom one: the glyph whose outline each layer fills and the index of its color in the palette.
public ColorLayer[]? GetColorLayers(int glyphId)Parameters
glyphIdint
Returns
ColorLayer[]? null when the glyph has no layers; a glyph of version 1 has paints, see FontFace.BuildColorGlyph.
Exceptions
InvalidFontException- The layers of the glyph are malformed.
GetLayoutDelta(int, int)
FontFace.csGetLeftSideBearing(int)
FontFace.csGetLegacyKerning(int, int)
FontFace.csGetLigatureCarets(int, Span<int>)
FontFace.csGets the positions of the carets inside a ligature glyph, in font units along its advance, from the GDEF table.
Parameters
glyphIdint- The ligature glyph.
caretsSpan<int>- Receives the positions, in the order of the components of the ligature.
Returns
int The number of carets the font gives for the glyph; 0 when it gives none.
Exceptions
InvalidFontException- The list of the carets is malformed.
GetMathConstant(MathConstant)
FontFace.csGets a constant of mathematical layout, with the delta of the instance of a variable font; 0 when the font has none.
public int GetMathConstant(MathConstant constant)GetMathGlyphConstruction(int, bool)
FontFace.csGets how a glyph of mathematical layout grows along a direction: its larger forms and its assembly.
public MathGlyphConstruction? GetMathGlyphConstruction(int glyphId, bool isVertical)Parameters
Returns
MathGlyphConstruction? null when the glyph does not grow in the direction.
Exceptions
InvalidFontException- The subtables of the glyph are malformed.
GetName(int)
FontFace.csGetNames(int)
FontFace.csGets the values a name of the font has in every language of the name table, each one once.
public IReadOnlyList<string> GetNames(int nameId)GetPaletteType(int, bool, bool)
FontFace.csGetTopSideBearing(int)
FontFace.csGetVerticalOrigin(int, GlyphScratch?, int, int)
FontFace.csGets the vertical origin of a glyph, in font units from its horizontal origin: the point of the glyph that is on the pen in a vertical line, at the top of its advance height and in the middle of its width.
public void GetVerticalOrigin(int glyphId, GlyphScratch? scratch, out int x, out int y)Parameters
glyphIdintscratchGlyphScratch?xintyint
Remarks
Horizontally, the origin is the middle of the advance width. Vertically, it is the one the VORG table gives (with the delta of the VVAR table in an instance); without that table, the top of the outline plus the top side bearing of the vmtx table; without vertical metrics, the top of the outline plus half of what the advance height has more than the outline is tall, which centers the glyph in its advance. A glyph without outline, such as a space, has an outline without height at the baseline.
These are the rules of the reference shaper, which the positions of a vertical text are compared with.
IsColorGlyph(int)
FontFace.csIsLayeredColorGlyph(int)
FontFace.csIsMathExtendedShape(int)
FontFace.csTells whether a glyph of mathematical layout is an extended shape, such as a large operator.
MapCodePoint(int)
FontFace.csMapVariation(int, int, int)
FontFace.csGets the glyph of a variation sequence.
public CmapVariation MapVariation(int codePoint, int selector, out int glyphId)TryGetBaseline(bool, ReadOnlySpan<uint>, uint, int)
FontFace.csGets a baseline of a script, in font units: along the y axis of the glyphs for horizontal lines, along their x axis for vertical lines.
public bool TryGetBaseline(bool isVertical, ReadOnlySpan<uint> scripts, uint baseline, out int coordinate)Parameters
isVerticalbooltruefor the baselines of vertical lines.scriptsReadOnlySpan<uint>- The script tags of the text, by order of preference.
baselineuint- The tag of the baseline.
coordinateint- The coordinate of the baseline, with the delta of the
BASEtable in an instance of a variable font.
Returns
bool false when the font has no BASE table, or the table does not give the baseline.
Exceptions
InvalidFontException- The table is malformed.
TryGetBitmapGlyph(int, double, BitmapGlyph)
FontFace.csFinds the image of a glyph the font gives as a bitmap, in the strike that suits a size.
public bool TryGetBitmapGlyph(int glyphId, double size, out BitmapGlyph glyph)Parameters
glyphIdintsizedoubleglyphBitmapGlyph
Returns
bool false when the font has no image for the glyph.
TryGetGlyphBounds(int, GlyphScratch, GlyphBox)
FontFace.csGets the box of the outline of a glyph, in font units: the box the glyf table declares for the glyph in a font with TrueType outlines that does not vary them, otherwise the box of the points of its outline, rounded outward.
public bool TryGetGlyphBounds(int glyphId, GlyphScratch scratch, out GlyphBox bounds)Parameters
glyphIdint- The glyph.
scratchGlyphScratch- The working storage of the outline, when it has to be decoded.
boundsGlyphBox- The box.
Returns
bool false for a glyph without outline, such as a space.
Exceptions
InvalidFontException- The data of the glyph is malformed.
UnsupportedFontFeatureException- The outlines of the font are in a format that is not supported.
FontResourceLimitException- The glyph exceeds the complexity limit or the allocation limit.
TryGetIdeographicCenter(bool, ReadOnlySpan<uint>, double)
FontFace.csGets the middle of the ideographic em box of a script, in font units: halfway between the bottom and the top of the box (the ideo and idtp baselines), one em apart when the table only gives one of them.
public bool TryGetIdeographicCenter(bool isVertical, ReadOnlySpan<uint> scripts, out double center)Parameters
isVerticalbooltruefor the middle of the box of vertical lines, along the x axis of the glyphs.scriptsReadOnlySpan<uint>- The script tags of the text, by order of preference.
centerdouble- The middle of the box.
Returns
bool false when the font does not give the ideographic em box of the script.
Exceptions
InvalidFontException- The
BASEtable is malformed.
TryGetMathItalicsCorrection(int, int)
FontFace.csTryGetMathTopAccentAttachment(int, int)
FontFace.csGets where an accent above a glyph of mathematical layout is centered, in font units from its origin.
Parameters
Returns
bool false when the font gives none for the glyph.
Exceptions
InvalidFontException- The subtable is malformed.
TryGetPaletteColor(int, int, int, int, int, int)
FontFace.csTryGetTable(uint, ReadOnlyMemory<byte>)
FontFace.csGets a table of the face.
public bool TryGetTable(uint tag, out ReadOnlyMemory<byte> table)Parameters
taguinttableReadOnlyMemory<byte>
Returns
bool false when the face does not have the table.
WithCoordinates(ReadOnlySpan<int>)
FontFace.csGets the face of an instance of a variable font.
public FontFace WithCoordinates(ReadOnlySpan<int> userCoordinates)Parameters
userCoordinatesReadOnlySpan<int>- The value of each axis, in the order of the axes, as 16.16 fixed-point numbers; an axis without value is at its default. A value outside the range of its axis is brought to the nearest end.
Returns
FontFace The face of the instance; the face of the default instance when every axis is at its default.