Make DrawingCanvas factory internal and update tests

Author: JimBobSquarePants

src/ImageSharp.Drawing/Processing/DRAWING_CANVAS.md

@@ -59,8 +59,7 @@ Before looking at the flow, it helps to define the major terms in the sense used
 
 It is not the rasterizer. It is the object that makes the public drawing model coherent.
 
-Most callers reach that model through `IImageProcessingContext.Paint(...)`, while lower-level code can
-also create a canvas directly with the `CreateCanvas(...)` extension methods.
+Callers reach that model through `IImageProcessingContext.Paint(...)`.
 
 `DrawingCanvas<TPixel>` is the typed implementation that carries the target pixel format for brush normalization,
 readback, and backend execution. Factory methods return `DrawingCanvas` so CPU and GPU entry points expose the same
@@ -107,9 +106,8 @@ There are two backend-selection paths in the architecture:
 - direct `DrawingCanvas<TPixel>` construction resolves the backend from `Configuration`
 - specialized infrastructure can construct a canvas with an explicit backend
 
-The ordinary CPU entry points include `Paint(...)` on `IImageProcessingContext` and the `CreateCanvas(...)`
-extension methods on `Image`, `Image<TPixel>`, and `ImageFrame<TPixel>`. Those factories return `DrawingCanvas`
-and route into the typed implementation internally.
+The ordinary CPU entry point is `Paint(...)` on `IImageProcessingContext`, which routes into the typed
+implementation internally.
 
 That explicit-backend path matters for the WebGPU helpers. `WebGPUWindow<TPixel>`, `WebGPURenderTarget<TPixel>`, and `WebGPUDeviceContext<TPixel>` create canvases that point directly at their owned `WebGPUDrawingBackend` instance instead of storing that backend on the caller's `Configuration`.
 

src/ImageSharp.Drawing/Processing/DrawingCanvasFactoryExtensions.cs

@@ -1,109 +1,15 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
 
-using System.Diagnostics.CodeAnalysis;
-using SixLabors.ImageSharp.Advanced;
 using SixLabors.ImageSharp.Memory;
 
 namespace SixLabors.ImageSharp.Drawing.Processing;
 
 /// <summary>
 /// Convenience extension methods for creating drawing canvas instances from ImageSharp image types.
 /// </summary>
