Optimize text layout hot paths and caching

Improves rendering and layout performance by removing per-glyph allocations and reusing computed data. TextBlock now caches the most recent line-broken layout and lazily cached bounds with thread-safe publication, FontDescription precomputes the invariant uppercase font name once, and several hot-path foreach loops over interface-typed metric/break collections were replaced with index-based loops to avoid heap enumerators. The changeset also adds repository-wide AI agent instruction files, updates binary file patterns in .gitattributes, and advances the shared-infrastructure submodule.

Author: JimBobSquarePants

.gitattributes

@@ -84,12 +84,15 @@
 #   treat as binary
 ###############################################################################
 *.basis             binary
+*.a                 binary
 *.dll               binary
+*.dylib             binary
 *.exe               binary
 *.pdf               binary
 *.ppt               binary
 *.pptx              binary
 *.pvr               binary
+*.so                binary
 *.snk               binary
 *.xls               binary
 *.xlsx              binary

.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+# GitHub Copilot Instructions
+
+Read and follow [AGENTS.md](../AGENTS.md) as the repository-wide source of coding, performance, and verification requirements. Prefer existing local patterns and repository configuration whenever generated code or suggestions are accepted.

AGENTS.md

@@ -0,0 +1,41 @@
+# Six Labors AI Coding Guidelines
+
+These instructions apply to the entire repository. More-specific `AGENTS.md` files may add to or override them for their directory tree.
+
+## Working Practices
+
+- Inspect the relevant implementation, tests, benchmarks, project files, and nearby code before proposing or making changes. Do not infer current behavior when the source is available.
+- Make the smallest complete change that solves the requested problem. Avoid unrelated cleanup, speculative abstractions, and formatting churn.
+- Match established architecture, naming, formatting, documentation, and test patterns. Treat `.editorconfig`, analyzers, and repository build settings as authoritative.
+- Preserve public API and observable behavior unless the task explicitly requires a change. Public API documentation must describe observable behavior, not implementation details.
+- Do not use reflection against built assemblies, ad hoc assembly loading, or temporary probe projects unless explicitly requested.
+- Build .NET projects in Release configuration unless explicitly instructed otherwise.
+
+## Performance
+
+- Treat throughput, latency, memory use, and binary size as design constraints, especially in pixel-processing, drawing, parsing, encoding, and other hot paths.
+- Avoid unnecessary allocations, copies, boxing, closures, interface dispatch, repeated enumeration, and extra passes over data.
+- Reuse the repository's existing memory ownership, pooling, span, vectorization, and parallelization patterns. Do not introduce a new mechanism when an established one fits.
+- Keep hot loops simple and bounds-check-friendly. Hoist invariant work, preserve locality, and use the narrowest suitable data types without sacrificing correctness.
+- Do not trade correctness or maintainability for assumed speed. Support non-obvious optimizations with measurements or clear evidence, and add or update benchmarks when performance is the purpose of the change.
+- Consider all supported target frameworks and runtime capabilities. Do not regress fallback paths while optimizing newer runtimes.
+
+## C# Conventions
+
+- Follow the existing code around the change; local patterns take precedence over generic preferences.
+- Do not use `record` or `record struct` types.
+- Prefer established invariants over redundant guards. Validate at real external boundaries and do not add defensive checks for internally controlled states.
+- Do not extract single-use helpers merely to name a block. Extract only for genuine reuse, an established local pattern, or meaningful complexity reduction.
+- Add vertical whitespace after multi-line statements and declarations and between distinct logical stages. Never add trailing whitespace.
+- Document every method, constructor, and property, regardless of whether it is public, internal, protected, or private. Keep public API documentation limited to observable behavior; use private and internal documentation to capture the contract and intent needed to maintain the code.
+- Add inline comments throughout complex code. Explain algorithms, formulas, invariants, ownership, compatibility behavior, and performance tradeoffs at the operations and decisions they govern. Explain why the code is shaped that way rather than narrating the syntax.
+- Document SIMD code especially thoroughly. Explain the vector layout, lane meaning, widening or narrowing, masks, shuffles, constants, alignment or remainder handling, supported instruction paths, scalar equivalence, and the reason each non-obvious operation is correct.
+- Write algorithm and SIMD comments for a maintainer who is unfamiliar with the implementation. The reader should not need to reconstruct intent from external documentation, issue history, or benchmark results.
+
+## Verification
+
+- Add or update focused tests when behavior changes, following the test framework and conventions already used by the project.
+- Never hack, weaken, skip, conditionally bypass, or otherwise manipulate a test to make it pass. Fix the production defect or the genuine test defect while preserving the test's intended coverage and sensitivity.
+- Do not update golden files, reference images, snapshots, baselines, or expected-output artifacts to resolve a test failure. Treat a mismatch as evidence to investigate and correct the implementation.
+- Run the narrowest relevant formatting, test, and Release build commands, then expand verification in proportion to the risk and scope of the change.
+- Report what changed, the verification performed, and any remaining risks or unverified assumptions.

