Merge pull request #81 from SixLabors/js/vnext

Enhance font hinting and ANI documentation in ImageSharp

Author: JimBobSquarePants

articles/fonts/colorfonts.md

@@ -44,6 +44,34 @@ TextOptions options = new(font)
 };
 ```
 
+## Font palettes
+
+COLR glyphs take their colors from the font's CPAL palette table. Many color fonts ship more than one palette, such as a default and a dark-background variant. [`TextOptions.FontPalette`](xref:SixLabors.Fonts.TextOptions.FontPalette) selects the palette that resolves the colors. Leave the value `null` to keep the font's default palette.
+
+```csharp
+using SixLabors.Fonts;
+
+Font font = SystemFonts.CreateFont("Segoe UI Emoji", 32);
+TextOptions options = new(font)
+{
+    // Resolve COLR glyph colors with the font's second palette.
+    // Palette indexes are zero-based; null keeps the font's default.
+    FontPalette = new FontPalette(1)
+};
+```
+
+A palette selection can also override individual entries. Each [`FontPaletteOverride`](xref:SixLabors.Fonts.FontPaletteOverride) replaces the palette color at one index:
+
+```csharp
+// Start from the default palette, then replace entry 2 with opaque red.
+FontPalette palette = new(0,
+[
+    new FontPaletteOverride(2, new GlyphColor(255, 0, 0, 255))
+]);
+```
+
+[`TextRun.FontPalette`](xref:SixLabors.Fonts.TextRun.FontPalette) replaces the selection over a range of text. [`GlyphOptions.FontPalette`](xref:SixLabors.Fonts.GlyphOptions.FontPalette) applies the same selection when rendering or measuring by glyph ID.
+
 ## What happens in custom renderers
 
 When a resolved glyph is a painted color glyph, Fonts streams it through [`IGlyphRenderer`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer) as one or more layers.
@@ -52,9 +80,10 @@ That means custom renderers should pay attention to:
 
 - [`GlyphRendererParameters.GlyphType`](xref:SixLabors.Fonts.Rendering.GlyphRendererParameters.GlyphType)
 - [`BeginLayer(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginLayer*)
