Use WebGPUHostedSurface and normalize API

Author: JimBobSquarePants

WinFormsSamples.sln

@@ -1,4 +1,4 @@
-
+
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 18
 VisualStudioVersion = 18.4.11626.88
@@ -15,7 +15,7 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ImageSharp.Drawing.WebGPU.S
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DrawingBackendBenchmark", "samples\DrawingBackendBenchmark\DrawingBackendBenchmark.csproj", "{0AF23A97-CD73-409A-AA29-D214AA400AB0}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WebGPUHostedWindowDemo", "samples\WebGPUHostedWindowDemo\WebGPUHostedWindowDemo.csproj", "{478855A1-ECEA-4DF6-9D7B-0342EA26726E}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WebGPUHostedSurfaceDemo", "samples\WebGPUHostedSurfaceDemo\WebGPUHostedSurfaceDemo.csproj", "{478855A1-ECEA-4DF6-9D7B-0342EA26726E}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

samples/DrawingBackendBenchmark/CpuBenchmarkBackend.cs

@@ -33,7 +33,7 @@ public BenchmarkRenderResult Render(ReadOnlySpan<VisualLine> lines, int width, i
         Buffer2DRegion<Bgra32> region = new(image.Frames.RootFrame.PixelBuffer, image.Bounds);
 
         Stopwatch stopwatch = Stopwatch.StartNew();
-        using (DrawingCanvas<Bgra32> canvas = new(this.configuration, region, new DrawingOptions()))
+        using (DrawingCanvas<Bgra32> canvas = new(this.configuration, new DrawingOptions(), region))
         {
             VisualLine.RenderLinesToCanvas(canvas, lines);
             canvas.Flush();

…ndowDemo/Controls/WebGPURenderControl.cs …faceDemo/Controls/WebGPURenderControl.cssamples/WebGPUHostedWindowDemo/Controls/WebGPURenderControl.cs renamed to samples/WebGPUHostedSurfaceDemo/Controls/WebGPURenderControl.cs samples/WebGPUHostedWindowDemo/Controls/WebGPURenderControl.cs renamed to samples/WebGPUHostedSurfaceDemo/Controls/WebGPURenderControl.cs

@@ -6,11 +6,12 @@
 using SixLabors.ImageSharp.Drawing.Processing;
 using SixLabors.ImageSharp.Drawing.Processing.Backends;
 using SixLabors.ImageSharp.PixelFormats;
+using ImageSharpSize = SixLabors.ImageSharp.Size;
 
-namespace WebGPUHostedWindowDemo.Controls;
+namespace WebGPUHostedSurfaceDemo.Controls;
 
 /// <summary>
-/// A reusable WinForms control that embeds a <see cref="WebGPUHostedWindow{TPixel}"/> and drives a continuous
+/// A reusable WinForms control that embeds a <see cref="WebGPUHostedSurface{TPixel}"/> 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>
@@ -19,7 +20,8 @@ public sealed partial class WebGPURenderControl : Control
     private const int WM_MOVING = 0x0216;
     private const int WM_EXITSIZEMOVE = 0x0232;
 
-    private WebGPUHostedWindow<Bgra32>? window;
+    private WebGPUHostedSurface<Bgra32>? surface;
+    private Size framebufferSize;
     private bool idleHooked;
     private long lastTicks;
     private System.Windows.Forms.Timer? titleBarMoveTimer;
@@ -40,32 +42,40 @@ public WebGPURenderControl()
     }
 
     /// <summary>
-    /// Raised each frame once the hosted window has acquired a drawable frame.
+    /// Raised each frame once the hosted surface has acquired a drawable frame. The canvas dimensions match
+    /// <see cref="FramebufferSize"/>.
     /// </summary>
     public event Action<DrawingCanvas<Bgra32>, TimeSpan>? PaintFrame;
 
+    /// <summary>
+    /// Gets the drawable framebuffer size in pixels.
+    /// </summary>
+    public Size FramebufferSize => this.framebufferSize;
+
     /// <inheritdoc />
     protected override void OnHandleCreated(EventArgs e)
     {
         base.OnHandleCreated(e);
 
-        int width = Math.Max(this.ClientSize.Width, 1);
-        int height = Math.Max(this.ClientSize.Height, 1);
+        // WinForms ClientSize is the HWND client rectangle size; pass it through as the drawable framebuffer size.
+        this.framebufferSize = this.ClientSize;
+        ImageSharpSize initialFramebufferSize = new(
+            Math.Max(this.framebufferSize.Width, 1),
+            Math.Max(this.framebufferSize.Height, 1));
 
-        this.window = new WebGPUHostedWindow<Bgra32>(
-            WebGPUWindowHost.Win32(
+        this.surface = new WebGPUHostedSurface<Bgra32>(
+            WebGPUSurfaceHost.Win32(
                 this.Handle,
                 Marshal.GetHINSTANCE(typeof(WebGPURenderControl).Module)),
-            width,
-            height);
+            initialFramebufferSize);
 
         this.lastTicks = Stopwatch.GetTimestamp();
         Application.Idle += this.OnApplicationIdle;
         this.idleHooked = true;
 
         // Application.Idle stops firing during a title-bar drag (modal move loop).
         // Attach a NativeWindow to the parent form's handle so we can see WM_MOVING
-        // — which fires only during title-bar drags, never during border resizes —
+        // which fires only during title-bar drags, never during border resizes,
         // and drive a short Timer during those. Border resize is left untouched.
         Form? parentForm = this.FindForm();
         if (parentForm is not null && parentForm.IsHandleCreated)
@@ -97,18 +107,21 @@ protected override void OnHandleDestroyed(EventArgs e)
             this.titleBarMoveTimer = null;
         }
 
-        this.window?.Dispose();
-        this.window = null;
+        this.surface?.Dispose();
+        this.surface = null;
+        this.framebufferSize = Size.Empty;
         base.OnHandleDestroyed(e);
     }
 
     /// <inheritdoc />
     protected override void OnResize(EventArgs e)
     {
         base.OnResize(e);
-        if (this.window is not null && this.ClientSize.Width > 0 && this.ClientSize.Height > 0)
+        if (this.surface is not null)
         {
-            this.window.Resize(this.ClientSize.Width, this.ClientSize.Height);
+            // WinForms ClientSize is the HWND client rectangle size; pass it through as the drawable framebuffer size.
+            this.framebufferSize = this.ClientSize;
+            this.surface.Resize(new ImageSharpSize(this.framebufferSize.Width, this.framebufferSize.Height));
         }
     }
 
@@ -122,8 +135,8 @@ protected override void OnPaintBackground(PaintEventArgs pevent)
     protected override void OnPaint(PaintEventArgs e) => this.RenderOnce();
 
     // Application.Idle fires once when the WinForms message queue drains. Rendering only once
-    // would leave the scene frozen between user input events, so we loop here — re-rendering as
-    // long as the queue stays empty — and exit the moment a message arrives so WinForms can
+    // would leave the scene frozen between user input events, so we loop here, re-rendering as
+    // long as the queue stays empty, and exit the moment a message arrives so WinForms can
     // process it. Frame pacing is delegated to the swap-chain present mode: with Fifo (v-sync)
     // TryAcquireFrame blocks until the display is ready, so this loop naturally runs at the
     // display's refresh rate without a software timer capping it.
@@ -159,12 +172,12 @@ protected override void WndProc(ref Message m)
 
     private void RenderOnce()
     {
-        if (this.window is null || this.ClientSize.Width <= 0 || this.ClientSize.Height <= 0)
+        if (this.surface is null || this.framebufferSize.Width <= 0 || this.framebufferSize.Height <= 0)
         {
             return;
         }
 
-        if (!this.window.TryAcquireFrame(out WebGPUWindowFrame<Bgra32>? frame))
+        if (!this.surface.TryAcquireFrame(out WebGPUSurfaceFrame<Bgra32>? frame))
         {
             return;
         }
@@ -180,7 +193,7 @@ private void RenderOnce()
     }
 
     // PeekMessage with wRemoveMsg = 0 (PM_NOREMOVE) asks the OS "is there a message waiting?" without
-    // dequeuing it. Returning 0 means the queue is empty — the canonical "is the app idle right now"
+    // dequeuing it. Returning 0 means the queue is empty, the canonical "is the app idle right now"
     // check used by the WinForms continuous-render idiom. Cheaper than any managed alternative and the
     // only way to tell whether WinForms is about to break out of Application.Idle on the next pump.
     [StructLayout(LayoutKind.Sequential)]

…mples/WebGPUHostedWindowDemo/MainForm.cs …ples/WebGPUHostedSurfaceDemo/MainForm.cssamples/WebGPUHostedWindowDemo/MainForm.cs renamed to samples/WebGPUHostedSurfaceDemo/MainForm.cs samples/WebGPUHostedWindowDemo/MainForm.cs renamed to samples/WebGPUHostedSurfaceDemo/MainForm.cs

@@ -3,15 +3,15 @@
 
 using SixLabors.ImageSharp.Drawing.Processing;
 using SixLabors.ImageSharp.PixelFormats;
-using WebGPUHostedWindowDemo.Controls;
-using WebGPUHostedWindowDemo.Scenes;
+using WebGPUHostedSurfaceDemo.Controls;
+using WebGPUHostedSurfaceDemo.Scenes;
 
-namespace WebGPUHostedWindowDemo;
+namespace WebGPUHostedSurfaceDemo;
 
 /// <summary>
 /// Main window for the sample. A tab control switches between two demo scenes, each hosted by its own
-/// <see cref="WebGPURenderControl"/> instance. This demonstrates that multiple independent hosted windows
-/// can coexist in the same WinForms process without touching Silk, surfaces, or swap-chains in user code.
+/// <see cref="WebGPURenderControl"/> instance. This demonstrates that multiple independent hosted surfaces
+/// can coexist in the same WinForms process without managing surfaces or swapchains in user code.
 /// </summary>
 internal sealed class MainForm : Form
 {
@@ -23,7 +23,7 @@ internal sealed class MainForm : Form
 
     public MainForm()
     {
-        this.Text = "ImageSharp.Drawing WebGPU — Hosted Window Demo";
+        this.Text = "ImageSharp.Drawing WebGPU - Hosted Surface Demo";
         this.ClientSize = new Size(1280, 800);
         this.StartPosition = FormStartPosition.CenterScreen;
         this.BackColor = Color.FromArgb(11, 18, 32);
@@ -86,13 +86,13 @@ public MainForm()
 
     private void OnPaintClock(DrawingCanvas<Bgra32> canvas, TimeSpan delta)
     {
-        Size s = this.clockControl.ClientSize;
+        Size s = this.clockControl.FramebufferSize;
         this.clockScene.Paint(canvas, new SixLabors.ImageSharp.Size(s.Width, s.Height), delta);
     }
 
     private void OnPaintTiger(DrawingCanvas<Bgra32> canvas, TimeSpan delta)
     {
-        Size s = this.tigerControl.ClientSize;
+        Size s = this.tigerControl.FramebufferSize;
         this.tigerScene.Paint(canvas, new SixLabors.ImageSharp.Size(s.Width, s.Height), delta);
         this.tigerStatusLabel.Text = this.tigerScene.StatusText;
     }

…les/WebGPUHostedWindowDemo/MainForm.resx …es/WebGPUHostedSurfaceDemo/MainForm.resxsamples/WebGPUHostedWindowDemo/MainForm.resx renamed to samples/WebGPUHostedSurfaceDemo/MainForm.resx samples/WebGPUHostedWindowDemo/MainForm.resx renamed to samples/WebGPUHostedSurfaceDemo/MainForm.resx

@@ -1,7 +1,7 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
 
-namespace WebGPUHostedWindowDemo;
+namespace WebGPUHostedSurfaceDemo;
 
 internal static class Program
 {

samples/WebGPUHostedWindowDemo/Program.cs …mples/WebGPUHostedSurfaceDemo/Program.cssamples/WebGPUHostedWindowDemo/Program.cs renamed to samples/WebGPUHostedSurfaceDemo/Program.cs samples/WebGPUHostedWindowDemo/Program.cs renamed to samples/WebGPUHostedSurfaceDemo/Program.cs

@@ -0,0 +1,124 @@
+# WebGPU Hosted Surface Demo
+
+`WebGPUHostedSurfaceDemo` shows how to render ImageSharp.Drawing content into a UI object owned by an application framework. The sample uses a WinForms `Control`, but the API shape is intended for any externally-owned native drawable host.
+
+It exists to demonstrate:
+
+- creating a `WebGPUHostedSurface<Bgra32>` from a `WebGPUSurfaceHost`
+- keeping the hosted surface synchronized with the host control's drawable framebuffer size
+- acquiring `WebGPUSurfaceFrame<TPixel>` instances manually
+- drawing with the normal `DrawingCanvas<TPixel>` API
+- presenting by disposing the acquired frame
+
+## Running
+
+```bash
+dotnet run --project samples/WebGPUHostedSurfaceDemo -c Debug
+```
+
+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`
+
+When the sample starts you should see a WinForms window with two tabs:
+
+- `Clock`: a continuously-rendered animated clock scene
+- `Tiger`: an interactive SVG tiger viewer with pan and zoom
+
+## Why This Sample Matters
+
+`WebGPUWindow<TPixel>` owns a top-level native window. `WebGPUHostedSurface<TPixel>` 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:
+
+- the UI object and its lifecycle
+- the platform handle
+- layout and resize events
+- input events
+
+The hosted surface owns:
+
+- the WebGPU surface created for that host
+- swapchain configuration
+- frame acquisition
+- presentation
+- per-frame texture and texture-view handles
+
+## Code Tour
+
+The reusable integration point is [WebGPURenderControl.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/Controls/WebGPURenderControl.cs).
+
+### Surface Creation
+
+`WebGPURenderControl.OnHandleCreated(...)` creates the hosted surface from the WinForms control handle:
+
+```csharp
+this.surface = new WebGPUHostedSurface<Bgra32>(
+    WebGPUSurfaceHost.Win32(
+        this.Handle,
+        Marshal.GetHINSTANCE(typeof(WebGPURenderControl).Module)),
+    initialFramebufferSize);
+```
+
+`WebGPUSurfaceHost` is a small public descriptor for externally-owned native handles. The host keeps ownership of those handles; `WebGPUHostedSurface<TPixel>` only uses them to create and manage the WebGPU rendering surface.
+
+### Resize
+
+`WebGPUHostedSurface<TPixel>.Resize(...)` expects the drawable framebuffer size in pixels:
+
+```csharp
+this.framebufferSize = this.ClientSize;
+this.surface.Resize(new ImageSharpSize(this.framebufferSize.Width, this.framebufferSize.Height));
+```
+
+The sample stores that size as `FramebufferSize` so scene code can draw in the same pixel coordinate space as the acquired frame.
+
+### Frame Acquisition
+
+`RenderOnce()` acquires a frame, invokes user drawing code, and disposes the frame:
+
+```csharp
+if (!this.surface.TryAcquireFrame(out WebGPUSurfaceFrame<Bgra32>? frame))
+{
+    return;
+}
+
+using (frame)
+{
+    this.PaintFrame?.Invoke(frame.Canvas, delta);
+}
+```
+
+Disposing the frame flushes pending canvas work, presents the surface texture, and releases the per-frame WebGPU handles.
+
+### Rendering Loop
+
+The sample uses `Application.Idle` for continuous rendering. While the WinForms message queue is empty, the control renders frames. When input, resize, or other window messages arrive, the loop exits so WinForms can process them.
+
+Frame pacing is delegated to the present mode. With the default `WebGPUPresentMode.Fifo`, frame acquisition naturally waits for display presentation instead of using a separate software timer.
+
+## Scene Code
+
+[MainForm.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/MainForm.cs) creates two independent `WebGPURenderControl` instances, one per tab. Each control owns its own hosted surface.
+
+The scenes are deliberately ordinary canvas code:
+
+- [ClockScene.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/Scenes/ClockScene.cs): animated vector clock
+- [TigerViewerScene.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/Scenes/TigerViewerScene.cs): pan and zoom SVG tiger viewer
+
+Each scene receives:
+
+- `DrawingCanvas<Bgra32>` for the acquired frame
+- the current framebuffer size
+- elapsed time since the previous frame
+
+## Files
+
+- [WebGPURenderControl.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/Controls/WebGPURenderControl.cs): reusable WinForms hosted-surface control
+- [MainForm.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/MainForm.cs): tabs and scene wiring
+- [ClockScene.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/Scenes/ClockScene.cs): clock scene
+- [TigerViewerScene.cs](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/Scenes/TigerViewerScene.cs): tiger viewer scene
+- [WebGPUHostedSurfaceDemo.csproj](d:/GitHub/SixLabors/ImageSharp.Drawing/samples/WebGPUHostedSurfaceDemo/WebGPUHostedSurfaceDemo.csproj): sample project file

…tedWindowDemo/Properties/AssemblyInfo.cs …edSurfaceDemo/Properties/AssemblyInfo.cssamples/WebGPUHostedWindowDemo/Properties/AssemblyInfo.cs renamed to samples/WebGPUHostedSurfaceDemo/Properties/AssemblyInfo.cs samples/WebGPUHostedWindowDemo/Properties/AssemblyInfo.cs renamed to samples/WebGPUHostedSurfaceDemo/Properties/AssemblyInfo.cs

@@ -22,7 +22,7 @@
 using SystemFonts = SixLabors.Fonts.SystemFonts;
 using VerticalAlignment = SixLabors.Fonts.VerticalAlignment;
 
-namespace WebGPUHostedWindowDemo.Scenes;
+namespace WebGPUHostedSurfaceDemo.Scenes;
 
 /// <summary>
 /// Animated analog clock. Validates continuous render, curves, thin-stroke antialiasing, and text rendering.

samples/WebGPUHostedSurfaceDemo/README.md

@@ -5,7 +5,7 @@
 using SixLabors.ImageSharp.PixelFormats;
 using Size = SixLabors.ImageSharp.Size;
 
-namespace WebGPUHostedWindowDemo.Scenes;
+namespace WebGPUHostedSurfaceDemo.Scenes;
 
 /// <summary>
 /// Base class for a demo scene rendered into a shared <see cref="WebGPURenderControl"/>.
@@ -21,7 +21,7 @@ internal abstract class RenderScene
     /// <summary>
     /// Draws the scene into <paramref name="canvas"/> for the current frame.
     /// </summary>
-    /// <param name="canvas">The per-frame drawing canvas bound to the hosted window's swap-chain texture.</param>
+    /// <param name="canvas">The per-frame drawing canvas bound to the hosted surface's swap-chain texture.</param>
     /// <param name="viewportSize">The framebuffer size in pixels.</param>
     /// <param name="deltaTime">Elapsed time since the previous frame.</param>
     public abstract void Paint(DrawingCanvas<Bgra32> canvas, Size viewportSize, TimeSpan deltaTime);