CLAUDE.md

@@ -0,0 +1,3 @@
+# Claude Code Instructions
+
+Read and follow [AGENTS.md](AGENTS.md) as the repository-wide source of coding, performance, and verification requirements. Apply any more-specific `AGENTS.md` or `CLAUDE.md` found below the files being changed.

GEMINI.md

@@ -0,0 +1,3 @@
+# Gemini CLI Instructions
+
+Read and follow [AGENTS.md](AGENTS.md) as the repository-wide source of coding, performance, and verification requirements. Apply any more-specific `AGENTS.md` or `GEMINI.md` found below the files being changed.

shared-infrastructure

@@ -33,6 +33,10 @@ internal FontDescription(NameTable nameTable, OS2Table? os2, HeadTable? head)
         this.FontNameInvariantCulture = this.FontName(CultureInfo.InvariantCulture);
         this.FontFamilyInvariantCulture = this.FontFamily(CultureInfo.InvariantCulture);
         this.FontSubFamilyNameInvariantCulture = this.FontSubFamilyName(CultureInfo.InvariantCulture);
+
+        // Upper-cased once here: glyph renderer parameters embed this name for every rendered
+        // glyph, and per-glyph ToUpper calls would allocate a string per glyph per frame.
+        this.FontNameUpperInvariantCulture = this.FontNameInvariantCulture.ToUpper(CultureInfo.InvariantCulture);
     }
 
     /// <summary>
@@ -50,6 +54,12 @@ internal FontDescription(NameTable nameTable, OS2Table? os2, HeadTable? head)
     /// </summary>
     public string FontNameInvariantCulture { get; }
 
+    /// <summary>
+    /// Gets the invariant-culture font name upper-cased once at construction, shared by every
+    /// per-glyph renderer parameter instance.
+    /// </summary>
+    public string FontNameUpperInvariantCulture { get; }
+
     /// <summary>
     /// Gets the name of the font family in the invariant culture.
     /// </summary>

src/SixLabors.Fonts/FontDescription.cs

