Refactor drawing backend API and WebGPU helpers

Author: JimBobSquarePants

samples/DrawShapesWithImageSharp/Program.cs

@@ -29,7 +29,6 @@ public static class Program
     private const string DisplayFontFile = "WendyOne-Regular.ttf";
 
     private static readonly Size SampleSize = new(960, 640);
-    private static readonly Brush PageBrush = Brushes.Solid(Color.White);
     private static readonly FontCollection SampleFonts = new();
     private static readonly FontFamily ArabicFontFamily = LoadFontFamily(ArabicFontFile);
     private static readonly FontFamily CjkFontFamily = LoadFontFamily(CjkFontFile);
@@ -1199,7 +1198,7 @@ private static void SaveSample(string fileName, Size size, CanvasAction draw)
     private static void SaveImage(Image image, string fileName)
     {
         string fullPath = IOPath.Combine(AppContext.BaseDirectory, OutputDirectory, fileName);
-        IODirectory.CreateDirectory(IOPath.GetDirectoryName(fullPath)!);
+        IODirectory.CreateDirectory(IOPath.GetDirectoryName(fullPath));
         image.Save(fullPath);
     }
 

samples/DrawingBackendBenchmark/README.md

@@ -45,21 +45,21 @@ For each iteration the form:
 4. updates the running mean and standard deviation
 5. captures a preview image only on the last iteration
 
-That last point matters: preview capture is intentionally outside the measured timing path. The reported time measures scene submission and backend flush work only. Any readback, clone, or bitmap conversion needed for the UI happens afterward.
+That last point matters: preview capture is intentionally outside the measured timing path. The reported time measures canvas replay and backend submission work only. Any readback, clone, or bitmap conversion needed for the UI happens afterward.
 
 ## Timing model
 
 All backends follow the same basic timing rule:
 
 - start the stopwatch immediately before drawing the scene
-- stop it immediately after the backend flush or submission boundary
+- stop it immediately after the backend render or submission boundary
 - capture preview pixels only after the stopwatch stops
 
 In practice that means:
 
-- `CPU` measures drawing into the cached `Image<Bgra32>` through `DrawingCanvas.Flush()`
+- `CPU` measures drawing into the cached `Image<Bgra32>` through canvas disposal replay
 - `SkiaSharp` measures drawing through `SKCanvas.Flush()` and optional GPU context flush
-- `WebGPU` measures drawing through `DrawingCanvas.Flush()` into the offscreen `WebGPURenderTarget<Bgra32>`
+- `WebGPU` measures drawing through canvas disposal replay into the offscreen `WebGPURenderTarget`
 
 So the numbers are comparable as "render and submit" timings, not "render plus preview extraction" timings.
 
@@ -69,7 +69,7 @@ The sample uses a fixed benchmark size, so the backends keep their render target
 
 - `CpuBenchmarkBackend` caches one `Image<Bgra32>`
 - `SkiaSharpBenchmarkBackend` caches one `SKSurface`
-- `WebGpuBenchmarkBackend` caches one `WebGPURenderTarget<Bgra32>`
+- `WebGpuBenchmarkBackend` caches one `WebGPURenderTarget`
 
 This keeps the benchmark focused on scene rendering rather than repeated target allocation noise.
 
@@ -78,11 +78,11 @@ This keeps the benchmark focused on scene rendering rather than repeated target
 The WebGPU backend is intentionally small:
 
 - it probes support up front with `WebGPUEnvironment.ProbeComputePipelineSupport()`
-- it renders into an owned offscreen `WebGPURenderTarget<Bgra32>`
-- it draws through `CreateCanvas(...)`, not a hybrid CPU plus GPU canvas
+- it renders into an owned offscreen `WebGPURenderTarget`
+- it draws through `CreateCanvas(...)`
 - it reads back the final frame only when the UI requests the last-iteration preview
 
-The status line also reports whether the last WebGPU flush completed on the staged GPU path or had to fall back to CPU execution.
+The status line also reports whether the last WebGPU render used chunked staged execution.
 
 ## File guide
 

samples/DrawingBackendBenchmark/WebGpuBenchmarkBackend.cs

