Add ReadbackImage API and Buffer2DRegion usage

Author: JimBobSquarePants

samples/DrawingBackendBenchmark/WebGpuBenchmarkBackend.cs

@@ -60,7 +60,7 @@ public BenchmarkRenderResult Render(ReadOnlySpan<VisualLine> lines, int width, i
         {
             try
             {
-                preview = renderTarget.Readback<Bgra32>();
+                preview = renderTarget.ReadbackImage<Bgra32>();
             }
             catch (Exception ex)
             {

src/ImageSharp.Drawing.WebGPU/WebGPUFlushContext.cs

@@ -550,7 +550,7 @@ internal static void UploadTextureFromRegion<TPixel>(
             // Only use the direct path when the stride satisfies WebGPU's alignment requirement.
             if ((uint)sourceStrideBytes == alignedRowBytes && directByteCount <= packedByteCountEstimate * 2)
             {
-                int startPixelIndex = checked((sourceRegion.Rectangle.Y * sourceRegion.Buffer.RowStride) + sourceRegion.Rectangle.X);
+                int startPixelIndex = checked((sourceRegion.Bounds.Y * sourceRegion.Buffer.RowStride) + sourceRegion.Bounds.X);
                 int startByteOffset = checked(startPixelIndex * pixelSizeInBytes);
                 int uploadByteCount = checked((int)directByteCount);
                 nuint uploadByteCountNuint = checked((nuint)uploadByteCount);

src/ImageSharp.Drawing.WebGPU/WebGPURenderTarget.cs

@@ -119,7 +119,7 @@ private WebGPURenderTarget(
 
     /// <summary>
     /// Gets the native surface backing this render target.
-    /// Most callers should use <see cref="CreateCanvas()"/> or <see cref="Readback{TPixel}"/> instead.
+    /// Most callers should use <see cref="CreateCanvas()"/> or <see cref="ReadbackImage()"/> instead.
     /// </summary>
     internal NativeSurface Surface { get; }
 
@@ -179,12 +179,27 @@ public DrawingCanvas CreateCanvas(DrawingOptions options)
             this.Format);
     }
 
+    /// <summary>
+    /// Reads the current GPU texture contents back into a new CPU image.
+    /// </summary>
+    /// <returns>The readback image.</returns>
+    public Image ReadbackImage()
+#pragma warning disable CS8524
+        => this.Format switch
+        {
+            WebGPUTextureFormat.Rgba8Unorm => this.ReadbackImage<Rgba32>(),
+            WebGPUTextureFormat.Bgra8Unorm => this.ReadbackImage<Bgra32>(),
+            WebGPUTextureFormat.Rgba8Snorm => this.ReadbackImage<NormalizedByte4>(),
+            WebGPUTextureFormat.Rgba16Float => this.ReadbackImage<HalfVector4>()
+        };
+#pragma warning restore CS8524
+
     /// <summary>
     /// Reads the current GPU texture contents back into a new CPU image.
     /// </summary>
     /// <typeparam name="TPixel">The destination image pixel format.</typeparam>
     /// <returns>The readback image.</returns>
-    public Image<TPixel> Readback<TPixel>()
+    public Image<TPixel> ReadbackImage<TPixel>()
         where TPixel : unmanaged, IPixel<TPixel>
     {
         this.ThrowIfDisposed();
@@ -193,7 +208,8 @@ public Image<TPixel> Readback<TPixel>()
         Image<TPixel> image = new(this.Width, this.Height);
         try
         {
-            this.ReadbackInto(image);
+            this.ReadbackInto(image.Frames.RootFrame.PixelBuffer.GetRegion());
+
             return image;
         }
         catch
@@ -204,33 +220,31 @@ public Image<TPixel> Readback<TPixel>()
     }
 
     /// <summary>
-    /// Reads the current GPU texture contents back into an existing CPU image.
+    /// Reads the current GPU texture contents back into an existing CPU buffer region.
     /// </summary>
     /// <typeparam name="TPixel">The destination image pixel format.</typeparam>
-    /// <param name="destination">The destination image that receives the readback pixels.</param>
-    public void ReadbackInto<TPixel>(Image<TPixel> destination)
+    /// <param name="destination">The destination buffer region that receives the readback pixels.</param>
+    public void ReadbackInto<TPixel>(Buffer2DRegion<TPixel> destination)
         where TPixel : unmanaged, IPixel<TPixel>
     {
-        Guard.NotNull(destination, nameof(destination));
         this.ThrowIfDisposed();
         this.deviceContext.ThrowIfDisposed();
 
-        if (destination.Width != this.Width || destination.Height != this.Height)
-        {
-            throw new ArgumentException(
-                $"Destination image dimensions ({destination.Width}x{destination.Height}) must match render target dimensions ({this.Width}x{this.Height}).",
-                nameof(destination));
-        }
-
         NativeCanvasFrame<TPixel> frame = WebGPUCanvasFactory.CreateFrame<TPixel>(this.Bounds, this.Surface);
 
+        // A smaller destination region intentionally reads the matching top-left
+        // portion of the render target instead of forcing an intermediate full-size image.
+        int readbackWidth = Math.Min(this.Width, destination.Width);
+        int readbackHeight = Math.Min(this.Height, destination.Height);
+        Rectangle sourceRectangle = new(0, 0, readbackWidth, readbackHeight);
+
         // ReadRegion owns the pixel-format check because it is the point where
         // typed CPU pixels are copied from the native WebGPU texture.
         this.deviceContext.Backend.ReadRegion(
             this.deviceContext.Configuration,
             frame,
-            new Rectangle(0, 0, this.Width, this.Height),
-            new Buffer2DRegion<TPixel>(destination.Frames.RootFrame.PixelBuffer));
+            sourceRectangle,
+            destination);
     }
 
     /// <summary>

src/ImageSharp.Drawing/ImageSharp.Drawing.csproj

@@ -41,7 +41,7 @@
   </ItemGroup>
   <ItemGroup>
     <PackageReference Include="SixLabors.Fonts" Version="3.0.0-alpha.0.43" />
-    <PackageReference Include="SixLabors.ImageSharp" Version="4.0.0-alpha.0.102" />
+    <PackageReference Include="SixLabors.ImageSharp" Version="4.0.0-alpha.0.103" />
     <PackageReference Include="SixLabors.PolygonClipper" Version="1.0.0-alpha.0.55" />
   </ItemGroup>
 

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

@@ -114,7 +114,7 @@ internal ApplyBarrier(
                 configuration,
                 target,
                 sourceRect,
-                new Buffer2DRegion<TPixel>(sourceImage.Frames.RootFrame.PixelBuffer));
+                sourceImage.Frames.RootFrame.PixelBuffer.GetRegion());
 
             sourceImage.Mutate(this.Operation);
 

src/ImageSharp.Drawing/Processing/Backends/DefaultDrawingBackend.Helpers.cs

@@ -102,7 +102,7 @@ public BandTarget(Buffer2DRegion<TPixel> region, int absoluteLeft, int absoluteT
         public BandTarget(Buffer2D<TPixel> owner, Rectangle bounds, GraphicsOptions? graphicsOptions)
         {
             this.owner = owner;
-            this.Region = new Buffer2DRegion<TPixel>(owner);
+            this.Region = owner.GetRegion();
             this.AbsoluteLeft = bounds.X;
             this.AbsoluteTop = bounds.Y;
             this.GraphicsOptions = graphicsOptions;

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

@@ -135,7 +135,7 @@ private static void ExecuteSceneRow<TPixel>(
         where TPixel : unmanaged, IPixel<TPixel>
     {
         int bandTop = row.RowBandIndex * DefaultRasterizer.DefaultTileHeight;
-        int localBandTop = bandTop - destinationFrame.Rectangle.Y;
+        int localBandTop = bandTop - destinationFrame.Bounds.Y;
         int bandHeight = Math.Min(DefaultRasterizer.DefaultTileHeight, destinationFrame.Height - localBandTop);
         if (bandHeight <= 0)
         {
@@ -145,7 +145,7 @@ private static void ExecuteSceneRow<TPixel>(
         Buffer2DRegion<TPixel> destinationBand = destinationFrame.GetSubRegion(0, localBandTop, destinationFrame.Width, bandHeight);
         BandTarget<TPixel>[] targetStack = state.TargetStack;
         int targetCount = 1;
-        targetStack[0] = new BandTarget<TPixel>(destinationBand, destinationFrame.Rectangle.X, bandTop, null);
+        targetStack[0] = new BandTarget<TPixel>(destinationBand, destinationFrame.Bounds.X, bandTop, null);
         int scratchWidth = GetRowScratchWidth(scene, row, destinationFrame.Width);
         DefaultRasterizer.WorkerScratch scratch = state.GetOrCreateScratch(scratchWidth);
 

src/ImageSharp.Drawing/Processing/Backends/MemoryCanvasFrame{TPixel}.cs

@@ -26,7 +26,7 @@ public MemoryCanvasFrame(Buffer2DRegion<TPixel> region)
     }
 
     /// <inheritdoc />
-    public Rectangle Bounds => this.region.Rectangle;
+    public Rectangle Bounds => this.region.Bounds;
 
     /// <inheritdoc />
     public bool TryGetCpuRegion(out Buffer2DRegion<TPixel> region)

src/ImageSharp.Drawing/Processing/DRAWING_CANVAS.md

@@ -59,7 +59,9 @@ 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.
 
-Callers reach that model through `IImageProcessingContext.Paint(...)`.
+Callers usually reach that model through `IImageProcessingContext.Paint(...)`.
+
+When callers already have an `ImageFrame` or `ImageFrame<TPixel>`, the public `CreateCanvas(...)` frame extensions create a canvas directly over that frame. The caller owns the returned canvas and must dispose it to replay recorded work into the frame.
 
 `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
@@ -106,7 +108,7 @@ There are two backend-selection paths in the architecture:
 - specialized infrastructure can construct a canvas with an explicit backend
 
 The ordinary CPU entry point is `Paint(...)` on `IImageProcessingContext`, which routes into the typed
-implementation internally.
+implementation internally. Public `ImageFrame` canvas extensions provide the lower-level frame entry point for callers that want to own the canvas lifetime directly.
 
 That explicit-backend path matters for the WebGPU helpers. `WebGPUWindow`, `WebGPUExternalSurface`, and `WebGPURenderTarget` 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,25 +1,29 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
 
+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.
+/// Extension methods for creating drawing canvas instances over ImageSharp image frames.
 /// </summary>
-internal static class DrawingCanvasFactoryExtensions
+public static class DrawingCanvasFactoryExtensions
 {
     /// <summary>
-    /// Creates a drawing canvas over an existing frame.
+    /// Creates a drawing canvas over an existing typed image frame.
     /// </summary>
+    /// <remarks>
+    /// The caller owns the returned canvas and must dispose it to replay recorded work into the frame.
+    /// </remarks>
     /// <typeparam name="TPixel">The pixel format.</typeparam>
     /// <param name="frame">The frame backing the canvas.</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 <paramref name="frame"/>.</returns>
-    internal static DrawingCanvas CreateCanvas<TPixel>(
+    public static DrawingCanvas CreateCanvas<TPixel>(
         this ImageFrame<TPixel> frame,
         Configuration configuration,
         DrawingOptions options,
@@ -33,7 +37,52 @@ internal static DrawingCanvas CreateCanvas<TPixel>(
         return new DrawingCanvas<TPixel>(
             configuration,
             options,
-            new Buffer2DRegion<TPixel>(frame.PixelBuffer),
+            frame.PixelBuffer.GetRegion(),
             clipPaths);
     }
+
+    /// <summary>
+    /// Creates a drawing canvas over an existing image frame.
+    /// </summary>
+    /// <remarks>
+    /// The caller owns the returned canvas and must dispose it to replay recorded work into the frame.
+    /// </remarks>
+    /// <param name="frame">The frame backing the canvas.</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 <paramref name="frame"/>.</returns>
+    public static DrawingCanvas CreateCanvas(
+        this ImageFrame frame,
+        Configuration configuration,
+        DrawingOptions options,
+        params IPath[] clipPaths)
+    {
+        Guard.NotNull(frame, nameof(frame));
+        Guard.NotNull(options, nameof(options));
+        Guard.NotNull(clipPaths, nameof(clipPaths));
+
+        CanvasFactoryVisitor visitor = new(configuration, options, clipPaths);
+        frame.AcceptVisitor(visitor);
+        return visitor.Value!;
+    }
+
+    private struct CanvasFactoryVisitor : IImageFrameVisitor
+    {
+        private readonly Configuration configuration;
+        private readonly DrawingOptions options;
+        private readonly IPath[] clipPaths;
+
+        public CanvasFactoryVisitor(Configuration configuration, DrawingOptions options, IPath[] clipPaths)
+        {
+            this.configuration = configuration;
+            this.options = options;
+            this.clipPaths = clipPaths;
+        }
+
+        public DrawingCanvas? Value { get; private set; }
+
+        void IImageFrameVisitor.Visit<TPixel>(ImageFrame<TPixel> frame)
+            => this.Value = frame.CreateCanvas(this.configuration, this.options, this.clipPaths);
+    }
 }