Cleanup API and fix demo FPS display

Author: JimBobSquarePants

ImageSharp.Drawing.Samples.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 17
-VisualStudioVersion = 17.0.31903.59
+# Visual Studio Version 18
+VisualStudioVersion = 18.4.11626.88 stable
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{5D20AA90-6969-D8BD-9DCD-8634F4692FDA}"
 EndProject
@@ -113,4 +113,8 @@ Global
 		{AEFE7C59-5D1C-4F14-A83F-0FD665130FA3} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{0AF23A97-CD73-409A-AA29-D214AA400AB0} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 	EndGlobalSection
+	GlobalSection(SharedMSBuildProjectFiles) = preSolution
+		shared-infrastructure\src\SharedInfrastructure\SharedInfrastructure.projitems*{042b144e-5444-4b88-b4f2-038e54fc25d0}*SharedItemsImports = 5
+		shared-infrastructure\src\SharedInfrastructure\SharedInfrastructure.projitems*{439c7ccb-78f0-4f24-9d7f-6d6659495def}*SharedItemsImports = 5
+	EndGlobalSection
 EndGlobal

samples/DrawingBackendBenchmark/WebGpuBenchmarkBackend.cs

@@ -50,12 +50,18 @@ public BenchmarkRenderResult Render(ReadOnlySpan<VisualLine> lines, int width, i
 
         stopwatch.Stop();
 
-        Image<Bgra32>? preview = capturePreview ? renderTarget.Readback() : null;
+        Image<Bgra32>? preview = null;
+        string? readbackError = null;
+        if (capturePreview && !renderTarget.TryReadback(out preview, out readbackError))
+        {
+            preview = null;
+        }
+
         return new BenchmarkRenderResult(
             stopwatch.Elapsed.TotalMilliseconds,
             preview,
             renderTarget.Graphics.Backend.DiagnosticLastFlushUsedGPU,
-            renderTarget.Graphics.Backend.DiagnosticLastSceneFailure);
+            readbackError ?? renderTarget.Graphics.Backend.DiagnosticLastSceneFailure);
     }
 
     /// <summary>

samples/WebGPUWindowDemo/Program.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
 
+using System.Diagnostics;
 using System.Numerics;
 using SixLabors.Fonts;
 using SixLabors.ImageSharp;