@@ -22,7 +22,9 @@ internal GlyphRendererParameters(
         GlyphLayoutMode layoutMode,
         int graphemeIndex)
     {
-        this.Font = metrics.FontMetrics.Description.FontNameInvariantCulture?.ToUpper(CultureInfo.InvariantCulture) ?? string.Empty;
+        // The upper-cased invariant name is computed once on the immutable description; doing it
+        // here would allocate a string for every rendered glyph.
+        this.Font = metrics.FontMetrics.Description.FontNameUpperInvariantCulture;
         this.FontStyle = metrics.FontMetrics.Description.Style;
         this.GlyphId = metrics.GlyphId;
         this.GraphemeIndex = graphemeIndex;

src/SixLabors.Fonts/Rendering/GlyphRendererParameters.cs

@@ -9,8 +9,20 @@ namespace SixLabors.Fonts;
 /// <summary>
 /// Represents text prepared for repeated line layout, measurement, and rendering.
 /// </summary>
+/// <remarks>
+/// Instances are safe to measure and render concurrently. The block retains the most recent
+/// line-broken layout; concurrent calls can only duplicate deterministic layout work, never
+/// observe partial state.
+/// </remarks>
 public sealed partial class TextBlock
 {
+    /// <summary>
+    /// The most recent line-broken layout, retained so repeated measurement and rendering at an
+    /// unchanged wrapping length (the common redraw case) skip the full line-breaking rebuild.
+    /// Published with volatile handoff; a concurrent race only duplicates deterministic work.
+    /// </summary>
+    private CachedTextLayout? cachedLayout;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="TextBlock"/> class.
     /// </summary>
@@ -67,10 +79,69 @@ public TextBlock(ReadOnlySpan<char> text, TextOptions options)
     /// <summary>
     /// Breaks this block into lines for the supplied wrapping length.
     /// </summary>
+    /// <remarks>
+    /// The result is retained for the most recent wrapping length, so repeated measurement and
+    /// rendering at one length share a single line-breaking pass.
+    /// </remarks>
     /// <param name="wrappingLength">The wrapping length in pixels. Use <c>-1</c> to disable wrapping.</param>
     /// <returns>The line-broken text box.</returns>
     internal TextBox BreakLines(float wrappingLength)
-        => TextLayout.BreakLines(this.LogicalLine, this.Options, wrappingLength);
+        => this.GetOrCreateLayout(wrappingLength).TextBox;
+
+    /// <summary>
+    /// Gets the retained layout for the supplied wrapping length, or line-breaks and retains a new one.
+    /// </summary>
+    /// <remarks>
+    /// The retained <see cref="TextBox"/> has its lazy aggregates computed before publication so
+    /// concurrent readers never mutate shared state after the handoff. Concurrent calls with
+    /// different wrapping lengths recompute deterministically; the last writer's layout stays
+    /// retained.
+    /// </remarks>
+    /// <param name="wrappingLength">The wrapping length in pixels. Use <c>-1</c> to disable wrapping.</param>
+    /// <returns>The layout for the supplied wrapping length.</returns>
+    private CachedTextLayout GetOrCreateLayout(float wrappingLength)
+    {
+        CachedTextLayout? cached = Volatile.Read(ref this.cachedLayout);
+        if (cached is not null && cached.WrappingLength == wrappingLength)
+        {
+            return cached;
+        }
+
+        TextBox textBox = TextLayout.BreakLines(this.LogicalLine, this.Options, wrappingLength);
+
+        // Compute the box's memoized aggregates now: after publication the box is shared across
+        // calls (and potentially threads), and lazy initialization on a shared instance would
+        // race. The aggregate methods throw on an empty line list, so guard that case.
+        if (textBox.TextLines.Count > 0)
+        {
+            _ = textBox.ScaledMaxAdvance();
+            _ = textBox.ScaledMinY();
+        }
+
+        _ = textBox.CountGlyphLayouts();
+
+        CachedTextLayout created = new(wrappingLength, textBox);
+        Volatile.Write(ref this.cachedLayout, created);
+        return created;
+    }
+
+    /// <summary>
+    /// Gets the rendered bounds for a retained layout, computing and publishing them on first use.
+    /// </summary>
+    /// <param name="layout">The retained layout.</param>
+    /// <param name="wrappingLength">The wrapping length the layout was produced for.</param>
+    /// <returns>The rendered glyph bounds.</returns>
+    private FontRectangle GetOrComputeBounds(CachedTextLayout layout, float wrappingLength)
+    {
+        if (layout.TryGetBounds(out FontRectangle bounds))
+        {
+            return bounds;
+        }
+
+        bounds = GetBounds(layout.TextBox, this.Options, wrappingLength);
+        layout.SetBounds(in bounds);
+        return bounds;
+    }
 
     /// <summary>
     /// Measures the full set of layout metrics for this block at the supplied wrapping length.
@@ -127,7 +198,10 @@ public FontRectangle MeasureAdvance(float wrappingLength)
     /// <param name="wrappingLength">The wrapping length in pixels. Use <c>-1</c> to disable wrapping.</param>
     /// <returns>The rendered glyph bounds.</returns>
     public FontRectangle MeasureBounds(float wrappingLength)
-        => GetBounds(this.BreakLines(wrappingLength), this.Options, wrappingLength);
+    {
+        CachedTextLayout layout = this.GetOrCreateLayout(wrappingLength);
+        return this.GetOrComputeBounds(layout, wrappingLength);
+    }
 
     /// <summary>
     /// Measures the union of logical advance and rendered glyph bounds at the supplied wrapping length.
@@ -136,10 +210,11 @@ public FontRectangle MeasureBounds(float wrappingLength)
     /// <returns>The full renderable bounds.</returns>
     public FontRectangle MeasureRenderableBounds(float wrappingLength)
     {
-        TextBox textBox = this.BreakLines(wrappingLength);
+        CachedTextLayout layout = this.GetOrCreateLayout(wrappingLength);
+        TextBox textBox = layout.TextBox;
         FontRectangle advance = GetAdvance(textBox, this.Options.Dpi, this.Options.LayoutMode.IsHorizontal());
         FontRectangle absoluteAdvance = new(this.Options.Origin.X, this.Options.Origin.Y, advance.Width, advance.Height);
-        FontRectangle bounds = GetBounds(textBox, this.Options, wrappingLength);
+        FontRectangle bounds = this.GetOrComputeBounds(layout, wrappingLength);
         return FontRectangle.Union(absoluteAdvance, bounds);
     }
 
@@ -279,10 +354,12 @@ private LineLayout[] GetLineLayouts(TextBox textBox, float wrappingLength)
     /// <param name="wrappingLength">The wrapping length in pixels. Use <c>-1</c> to disable wrapping.</param>
     public void RenderTo(IGlyphRenderer renderer, float wrappingLength)
     {
-        TextBox textBox = this.BreakLines(wrappingLength);
-        FontRectangle rect = GetBounds(textBox, this.Options, wrappingLength);
+        // Repeated rendering at one wrapping length reuses both the retained line-broken box and
+        // its rendered bounds, so a warm call performs exactly one layout pass.
+        CachedTextLayout layout = this.GetOrCreateLayout(wrappingLength);
+        FontRectangle rect = this.GetOrComputeBounds(layout, wrappingLength);
 
-        RenderTo(renderer, textBox, this.Options, wrappingLength, rect);
+        RenderTo(renderer, layout.TextBox, this.Options, wrappingLength, rect);
     }
 
     /// <summary>
@@ -603,4 +680,72 @@ private static FontRectangle GetAdvance(TextBox textBox, float dpi, bool isHoriz
 
         return new FontRectangle(0, 0, verticalWidth * dpi, verticalHeight * dpi);
     }
+
+    /// <summary>
+    /// Retains one line-broken layout and its lazily computed rendered bounds.
+    /// </summary>
+    private sealed class CachedTextLayout
+    {
+        /// <summary>
+        /// The rendered glyph bounds; valid only after <see cref="hasBounds"/> is set.
+        /// </summary>
+        private FontRectangle bounds;
+
+        /// <summary>
+        /// Release/acquire gate for <see cref="bounds"/>: the volatile write in
+        /// <see cref="SetBounds"/> publishes the fully written rectangle to readers.
+        /// </summary>
+        private volatile bool hasBounds;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CachedTextLayout"/> class.
+        /// </summary>
+        /// <param name="wrappingLength">The wrapping length the layout was produced for.</param>
+        /// <param name="textBox">The line-broken text box.</param>
+        public CachedTextLayout(float wrappingLength, TextBox textBox)
+        {
+            this.WrappingLength = wrappingLength;
+            this.TextBox = textBox;
+        }
+
+        /// <summary>
+        /// Gets the wrapping length the layout was produced for.
+        /// </summary>
+        public float WrappingLength { get; }
+
+        /// <summary>
+        /// Gets the line-broken text box.
+        /// </summary>
+        public TextBox TextBox { get; }
+
+        /// <summary>
+        /// Tries to read the previously published rendered bounds.
+        /// </summary>
+        /// <param name="value">Receives the rendered bounds when available.</param>
+        /// <returns><see langword="true"/> when bounds have been published.</returns>
+        public bool TryGetBounds(out FontRectangle value)
+        {
+            if (this.hasBounds)
+            {
+                value = this.bounds;
+                return true;
+            }
+
+            value = default;
+            return false;
+        }
+
+        /// <summary>
+        /// Publishes the rendered bounds for this layout.
+        /// </summary>
+        /// <param name="value">The rendered bounds.</param>
+        public void SetBounds(in FontRectangle value)
+        {
+            // The field write precedes the volatile flag write, so a reader observing the flag
+            // also observes the completed rectangle. Concurrent writers store the same
+            // deterministic value.
+            this.bounds = value;
+            this.hasBounds = true;
+        }
+    }
 }