Fix text culling and glyph subpixel batching

Adds translation-only matrix detection and uses it to derive visible text bounds from canvas state, enabling safe line culling for text while correctly disabling the fast path for non-translation transforms. Text composition commands now carry a dedicated sub-pixel offset (instead of embedding it into per-glyph drawing options transforms), and backend prep paths apply that offset consistently. The batcher also avoids rebuilding scene commands when brush transforms are effectively no-ops. New text tests cover offscreen culling, translated and rotated transforms, and text-block rendering parity against unculled output.

Author: JimBobSquarePants

src/ImageSharp.Drawing/Helpers/MatrixUtilities.cs

@@ -43,6 +43,20 @@ public static float GetAverageScale(in Matrix4x4 matrix)
     public static bool IsAffine(in Matrix4x4 matrix)
         => matrix.M14 == 0F && matrix.M24 == 0F && matrix.M34 == 0F && matrix.M44 == 1F;
 
+    /// <summary>
+    /// Returns a value indicating whether the matrix is a pure 2D translation: an identity
+    /// linear part with no perspective terms, so geometry moves by the M41 and M42 offsets
+    /// without any scale, rotation, or skew.
+    /// </summary>
+    /// <param name="matrix">The transformation matrix.</param>
+    /// <returns><see langword="true"/> when the matrix only translates; otherwise, <see langword="false"/>.</returns>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static bool IsTranslationOnly(in Matrix4x4 matrix)
+        => matrix.M11 == 1F && matrix.M12 == 0F && matrix.M13 == 0F && matrix.M14 == 0F &&
+           matrix.M21 == 0F && matrix.M22 == 1F && matrix.M23 == 0F && matrix.M24 == 0F &&
+           matrix.M31 == 0F && matrix.M32 == 0F && matrix.M33 == 1F && matrix.M34 == 0F &&
+           matrix.M44 == 1F;
+
     /// <summary>
     /// Returns a value indicating whether the matrix maps axis-aligned rectangles to axis-aligned rectangles.
     /// </summary>

src/ImageSharp.Drawing/Processing/Backends/CompositionCommand.cs

@@ -71,6 +71,7 @@ public readonly struct CompositionCommand
     /// <param name="clipDescriptor">The clip descriptor, or <see langword="null"/> for non begin-clip commands.</param>
     /// <param name="isInsideLayer">True if the command was recorded inside a layer.</param>
     /// <param name="applyBarrier">The apply barrier, or <see langword="null"/> for non-apply commands.</param>
