Refactor WebGPU handles and render targets

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WebGPUFlushContext.cs

@@ -529,10 +529,10 @@ private bool InitializeNativeTarget()
         this.queueReference = this.queueHandle.AcquireReference();
         this.targetTextureReference = this.targetTextureHandle.AcquireReference();
         this.targetTextureViewReference = this.targetTextureViewHandle.AcquireReference();
-        this.Device = (Device*)this.deviceReference.Handle;
-        this.Queue = (Queue*)this.queueReference.Handle;
-        this.TargetTexture = (Texture*)this.targetTextureReference.Handle;
-        this.TargetView = (TextureView*)this.targetTextureViewReference.Handle;
+        this.Device = (Device*)this.deviceReference.Value.Handle;
+        this.Queue = (Queue*)this.queueReference.Value.Handle;
+        this.TargetTexture = (Texture*)this.targetTextureReference.Value.Handle;
+        this.TargetView = (TextureView*)this.targetTextureViewReference.Value.Handle;
         this.ownsTargetTexture = false;
         this.ownsTargetView = false;
         return true;

src/ImageSharp.Drawing.WebGPU/WebGPUHandle.cs

@@ -77,9 +77,11 @@ internal HandleReference AcquireReference()
     /// <remarks>
     /// This token exists so callers can use a normal <c>using</c> scope around raw WebGPU pointers
     /// without carrying a separate success flag beside the handle. Disposing it releases the
-    /// reference acquired by <see cref="AcquireReference"/>.
+    /// reference acquired by <see cref="AcquireReference"/>. Modeled after
+    /// <see cref="System.Buffers.MemoryHandle"/>: a lightweight scoped value that should not be
+    /// copied or stored beyond the immediate native-call scope.
     /// </remarks>
-    internal sealed class HandleReference : IDisposable
+    internal struct HandleReference : IDisposable
     {
         private WebGPUHandle? owner;
 

src/ImageSharp.Drawing.WebGPU/WebGPURenderTarget{TPixel}.cs

@@ -19,25 +19,6 @@ public sealed class WebGPURenderTarget<TPixel> : IDisposable
     private readonly bool ownsGraphics;
     private bool isDisposed;
 
-    private WebGPURenderTarget(
-        WebGPUDeviceContext<TPixel> graphics,
-        bool ownsGraphics,
-        WebGPUTextureHandle textureHandle,
-        WebGPUTextureViewHandle textureViewHandle,
-        NativeSurface surface,
-        WebGPUTextureFormatId format,
-        Rectangle bounds)
-    {
-        this.Graphics = graphics;
-        this.ownsGraphics = ownsGraphics;
-        this.TextureHandle = textureHandle;
-        this.TextureViewHandle = textureViewHandle;
-        this.Surface = surface;
-        this.Format = format;
-        this.Bounds = bounds;
-        this.NativeFrame = new NativeCanvasFrame<TPixel>(bounds, surface);
-    }
-
     /// <summary>
     /// Initializes a new instance of the <see cref="WebGPURenderTarget{TPixel}"/> class using the shared process-level device.
     /// </summary>
@@ -55,31 +36,57 @@ public WebGPURenderTarget(int width, int height)
     /// <param name="width">The target width in pixels.</param>
     /// <param name="height">The target height in pixels.</param>
     public WebGPURenderTarget(Configuration configuration, int width, int height)
-        : this(AllocateOwnedTarget(configuration, width, height))
+        : this(new WebGPUDeviceContext<TPixel>(configuration), ownsGraphics: true, width, height)
     {
     }
 
-    private WebGPURenderTarget(OwnedTarget ownedTarget)
-        : this(
-            ownedTarget.Graphics,
-            ownsGraphics: true,
-            ownedTarget.TextureHandle,
-            ownedTarget.TextureViewHandle,
-            ownedTarget.Surface,
-            ownedTarget.Format,
-            ownedTarget.Bounds)
+    private WebGPURenderTarget(WebGPUDeviceContext<TPixel> graphics, bool ownsGraphics, int width, int height)
     {
-    }
+        this.Graphics = graphics;
+        this.ownsGraphics = ownsGraphics;
 
-    /// <summary>
-    /// Gets the owned wrapped texture handle behind this render target.
-    /// </summary>
-    internal WebGPUTextureHandle TextureHandle { get; }
+        try
+        {
+            graphics.ThrowIfDisposed();
 
-    /// <summary>
-    /// Gets the owned wrapped texture-view handle bound when this render target is used as a native surface.
-    /// </summary>
-    internal WebGPUTextureViewHandle TextureViewHandle { get; }
+            WebGPU api = WebGPURuntime.GetApi();
+            if (!WebGPURenderTargetAllocation.TryCreateRenderTarget<TPixel>(
+                    api,
+                    graphics.DeviceHandle,
+                    graphics.QueueHandle,
+                    width,
+                    height,
+                    out NativeSurface surface,
+                    out WebGPUTextureHandle? textureHandle,
+                    out WebGPUTextureViewHandle? textureViewHandle,
+                    out WebGPUTextureFormatId format,
+                    out string allocationError))
+            {
+                throw new InvalidOperationException(allocationError);
+            }
+
+            if (textureHandle is null || textureViewHandle is null)
+            {
+                throw new InvalidOperationException("WebGPU render-target allocation succeeded without returning both owned texture handles.");
+            }
+
+            this.TextureHandle = textureHandle;
+            this.TextureViewHandle = textureViewHandle;
+            this.Surface = surface;
+            this.Format = format;
+            this.Bounds = new Rectangle(0, 0, width, height);
+            this.NativeFrame = new NativeCanvasFrame<TPixel>(this.Bounds, surface);
+        }
+        catch
+        {
+            if (ownsGraphics)
+            {
+                graphics.Dispose();
+            }
+
+            throw;
+        }
+    }
 
     /// <summary>
     /// Gets the graphics device context used by this target.