+- [`BeginGroup(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginGroup*) and [`EndGroup()`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.EndGroup*)
 - [`Paint`](xref:SixLabors.Fonts.Rendering.Paint)
 - [`FillRule`](xref:SixLabors.Fonts.Rendering.FillRule)
-- [`ClipQuad`](xref:SixLabors.Fonts.ClipQuad)
+- [`ClipBounds`](xref:SixLabors.Fonts.ClipBounds)
 
 Depending on the font technology in use, the `Paint` passed to `BeginLayer(...)` may be:
 
@@ -63,6 +92,8 @@ Depending on the font technology in use, the `Paint` passed to `BeginLayer(...)`
 - [`RadialGradientPaint`](xref:SixLabors.Fonts.Rendering.RadialGradientPaint)
 - [`SweepGradientPaint`](xref:SixLabors.Fonts.Rendering.SweepGradientPaint)
 
+COLR v1 paint graphs can also form composite groups. Fonts wraps such content in [`BeginGroup(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginGroup*) and [`EndGroup()`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.EndGroup*) calls. Layers inside a group compose as one isolated unit. The finished group then blends onto the content below it with the [`CompositeMode`](xref:SixLabors.Fonts.Rendering.CompositeMode) given to `BeginGroup(...)`. A clip for the glyph arrives through [`GlyphRendererParameters.ClipBounds`](xref:SixLabors.Fonts.Rendering.GlyphRendererParameters.ClipBounds).
+
 If your renderer ignores paint information, the glyph can still be drawn, but it will no longer preserve the font's intended color presentation.
 
 ## Inspect color glyphs directly

articles/fonts/customrendering.md

@@ -5,7 +5,7 @@
 
 Most developers meet Fonts through [ImageSharp.Drawing](../imagesharp.drawing/index.md), where the rendering surface is already handled for you. This page is for the next step down: when you want Fonts to do the shaping and glyph decomposition, but you want to decide how those glyphs are painted or exported.
 
-Custom rendering in Fonts is built around [`IGlyphRenderer`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer). [`TextRenderer.RenderTextTo(...)`](xref:SixLabors.Fonts.Rendering.TextRenderer.RenderTextTo*) performs layout and shaping, then sends the result to your renderer as glyphs, layers, figures, and path commands.
+Custom rendering in Fonts is built around [`IGlyphRenderer`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer). [`TextRenderer.RenderTo(...)`](xref:SixLabors.Fonts.Rendering.TextRenderer.RenderTo*) performs layout and shaping, then sends the result to your renderer as glyphs, layers, figures, and path commands.
 
 ## When to use it
 
@@ -27,9 +27,9 @@ For monochrome outline glyphs, the path callbacks are delivered inside [`BeginGl
 5. `SetDecoration(...)` for any decorations requested by `EnabledDecorations()`
 6. `EndText()`
 
-Painted color glyphs add [`BeginLayer(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginLayer*) / [`EndLayer()`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.EndLayer*) around each painted layer between [`BeginGlyph(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginGlyph*) and [`EndGlyph()`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.EndGlyph*).
+Painted color glyphs add [`BeginLayer(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginLayer*) / [`EndLayer()`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.EndLayer*) around each painted layer between [`BeginGlyph(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginGlyph*) and [`EndGlyph()`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.EndGlyph*). COLR v1 composite content adds [`BeginGroup(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginGroup*) / [`EndGroup()`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.EndGroup*) around layers that must compose as one isolated unit before they blend onto the content below.
 
-[`BeginGlyph(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginGlyph*) receives [`GlyphRendererParameters`](xref:SixLabors.Fonts.Rendering.GlyphRendererParameters), which identify the glyph instance being rendered, including the glyph ID, the glyph's [`CodePoint`](xref:SixLabors.Fonts.Unicode.CodePoint) value, font style, point size, DPI, layout mode, and active [`TextRun`](xref:SixLabors.Fonts.TextRun). Return `false` from `BeginGlyph(...)` if you want to skip rendering that glyph.
+[`BeginGlyph(...)`](xref:SixLabors.Fonts.Rendering.IGlyphRenderer.BeginGlyph*) receives [`GlyphRendererParameters`](xref:SixLabors.Fonts.Rendering.GlyphRendererParameters), which identify the glyph instance being rendered, including the glyph ID, the glyph's [`CodePoint`](xref:SixLabors.Fonts.Unicode.CodePoint) value, font style, point size, DPI, layout mode, hinting mode, and active [`TextRun`](xref:SixLabors.Fonts.TextRun). Return `false` from `BeginGlyph(...)` if you want to skip rendering that glyph. The parameters include everything that changes glyph geometry, so a renderer can use them as a cache key.
 
 ## A minimal renderer
 
@@ -57,14 +57,22 @@ public sealed class RecordingGlyphRenderer : IGlyphRenderer
     {
     }
 
-    public void BeginLayer(Paint? paint, FillRule fillRule, ClipQuad? clipBounds)
+    public void BeginLayer(Paint? paint, FillRule fillRule)
     {
     }
 
     public void EndLayer()
     {
     }
 
+    public void BeginGroup(CompositeMode mode)
+    {
+    }
+
+    public void EndGroup()
+    {
+    }
+
     public void BeginFigure()
     {
     }
@@ -114,7 +122,7 @@ TextOptions options = new(font)
 };
 
 RecordingGlyphRenderer renderer = new();
-TextRenderer.RenderTextTo(renderer, "Hello world", options);
+TextRenderer.RenderTo(renderer, "Hello world", options);
 ```
 
 Replace `"Segoe UI"` with any installed family that exists on your machine.

articles/fonts/fallbackfonts.md

@@ -34,6 +34,28 @@ Fallback families are searched in the order you provide them.
 - Put emoji fonts after your normal text families unless you explicitly want them to win earlier.
 - Keep the fallback list as small and intentional as possible so the selection stays predictable.
 
+## Resolver-based fallback
+
+[`FallbackFontFamilies`](xref:SixLabors.Fonts.TextOptions.FallbackFontFamilies) is a fixed list. [`TextOptions.FontFallbackResolver`](xref:SixLabors.Fonts.TextOptions.FontFallbackResolver) adds a dynamic last step behind it. Shaping consults the resolver only for code points that neither the primary font nor any fallback family can shape. It asks at most once per distinct unresolved code point per shaping operation. Leave the value `null` to render such code points as the missing-glyph outline.
+
+[`SystemFonts.FallbackResolver`](xref:SixLabors.Fonts.SystemFonts.FallbackResolver) is a built-in resolver that selects from the fonts installed on the current machine:
+
+```csharp
+using SixLabors.Fonts;
+
+Font font = SystemFonts.CreateFont("Segoe UI", 18);
+TextOptions options = new(font)
+{
+    // Ask the operating system for a family when no configured font
+    // can shape a code point.
+    FontFallbackResolver = SystemFonts.FallbackResolver
+};
+```
+
+Installed fonts differ between machines, so output rendered with the system resolver can differ too. Pin `FallbackFontFamilies` for output that must stay identical everywhere, and use the resolver as a safety net behind them.
+
+Implement [`IFontFallbackResolver`](xref:SixLabors.Fonts.IFontFallbackResolver) for a custom policy. The resolver receives the code point, the requested family, the style, and the culture. It returns the family that contains a glyph for the code point.
+
 ## Mixed-script example
 
 This pattern works well for text that mixes Latin, Arabic, and emoji:

articles/fonts/fontmetrics.md

@@ -41,6 +41,7 @@ The core identity and scaling properties are:
 - [`Description`](xref:SixLabors.Fonts.FontMetrics.Description) for the face metadata
 - [`UnitsPerEm`](xref:SixLabors.Fonts.FontMetrics.UnitsPerEm) for the design-space resolution of the font
 - [`ScaleFactor`](xref:SixLabors.Fonts.FontMetrics.ScaleFactor) for the face-level unit-to-point scaling used by glyph metrics
+- [`XHeight`](xref:SixLabors.Fonts.FontMetrics.XHeight) and [`CapHeight`](xref:SixLabors.Fonts.FontMetrics.CapHeight) for the lowercase and capital letter heights in design units, or `0` when the font does not provide them
 
 `UnitsPerEm` is the important anchor for understanding almost every other metric on the typeface. Values like ascenders, underline positions, or glyph advances are stored in font units and should be interpreted relative to that em square.
 

articles/fonts/hinting.md

@@ -1,6 +1,6 @@
-# TrueType Hinting
+# Font Hinting
 
-Font hinting is the use of instructions in a font to adjust outline glyphs for a raster grid. In TrueType fonts, those instructions are bytecode programs stored in the font. The rasterizer executes them at a given size and DPI to move outline points before the glyph is drawn.
+Font hinting adjusts outline glyphs for a raster grid. TrueType fonts carry bytecode programs that move outline points at a given size and DPI. CFF fonts declare stem hints and alignment zones that a rasterizer fits to the grid. Fonts supports both models.
 
 ## Why Hinting Exists
 
@@ -17,12 +17,13 @@ Hinting changes the scaled outline before rasterization. It can improve:
 
 The effect is most visible for small UI text at ordinary screen DPI. At larger sizes or high-resolution outputs, the outline has more pixels available and hinting usually has less visible effect.
 
-## How Fonts Applies Hinting
+## Hinting Modes
 
-[`TextOptions.HintingMode`](xref:SixLabors.Fonts.TextOptions.HintingMode) controls whether Fonts applies TrueType hinting:
+[`TextOptions.HintingMode`](xref:SixLabors.Fonts.TextOptions.HintingMode) controls how Fonts applies hinting:
 
 - [`HintingMode.None`](xref:SixLabors.Fonts.HintingMode.None) leaves glyph outlines unhinted.
-- [`HintingMode.Standard`](xref:SixLabors.Fonts.HintingMode.Standard) applies the library's FreeType v40-compatible TrueType hinting behavior.
+- [`HintingMode.Standard`](xref:SixLabors.Fonts.HintingMode.Standard) fits outlines to the pixel grid on the vertical axis only. Horizontal placement stays smooth.
+- [`HintingMode.Full`](xref:SixLabors.Fonts.HintingMode.Full) fits outlines and glyph origins to the pixel grid on both axes. This reproduces the classic bi-level grid fitting that font hints were originally authored for.
 
 ```csharp
 using SixLabors.Fonts;
@@ -37,13 +38,32 @@ TextOptions options = new(font)
 
 The active font size and [`Dpi`](xref:SixLabors.Fonts.TextOptions.Dpi) matter because hinting targets a specific pixels-per-em scale.
 
-## Fonts' Hinting Approach
+## Standard Hinting
 
-Fonts uses a TrueType bytecode interpreter modeled on FreeType's v40 subpixel hinting behavior. In practical terms, that means Fonts preserves full vertical TrueType instruction processing while intentionally disabling horizontal hinting.
+Standard hinting models FreeType's v40 subpixel hinting behavior. For TrueType fonts, it preserves full vertical instruction processing while intentionally disabling horizontal hinting. For CFF fonts, it fits the vertical axis only from the declared hints.
 
-This approach is designed for modern antialiased text rendering, where horizontal subpixel placement should remain smooth and glyph advances should not be forced into old bi-level grid-fitting behavior. It gives small text the vertical alignment benefits of TrueType hinting while avoiding legacy horizontal snapping that can make spacing and shapes less consistent in modern raster output.
+This mode is designed for modern antialiased text rendering, where horizontal subpixel placement remains smooth and glyph advances keep their fractional shaped values. It gives small text the vertical alignment benefits of hinting while avoiding legacy horizontal snapping that can make spacing less consistent.
 
-When hinting is active, Fonts:
+## Full Hinting
+
+Full hinting reproduces the classic rasterizer pipeline. It produces the sharpest results at small sizes, at the cost of shape fidelity and spacing regularity.
+
+Under full hinting, Fonts:
+
+- rounds the em size to a whole number of pixels, with a minimum of one pixel
+- executes the complete horizontal and vertical TrueType instruction set, or fits CFF outlines on both axes
+- aligns glyph origins and text decorations to the pixel grid on both axes
+- replaces fractional advances on the flow axis with whole-pixel advances
+
+For TrueType fonts, the whole-pixel advance comes from the font's `hdmx` device record when the font carries one. Otherwise Fonts uses the hinted advance that instruction execution produced, or the design advance rounded to whole pixels for glyphs the interpreter could not hint. CFF fonts carry no device advance records, so the design advance rounds to whole pixels.
+
+Whole-pixel advances change spacing. Fractional positioning adjustments on the flow axis, such as pair kerning, are dropped because the classic pipeline never applied them. Inter-glyph spacing can vary by up to half a pixel from the unhinted design. Measurement uses the same advances as rendering, so measured layout and rendered output stay in agreement.
+
+Two cases keep their shaped fractional advances: subscript and superscript runs, and upright glyphs in vertical layout.
+
+## The TrueType Pipeline
+
+Fonts uses a TrueType bytecode interpreter. When hinting is active, Fonts:
 
 - executes the font program from `fpgm` to initialize TrueType function definitions
 - scales the Control Value Table from `cvt ` for the current size and DPI
@@ -54,27 +74,32 @@ When hinting is active, Fonts:
 - executes each glyph's TrueType instructions against the resolved outline
 - leaves the outline unhinted if a glyph has no instructions, hinting is inhibited by the font program, or instruction execution fails
 
-## TrueType Scope
+Some fonts are known to require hinting for correct rendering, and some are known to render badly with it. Fonts maintains compatibility lists that force such TrueType fonts to full hinting or to no hinting, regardless of the requested mode.
+
+## The CFF Pipeline
 
-Fonts applies this hinting path to TrueType outlines. It does not turn CFF or CFF2 outlines into hinted TrueType outlines, and it does not change which glyphs are selected for the text.
+CFF outlines carry no instructions. Instead, the font declares the regularities in its design:
 
-Within the TrueType path, Fonts supports:
+- horizontal and vertical stem hints in each glyph's charstring
+- hint masks and counter masks that control which stems apply in each region of the glyph
+- alignment zones, standard stem widths, and related values in the Private DICT
 
-- TrueType glyph instruction execution.
-- Standard TrueType hinting tables such as `fpgm`, `prep`, and `cvt `.
-- Per-glyph hinting at the active size and DPI.
-- `cvar`-driven control-value adjustments for variable TrueType fonts before hinting runs.
-- Hinted contour-point resolution for GPOS anchor data when a font uses contour-point anchors.
-- Font-specific compatibility behavior for fonts known to require hinting.
+When hinting is active, Fonts collects these declared hints while it evaluates the charstring, then fits the outline through a hint map. Standard hinting fits the vertical axis only, from the declared horizontal stem zones and alignment-zone flats. Full hinting fits both axes.
 
-## When to Enable It
+## Choosing a Mode
 
-Use [`HintingMode.Standard`](xref:SixLabors.Fonts.HintingMode.Standard) when rendering small TrueType UI text to a raster target and you want grid-fitted outlines.
+Use [`HintingMode.Standard`](xref:SixLabors.Fonts.HintingMode.Standard) when rendering small UI text to a raster target and you want grid-fitted outlines with smooth, fractional spacing.
+
+Use [`HintingMode.Full`](xref:SixLabors.Fonts.HintingMode.Full) when you want the sharpest possible small text and accept the classic-rasterizer tradeoffs: whole-pixel spacing, dropped fractional kerning, and altered glyph shapes. It is also the mode to compare output against classic bi-level rasterizers.
 
 Use [`HintingMode.None`](xref:SixLabors.Fonts.HintingMode.None) when you want raw outline behavior, when you are rendering large display text, or when the text is being treated as artwork rather than screen UI.
 
 There is no universal best setting. Hinting is a raster-quality tradeoff: it can make small text clearer, but it can also move outlines away from their pure scaled design.
 
+## Custom Renderers
+
+The requested hinting mode is part of [`GlyphRendererParameters`](xref:SixLabors.Fonts.Rendering.GlyphRendererParameters). A renderer that caches glyph geometry can include the parameters in its cache key, so outlines fitted under one mode are never reused under another.
+
 ## Common Misunderstandings
 
 Hinting does not:

articles/fonts/index.md

@@ -107,7 +107,7 @@ If you are new to Fonts, start with [Loading Fonts and Collections](gettingstart
 - [Text Layout and Options](textlayout.md)
 - [OpenType Features](opentypefeatures.md)
 - [Text Shaping](shaping.md)
-- [TrueType Hinting](hinting.md)
+- [Font Hinting](hinting.md)
 - [Color Fonts](colorfonts.md)
 - [Unicode, Code Points, and Graphemes](unicode.md)
 - [Fallback Fonts and Multilingual Text](fallbackfonts.md)