Update WebGPU docs.

Author: JimBobSquarePants

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

@@ -6,8 +6,10 @@
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 
 /// <summary>
-/// A WebGPU drawing context for a specific <typeparamref name="TPixel"/> that owns the drawing backend and device handles used to create frames, canvases, and render targets.
-/// Use this type when you already own the device and queue, or when you want direct control over how ImageSharp.Drawing wraps external WebGPU textures.
+/// Binds ImageSharp.Drawing's WebGPU backend to an externally-owned device and queue.
+/// Use <see cref="CreateCanvas(nint, nint, WebGPUTextureFormatId, int, int, DrawingOptions)"/> to render into a
+/// host-supplied texture (typically a swap-chain back buffer for UI-framework embedding), or
+/// <see cref="CreateRenderTarget(int, int)"/> to allocate an offscreen target on the same device.
 /// </summary>
 /// <typeparam name="TPixel">The canvas pixel format.</typeparam>
 public sealed class WebGPUDeviceContext<TPixel> : IDisposable
@@ -129,6 +131,10 @@ internal WebGPUDeviceContext(Configuration configuration, WebGPUDeviceHandle dev
 
     /// <summary>
     /// Gets the WebGPU drawing backend owned by this context.
+    /// Use this to inspect per-flush diagnostics
+    /// (<see cref="WebGPUDrawingBackend.DiagnosticLastFlushUsedGPU"/>,
+    /// <see cref="WebGPUDrawingBackend.DiagnosticLastSceneFailure"/>) when you need to confirm whether the staged
+    /// GPU path executed or fell back to the CPU backend.
     /// </summary>
     public WebGPUDrawingBackend Backend { get; }
 
@@ -158,14 +164,21 @@ public WebGPURenderTarget<TPixel> CreateRenderTarget(int width, int height)
     }
 
     /// <summary>
-    /// Creates a native-only frame over an externally-owned WebGPU texture and view.
+    /// Creates a native-only frame over an externally-owned WebGPU texture and view — typically the per-frame
+    /// swap-chain back buffer obtained from <c>wgpuSurfaceGetCurrentTexture</c> on a host-owned surface.
     /// </summary>
     /// <param name="textureHandle">The external WebGPU texture handle.</param>
     /// <param name="textureViewHandle">The external WebGPU texture-view handle.</param>
-    /// <param name="format">The texture format identifier.</param>
+    /// <param name="format">The texture format identifier. Must match the format expected for <typeparamref name="TPixel"/>.</param>
     /// <param name="width">The frame width in pixels.</param>
     /// <param name="height">The frame height in pixels.</param>
     /// <returns>A native-only canvas frame.</returns>