@@ -41,14 +42,13 @@ public static void Main()
     private sealed class DemoApp
     {
         private const int BallCount = 1000;
+        private static readonly TimeSpan FpsUpdateInterval = TimeSpan.FromSeconds(1);
 
         private readonly WebGPUWindow<Bgra32> window;
         private readonly Random rng = new(42);
+        private readonly Stopwatch fpsWindow = Stopwatch.StartNew();
         private Ball[] balls = [];
         private int frameCount;
-        private double fpsElapsed;
-        private double fpsSum;
-        private double fpsSumSquares;
         private IPathCollection scrollPaths = new PathCollection();
         private float scrollOffset;
         private float scrollTextHeight;
@@ -126,11 +126,11 @@ private void InitializeScene()
         /// <summary>
         /// Advances the animation state for the next frame.
         /// </summary>
-        /// <param name="deltaTime">Elapsed time since the previous update, in seconds.</param>
-        private void OnUpdate(double deltaTime)
+        /// <param name="deltaTime">Elapsed time since the previous update.</param>
+        private void OnUpdate(TimeSpan deltaTime)
         {
             Size framebufferSize = this.window.FramebufferSize;
-            float dt = (float)deltaTime;
+            float dt = (float)deltaTime.TotalSeconds;
             for (int i = 0; i < this.balls.Length; i++)
             {
                 this.balls[i].Update(dt, framebufferSize.Width, framebufferSize.Height);
@@ -152,32 +152,24 @@ private void OnRender(WebGPUWindowFrame<Bgra32> frame)
             DrawingCanvas<Bgra32> canvas = frame.Canvas;
             canvas.Fill(Brushes.Solid(Color.FromPixel(new Bgra32(30, 30, 40, 255))));
 
-            this.DrawScrollingText(canvas, frame.FramebufferSize.Width, frame.FramebufferSize.Height);
-
             for (int i = 0; i < this.balls.Length; i++)
             {
                 ref Ball ball = ref this.balls[i];
                 EllipsePolygon ellipse = new(ball.X, ball.Y, ball.Radius);
                 canvas.Fill(Brushes.Solid(ball.Color), ellipse);
             }
 
+            this.DrawScrollingText(canvas, frame.FramebufferSize.Width, frame.FramebufferSize.Height);
+
             this.frameCount++;
-            double frameSeconds = frame.DeltaTime.TotalSeconds;
-            this.fpsElapsed += frameSeconds;
-            double frameFps = frameSeconds > 0D ? 1D / frameSeconds : 0D;
-            this.fpsSum += frameFps;
-            this.fpsSumSquares += frameFps * frameFps;
-            if (this.fpsElapsed >= 1D)
+            TimeSpan elapsed = this.fpsWindow.Elapsed;
+            if (elapsed >= FpsUpdateInterval)
             {
-                double meanFps = this.fpsSum / this.frameCount;
-                double variance = Math.Max(0D, (this.fpsSumSquares / this.frameCount) - (meanFps * meanFps));
-                double stdDevFps = Math.Sqrt(variance);
-                double frameTimeMs = frame.DeltaTime.TotalMilliseconds;
-                this.window.Title = $"ImageSharp.Drawing WebGPU Demo - Current: {frameTimeMs:F1} ms / {frameFps:F1} FPS | Mean: {meanFps:F1} FPS | StdDev: {stdDevFps:F1}";
+                double fps = this.frameCount / elapsed.TotalSeconds;
+                double frameTimeMs = elapsed.TotalMilliseconds / this.frameCount;
+                this.window.Title = $"ImageSharp.Drawing WebGPU Demo - {frameTimeMs:F1} ms / {fps:F1} FPS";
                 this.frameCount = 0;
-                this.fpsElapsed = 0;
-                this.fpsSum = 0;
-                this.fpsSumSquares = 0;
+                this.fpsWindow.Restart();
             }
         }
 

samples/WebGPUWindowDemo/README.md

@@ -92,7 +92,7 @@ The important pattern here is that text shaping is not done every frame. The sam
 this.window.Update += this.OnUpdate;
 ```
 
-`OnUpdate(double deltaTime)` performs simulation only:
+`OnUpdate(TimeSpan deltaTime)` performs simulation only:
 
 - each ball advances by `velocity * dt`
 - each ball reflects off the framebuffer edges

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

@@ -2,6 +2,7 @@
 // Licensed under the Six Labors Split License.
 
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using Silk.NET.WebGPU;
@@ -26,6 +27,28 @@ public bool TryReadRegion<TPixel>(
         Rectangle sourceRectangle,
         Buffer2DRegion<TPixel> destination)
         where TPixel : unmanaged, IPixel<TPixel>
+        => this.TryReadRegion(configuration, target, sourceRectangle, destination, out _);
+
+    /// <summary>
+    /// Attempts to read source pixels from the target into a caller-provided buffer.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    /// <param name="configuration">The active processing configuration.</param>
+    /// <param name="target">The target frame.</param>
+    /// <param name="sourceRectangle">Source rectangle in target-local coordinates.</param>
+    /// <param name="destination">
+    /// The caller-allocated region to receive the pixel data.
+    /// Must be at least as large as <paramref name="sourceRectangle"/> (clamped to target bounds).
+    /// </param>
+    /// <param name="error">Receives the failure reason when readback cannot complete.</param>
+    /// <returns><see langword="true"/> when readback succeeds; otherwise <see langword="false"/>.</returns>
+    public bool TryReadRegion<TPixel>(
+        Configuration configuration,
+        ICanvasFrame<TPixel> target,
+        Rectangle sourceRectangle,
+        Buffer2DRegion<TPixel> destination,
+        [NotNullWhen(false)] out string? error)
+        where TPixel : unmanaged, IPixel<TPixel>
     {
         this.ThrowIfDisposed();
         Guard.NotNull(configuration, nameof(configuration));
@@ -39,12 +62,14 @@ public bool TryReadRegion<TPixel>(
             capability.Queue == 0 ||
             capability.TargetTexture == 0)
         {
+            error = "Readback is only available for native WebGPU targets with valid device, queue, and texture handles.";
             return false;
         }
 
         if (!TryGetCompositeTextureFormat<TPixel>(out WebGPUTextureFormatId expectedFormat, out FeatureName requiredFeature) ||
             expectedFormat != capability.TargetFormat)
         {
+            error = $"Pixel type '{typeof(TPixel).Name}' is not compatible with target format '{capability.TargetFormat}'.";
             return false;
         }
 
@@ -60,6 +85,7 @@ public bool TryReadRegion<TPixel>(
 
         if (source.Width <= 0 || source.Height <= 0)
         {
+            error = "The requested source rectangle does not intersect the target bounds.";
             return false;
         }
 
@@ -70,6 +96,7 @@ public bool TryReadRegion<TPixel>(
         if (requiredFeature != FeatureName.Undefined
             && !WebGPURuntime.GetOrCreateDeviceState(api, device).HasFeature(requiredFeature))
         {
+            error = $"The target device does not support required feature '{requiredFeature}' for pixel type '{typeof(TPixel).Name}'.";
             return false;
         }
 
@@ -97,13 +124,15 @@ public bool TryReadRegion<TPixel>(
             readbackBuffer = api.DeviceCreateBuffer(device, in bufferDescriptor);
             if (readbackBuffer is null)
             {
+                error = "WebGPU.DeviceCreateBuffer returned null for readback.";
                 return false;
             }
 
             CommandEncoderDescriptor encoderDescriptor = default;
             commandEncoder = api.DeviceCreateCommandEncoder(device, in encoderDescriptor);
             if (commandEncoder is null)
             {
+                error = "WebGPU.DeviceCreateCommandEncoder returned null.";
                 return false;
             }
 
@@ -134,6 +163,7 @@ public bool TryReadRegion<TPixel>(
             commandBuffer = api.CommandEncoderFinish(commandEncoder, in commandBufferDescriptor);
             if (commandBuffer is null)
             {
+                error = "WebGPU.CommandEncoderFinish returned null.";
                 return false;
             }
 
@@ -157,13 +187,15 @@ void Callback(BufferMapAsyncStatus status, void* userData)
             api.BufferMapAsync(readbackBuffer, MapMode.Read, 0, (nuint)readbackByteCount, callback, null);
             if (!WaitForMapSignal(lease.WgpuExtension, device, mapReady) || mapStatus != BufferMapAsyncStatus.Success)
             {
+                error = $"WebGPU readback map failed with status '{mapStatus}'.";
                 return false;
             }
 
             void* mapped = api.BufferGetConstMappedRange(readbackBuffer, 0, (nuint)readbackByteCount);
             if (mapped is null)
             {
                 api.BufferUnmap(readbackBuffer);
+                error = "WebGPU.BufferGetConstMappedRange returned null.";
                 return false;
             }
 
@@ -181,6 +213,7 @@ void Callback(BufferMapAsyncStatus status, void* userData)
                         .CopyTo(MemoryMarshal.AsBytes(destination.DangerousGetRowSpan(y)));
                 }
 
+                error = null;
                 return true;
             }
             finally

src/ImageSharp.Drawing.WebGPU/WebGPUDrawingBackend.cs

@@ -14,6 +14,9 @@ namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 /// <remarks>
 /// Scene composition uses a staged WebGPU raster path when the target surface and pixel format are supported,
 /// and falls back to <see cref="DefaultDrawingBackend"/> otherwise.
+/// Public diagnostic properties on this type describe only the most recent flush executed by this backend
+/// instance. They are lightweight inspection state for debugging, tests, and benchmarks, and they are
+/// overwritten by the next flush.
 /// </remarks>
 public sealed unsafe partial class WebGPUDrawingBackend : IDrawingBackend, IDisposable
 {
@@ -72,21 +75,39 @@ public WebGPUDrawingBackend()
     /// <summary>
     /// Gets a value indicating whether the last flush completed on the staged path.
     /// </summary>
+    /// <remarks>
+    /// This value describes only the most recent call to <see cref="FlushCompositions{TPixel}(Configuration, ICanvasFrame{TPixel}, CompositionScene)"/>
+    /// on this backend instance. It is overwritten by the next flush.
+    /// </remarks>
     public bool DiagnosticLastFlushUsedGPU => this.TestingLastFlushUsedGPU;
 
     /// <summary>
     /// Gets the last staged-scene creation or dispatch failure that forced CPU fallback.
     /// </summary>
+    /// <remarks>
+    /// This value describes only the most recent call to <see cref="FlushCompositions{TPixel}(Configuration, ICanvasFrame{TPixel}, CompositionScene)"/>
+    /// on this backend instance. It is reset at the start of each flush and overwritten by the next failure.
+    /// A <see langword="null"/> value means no failure reason was recorded for the most recent flush.
+    /// </remarks>
     public string? DiagnosticLastSceneFailure => this.TestingLastGPUInitializationFailure;
 
     /// <summary>
     /// Gets a value indicating whether the last staged flush used the chunked oversized-scene path.
     /// </summary>
+    /// <remarks>
+    /// This value describes only the most recent call to <see cref="FlushCompositions{TPixel}(Configuration, ICanvasFrame{TPixel}, CompositionScene)"/>
+    /// on this backend instance. It is overwritten by the next flush.
+    /// </remarks>
     public bool DiagnosticLastFlushUsedChunking => this.TestingLastFlushUsedChunking;
 
     /// <summary>
     /// Gets the chunkable binding-limit failure that selected the chunked oversized-scene path for the last staged flush.
     /// </summary>
+    /// <remarks>
+    /// This value describes only the most recent call to <see cref="FlushCompositions{TPixel}(Configuration, ICanvasFrame{TPixel}, CompositionScene)"/>
+    /// on this backend instance. When the most recent flush did not use the chunked path, this property returns
+    /// the default <c>None</c> value from <see cref="WebGPUSceneDispatch.BindingLimitBuffer"/>.
+    /// </remarks>
     public string DiagnosticLastChunkingBindingFailure => this.TestingLastChunkingBindingFailure.ToString();
 
     /// <inheritdoc />

src/ImageSharp.Drawing.WebGPU/WebGPUNativeSurfaceFactory.cs

@@ -39,6 +39,7 @@ public static NativeSurface Create<TPixel>(
         ValidateCommon(
             deviceHandle,
             queueHandle,
+            targetTextureHandle,
             targetTextureViewHandle,
             width,
             height);
@@ -63,6 +64,7 @@ public static NativeSurface Create<TPixel>(
     private static void ValidateCommon(
         nint deviceHandle,
         nint queueHandle,
+        nint targetTextureHandle,
         nint targetTextureViewHandle,
         int width,
         int height)
@@ -77,6 +79,11 @@ private static void ValidateCommon(
             throw new ArgumentOutOfRangeException(nameof(queueHandle), "Queue handle must be non-zero.");
         }
 
+        if (targetTextureHandle == 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(targetTextureHandle), "Texture handle must be non-zero.");
+        }
+
         if (targetTextureViewHandle == 0)
         {
             throw new ArgumentOutOfRangeException(nameof(targetTextureViewHandle), "Texture view handle must be non-zero.");