@@ -116,48 +123,15 @@ private WebGPURenderTarget(OwnedTarget ownedTarget)
     /// </summary>
     public WebGPUTextureFormatId Format { get; }
 
-    private static OwnedTarget AllocateOwnedTarget(Configuration configuration, int width, int height)
-    {
-        WebGPUDeviceContext<TPixel> graphics = new(configuration);
-        try
-        {
-            WebGPU api = WebGPURuntime.GetApi();
-            if (!WebGPURenderTargetAllocation.TryCreateRenderTarget<TPixel>(
-                    api,
-                    graphics.DeviceHandle,
-                    graphics.QueueHandle,
-                    width,
-                    height,
-                    out NativeSurface surface,
-                    out WebGPUTextureHandle? textureHandle,
-                    out WebGPUTextureViewHandle? textureViewHandle,
-                    out WebGPUTextureFormatId format,
-                    out string allocationError))
-            {
-                graphics.Dispose();
-                throw new InvalidOperationException(allocationError);
-            }
-
-            if (textureHandle is null || textureViewHandle is null)
-            {
-                graphics.Dispose();
-                throw new InvalidOperationException("WebGPU render-target allocation succeeded without returning both owned texture handles.");
-            }
+    /// <summary>
+    /// Gets the owned wrapped texture handle behind this render target.
+    /// </summary>
+    internal WebGPUTextureHandle TextureHandle { get; }
 
-            return new OwnedTarget(
-                graphics,
-                textureHandle,
-                textureViewHandle,
-                surface,
-                format,
-                new Rectangle(0, 0, width, height));
-        }
-        catch
-        {
-            graphics.Dispose();
-            throw;
-        }
-    }
+    /// <summary>
+    /// Gets the owned wrapped texture-view handle bound when this render target is used as a native surface.
+    /// </summary>
+    internal WebGPUTextureViewHandle TextureViewHandle { get; }
 
     /// <summary>
     /// Creates a native-only frame over this render target.
@@ -274,81 +248,8 @@ public void Dispose()
     /// <param name="height">The target height in pixels.</param>
     /// <returns>The created render target.</returns>
     internal static WebGPURenderTarget<TPixel> CreateFromContext(WebGPUDeviceContext<TPixel> graphics, int width, int height)