-public static class DrawingCanvasFactoryExtensions
+internal static class DrawingCanvasFactoryExtensions
 {
-    /// <summary>
-    /// Creates a drawing canvas over a specific frame of an image whose pixel type is known only at runtime.
-    /// </summary>
-    /// <param name="image">The image containing the frame.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="frameIndex">The zero-based frame index to target.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the selected frame.</returns>
-    public static DrawingCanvas CreateCanvas(
-        this Image image,
-        DrawingOptions options,
-        int frameIndex,
-        params IPath[] clipPaths)
-        => CreateCanvas(image, image.Configuration, options, frameIndex, clipPaths);
-
-    /// <summary>
-    /// Creates a drawing canvas over a specific frame of an image whose pixel type is known only at runtime.
-    /// </summary>
-    /// <param name="image">The image containing the frame.</param>
-    /// <param name="configuration">The configuration to use for this canvas instance.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="frameIndex">The zero-based frame index to target.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the selected frame.</returns>
-    public static DrawingCanvas CreateCanvas(
-        this Image image,
-        Configuration configuration,
-        DrawingOptions options,
-        int frameIndex,
-        params IPath[] clipPaths)
-    {
-        Guard.NotNull(image, nameof(image));
-        Guard.NotNull(options, nameof(options));
-        Guard.NotNull(clipPaths, nameof(clipPaths));
-        Guard.MustBeBetweenOrEqualTo(frameIndex, 0, image.Frames.Count - 1, nameof(frameIndex));
-
-        CreateCanvasVisitor visitor = new(configuration, options, frameIndex, clipPaths);
-        image.AcceptVisitor(visitor);
-        return visitor.Canvas!;
-    }
-
-    /// <summary>
-    /// Creates a drawing canvas over the root frame of an image whose pixel type is known only at runtime.
-    /// </summary>
-    /// <param name="image">The image whose root frame should be targeted.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the root frame.</returns>
-    public static DrawingCanvas CreateCanvas(
-        this Image image,
-        DrawingOptions options,
-        params IPath[] clipPaths)
-        => CreateCanvas(image, image.Configuration, options, clipPaths);
-
-    /// <summary>
-    /// Creates a drawing canvas over the root frame of an image whose pixel type is known only at runtime.
-    /// </summary>
-    /// <param name="image">The image whose root frame should be targeted.</param>
-    /// <param name="configuration">The configuration to use for this canvas instance.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the root frame.</returns>
-    public static DrawingCanvas CreateCanvas(
-        this Image image,
-        Configuration configuration,
-        DrawingOptions options,
-        params IPath[] clipPaths)
-    {
-        Guard.NotNull(image, nameof(image));
-        Guard.NotNull(options, nameof(options));
-        Guard.NotNull(clipPaths, nameof(clipPaths));
-
-        CreateCanvasVisitor visitor = new(configuration, options, frameIndex: 0, clipPaths);
-        image.AcceptVisitor(visitor);
-        return visitor.Canvas!;
-    }
-
-    /// <summary>
-    /// Creates a drawing canvas over an existing frame.
-    /// </summary>
-    /// <typeparam name="TPixel">The pixel format.</typeparam>
-    /// <param name="frame">The frame backing the canvas.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting <paramref name="frame"/>.</returns>
-    public static DrawingCanvas CreateCanvas<TPixel>(
-        this ImageFrame<TPixel> frame,
-        DrawingOptions options,
-        params IPath[] clipPaths)
-        where TPixel : unmanaged, IPixel<TPixel>
-        => CreateCanvas(frame, frame.Configuration, options, clipPaths);
-
     /// <summary>
     /// Creates a drawing canvas over an existing frame.
     /// </summary>
@@ -113,7 +19,7 @@ public static DrawingCanvas CreateCanvas<TPixel>(
     /// <param name="options">Initial drawing options for this canvas instance.</param>
     /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
     /// <returns>A drawing canvas targeting <paramref name="frame"/>.</returns>
-    public static DrawingCanvas CreateCanvas<TPixel>(
+    internal static DrawingCanvas CreateCanvas<TPixel>(
         this ImageFrame<TPixel> frame,
         Configuration configuration,
         DrawingOptions options,
@@ -130,116 +36,4 @@ public static DrawingCanvas CreateCanvas<TPixel>(
             new Buffer2DRegion<TPixel>(frame.PixelBuffer),
             clipPaths);
     }
-
-    /// <summary>
-    /// Creates a drawing canvas over a specific frame of an image.
-    /// </summary>
-    /// <typeparam name="TPixel">The pixel format.</typeparam>
-    /// <param name="image">The image containing the frame.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="frameIndex">The zero-based frame index to target.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the selected frame.</returns>
-    public static DrawingCanvas CreateCanvas<TPixel>(
-        this Image<TPixel> image,
-        DrawingOptions options,
-        int frameIndex,
-        params IPath[] clipPaths)
-        where TPixel : unmanaged, IPixel<TPixel>
-        => CreateCanvas(image, image.Configuration, options, frameIndex, clipPaths);
-
-    /// <summary>
-    /// Creates a drawing canvas over a specific frame of an image.
-    /// </summary>
-    /// <typeparam name="TPixel">The pixel format.</typeparam>
-    /// <param name="image">The image containing the frame.</param>
-    /// <param name="configuration">The configuration to use for this canvas instance.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="frameIndex">The zero-based frame index to target.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the selected frame.</returns>
-    public static DrawingCanvas CreateCanvas<TPixel>(
-        this Image<TPixel> image,
-        Configuration configuration,
-        DrawingOptions options,
-        int frameIndex,
-        params IPath[] clipPaths)
-        where TPixel : unmanaged, IPixel<TPixel>
-    {
-        Guard.NotNull(image, nameof(image));
-        Guard.NotNull(options, nameof(options));
-        Guard.NotNull(clipPaths, nameof(clipPaths));
-        Guard.MustBeBetweenOrEqualTo(frameIndex, 0, image.Frames.Count - 1, nameof(frameIndex));
-
-        return image.Frames[frameIndex].CreateCanvas(configuration, options, clipPaths);
-    }
-
-    /// <summary>
-    /// Creates a drawing canvas over the root frame of an image.
-    /// </summary>
-    /// <typeparam name="TPixel">The pixel format.</typeparam>
-    /// <param name="image">The image whose root frame should be targeted.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the root frame.</returns>
-    public static DrawingCanvas CreateCanvas<TPixel>(
-        this Image<TPixel> image,
-        DrawingOptions options,
-        params IPath[] clipPaths)
-        where TPixel : unmanaged, IPixel<TPixel>
-        => CreateCanvas(image, image.Configuration, options, clipPaths);
-
-    /// <summary>
-    /// Creates a drawing canvas over the root frame of an image.
-    /// </summary>
-    /// <typeparam name="TPixel">The pixel format.</typeparam>
-    /// <param name="image">The image whose root frame should be targeted.</param>
-    /// <param name="configuration">The configuration to use for this canvas instance.</param>
-    /// <param name="options">Initial drawing options for this canvas instance.</param>
-    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
-    /// <returns>A drawing canvas targeting the root frame.</returns>
-    public static DrawingCanvas CreateCanvas<TPixel>(
-        this Image<TPixel> image,
-        Configuration configuration,
-        DrawingOptions options,
-        params IPath[] clipPaths)
-        where TPixel : unmanaged, IPixel<TPixel>
-    {
-        Guard.NotNull(image, nameof(image));
-        Guard.NotNull(options, nameof(options));
-        Guard.NotNull(clipPaths, nameof(clipPaths));
-
-        return image.Frames.RootFrame.CreateCanvas(configuration, options, clipPaths);
-    }
-
-    private sealed class CreateCanvasVisitor : IImageVisitor
-    {
-        private readonly Configuration configuration;
-        private readonly DrawingOptions options;
-        private readonly int frameIndex;
-        private readonly IPath[] clipPaths;
-
-        public CreateCanvasVisitor(
-            Configuration configuration,
-            DrawingOptions options,
-            int frameIndex,
-            IPath[] clipPaths)
-        {
-            this.configuration = configuration;
-            this.options = options;
-            this.frameIndex = frameIndex;
-            this.clipPaths = clipPaths;
-        }
-
-        public DrawingCanvas? Canvas { get; private set; }
-
-        [MemberNotNull(nameof(Canvas))]
-        public void Visit<TPixel>(Image<TPixel> image)
-            where TPixel : unmanaged, IPixel<TPixel>
-            => this.Canvas = image.CreateCanvas(
-                this.configuration,
-                this.options,
-                this.frameIndex,
-                this.clipPaths);
-    }
 }

tests/ImageSharp.Drawing.Benchmarks/Drawing/DrawTextRepeatedGlyphs.cs

@@ -6,6 +6,7 @@
 using SixLabors.ImageSharp.Drawing.Processing;
 using SixLabors.ImageSharp.Drawing.Processing.Backends;
 using SixLabors.ImageSharp.PixelFormats;
+using SixLabors.ImageSharp.Processing;
 
 namespace SixLabors.ImageSharp.Drawing.Benchmarks.Drawing;
 
@@ -68,9 +69,9 @@ public void Cleanup()
     [Benchmark(Baseline = true, Description = "DrawingCanvas Default Backend")]
     public void DrawingCanvasDefaultBackend()
     {
-        using DrawingCanvas canvas = this.defaultImage.CreateCanvas(this.drawingOptions);
-        canvas.DrawText(this.textOptions, this.text, this.brush, null);
-        canvas.Flush();
+        this.defaultImage.Mutate(c => c.Paint(
+            this.drawingOptions,
+            canvas => canvas.DrawText(this.textOptions, this.text, this.brush, null)));
     }
 
     [Benchmark(Description = "DrawingCanvas WebGPU Backend (NativeSurface)")]

tests/ImageSharp.Drawing.Tests/Processing/Backends/WebGPUDrawingBackendTests.cs

@@ -619,36 +619,26 @@ public void DrawText_WithRepeatedGlyphs_AfterClear_UsesBlendFastPath<TPixel>(Tes
         string text = new('A', glyphCount);
         Brush drawBrush = Brushes.Solid(Color.HotPink);
         Brush clearBrush = Brushes.Solid(Color.White);
-        using Image<TPixel> defaultImage = provider.GetImage();
-        using (DrawingCanvas defaultClearCanvas = defaultImage.CreateCanvas(Configuration.Default, clearOptions))
+        void DrawAction(DrawingCanvas canvas)
         {
-            defaultClearCanvas.Fill(clearBrush);
-            defaultClearCanvas.Flush();
+            canvas.Fill(clearBrush);
+            canvas.Flush();
+            canvas.Save(drawingOptions);
+            canvas.DrawText(textOptions, text, drawBrush, null);
+            canvas.Restore();
         }
 
-        using (DrawingCanvas defaultDrawCanvas = defaultImage.CreateCanvas(Configuration.Default, drawingOptions))
-        {
-            defaultDrawCanvas.DrawText(textOptions, text, drawBrush, null);
-            defaultDrawCanvas.Flush();
-        }
+        using Image<TPixel> defaultImage = provider.GetImage();
+        defaultImage.Mutate(c => c.Paint(clearOptions, DrawAction));
 
         using WebGPUDrawingBackend nativeSurfaceBackend = new();
         using WebGPURenderTarget<TPixel> renderTarget = new(defaultImage.Width, defaultImage.Height);
         Configuration nativeSurfaceConfiguration = Configuration.Default.Clone();
         nativeSurfaceConfiguration.SetDrawingBackend(nativeSurfaceBackend);
 
-        using (DrawingCanvas<TPixel> nativeSurfaceClearCanvas =
-               new(nativeSurfaceConfiguration, clearOptions, nativeSurfaceBackend, renderTarget.NativeFrame))
+        using (DrawingCanvas<TPixel> nativeSurfaceCanvas = new(nativeSurfaceConfiguration, clearOptions, nativeSurfaceBackend, renderTarget.NativeFrame))
         {
-            nativeSurfaceClearCanvas.Fill(clearBrush);
-            nativeSurfaceClearCanvas.Flush();
-        }
-
-        using (DrawingCanvas<TPixel> nativeSurfaceDrawCanvas =
-               new(nativeSurfaceConfiguration, drawingOptions, nativeSurfaceBackend, renderTarget.NativeFrame))
-        {
-            nativeSurfaceDrawCanvas.DrawText(textOptions, text, drawBrush, null);
-            nativeSurfaceDrawCanvas.Flush();
+            DrawAction(nativeSurfaceCanvas);
         }
 
         using Image<TPixel> nativeSurfaceImage = renderTarget.Readback();
@@ -657,13 +647,8 @@ public void DrawText_WithRepeatedGlyphs_AfterClear_UsesBlendFastPath<TPixel>(Tes
         AssertBackendPairReferenceOutputs(provider, "RepeatedGlyphs_AfterClear", defaultImage, nativeSurfaceImage);
     }
 
-    private static void RenderWithDefaultBackend<TPixel>(Image<TPixel> image, DrawingOptions options, Action<DrawingCanvas> drawAction)
-        where TPixel : unmanaged, IPixel<TPixel>
-    {
-        using DrawingCanvas canvas = image.CreateCanvas(Configuration.Default, options);
-        drawAction(canvas);
-        canvas.Flush();
-    }
+    private static void RenderWithDefaultBackend<TPixel>(Image<TPixel> image, DrawingOptions options, CanvasAction drawAction)
+        where TPixel : unmanaged, IPixel<TPixel> => image.Mutate(c => c.Paint(options, drawAction));
 
     private static IPath CreateLargeSceneDenseRectangleGridPath()
     {
@@ -1307,40 +1292,25 @@ public void MultipleFlushes_OnSameBackend_ProduceCorrectResults<TPixel>(TestImag
         Brush blueBrush = Brushes.Solid(Color.Blue);
         RectangularPolygon rect1 = new(20, 20, 120, 80);
         RectangularPolygon rect2 = new(160, 100, 120, 80);
-
-        // Default backend: two separate flushes.
-        using Image<TPixel> defaultImage = provider.GetImage();
-        using (DrawingCanvas canvas1 = defaultImage.CreateCanvas(Configuration.Default, drawingOptions))
+        void DrawAction(DrawingCanvas canvas)
         {
-            canvas1.Fill(redBrush, rect1);
-            canvas1.Flush();
+            canvas.Clear(Brushes.Solid(Color.White));
+            canvas.Fill(redBrush, rect1);
+            canvas.Flush();
+            canvas.Fill(blueBrush, rect2);
         }
 
-        using (DrawingCanvas canvas2 = defaultImage.CreateCanvas(Configuration.Default, drawingOptions))
-        {
-            canvas2.Fill(blueBrush, rect2);
-            canvas2.Flush();
-        }
+        using Image<TPixel> defaultImage = provider.GetImage();
+        defaultImage.Mutate(c => c.Paint(drawingOptions, DrawAction));
 
-        // Native surface: two separate flushes reusing same backend.
         using WebGPUDrawingBackend nativeSurfaceBackend = new();
         using WebGPURenderTarget<TPixel> renderTarget = new(defaultImage.Width, defaultImage.Height);
         Configuration nativeConfig = Configuration.Default.Clone();
         nativeConfig.SetDrawingBackend(nativeSurfaceBackend);
 
-        using (DrawingCanvas<TPixel> canvas1 =
-               new(nativeConfig, drawingOptions, nativeSurfaceBackend, renderTarget.NativeFrame))
-        {
-            canvas1.Clear(Brushes.Solid(Color.White));
-            canvas1.Fill(redBrush, rect1);
-            canvas1.Flush();
-        }
-
-        using (DrawingCanvas<TPixel> canvas2 =
-               new(nativeConfig, drawingOptions, nativeSurfaceBackend, renderTarget.NativeFrame))
+        using (DrawingCanvas<TPixel> canvas = new(nativeConfig, drawingOptions, nativeSurfaceBackend, renderTarget.NativeFrame))
         {
-            canvas2.Fill(blueBrush, rect2);
-            canvas2.Flush();
+            DrawAction(canvas);
         }
 
         using Image<TPixel> nativeSurfaceImage = renderTarget.Readback();