@@ -15,7 +15,7 @@ namespace DrawingBackendBenchmark;
 /// </summary>
 internal sealed class WebGpuBenchmarkBackend : IBenchmarkBackend
 {
-    private WebGPURenderTarget<Bgra32>? renderTarget;
+    private WebGPURenderTarget? renderTarget;
     private int cachedWidth;
     private int cachedHeight;
 
@@ -43,7 +43,7 @@ public static bool TryCreate([NotNullWhen(true)] out WebGpuBenchmarkBackend? res
     /// </summary>
     public BenchmarkRenderResult Render(ReadOnlySpan<VisualLine> lines, int width, int height, bool capturePreview)
     {
-        WebGPURenderTarget<Bgra32> renderTarget = this.EnsureRenderTarget(width, height);
+        WebGPURenderTarget renderTarget = this.EnsureRenderTarget(width, height);
 
         Stopwatch stopwatch = Stopwatch.StartNew();
         using (DrawingCanvas canvas = renderTarget.CreateCanvas(new DrawingOptions()))
@@ -60,7 +60,7 @@ public BenchmarkRenderResult Render(ReadOnlySpan<VisualLine> lines, int width, i
         {
             try
             {
-                preview = renderTarget.Readback();
+                preview = renderTarget.Readback<Bgra32>();
             }
             catch (Exception ex)
             {
@@ -87,15 +87,15 @@ public void Dispose()
         this.renderTarget = null;
     }
 
-    private WebGPURenderTarget<Bgra32> EnsureRenderTarget(int width, int height)
+    private WebGPURenderTarget EnsureRenderTarget(int width, int height)
     {
         if (this.renderTarget is not null && this.cachedWidth == width && this.cachedHeight == height)
         {
             return this.renderTarget;
         }
 
         this.renderTarget?.Dispose();
-        this.renderTarget = new WebGPURenderTarget<Bgra32>(width, height);
+        this.renderTarget = new WebGPURenderTarget(WebGPUTextureFormat.Bgra8Unorm, width, height);
         this.cachedWidth = width;
         this.cachedHeight = height;
         return this.renderTarget;

samples/WebGPUExternalSurfaceDemo/Controls/WebGPURenderControl.cs

@@ -5,13 +5,12 @@
 using System.Runtime.InteropServices;
 using SixLabors.ImageSharp.Drawing.Processing;
 using SixLabors.ImageSharp.Drawing.Processing.Backends;
-using SixLabors.ImageSharp.PixelFormats;
 using ImageSharpSize = SixLabors.ImageSharp.Size;
 
 namespace WebGPUExternalSurfaceDemo.Controls;
 
 /// <summary>
-/// A reusable WinForms control that embeds a <see cref="WebGPUExternalSurface{TPixel}"/> and drives a continuous
+/// A reusable WinForms control that embeds a <see cref="WebGPUExternalSurface"/> and drives a continuous
 /// render loop via <see cref="Application.Idle"/>. Callers hook <see cref="PaintFrame"/> with their scene logic;
 /// the control handles construction, resize, acquire/present, and teardown.
 /// </summary>
@@ -20,7 +19,7 @@ public sealed partial class WebGPURenderControl : Control
     private const int WM_MOVING = 0x0216;
     private const int WM_EXITSIZEMOVE = 0x0232;
 
-    private WebGPUExternalSurface<Bgra32>? surface;
+    private WebGPUExternalSurface? surface;
     private Size framebufferSize;
     private bool idleHooked;
     private long lastTicks;
@@ -63,11 +62,15 @@ protected override void OnHandleCreated(EventArgs e)
 
         // The module handle is required by the Win32 surface descriptor. It identifies the process module
         // that owns the window class backing this control.
-        this.surface = new WebGPUExternalSurface<Bgra32>(
+        this.surface = new WebGPUExternalSurface(
             WebGPUSurfaceHost.Win32(
                 this.Handle,
                 Marshal.GetHINSTANCE(typeof(WebGPURenderControl).Module)),
-            initialFramebufferSize);
+            initialFramebufferSize,
+            new WebGPUExternalSurfaceOptions
+            {
+                Format = WebGPUTextureFormat.Bgra8Unorm
+            });
 
         this.lastTicks = Stopwatch.GetTimestamp();
         Application.Idle += this.OnApplicationIdle;
@@ -179,7 +182,7 @@ private void RenderOnce()
 
         // Frame acquisition can fail transiently while the surface is unavailable, for example during resize
         // or device recovery. Skipping the frame keeps the UI message loop responsive.
-        if (!this.surface.TryAcquireFrame(out WebGPUSurfaceFrame<Bgra32>? frame))
+        if (!this.surface.TryAcquireFrame(out WebGPUSurfaceFrame? frame))
         {
             return;
         }
@@ -191,7 +194,7 @@ private void RenderOnce()
         using (frame)
         {
             // The canvas records drawing work against the acquired surface texture. Disposing the frame
-            // flushes that work, presents the texture, and releases the per-frame native handles.
+            // renders that work, presents the texture, and releases the per-frame native handles.
             this.PaintFrame?.Invoke(frame.Canvas, delta);
         }
     }

samples/WebGPUExternalSurfaceDemo/README.md

@@ -4,9 +4,9 @@
 
 It exists to demonstrate:
 
-- creating a `WebGPUExternalSurface<Bgra32>` from a `WebGPUSurfaceHost`
+- creating a `WebGPUExternalSurface` from a `WebGPUSurfaceHost`
 - keeping the external surface synchronized with the host control's drawable framebuffer size
-- acquiring `WebGPUSurfaceFrame<TPixel>` instances manually
+- acquiring `WebGPUSurfaceFrame` instances manually
 - drawing with the normal `DrawingCanvas` API
 - presenting by disposing the acquired frame
 
@@ -21,7 +21,7 @@ Requirements:
 - .NET 8.0 SDK or later
 - Windows, because this sample is a WinForms app
 - a WebGPU-capable desktop backend such as D3D12 or Vulkan
-- adapter support for the storage-capable BGRA format required by `Bgra32`
+- adapter support for the storage-capable BGRA format selected by the sample
 
 When the sample starts you should see a WinForms window with three tabs:
 
@@ -31,7 +31,7 @@ When the sample starts you should see a WinForms window with three tabs:
 
 ## Why This Sample Matters
 
-`WebGPUWindow<TPixel>` owns a top-level native window. `WebGPUExternalSurface<TPixel>` is different: it attaches WebGPU rendering to something the application already owns, such as a control, view, widget, or native surface.
+`WebGPUWindow` owns a top-level native window. `WebGPUExternalSurface` is different: it attaches WebGPU rendering to something the application already owns, such as a control, view, widget, or native surface.
 
 That makes it the integration path for UI frameworks. The host owns:
 
@@ -57,18 +57,22 @@ The reusable integration point is [WebGPURenderControl.cs](d:/GitHub/SixLabors/I
 `WebGPURenderControl.OnHandleCreated(...)` creates the external surface from the WinForms control handle:
 
 ```csharp
-this.surface = new WebGPUExternalSurface<Bgra32>(
+this.surface = new WebGPUExternalSurface(
     WebGPUSurfaceHost.Win32(
         this.Handle,
         Marshal.GetHINSTANCE(typeof(WebGPURenderControl).Module)),
-    initialFramebufferSize);
+    initialFramebufferSize,
+    new WebGPUExternalSurfaceOptions
+    {
+        Format = WebGPUTextureFormat.Bgra8Unorm
+    });
 ```
 
-`WebGPUSurfaceHost` is a small public descriptor for externally-owned native handles. The host keeps ownership of those handles; `WebGPUExternalSurface<TPixel>` only uses them to create and manage the WebGPU rendering surface.
+`WebGPUSurfaceHost` is a small public descriptor for externally-owned native handles. The host keeps ownership of those handles; `WebGPUExternalSurface` only uses them to create and manage the WebGPU rendering surface.
 
 ### Resize
 
-`WebGPUExternalSurface<TPixel>.Resize(...)` expects the drawable framebuffer size in pixels:
+`WebGPUExternalSurface.Resize(...)` expects the drawable framebuffer size in pixels:
 
 ```csharp
 this.framebufferSize = this.ClientSize;
@@ -82,7 +86,7 @@ The acquired frame exposes the same pixel coordinate space through `frame.Canvas
 `RenderOnce()` acquires a frame, invokes user drawing code, and disposes the frame:
 
 ```csharp
-if (!this.surface.TryAcquireFrame(out WebGPUSurfaceFrame<Bgra32>? frame))
+if (!this.surface.TryAcquireFrame(out WebGPUSurfaceFrame? frame))
 {
     return;
 }
@@ -93,7 +97,7 @@ using (frame)
 }
 ```
 
-Disposing the frame flushes pending canvas work, presents the surface texture, and releases the per-frame WebGPU handles.
+Disposing the frame renders pending canvas work, presents the surface texture, and releases the per-frame WebGPU handles.
 
 ### Rendering Loop
 

samples/WebGPUWindowDemo/Program.cs

@@ -25,10 +25,11 @@ public static class Program
     public static void Main()
     {
         // FIFO is the safest sample default: it presents in display order with normal v-sync behavior.
-        using WebGPUWindow<Bgra32> window = new(new WebGPUWindowOptions
+        using WebGPUWindow window = new(new WebGPUWindowOptions
         {
             Title = "ImageSharp.Drawing WebGPU Demo",
             Size = new Size(800, 600),
+            Format = WebGPUTextureFormat.Bgra8Unorm,
             PresentMode = WebGPUPresentMode.Fifo,
         });
 
@@ -46,7 +47,7 @@ private sealed class DemoApp
         private static readonly Brush BackgroundBrush = Brushes.Solid(Color.FromPixel(new Bgra32(30, 30, 40, 255)));
         private static readonly Brush TextBrush = Brushes.Solid(Color.FromPixel(new Bgra32(70, 70, 100, 255)));
 
-        private readonly WebGPUWindow<Bgra32> window;
+        private readonly WebGPUWindow window;
         private readonly Random rng = new(42);
         private readonly Stopwatch fpsWindow = Stopwatch.StartNew();
         private Ball[] balls = [];
@@ -70,18 +71,17 @@ private sealed class DemoApp
             "using a WebGPU compute pipeline that evaluates " +
             "Porter-Duff blending per pixel.\n\n" +
             "The drawing backend automatically manages texture " +
-            "atlases, bind groups, and pipeline state. It falls " +
-            "back to the CPU backend for unsupported pixel " +
-            "formats or when no GPU device is available.\n\n" +
+            "atlases, bind groups, and pipeline state for the " +
+            "native target selected by the window.\n\n" +
             "SixLabors ImageSharp.Drawing\n" +
             "github.com/SixLabors/ImageSharp.Drawing\n\n" +
-            "Built on the new WebGPUWindow<TPixel> wrapper.";
+            "Built on the WebGPUWindow wrapper.";
 
         /// <summary>
         /// Initializes a new instance of the <see cref="DemoApp"/> class.
         /// </summary>
         /// <param name="window">The demo window that supplies update and render callbacks.</param>
-        public DemoApp(WebGPUWindow<Bgra32> window)
+        public DemoApp(WebGPUWindow window)
         {
             this.window = window;
             this.window.Update += this.OnUpdate;
@@ -146,10 +146,10 @@ private void OnUpdate(TimeSpan deltaTime)
         /// </summary>
         /// <param name="frame">The acquired frame that exposes the drawing canvas.</param>
         /// <remarks>
-        /// The window loop disposes the frame after this callback returns, which flushes any queued canvas work,
+        /// The window loop disposes the frame after this callback returns, which renders queued canvas work,
         /// presents the swapchain texture, and releases the per-frame WebGPU handles.
         /// </remarks>
-        private void OnRender(WebGPUSurfaceFrame<Bgra32> frame)
+        private void OnRender(WebGPUSurfaceFrame frame)
         {
             DrawingCanvas canvas = frame.Canvas;
             Rectangle bounds = canvas.Bounds;