Bump to latest stable and update docs.

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

@@ -27,7 +27,7 @@ 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, 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.
 
@@ -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()
     {
     }

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/shaping.md

@@ -53,7 +53,7 @@ At a high level, Fonts does the following:
 5. Applies right-to-left mirrored forms and vertical alternates where the layout requires them.
 6. Applies OpenType GSUB substitutions through the appropriate script shaper.
 7. Applies GPOS positioning for kerning, marks, cursive attachment, and related placement behavior.
-8. Retries unmapped code points with the configured fallback font families.
+8. Retries unmapped code points with the configured fallback font families, then with families from [`FontFallbackResolver`](xref:SixLabors.Fonts.TextOptions.FontFallbackResolver) when one is set.
 9. Updates final glyph positions for every font involved in the shaped result.
 
 The first shaping result is independent of wrapping width. Line composition and alignment happen after shaping, so the same shaped text can be measured, wrapped, rendered, or inspected without changing which glyphs were chosen.
@@ -127,7 +127,7 @@ Mirrored forms, such as paired punctuation in right-to-left runs, are part of th
 
 Fallback is not just a missing-glyph replacement step at the end of rendering. It participates in shaping because each font has its own glyph coverage, metrics, OpenType tables, script tags, and mark positioning behavior.
 
-When the primary text-run font cannot map every code point, Fonts retries unresolved text against [`FallbackFontFamilies`](xref:SixLabors.Fonts.TextOptions.FallbackFontFamilies). The fallback font supplies the glyphs and positions for the code points it covers.
+When the primary text-run font cannot map every code point, Fonts retries unresolved text against [`FallbackFontFamilies`](xref:SixLabors.Fonts.TextOptions.FallbackFontFamilies). The fallback font supplies the glyphs and positions for the code points it covers. A configured [`FontFallbackResolver`](xref:SixLabors.Fonts.TextOptions.FontFallbackResolver) is consulted last, for code points that no listed family can shape. See [Fallback Fonts and Multilingual Text](fallbackfonts.md).
 
 For multilingual text, emoji, and complex scripts, validate fallback with real production strings. A font can contain the individual code points but still lack the OpenType data needed for correct shaping.
 

articles/fonts/systemfonts.md

@@ -12,6 +12,8 @@ The main entry points are:
 - [`SystemFonts.Get(...)`](xref:SixLabors.Fonts.SystemFonts.Get*) and [`SystemFonts.TryGet(...)`](xref:SixLabors.Fonts.SystemFonts.TryGet*) to resolve a family by invariant name
 - [`SystemFonts.CreateFont(...)`](xref:SixLabors.Fonts.SystemFonts.CreateFont*) to create a [`Font`](xref:SixLabors.Fonts.Font) directly
 - [`SystemFonts.Collection`](xref:SixLabors.Fonts.SystemFonts.Collection) when you also need access to the searched directories