-        => CreateCore(graphics, ownsGraphics: false, width, height);
-
-    private static WebGPURenderTarget<TPixel> CreateCore(
-        WebGPUDeviceContext<TPixel> graphics,
-        bool ownsGraphics,
-        int width,
-        int height)
-    {
-        graphics.ThrowIfDisposed();
-
-        WebGPU api = WebGPURuntime.GetApi();
-        if (!WebGPURenderTargetAllocation.TryCreateRenderTarget<TPixel>(
-                api,
-                graphics.DeviceHandle,
-                graphics.QueueHandle,
-                width,
-                height,
-                out NativeSurface surface,
-                out WebGPUTextureHandle? textureHandle,
-                out WebGPUTextureViewHandle? textureViewHandle,
-                out WebGPUTextureFormatId format,
-                out string error))
-        {
-            throw new InvalidOperationException(error);
-        }
+        => new(graphics, ownsGraphics: false, width, height);
 
-        if (textureHandle is null || textureViewHandle is null)
-        {
-            throw new InvalidOperationException("WebGPU render-target allocation succeeded without returning both owned texture handles.");
-        }
-
-        return new WebGPURenderTarget<TPixel>(
-            graphics,
-            ownsGraphics,
-            textureHandle,
-            textureViewHandle,
-            surface,
-            format,
-            new Rectangle(0, 0, width, height));
-    }
-
-    /// <summary>
-    /// Throws when this render target is disposed.
-    /// </summary>
     private void ThrowIfDisposed()
         => ObjectDisposedException.ThrowIf(this.isDisposed, this);
-
-    private sealed class OwnedTarget
-    {
-        public OwnedTarget(
-            WebGPUDeviceContext<TPixel> graphics,
-            WebGPUTextureHandle textureHandle,
-            WebGPUTextureViewHandle textureViewHandle,
-            NativeSurface surface,
-            WebGPUTextureFormatId format,
-            Rectangle bounds)
-        {
-            this.Graphics = graphics;
-            this.TextureHandle = textureHandle;
-            this.TextureViewHandle = textureViewHandle;
-            this.Surface = surface;
-            this.Format = format;
-            this.Bounds = bounds;
-        }
-
-        public WebGPUDeviceContext<TPixel> Graphics { get; }
-
-        public WebGPUTextureHandle TextureHandle { get; }
-
-        public WebGPUTextureViewHandle TextureViewHandle { get; }
-
-        public NativeSurface Surface { get; }
-
-        public WebGPUTextureFormatId Format { get; }
-
-        public Rectangle Bounds { get; }
-    }
 }

src/ImageSharp.Drawing.WebGPU/WebGPURuntime.DeviceSharedState.cs

@@ -58,7 +58,7 @@ internal sealed class DeviceSharedState : IDisposable
         private readonly ConcurrentDictionary<string, CompositeComputePipelineInfrastructure> compositeComputePipelines = new(StringComparer.Ordinal);
         private readonly ConcurrentDictionary<string, SharedBufferInfrastructure> sharedBuffers = new(StringComparer.Ordinal);
         private readonly HashSet<FeatureName> deviceFeatures;
-        private readonly WebGPUHandle.HandleReference deviceReference;
+        private WebGPUHandle.HandleReference deviceReference;
         private bool disposed;
 
         internal DeviceSharedState(WebGPU api, WebGPUDeviceHandle deviceHandle)

src/ImageSharp.Drawing.WebGPU/WebGPUWindowFrame{TPixel}.cs

@@ -15,7 +15,7 @@ public sealed unsafe class WebGPUWindowFrame<TPixel> : IDisposable
     where TPixel : unmanaged, IPixel<TPixel>
 {
     private readonly WebGPU api;
-    private readonly WebGPUHandle.HandleReference surfaceReference;
+    private WebGPUHandle.HandleReference surfaceReference;
     private readonly WebGPUTextureHandle textureHandle;
     private readonly WebGPUTextureViewHandle textureViewHandle;
     private bool isDisposed;

src/ImageSharp.Drawing.WebGPU/WebGPUWindow{TPixel}.cs

@@ -51,25 +51,16 @@ public WebGPUWindow(WebGPUWindowOptions options)
     /// <param name="configuration">The configuration instance to bind to the created backend.</param>
     /// <param name="options">The window creation options.</param>
     public WebGPUWindow(Configuration configuration, WebGPUWindowOptions options)
-        : this(CreateConstruction(configuration, options))
     {
-    }
-
-    private WebGPUWindow(WindowConstruction construction)
-        : this(construction.Window, construction.Configuration, construction.Format, construction.PresentMode)
-    {
-    }
+        if (!WebGPUDrawingBackend.TryGetCompositeTextureFormat<TPixel>(out WebGPUTextureFormatId expectedFormat))
+        {
+            throw new NotSupportedException($"Pixel type '{typeof(TPixel).Name}' is not supported by the WebGPU backend.");
+        }
 
-    private WebGPUWindow(
-        IWindow window,
-        Configuration configuration,
-        WebGPUTextureFormatId format,
-        WebGPUPresentMode presentMode)
-    {
-        this.window = window;
+        this.window = Window.Create(CreateSilkOptions(options));
         this.Configuration = configuration;
-        this.Format = format;
-        this.presentMode = presentMode;
+        this.Format = expectedFormat;
+        this.presentMode = options.PresentMode;
 
         try
         {
@@ -588,17 +579,6 @@ private WindowResources CreateResources()
         }
     }
 
-    private static WindowConstruction CreateConstruction(Configuration configuration, WebGPUWindowOptions options)
-    {
-        if (!WebGPUDrawingBackend.TryGetCompositeTextureFormat<TPixel>(out WebGPUTextureFormatId expectedFormat))
-        {
-            throw new NotSupportedException($"Pixel type '{typeof(TPixel).Name}' is not supported by the WebGPU backend.");
-        }
-
-        IWindow window = Window.Create(CreateSilkOptions(options));
-        return new WindowConstruction(window, configuration, expectedFormat, options.PresentMode);
-    }
-
     private bool TryAcquireFrameCore(
         TimeSpan deltaTime,
         [NotNullWhen(true)] out WebGPUWindowFrame<TPixel>? frame,
@@ -919,27 +899,4 @@ public void Dispose()
             this.InstanceHandle.Dispose();
         }
     }
