Use WebGPUEnvironmentError for probe results

Author: JimBobSquarePants

samples/DrawingBackendBenchmark/README.md

@@ -15,7 +15,7 @@ Depending on what the machine can initialize, the sample can show:
 - `SkiaSharp (GPU)`: Skia using a GPU-backed `GRContext` when the hidden GL host is available
 - `WebGPU`: the offscreen `ImageSharp.Drawing.WebGPU` backend
 
-The sample always starts with the CPU and Skia CPU paths. The WebGPU backend is added only when `WebGPUEnvironment.TryProbeComputePipelineSupport(...)` succeeds. The Skia GPU backend is added once the hidden `SKGLControl` has produced a usable `GRContext`.
+The sample always starts with the CPU and Skia CPU paths. The WebGPU backend is added only when `WebGPUEnvironment.ProbeComputePipelineSupport()` returns `WebGPUEnvironmentError.Success`. The Skia GPU backend is added once the hidden `SKGLControl` has produced a usable `GRContext`.
 
 ## What the UI shows
 
@@ -77,7 +77,7 @@ 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.TryProbeComputePipelineSupport(...)`
+- 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 reads back the final frame only when the UI requests the last-iteration preview

samples/DrawingBackendBenchmark/WebGpuBenchmarkBackend.cs

@@ -23,9 +23,11 @@ private WebGpuBenchmarkBackend()
 
     public static bool TryCreate([NotNullWhen(true)] out WebGpuBenchmarkBackend? result, [NotNullWhen(false)] out string? error)
     {
-        if (!WebGPUEnvironment.TryProbeComputePipelineSupport(out error))
+        WebGPUEnvironmentError probeError = WebGPUEnvironment.ProbeComputePipelineSupport();
+        if (probeError != WebGPUEnvironmentError.Success)
         {
             result = null;
+            error = $"WebGPU unavailable: {probeError}.";
             return false;
         }
 

src/ImageSharp.Drawing.WebGPU/RemoteExecutor/Program.cs

@@ -25,7 +25,7 @@ private static int Main(string[] args)
 
         return methodName switch
         {
-            nameof(WebGPURuntime.ProbeComputePipelineSupport) => WebGPURuntime.ProbeComputePipelineSupport(),
+            nameof(WebGPURuntime.RunComputePipelineSupportProbe) => WebGPURuntime.RunComputePipelineSupportProbe(),
             _ => -1
         };
     }

src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND.md

@@ -28,8 +28,8 @@ Those types all exist to get a `DrawingCanvas<TPixel>` over a native WebGPU targ
 
 The support probes also live outside the backend:
 
-- `WebGPUEnvironment.TryProbeAvailability(...)` checks whether the library-managed WebGPU device and queue can be acquired
-- `WebGPUEnvironment.TryProbeComputePipelineSupport(...)` runs the crash-isolated trivial compute-pipeline probe
+- `WebGPUEnvironment.ProbeAvailability()` checks whether the library-managed WebGPU device and queue can be acquired
+- `WebGPUEnvironment.ProbeComputePipelineSupport()` runs the crash-isolated trivial compute-pipeline probe
 
 That split keeps support probing separate from flush execution. `WebGPUDrawingBackend` is the flush executor, not the public support API. The WebGPU constructors create their objects directly; callers use `WebGPUEnvironment` when they want explicit preflight checks.
 

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

@@ -36,11 +36,11 @@ public WebGPUDeviceContext(Configuration configuration)
 
         try
         {
-            if (!WebGPURuntime.TryGetOrCreateDevice(out WebGPUDeviceHandle? deviceHandle, out WebGPUQueueHandle? queueHandle, out string? error)
+            if (!WebGPURuntime.TryGetOrCreateDevice(out WebGPUDeviceHandle? deviceHandle, out WebGPUQueueHandle? queueHandle, out WebGPUEnvironmentError errorCode)
                 || deviceHandle is null
                 || queueHandle is null)
             {
-                throw new InvalidOperationException(error);
+                throw new InvalidOperationException(WebGPURuntime.CreateEnvironmentExceptionMessage(errorCode));
             }
 
             this.DeviceHandle = deviceHandle;

src/ImageSharp.Drawing.WebGPU/WebGPUEnvironment.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
 
-using System.Diagnostics.CodeAnalysis;
-
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 
 /// <summary>
@@ -12,18 +10,22 @@ namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 public static class WebGPUEnvironment
 {
     /// <summary>
-    /// Tries to acquire the library-managed WebGPU device and queue.
+    /// Probes whether the library-managed WebGPU device and queue are available.
     /// </summary>
-    /// <param name="error">Receives the failure reason when the probe fails.</param>
-    /// <returns><see langword="true"/> when the library-managed WebGPU device and queue are available; otherwise, <see langword="false"/>.</returns>
-    public static bool TryProbeAvailability([NotNullWhen(false)] out string? error)
-        => WebGPURuntime.TryProbeAvailability(out error);
+    /// <returns>
+    /// <see cref="WebGPUEnvironmentError.Success"/> when the library-managed WebGPU device and queue are available;
+    /// otherwise, the stable failure code describing why the probe failed.
+    /// </returns>
+    public static WebGPUEnvironmentError ProbeAvailability()
+        => WebGPURuntime.ProbeAvailability();
 
     /// <summary>
-    /// Tries to create a trivial compute pipeline using the library-managed WebGPU device.
+    /// Probes whether the library-managed WebGPU device can create a trivial compute pipeline.
     /// </summary>
-    /// <param name="error">Receives the failure reason when the probe fails.</param>
-    /// <returns><see langword="true"/> when compute pipeline creation succeeds; otherwise, <see langword="false"/>.</returns>
-    public static bool TryProbeComputePipelineSupport([NotNullWhen(false)] out string? error)
-        => WebGPURuntime.TryProbeComputePipelineSupport(out error);
+    /// <returns>
+    /// <see cref="WebGPUEnvironmentError.Success"/> when compute pipeline creation succeeds;
+    /// otherwise, the stable failure code describing why the probe failed.
+    /// </returns>
+    public static WebGPUEnvironmentError ProbeComputePipelineSupport()
+        => WebGPURuntime.ProbeComputePipelineSupport();
 }

src/ImageSharp.Drawing.WebGPU/WebGPUEnvironmentError.cs

@@ -0,0 +1,69 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+/// <summary>
+/// Error codes returned by <see cref="WebGPUEnvironment"/> probe methods.
+/// </summary>
+/// <remarks>
+/// <see cref="Success"/> is the only successful result. All other values describe one stable
+/// failure case that callers can branch on without parsing diagnostic strings.
+/// </remarks>
+public enum WebGPUEnvironmentError
+{
+    /// <summary>
+    /// The probe succeeded.
+    /// </summary>
+    Success = 0,
+
+    /// <summary>
+    /// The shared WebGPU API loader or required extension could not be initialized.
+    /// </summary>
+    ApiInitializationFailed,
+
+    /// <summary>
+    /// The runtime could not create a WebGPU instance.
+    /// </summary>
+    InstanceCreationFailed,
+
+    /// <summary>
+    /// The adapter request callback did not complete before the timeout expired.
+    /// </summary>
+    AdapterRequestTimedOut,
+
+    /// <summary>
+    /// The runtime failed to acquire a WebGPU adapter.
+    /// </summary>
+    AdapterRequestFailed,
+
+    /// <summary>
+    /// The device request callback did not complete before the timeout expired.
+    /// </summary>
+    DeviceRequestTimedOut,
+
+    /// <summary>
+    /// The runtime failed to acquire a WebGPU device.
+    /// </summary>
+    DeviceRequestFailed,
+
+    /// <summary>
+    /// The runtime acquired a device but could not retrieve its default queue.
+    /// </summary>
+    QueueAcquisitionFailed,
+
+    /// <summary>
+    /// The runtime could not provision the shared device/queue pair for an unspecified reason.
+    /// </summary>
+    DeviceAcquisitionFailed,
+
+    /// <summary>
+    /// The isolated compute-pipeline probe ran to completion and reported that compute pipeline creation failed.
+    /// </summary>
+    ComputePipelineCreationFailed,
+
+    /// <summary>
+    /// The isolated compute-pipeline probe process terminated before it could report a normal result.
+    /// </summary>
+    ComputePipelineProbeProcessFailed,
+}