+- [`SystemFonts.TryMatchCharacter(...)`](xref:SixLabors.Fonts.SystemFonts.TryMatchCharacter*) to ask the operating system which installed font covers a code point
+- [`SystemFonts.FallbackResolver`](xref:SixLabors.Fonts.SystemFonts.FallbackResolver) to let text shaping consult the system for unresolved code points; see [Fallback Fonts and Multilingual Text](fallbackfonts.md)
 
 ```csharp
 using SixLabors.Fonts;

articles/imagesharp.drawing/canvas.md

@@ -220,7 +220,7 @@ Layer bounds limit the isolated target and final composition area. They do not m
 
 A layer is useful when a group of commands must be blended as one result. Without a layer, each command is blended into the parent independently. With a layer, commands first render into an isolated target, then that whole target is composited back once.
 
-`SaveLayer(...)` overloads also accept a [`LayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.LayerEffect), such as blur, drop shadow, glow, or a backdrop filter, that transforms the layer when it is restored. See [Clipping, Regions, and Layers](clippingregionslayers.md) for the effect model.
+`SaveLayer(...)` overloads also accept a [`LayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.LayerEffect), such as blur, drop shadow, glow, or a backdrop filter, that transforms the layer when it is restored. See [Layer and Backdrop Effects](layereffects.md) for the effect model.
 
 The layer lifecycle is:
 

articles/imagesharp.drawing/clippingregionslayers.md

@@ -114,83 +114,14 @@ Use layers when a group of commands should blend back as one result. Without a l
 
 ## Layer Effects
 
-`SaveLayer(...)` overloads accept a [`LayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.LayerEffect) that transforms the layer content when the layer is restored. The layer isolates the content, so the effect operates on exactly what was drawn between `SaveLayer(...)` and `Restore()`, against transparency, before the result composites onto the canvas.
-
-The built-in content effects are:
-
-- [`BlurLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.BlurLayerEffect) blurs the layer content with a Gaussian sigma.
-- [`DropShadowLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.DropShadowLayerEffect) slots a blurred, offset shadow beneath the layer content.
-- [`GlowLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.GlowLayerEffect) surrounds the content with a colored glow.
-- [`InnerShadowLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.InnerShadowLayerEffect) shades the content inside its own edges.
-- [`ColorMatrixLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.ColorMatrixLayerEffect) transforms the content colors through a `ColorMatrix`.
-
-The layer bounds are expanded internally by the effect's reach, so blurred or offset output is not cut off.
-
-```csharp
-using SixLabors.ImageSharp;
-using SixLabors.ImageSharp.Drawing.Processing;
-using SixLabors.ImageSharp.PixelFormats;
-using SixLabors.ImageSharp.Processing;
-
-using Image<Rgba32> image = new(360, 220, Color.White.ToPixel<Rgba32>());
-
-image.Mutate(ctx => ctx.Paint(canvas =>
-{
-    _ = canvas.SaveLayer(
-        new GraphicsOptions(),
-        new Rectangle(60, 40, 240, 140),
-        new DropShadowLayerEffect(new Point(6, 6), 4F, Color.Black.WithAlpha(0.5F)));
-
-    canvas.FillEllipse(Brushes.Solid(Color.OrangeRed), new(180, 110), new(90, 50));
-    canvas.Restore();
-}));
-```
-
-An overload accepts an `IPath` region instead of a rectangle. The effect then processes only pixels covered by the path, and its output lands on the path translated by the effect's offset.
-
-## Backdrop Effects
-
-A [`BackdropLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.BackdropLayerEffect) filters the pixels already on the canvas beneath the layer's region. The filter runs when the layer is opened, the filtered result is clipped to the region, and the layer's content then renders above it. This is the CSS `backdrop-filter` model.
-
-The built-in backdrop effects are:
-
-- [`BackdropBlurLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.BackdropBlurLayerEffect) blurs the backdrop, the classic frosted-glass base.
-- [`BackdropAcrylicLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.BackdropAcrylicLayerEffect) combines a blur with a tint color for acrylic panels.
-- [`BackdropDropShadowLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.BackdropDropShadowLayerEffect) casts a shadow from the backdrop content.
-- [`BackdropColorMatrixLayerEffect`](xref:SixLabors.ImageSharp.Drawing.Processing.BackdropColorMatrixLayerEffect) transforms backdrop colors through a `ColorMatrix`. Prebuilt variants cover brightness, contrast, grayscale, hue rotation, inversion, opacity, sepia, and saturation.
-
-```csharp
-using SixLabors.ImageSharp;
-using SixLabors.ImageSharp.Drawing.Processing;
-using SixLabors.ImageSharp.PixelFormats;
-using SixLabors.ImageSharp.Processing;
-
-using Image<Rgba32> image = Image.Load<Rgba32>("photo.jpg");
-
-image.Mutate(ctx => ctx.Paint(canvas =>
-{
-    Rectangle panel = new(70, 46, 220, 128);
-
-    _ = canvas.SaveLayer(
-        new GraphicsOptions(),
-        panel,
-        new BackdropAcrylicLayerEffect(10F, Color.White.WithAlpha(0.3F)));
-
-    // The backdrop inside the panel is already blurred and tinted.
-    // Content drawn here renders above the filtered backdrop.
-    canvas.Draw(Pens.Solid(Color.White, 2), panel);
-    canvas.Restore();
-}));
-```
-
-Content effects and backdrop effects answer different questions. Use a content effect when the drawing inside the layer needs the treatment. Use a backdrop effect when the pixels behind a panel need the treatment and the panel content must stay sharp.
+`SaveLayer(...)` overloads accept effects that transform the layer when it is restored: blur, drop shadow, glow, inner shadow, color matrix, and CSS-style backdrop filters. The built-in set, the GPU shader implementations, and custom effect authoring have a dedicated page. See [Layer and Backdrop Effects](layereffects.md).
 
 ## Practical Guidance
 
 - Use clips when geometry should constrain later commands in the current coordinate space.
 - Use regions when a child layout should have its own local origin.
 - Use layers when several commands should blend back as one grouped result.
-- Use a `LayerEffect` when the layer content needs blur, shadow, glow, or color treatment as a group.
+- Use a `LayerEffect` when the layer content needs blur, shadow, glow, or color treatment as a group. See [Layer and Backdrop Effects](layereffects.md).
 - Use a `BackdropLayerEffect` when the pixels behind a region need treatment while the content on top stays sharp.
 - Remember that layer bounds constrain composition but do not move the coordinate system.
 - Restore saved state as soon as the scoped work is complete.