+    /// <param name="subPixelOffset">The fractional translation composed into <see cref="Transform"/>.</param>
     private CompositionCommand(
         CompositionCommandKind kind,
         IPath? sourcePath,
@@ -83,7 +84,8 @@ private CompositionCommand(
         Point destinationOffset,
         DrawingClipDescriptor? clipDescriptor,
         bool isInsideLayer,
-        ApplyBarrier? applyBarrier)
+        ApplyBarrier? applyBarrier,
+        Vector2 subPixelOffset)
     {
         this.Kind = kind;
         this.sourcePath = sourcePath;
@@ -97,6 +99,7 @@ private CompositionCommand(
         this.clipDescriptor = clipDescriptor;
         this.IsInsideLayer = isInsideLayer;
         this.applyBarrier = applyBarrier;
+        this.SubPixelOffset = subPixelOffset;
     }
 
     /// <summary>
@@ -152,9 +155,31 @@ private CompositionCommand(
     public IPath SourcePath => this.sourcePath ?? throw new InvalidOperationException("Layer commands do not carry path geometry.");
 
     /// <summary>
-    /// Gets the command transform.
+    /// Gets the fractional translation applied after the drawing options transform. Glyph
+    /// geometry rides an integer destination offset; the sub-pixel remainder travels here so
+    /// the queued command does not need per-operation drawing options to carry it.
     /// </summary>
-    public Matrix4x4 Transform => this.drawingOptions?.Transform ?? Matrix4x4.Identity;
+    public Vector2 SubPixelOffset { get; }
+
+    /// <summary>
+    /// Gets the command transform: the drawing options transform followed by the sub-pixel
+    /// translation.
+    /// </summary>
+    public Matrix4x4 Transform
+    {
+        get
+        {
+            Matrix4x4 transform = this.drawingOptions?.Transform ?? Matrix4x4.Identity;
+            if (this.SubPixelOffset == Vector2.Zero)
+            {
+                return transform;
+            }
+
+            return transform.IsIdentity
+                ? Matrix4x4.CreateTranslation(this.SubPixelOffset.X, this.SubPixelOffset.Y, 0F)
+                : transform * Matrix4x4.CreateTranslation(this.SubPixelOffset.X, this.SubPixelOffset.Y, 0F);
+        }
+    }
 
     /// <summary>
     /// Gets the clip descriptor opened by a <see cref="CompositionCommandKind.BeginClip"/> command.
@@ -248,7 +273,8 @@ internal static CompositionCommand Create(
             destinationOffset,
             null,
             isInsideLayer,
-            null);
+            null,
+            Vector2.Zero);
 
     /// <summary>
     /// Creates a fill-path composition command with the owning layer state recorded by the canvas.
@@ -269,6 +295,38 @@ internal static CompositionCommand Create(
         Rectangle targetBounds,
         Point destinationOffset,
         DrawingCanvasLayer? layer)
+        => Create(
+            path,
+            brush,
+            drawingOptions,
+            in rasterizerOptions,
+            targetBounds,
+            destinationOffset,
+            layer,
+            Vector2.Zero);
+
+    /// <summary>
+    /// Creates a fill-path composition command carrying a sub-pixel translation alongside the
+    /// owning layer state recorded by the canvas.
+    /// </summary>
+    /// <param name="path">Path in target-local coordinates.</param>
+    /// <param name="brush">Brush used during composition.</param>
+    /// <param name="drawingOptions">Drawing options (graphics, shape, transform) used during composition.</param>
+    /// <param name="rasterizerOptions">Rasterizer options used to generate coverage.</param>
+    /// <param name="targetBounds">The absolute bounds of the logical target for this command.</param>
+    /// <param name="destinationOffset">Absolute destination offset where coverage is composited.</param>
+    /// <param name="layer">The layer that owned this command when it was recorded.</param>
+    /// <param name="subPixelOffset">The fractional translation composed into <see cref="Transform"/>.</param>
+    /// <returns>The composition command.</returns>
+    internal static CompositionCommand Create(
+        IPath path,
+        Brush brush,
+        DrawingOptions drawingOptions,
+        in RasterizerOptions rasterizerOptions,
+        Rectangle targetBounds,
+        Point destinationOffset,
+        DrawingCanvasLayer? layer,
+        Vector2 subPixelOffset)
         => new(
             CompositionCommandKind.FillLayer,
             path,
@@ -281,7 +339,8 @@ internal static CompositionCommand Create(
             destinationOffset,
             null,
             layer is not null,
-            null);
+            null,
+            subPixelOffset);
 
     /// <summary>
     /// Creates a begin-layer composition command with shared layer state.
@@ -304,7 +363,8 @@ internal static CompositionCommand CreateBeginLayer(
             default,
             null,
             false,
-            null);
+            null,
+            Vector2.Zero);
 
     /// <summary>
     /// Creates an end-layer composition command with shared layer state.
@@ -325,7 +385,8 @@ internal static CompositionCommand CreateEndLayer(Rectangle layerBounds, Drawing
             default,
             null,
             false,
-            null);
+            null,
+            Vector2.Zero);
 
     /// <summary>
     /// Creates a begin-clip composition command.
@@ -346,7 +407,8 @@ internal static CompositionCommand CreateBeginClip(DrawingClipDescriptor descrip
             destinationOffset,
             descriptor,
             false,
-            null);
+            null,
+            Vector2.Zero);
 
     /// <summary>
     /// Creates an end-clip composition command.
@@ -365,7 +427,8 @@ internal static CompositionCommand CreateEndClip()
             default,
             null,
             false,
-            null);
+            null,
+            Vector2.Zero);
 
     /// <summary>
     /// Creates an apply composition command.
@@ -422,7 +485,8 @@ private static CompositionCommand CreateApply(
             barrier.DestinationOffset,
             null,
             barrier.IsInsideLayer,
-            barrier);
+            barrier,
+            Vector2.Zero);
     }
 
     /// <summary>

src/ImageSharp.Drawing/Processing/Backends/FlushScene.cs

