Refactor WebGPU native surface and chunking

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WebGPUDeviceContext.cs

@@ -252,15 +252,15 @@ internal DrawingCanvas CreateCanvas(
         int height)
     {
         Rectangle bounds = new(0, 0, width, height);
-        NativeSurface surface = this.CreateSurface(textureHandle, textureViewHandle, format, width, height);
+        WebGPUNativeSurface surface = this.CreateSurface(textureHandle, textureViewHandle, format, width, height);
 
         return WebGPUCanvasFactory.CreateCanvas(this.Configuration, options, this.Backend, bounds, surface, format);
     }
 
     /// <summary>
     /// Creates the wrapped native surface over the supplied texture handles.
     /// </summary>
-    private NativeSurface CreateSurface(
+    private WebGPUNativeSurface CreateSurface(
         WebGPUTextureHandle textureHandle,
         WebGPUTextureViewHandle textureViewHandle,
         WebGPUTextureFormat format,

src/ImageSharp.Drawing.WebGPU/WebGPUDrawingBackend.Readback.cs

@@ -33,15 +33,12 @@ public void ReadRegion<TPixel>(
         Guard.NotNull(destination.Buffer, nameof(destination));
 
         // Readback is only available for native WebGPU targets with valid interop handles.
-        if (!target.TryGetNativeSurface(out NativeSurface? nativeSurface))
+        if (!target.TryGetNativeSurface(out NativeSurface? nativeSurface) || nativeSurface is not WebGPUNativeSurface nativeTarget)
         {
             throw new NotSupportedException("The target does not expose a native surface for readback.");
         }
 
-        WebGPUNativeTarget nativeTarget = nativeSurface.GetNativeTarget<WebGPUNativeTarget>();
-        if (nativeTarget.DeviceHandle.IsInvalid ||
-            nativeTarget.QueueHandle.IsInvalid ||
-            nativeTarget.TargetTextureHandle.IsInvalid)
+        if (nativeTarget.DeviceHandle.IsInvalid || nativeTarget.QueueHandle.IsInvalid || nativeTarget.TargetTextureHandle.IsInvalid)
         {
             throw new NotSupportedException("The target does not expose valid WebGPU device, queue, and texture handles for readback.");
         }

src/ImageSharp.Drawing.WebGPU/WebGPUDrawingBackend.cs

@@ -42,6 +42,14 @@ public sealed unsafe partial class WebGPUDrawingBackend : IDrawingBackend, IDisp
     private WebGPUSceneSchedulingArena? cachedSchedulingArena;
     private WebGPUSceneResourceArena? cachedResourceArena;
 
+    // Advisory first-guess state for repeated oversized eager scenes. Parallel renders may
+    // race to update it; every hinted chunk is still validated before dispatch, so a stale
+    // or cross-scene value can only affect the first shrink attempt, not correctness.
+    private int chunkHintBinding;
+    private int chunkHintTargetWidth;
+    private int chunkHintTargetHeight;
+    private int chunkHintTileHeight;
+
     private WebGPUSceneDispatch.BindingLimitBuffer lastChunkingBindingFailure;
     private bool isDisposed;
 
@@ -117,10 +125,10 @@ public void RenderScene<TPixel>(
             throw new NotSupportedException($"The WebGPU backend does not support pixel format '{typeof(TPixel).Name}'.");
         }
 
-        // RenderScene only accepts native frames on the WebGPU path; unwrap the surface once
-        // so staging does not repeat the generic frame capability checks.
+        // RenderScene only accepts WebGPU native frames on this path, so cast once at the backend
+        // boundary and keep staging focused on dispatch data.
         _ = nativeTarget.TryGetNativeSurface(out NativeSurface? nativeSurface);
-        WebGPUNativeTarget webGPUTarget = nativeSurface!.GetNativeTarget<WebGPUNativeTarget>();
+        WebGPUNativeSurface webGPUTarget = (WebGPUNativeSurface)nativeSurface!;
         TextureFormat textureFormat = WebGPUTextureFormatMapper.ToNative(webGPUTarget.TargetFormat);
 
         if (webGPUTarget.TargetFormat != formatId)
@@ -178,13 +186,24 @@ public void RenderScene<TPixel>(
                         bool renderSucceeded = WebGPUSceneDispatch.TryRenderStagedScene(
                             ref stagedScene,
                             ref schedulingArena,
+                            this.GetChunkTileHeightHint(stagedScene.BindingLimitFailure.Buffer, encodedScene.TargetSize),
                             out bool requiresGrowth,
                             out WebGPUSceneBumpSizes grownBumpSizes,
+                            out uint successfulChunkTileHeight,
                             out string? error);
 
                         if (renderSucceeded)
                         {
                             currentBumpSizes = MaxBumpSizes(currentBumpSizes, grownBumpSizes);
+
+                            if (successfulChunkTileHeight != 0)
+                            {
+                                this.UpdateChunkTileHeightHint(
+                                    stagedScene.BindingLimitFailure.Buffer,
+                                    encodedScene.TargetSize,
+                                    successfulChunkTileHeight);
+                            }
+
                             renderCompleted = true;
                             break;
                         }
@@ -237,6 +256,50 @@ private static WebGPUSceneBumpSizes MaxBumpSizes(
             Math.Max(left.BlendSpill, right.BlendSpill),
             Math.Max(left.Ptcl, right.Ptcl));
 
+    /// <summary>
+    /// Gets the last successful chunk height for a matching oversized render.
+    /// </summary>
+    /// <param name="binding">The binding category that selected chunked rendering.</param>
+    /// <param name="targetSize">The target size being rendered.</param>
+    /// <returns>The advisory chunk height, or <c>0</c> when no matching hint exists.</returns>
+    private uint GetChunkTileHeightHint(WebGPUSceneDispatch.BindingLimitBuffer binding, Size targetSize)
+    {
+        int tileHeight = Volatile.Read(ref this.chunkHintTileHeight);
+        if (tileHeight <= 0)
+        {
+            return 0;
+        }
+
+        if (Volatile.Read(ref this.chunkHintBinding) != (int)binding ||
+            Volatile.Read(ref this.chunkHintTargetWidth) != targetSize.Width ||
+            Volatile.Read(ref this.chunkHintTargetHeight) != targetSize.Height)
+        {
+            return 0;
+        }
+
+        return unchecked((uint)tileHeight);
+    }
+
+    /// <summary>
+    /// Stores the last successful chunk height for later eager renders on this backend.
+    /// </summary>
+    /// <param name="binding">The binding category that selected chunked rendering.</param>
+    /// <param name="targetSize">The target size being rendered.</param>
+    /// <param name="tileHeight">The successful chunk height.</param>
+    private void UpdateChunkTileHeightHint(
+        WebGPUSceneDispatch.BindingLimitBuffer binding,
+        Size targetSize,
+        uint tileHeight)
+    {
+        Volatile.Write(ref this.chunkHintBinding, (int)binding);
+        Volatile.Write(ref this.chunkHintTargetWidth, targetSize.Width);
+        Volatile.Write(ref this.chunkHintTargetHeight, targetSize.Height);
+
+        // Publish the height last so readers never observe a new non-zero hint before
+        // its binding and target-size key have been written.
+        Volatile.Write(ref this.chunkHintTileHeight, unchecked((int)tileHeight));
+    }
+
     /// <summary>
     /// Rents the cached scene resource arena for a render, leaving the backend cache empty.
     /// </summary>

src/ImageSharp.Drawing.WebGPU/WebGPUFlushContext.cs

@@ -170,10 +170,10 @@ public static WebGPUFlushContext Create<TPixel>(
         MemoryAllocator memoryAllocator)
         where TPixel : unmanaged, IPixel<TPixel>
     {
-        // The native-frame overload is used after WebGPU target selection has already
-        // succeeded, so this unwraps the known native surface instead of probing support.
+        // The native-frame overload is used after WebGPU target selection has already succeeded,
+        // so this casts once at the backend boundary and keeps the concrete target data together.
         _ = frame.TryGetNativeSurface(out NativeSurface? nativeSurface);
-        WebGPUNativeTarget nativeTarget = nativeSurface!.GetNativeTarget<WebGPUNativeTarget>();
+        WebGPUNativeSurface nativeTarget = (WebGPUNativeSurface)nativeSurface!;
         WebGPU api = WebGPURuntime.GetApi();
         TextureFormat textureFormat = WebGPUTextureFormatMapper.ToNative(nativeTarget.TargetFormat);
         Rectangle bounds = frame.Bounds;

src/ImageSharp.Drawing.WebGPU/WebGPUNativeSurface.cs

@@ -6,18 +6,77 @@
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 
 /// <summary>
-/// WebGPU native drawing target exposed through the backend-agnostic <see cref="NativeSurface"/> contract.
+/// WebGPU native drawing surface exposed through the backend-agnostic <see cref="NativeSurface"/> base type.
 /// </summary>
 internal sealed class WebGPUNativeSurface : NativeSurface
 {
-    private readonly WebGPUNativeTarget target;
-
     /// <summary>
     /// Initializes a new instance of the <see cref="WebGPUNativeSurface"/> class.
     /// </summary>
-    /// <param name="target">The WebGPU target exposed by this surface.</param>
-    internal WebGPUNativeSurface(WebGPUNativeTarget target)
-        => this.target = target;
+    /// <param name="deviceHandle">The wrapped device handle that owns the target texture.</param>
+    /// <param name="queueHandle">The wrapped queue handle used to submit work against the target texture.</param>
+    /// <param name="targetTextureHandle">The wrapped target texture handle.</param>
+    /// <param name="targetTextureViewHandle">The wrapped target texture-view handle.</param>
+    /// <param name="targetFormat">The target texture format.</param>
+    /// <param name="width">The surface width in pixels.</param>
+    /// <param name="height">The surface height in pixels.</param>
+    public WebGPUNativeSurface(
+        WebGPUDeviceHandle deviceHandle,
+        WebGPUQueueHandle queueHandle,
+        WebGPUTextureHandle targetTextureHandle,
+        WebGPUTextureViewHandle targetTextureViewHandle,
+        WebGPUTextureFormat targetFormat,
+        int width,
+        int height)
+    {
+        Guard.NotNull(deviceHandle, nameof(deviceHandle));
+        Guard.NotNull(queueHandle, nameof(queueHandle));
+        Guard.NotNull(targetTextureHandle, nameof(targetTextureHandle));
+        Guard.NotNull(targetTextureViewHandle, nameof(targetTextureViewHandle));
+
+        this.DeviceHandle = deviceHandle;
+        this.QueueHandle = queueHandle;
+        this.TargetTextureHandle = targetTextureHandle;
+        this.TargetTextureViewHandle = targetTextureViewHandle;
+        this.TargetFormat = targetFormat;
+        this.Width = width;
+        this.Height = height;
+    }
+
+    /// <summary>
+    /// Gets the wrapped device handle that owns the target texture.
+    /// </summary>
+    public WebGPUDeviceHandle DeviceHandle { get; }
+
+    /// <summary>
+    /// Gets the wrapped queue handle used to submit work against the target texture.
+    /// </summary>
+    public WebGPUQueueHandle QueueHandle { get; }
+
+    /// <summary>
+    /// Gets the wrapped target texture handle.
+    /// </summary>
+    public WebGPUTextureHandle TargetTextureHandle { get; }
+
+    /// <summary>
+    /// Gets the wrapped target texture-view handle.
+    /// </summary>
+    public WebGPUTextureViewHandle TargetTextureViewHandle { get; }
+
+    /// <summary>
+    /// Gets the native render target texture format identifier.
+    /// </summary>
+    public WebGPUTextureFormat TargetFormat { get; }
+
+    /// <summary>
+    /// Gets the surface width in pixels.
+    /// </summary>
+    public int Width { get; }
+
+    /// <summary>
+    /// Gets the surface height in pixels.
+    /// </summary>
+    public int Height { get; }
 
     /// <summary>
     /// Allocates a WebGPU render target and creates a native surface over the owned texture handles.
@@ -31,7 +90,7 @@ internal WebGPUNativeSurface(WebGPUNativeTarget target)
     /// <param name="textureHandle">Receives the allocated wrapped <c>WGPUTexture*</c> handle.</param>
     /// <param name="textureViewHandle">Receives the allocated wrapped <c>WGPUTextureView*</c> handle.</param>
     /// <returns>The native surface wrapping the allocated texture.</returns>
-    internal static unsafe NativeSurface Create(
+    internal static unsafe WebGPUNativeSurface Create(
         WebGPU api,
         WebGPUDeviceHandle deviceHandle,
         WebGPUQueueHandle queueHandle,
@@ -105,7 +164,7 @@ internal static unsafe NativeSurface Create(
         {
             createdTextureHandle = new WebGPUTextureHandle(api, (nint)texture, ownsHandle: true);
             createdTextureViewHandle = new WebGPUTextureViewHandle(api, (nint)textureView, ownsHandle: true);
-            NativeSurface surface = Create(
+            WebGPUNativeSurface surface = Create(
                 deviceHandle,
                 queueHandle,
                 createdTextureHandle,
@@ -140,7 +199,7 @@ internal static unsafe NativeSurface Create(
     /// <summary>
     /// Creates a native surface over wrapped WebGPU texture handles.
     /// </summary>
-    internal static NativeSurface Create(
+    internal static WebGPUNativeSurface Create(
         WebGPUDeviceHandle deviceHandle,
         WebGPUQueueHandle queueHandle,
         WebGPUTextureHandle targetTextureHandle,
@@ -157,25 +216,13 @@ internal static NativeSurface Create(
         Guard.MustBeGreaterThan(width, 0, nameof(width));
         Guard.MustBeGreaterThan(height, 0, nameof(height));
 
-        return new WebGPUNativeSurface(new WebGPUNativeTarget(
+        return new WebGPUNativeSurface(
             deviceHandle,
             queueHandle,
             targetTextureHandle,
             targetTextureViewHandle,
             targetFormat,
             width,
-            height));
-    }
-
-    /// <inheritdoc />
-    public override TNativeTarget GetNativeTarget<TNativeTarget>()
-        where TNativeTarget : class
-    {
-        if (this.target is TNativeTarget typed)
-        {
-            return typed;
-        }
-
-        throw new NotSupportedException($"The native surface does not expose a native target of type '{typeof(TNativeTarget).Name}'.");
+            height);
     }
 }

src/ImageSharp.Drawing.WebGPU/WebGPUNativeTarget.cs

@@ -85,7 +85,7 @@ private WebGPURenderTarget(
             deviceContext.ThrowIfDisposed();
 
             WebGPU api = WebGPURuntime.GetApi();
-            NativeSurface surface = WebGPUNativeSurface.Create(
+            WebGPUNativeSurface surface = WebGPUNativeSurface.Create(
                 api,
                 deviceContext.DeviceHandle,
                 deviceContext.QueueHandle,
@@ -121,7 +121,7 @@ private WebGPURenderTarget(
     /// Gets the native surface backing this render target.
     /// Most callers should use <see cref="CreateCanvas()"/> or <see cref="ReadbackImage()"/> instead.
     /// </summary>
-    internal NativeSurface Surface { get; }
+    internal WebGPUNativeSurface Surface { get; }
 
     /// <summary>
     /// Gets the target width in pixels.