+    /// <remarks>
+    /// The caller retains ownership of the texture and view; this context does not release them.
+    /// The texture must have been created with <c>RenderAttachment | TextureBinding</c> usage.
+    /// Both handles are typically valid only for the current frame: dispose any consumer of the returned frame
+    /// before the host calls <c>wgpuSurfacePresent</c>, then re-acquire on the next frame.
+    /// </remarks>
     public NativeCanvasFrame<TPixel> CreateFrame(
         nint textureHandle,
         nint textureViewHandle,
@@ -175,14 +188,20 @@ public NativeCanvasFrame<TPixel> CreateFrame(
         => this.CreateFrame(CreateExternalTextureHandle(textureHandle), CreateExternalTextureViewHandle(textureViewHandle), format, width, height);
 
     /// <summary>
-    /// Creates a drawing canvas over an externally-owned WebGPU texture.
+    /// Creates a drawing canvas that renders directly into an externally-owned WebGPU texture — typically the per-frame
+    /// swap-chain back buffer obtained from <c>wgpuSurfaceGetCurrentTexture</c> on a host-owned surface.
     /// </summary>
     /// <param name="textureHandle">The external WebGPU texture handle.</param>
     /// <param name="textureViewHandle">The external WebGPU texture-view handle.</param>
-    /// <param name="format">The texture format identifier.</param>
+    /// <param name="format">The texture format identifier. Must match the format expected for <typeparamref name="TPixel"/>.</param>
     /// <param name="width">The frame width in pixels.</param>
     /// <param name="height">The frame height in pixels.</param>
     /// <returns>A drawing canvas targeting the external texture.</returns>
+    /// <remarks>
+    /// The caller retains ownership of the texture and view; this context does not release them.
+    /// The texture must have been created with <c>RenderAttachment | TextureBinding</c> usage.
+    /// Dispose the returned canvas before the host calls <c>wgpuSurfacePresent</c>, then create a new canvas on the next frame.
+    /// </remarks>
     public DrawingCanvas<TPixel> CreateCanvas(
         nint textureHandle,
         nint textureViewHandle,
@@ -192,15 +211,21 @@ public DrawingCanvas<TPixel> CreateCanvas(
         => this.CreateCanvas(CreateExternalTextureHandle(textureHandle), CreateExternalTextureViewHandle(textureViewHandle), format, width, height, new DrawingOptions());
 
     /// <summary>
-    /// Creates a drawing canvas over an externally-owned WebGPU texture.
+    /// Creates a drawing canvas that renders directly into an externally-owned WebGPU texture — typically the per-frame
+    /// swap-chain back buffer obtained from <c>wgpuSurfaceGetCurrentTexture</c> on a host-owned surface.
     /// </summary>
     /// <param name="textureHandle">The external WebGPU texture handle.</param>
     /// <param name="textureViewHandle">The external WebGPU texture-view handle.</param>
-    /// <param name="format">The texture format identifier.</param>
+    /// <param name="format">The texture format identifier. Must match the format expected for <typeparamref name="TPixel"/>.</param>
     /// <param name="width">The frame width in pixels.</param>
     /// <param name="height">The frame height in pixels.</param>
     /// <param name="options">The initial drawing options.</param>
     /// <returns>A drawing canvas targeting the external texture.</returns>
+    /// <remarks>
+    /// The caller retains ownership of the texture and view; this context does not release them.
+    /// The texture must have been created with <c>RenderAttachment | TextureBinding</c> usage.
+    /// Dispose the returned canvas before the host calls <c>wgpuSurfacePresent</c>, then create a new canvas on the next frame.
+    /// </remarks>
     public DrawingCanvas<TPixel> CreateCanvas(
         nint textureHandle,
         nint textureViewHandle,

src/ImageSharp.Drawing.WebGPU/WebGPUNativeSurfaceFactory.cs

@@ -6,8 +6,14 @@
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 
 /// <summary>
-/// Creates <see cref="NativeSurface"/> instances for WebGPU targets.
+/// Low-level escape hatch for constructing a <see cref="NativeSurface"/> directly from raw WebGPU handles.
 /// </summary>
+/// <remarks>
+/// Most callers should use <see cref="WebGPUDeviceContext{TPixel}.CreateCanvas(nint, nint, WebGPUTextureFormatId, int, int, DrawingOptions)"/>
+/// or <see cref="WebGPUDeviceContext{TPixel}.CreateFrame(nint, nint, WebGPUTextureFormatId, int, int)"/> instead, which wrap this factory
+/// and validate handle/format compatibility against the canvas pixel type. Use this factory only when you need a
+/// <see cref="NativeSurface"/> independent of <see cref="WebGPUDeviceContext{TPixel}"/>.
+/// </remarks>
 public static class WebGPUNativeSurfaceFactory
 {
     /// <summary>

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

@@ -13,6 +13,11 @@ namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 /// <see cref="Readback"/> or <see cref="ReadbackInto(Image{TPixel})"/>.
 /// </summary>
 /// <typeparam name="TPixel">The canvas pixel format.</typeparam>
+/// <remarks>
+/// The constructors on this type allocate a target on the shared process WebGPU device. To allocate offscreen
+/// targets against an externally-owned device (for example, a host UI framework's WebGPU device), call
+/// <see cref="WebGPUDeviceContext{TPixel}.CreateRenderTarget(int, int)"/> instead.
+/// </remarks>
 public sealed class WebGPURenderTarget<TPixel> : IDisposable
     where TPixel : unmanaged, IPixel<TPixel>
 {
@@ -94,12 +99,16 @@ private WebGPURenderTarget(WebGPUDeviceContext<TPixel> graphics, bool ownsGraphi
     public WebGPUDeviceContext<TPixel> Graphics { get; }
 
     /// <summary>
-    /// Gets the wrapped native surface.
+    /// Gets the wrapped native surface backing this render target.
+    /// Exposed for advanced interop with <see cref="WebGPUDrawingBackend"/> APIs that consume a native surface;
+    /// most callers do not need to touch this directly.
     /// </summary>
     public NativeSurface Surface { get; }
 
     /// <summary>
     /// Gets the native-only frame over this render target.
+    /// Pass this to <see cref="WebGPUDrawingBackend.TryReadRegion{TPixel}(Configuration, ICanvasFrame{TPixel}, Rectangle, Buffer2DRegion{TPixel})"/>
+    /// when you need to read back into a caller-owned region instead of using <see cref="Readback"/>.
     /// </summary>
     public NativeCanvasFrame<TPixel> NativeFrame { get; }
 

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

@@ -13,10 +13,18 @@
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 
 /// <summary>
-/// A WebGPU-backed window that provides a <see cref="DrawingCanvas{TPixel}"/> for each frame.
-/// Use <see cref="Run(Action{DrawingCanvas{TPixel}})"/> when you want the window to drive rendering for you, or <see cref="TryAcquireFrame(TimeSpan, out WebGPUWindowFrame{TPixel}?)"/> when you need to drive the frame loop yourself.
+/// A self-contained WebGPU-backed window that owns the platform window, the WebGPU device and queue, the surface
+/// and swap chain, and the per-frame texture acquire/present cycle, exposing a <see cref="DrawingCanvas{TPixel}"/>
+/// for each frame. Use <see cref="Run(Action{DrawingCanvas{TPixel}})"/> to let the window drive rendering, or
+/// <see cref="TryAcquireFrame(TimeSpan, out WebGPUWindowFrame{TPixel}?)"/> to drive the frame loop yourself.
 /// </summary>
 /// <typeparam name="TPixel">The canvas pixel format.</typeparam>
+/// <remarks>
+/// Use this type when ImageSharp.Drawing owns the application's window. To render into a window owned by a host
+/// application or UI framework, wrap the host's device and queue with <see cref="WebGPUDeviceContext{TPixel}"/>
+/// and pass the host's per-frame swap-chain texture to
+/// <see cref="WebGPUDeviceContext{TPixel}.CreateCanvas(nint, nint, WebGPUTextureFormatId, int, int, DrawingOptions)"/> instead.
+/// </remarks>
 public sealed unsafe class WebGPUWindow<TPixel> : IDisposable
     where TPixel : unmanaged, IPixel<TPixel>
 {