@@ -1006,6 +1006,7 @@ private static void ProcessPathCommand(
                     command.RasterizerOptions,
                     command.TargetBounds,
                     command.DestinationOffset,
+                    command.SubPixelOffset,
                     allocator,
                     out PreparedFillItem preparedApply))
             {
@@ -1364,6 +1365,7 @@ private static bool TryPrepareFillPath(
             command.RasterizerOptions,
             command.TargetBounds,
             command.DestinationOffset,
+            command.SubPixelOffset,
             allocator,
             out prepared);
 
@@ -1378,6 +1380,7 @@ private static bool TryPrepareFillPath(
     /// <param name="sourceRasterizerOptions">The rasterizer options recorded with the command.</param>
     /// <param name="targetBounds">The destination bounds of the flush.</param>
     /// <param name="destinationOffset">The offset from path-local to destination coordinates.</param>
+    /// <param name="subPixelOffset">The fractional translation applied after the drawing options transform.</param>
     /// <param name="allocator">The allocator used for retained raster storage.</param>
     /// <param name="prepared">The prepared fill payload when successful.</param>
     /// <returns><see langword="true"/> when the fill intersects the target and rasterizable geometry was created; otherwise <see langword="false"/>.</returns>
@@ -1388,10 +1391,21 @@ internal static bool TryPrepareFillPath(
         in RasterizerOptions sourceRasterizerOptions,
         Rectangle targetBounds,
         Point destinationOffset,
+        Vector2 subPixelOffset,
         MemoryAllocator allocator,
         out PreparedFillItem prepared)
     {
         Matrix4x4 transform = drawingOptions.Transform;
+        if (subPixelOffset != Vector2.Zero)
+        {
+            // The sub-pixel remainder is a device-space nudge applied after the recorded
+            // transform, mirroring CompositionCommand.Transform for callers that receive the
+            // options and offset separately.
+            transform = transform.IsIdentity
+                ? Matrix4x4.CreateTranslation(subPixelOffset.X, subPixelOffset.Y, 0F)
+                : transform * Matrix4x4.CreateTranslation(subPixelOffset.X, subPixelOffset.Y, 0F);
+        }
+
         Vector2 scale = MatrixUtilities.GetScale(transform);
         Matrix4x4 residual = MatrixUtilities.GetResidual(scale, transform);
         LinearGeometry geometry = path.ToLinearGeometry(scale);

src/ImageSharp.Drawing/Processing/Backends/StrokePathCommand.cs

@@ -73,6 +73,45 @@ internal StrokePathCommand(
         Pen pen,
         bool isInsideLayer,
         DrawingCanvasLayer? ownerLayer)
+        : this(
+            sourcePath,
+            brush,
+            drawingOptions,
+            in rasterizerOptions,
+            targetBounds,
+            destinationOffset,
+            pen,
+            isInsideLayer,
+            ownerLayer,
+            Vector2.Zero)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="StrokePathCommand"/> struct carrying a
+    /// sub-pixel translation alongside the owning layer state recorded by the canvas.
+    /// </summary>
+    /// <param name="sourcePath">The source stroke path.</param>
+    /// <param name="brush">The brush used to shade the stroke.</param>
+    /// <param name="drawingOptions">The drawing options (graphics, shape, transform) used during composition.</param>
+    /// <param name="rasterizerOptions">The rasterizer options used to generate coverage.</param>
+    /// <param name="targetBounds">The absolute bounds of the logical target.</param>
+    /// <param name="destinationOffset">The absolute destination offset of the command.</param>
+    /// <param name="pen">The stroke metadata.</param>
+    /// <param name="isInsideLayer">True if the command was recorded inside a layer.</param>
+    /// <param name="ownerLayer">The layer that owned this command when it was recorded.</param>
+    /// <param name="subPixelOffset">The fractional translation composed into <see cref="Transform"/>.</param>
+    internal StrokePathCommand(
+        IPath sourcePath,
+        Brush brush,
+        DrawingOptions drawingOptions,
+        in RasterizerOptions rasterizerOptions,
+        Rectangle targetBounds,
+        Point destinationOffset,
+        Pen pen,
+        bool isInsideLayer,
+        DrawingCanvasLayer? ownerLayer,
+        Vector2 subPixelOffset)
     {
         this.sourcePath = sourcePath;
         this.drawingOptions = drawingOptions;
@@ -83,6 +122,7 @@ internal StrokePathCommand(
         this.DestinationOffset = destinationOffset;
         this.Pen = pen;
         this.IsInsideLayer = isInsideLayer;
+        this.SubPixelOffset = subPixelOffset;
     }
 
     /// <summary>
@@ -126,9 +166,31 @@ internal StrokePathCommand(
     public IPath SourcePath => this.sourcePath;
 
     /// <summary>
-    /// Gets the drawing transform.
+    /// Gets the fractional translation applied after the drawing options transform. Glyph
+    /// geometry rides an integer destination offset; the sub-pixel remainder travels here so
+    /// the queued command does not need per-operation drawing options to carry it.
     /// </summary>
-    public Matrix4x4 Transform => this.drawingOptions.Transform;
+    public Vector2 SubPixelOffset { get; }
+
+    /// <summary>
+    /// Gets the drawing transform: the drawing options transform followed by the sub-pixel
+    /// translation.
+    /// </summary>
+    public Matrix4x4 Transform
+    {
+        get
+        {
+            Matrix4x4 transform = this.drawingOptions.Transform;
+            if (this.SubPixelOffset == Vector2.Zero)
+            {
+                return transform;
+            }
+
+            return transform.IsIdentity
+                ? Matrix4x4.CreateTranslation(this.SubPixelOffset.X, this.SubPixelOffset.Y, 0F)
+                : transform * Matrix4x4.CreateTranslation(this.SubPixelOffset.X, this.SubPixelOffset.Y, 0F);
+        }
+    }
 
     /// <summary>
     /// Gets a value indicating whether the command was recorded inside a layer.