-
-    private sealed class WindowConstruction
-    {
-        public WindowConstruction(
-            IWindow window,
-            Configuration configuration,
-            WebGPUTextureFormatId format,
-            WebGPUPresentMode presentMode)
-        {
-            this.Window = window;
-            this.Configuration = configuration;
-            this.Format = format;
-            this.PresentMode = presentMode;
-        }
-
-        public IWindow Window { get; }
-
-        public Configuration Configuration { get; }
-
-        public WebGPUTextureFormatId Format { get; }
-
-        public WebGPUPresentMode PresentMode { get; }
-    }
 }

src/ImageSharp.Drawing/Processing/DRAWING_CANVAS.md

@@ -76,9 +76,10 @@ The command remains relatively close to the original user request. It may hold t
 
 ### Preparation
 
-Preparation is the flush-time normalization step. In code this lives in `CompositionCommand.Prepare(...)` and the surrounding `CompositionCommandPreparer`.
+Preparation is the flush-time normalization step that turns recorded intent into backend-ready geometry and metadata. It is split across two stages:
 
-Preparation turns recorded intent into backend-ready geometry and metadata. That is where path transforms are applied, strokes become outlines, clip paths are applied, prepared geometry is built or reused, and raster interest is recomputed.
+1. `DrawingCanvasBatcher<TPixel>.PrepareCommands(...)` runs first and only when needed. It applies command transforms, expands strokes to fill paths, and applies clip paths so that clipped commands reach the backend as ordinary fills. It also expands dashed strokes when a stroke pattern is present.
+2. The CPU backend then calls `FlushScene.Create(...)`, which lowers each command into a row-oriented retained representation through `TryPrepareFillPath` / `TryPrepareStrokePath`. That is where prepared rasterizable geometry is built, brushes are bound to the prepared coordinate space, and bounds and raster interest are recomputed.
 
 Preparation is where the architecture moves from "what the caller asked for" to "what the backend can execute".
 
@@ -363,12 +364,11 @@ If you want to move from the architecture into the code, this is the best order.
 2. `DrawingCanvasExtensions.cs`
 3. `DrawingCanvasBatcher{TPixel}.cs`
 4. `CompositionCommand.cs`
-5. `CompositionCommandPreparer.cs`
-6. `DefaultDrawingBackend.cs`
-7. `FlushScene.cs`
-8. `WebGPUEnvironment.cs`
-9. `WebGPUWindow{TPixel}.cs`, `WebGPURenderTarget{TPixel}.cs`, and `WebGPUDeviceContext{TPixel}.cs`
-10. `WebGPUDrawingBackend` and its scene/dispatch types
+5. `DefaultDrawingBackend.cs`
+6. `FlushScene.cs`
+7. `WebGPUEnvironment.cs`
+8. `WebGPUWindow{TPixel}.cs`, `WebGPURenderTarget{TPixel}.cs`, and `WebGPUDeviceContext{TPixel}.cs`
+9. `WebGPUDrawingBackend` and its scene/dispatch types
 
 That path follows the real runtime flow: