Refactor WebGPU resource allocation to throw

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WebGPURenderTargetAllocation.cs

@@ -1,7 +1,6 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
 
-using System.Diagnostics.CodeAnalysis;
 using Silk.NET.WebGPU;
 using SixLabors.ImageSharp.PixelFormats;
 
@@ -13,66 +12,45 @@ namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 internal static unsafe class WebGPURenderTargetAllocation
 {
     /// <summary>
-    /// Tries to allocate a WebGPU render target for the specified pixel type.
+    /// Allocates a WebGPU render target for the specified pixel type.
     /// </summary>
     /// <typeparam name="TPixel">The pixel format.</typeparam>
     /// <param name="api">The WebGPU API instance used to allocate native resources.</param>
     /// <param name="deviceHandle">The wrapped <c>WGPUDevice*</c> handle.</param>
     /// <param name="queueHandle">The wrapped <c>WGPUQueue*</c> handle.</param>
     /// <param name="width">The texture width in pixels.</param>
     /// <param name="height">The texture height in pixels.</param>
-    /// <param name="surface">Receives the native surface wrapping the allocated texture.</param>
     /// <param name="textureHandle">Receives the allocated wrapped <c>WGPUTexture*</c> handle.</param>
     /// <param name="textureViewHandle">Receives the allocated wrapped <c>WGPUTextureView*</c> handle.</param>
     /// <param name="formatId">Receives the allocated texture format identifier.</param>
-    /// <param name="error">Receives the failure reason when allocation fails.</param>
-    /// <returns><see langword="true"/> when allocation succeeds; otherwise <see langword="false"/>.</returns>
-    internal static bool TryCreateRenderTarget<TPixel>(
+    /// <returns>The native surface wrapping the allocated texture.</returns>
+    internal static NativeSurface CreateRenderTarget<TPixel>(
         WebGPU api,
         WebGPUDeviceHandle deviceHandle,
         WebGPUQueueHandle queueHandle,
         int width,
         int height,
-        out NativeSurface surface,
-        [NotNullWhen(true)] out WebGPUTextureHandle? textureHandle,
-        [NotNullWhen(true)] out WebGPUTextureViewHandle? textureViewHandle,
-        out WebGPUTextureFormatId formatId,
-        out string error)
+        out WebGPUTextureHandle textureHandle,
+        out WebGPUTextureViewHandle textureViewHandle,
+        out WebGPUTextureFormatId formatId)
         where TPixel : unmanaged, IPixel<TPixel>
     {
-        surface = new NativeSurface(TPixel.GetPixelTypeInfo());
-        textureHandle = null;
-        textureViewHandle = null;
-        formatId = default;
-
         if (deviceHandle.IsInvalid)
         {
-            error = "Device handle must be non-zero.";
-            return false;
+            throw new InvalidOperationException("The WebGPU device handle is invalid.");
         }
 
         if (queueHandle.IsInvalid)
         {
-            error = "Queue handle must be non-zero.";
-            return false;
-        }
-
-        if (width <= 0)
-        {
-            error = "Width must be greater than zero.";
-            return false;
+            throw new InvalidOperationException("The WebGPU queue handle is invalid.");
         }
 
-        if (height <= 0)
-        {
-            error = "Height must be greater than zero.";
-            return false;
-        }
+        Guard.MustBeGreaterThan(width, 0, nameof(width));
+        Guard.MustBeGreaterThan(height, 0, nameof(height));
 
         if (!WebGPUDrawingBackend.TryGetCompositeTextureFormat<TPixel>(out formatId, out FeatureName requiredFeature))
         {
-            error = $"Pixel type '{typeof(TPixel).Name}' is not supported by the WebGPU backend.";
-            return false;
+            throw new NotSupportedException($"Pixel type '{typeof(TPixel).Name}' is not supported by the WebGPU backend.");
         }
 
         using WebGPUHandle.HandleReference deviceReference = deviceHandle.AcquireReference();
@@ -81,8 +59,7 @@ internal static bool TryCreateRenderTarget<TPixel>(
         if (requiredFeature != FeatureName.Undefined &&
             !WebGPURuntime.GetOrCreateDeviceState(api, deviceHandle).HasFeature(requiredFeature))
         {
-            error = $"Device does not support required feature '{requiredFeature}' for pixel type '{typeof(TPixel).Name}'.";
-            return false;
+            throw new NotSupportedException($"The WebGPU device does not support required feature '{requiredFeature}' for pixel type '{typeof(TPixel).Name}'.");
         }
 
         TextureFormat textureFormat = WebGPUTextureFormatMapper.ToSilk(formatId);
@@ -99,8 +76,7 @@ internal static bool TryCreateRenderTarget<TPixel>(
         Texture* texture = api.DeviceCreateTexture(device, in textureDescriptor);
         if (texture is null)
         {
-            error = "WebGPU.DeviceCreateTexture returned null.";
-            return false;
+            throw new InvalidOperationException("The WebGPU device could not create a render-target texture.");
         }
 
         TextureViewDescriptor textureViewDescriptor = new()
@@ -118,8 +94,7 @@ internal static bool TryCreateRenderTarget<TPixel>(
         if (textureView is null)
         {
             api.TextureRelease(texture);
-            error = "WebGPU.TextureCreateView returned null.";
-            return false;
+            throw new InvalidOperationException("The WebGPU device could not create a render-target texture view.");
         }
 
         WebGPUTextureHandle? createdTextureHandle = null;
@@ -128,7 +103,7 @@ internal static bool TryCreateRenderTarget<TPixel>(
         {
             createdTextureHandle = new WebGPUTextureHandle(api, (nint)texture, ownsHandle: true);
             createdTextureViewHandle = new WebGPUTextureViewHandle(api, (nint)textureView, ownsHandle: true);
-            surface = WebGPUNativeSurfaceFactory.Create<TPixel>(
+            NativeSurface surface = WebGPUNativeSurfaceFactory.Create<TPixel>(
                 deviceHandle,
                 queueHandle,
                 createdTextureHandle,
@@ -138,10 +113,9 @@ internal static bool TryCreateRenderTarget<TPixel>(
                 height);
             textureHandle = createdTextureHandle;
             textureViewHandle = createdTextureViewHandle;
-            error = string.Empty;
-            return true;
+            return surface;
         }
-        catch (Exception ex)
+        catch
         {
             createdTextureViewHandle?.Dispose();
             createdTextureHandle?.Dispose();
@@ -156,8 +130,7 @@ internal static bool TryCreateRenderTarget<TPixel>(
                 api.TextureRelease(texture);
             }
 
-            error = ex.Message;
-            return false;
+            throw;
         }
     }
 }

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

@@ -55,20 +55,15 @@ private WebGPURenderTarget(WebGPUDeviceContext<TPixel> graphics, bool ownsGraphi
             graphics.ThrowIfDisposed();
 
             WebGPU api = WebGPURuntime.GetApi();
-            if (!WebGPURenderTargetAllocation.TryCreateRenderTarget<TPixel>(
-                    api,
-                    graphics.DeviceHandle,
-                    graphics.QueueHandle,
-                    width,
-                    height,
-                    out NativeSurface surface,
-                    out WebGPUTextureHandle? textureHandle,
-                    out WebGPUTextureViewHandle? textureViewHandle,
-                    out WebGPUTextureFormatId format,
-                    out string allocationError))
-            {
-                throw new InvalidOperationException(allocationError);
-            }
+            NativeSurface surface = WebGPURenderTargetAllocation.CreateRenderTarget<TPixel>(
+                api,
+                graphics.DeviceHandle,
+                graphics.QueueHandle,
+                width,
+                height,
+                out WebGPUTextureHandle textureHandle,
+                out WebGPUTextureViewHandle textureViewHandle,
+                out WebGPUTextureFormatId format);
 
             this.TextureHandle = textureHandle;
             this.TextureViewHandle = textureViewHandle;

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

@@ -429,22 +429,15 @@ private static DeviceResources CreateDeviceResources(
 
         try
         {
-            if (!TryRequestAdapter(api, instance, surface, out adapter, out string? adapterError))
-            {
-                throw new InvalidOperationException(adapterError);
-            }
-
+            adapter = RequestAdapter(api, instance, surface);
             adapterHandle = new WebGPUAdapterHandle(api, (nint)adapter, ownsHandle: true);
-            if (!TryRequestDevice(api, adapter, requiredFeature, out Device* device, out string? deviceError))
-            {
-                throw new InvalidOperationException(deviceError);
-            }
 
+            Device* device = RequestDevice(api, adapter, requiredFeature);
             deviceHandle = new WebGPUDeviceHandle(api, (nint)device, ownsHandle: true);
             Queue* queue = api.DeviceGetQueue(device);
             if (queue is null)
             {
-                throw new InvalidOperationException("WebGPU queue acquisition failed.");
+                throw new InvalidOperationException("The WebGPU device did not provide a default queue.");
             }
 
             queueHandle = new WebGPUQueueHandle(api, (nint)queue, ownsHandle: true);
@@ -520,21 +513,16 @@ private void RecoverDeviceResources(WebGPUPresentMode presentMode, Size framebuf
     }
 
     /// <summary>
-    /// Requests a high-performance adapter compatible with <paramref name="surface"/> and waits synchronously on the
-    /// asynchronous callback, up to <see cref="CallbackTimeoutMilliseconds"/>.
+    /// Requests a high-performance adapter compatible with <paramref name="surface"/>.
     /// </summary>
     /// <param name="api">The shared WebGPU API loader.</param>
     /// <param name="instance">The WebGPU instance the adapter is requested from.</param>
     /// <param name="surface">The surface the adapter must be compatible with.</param>
-    /// <param name="adapter">Receives the requested adapter on success.</param>
-    /// <param name="error">Receives the failure reason when the adapter request cannot complete.</param>
-    /// <returns><see langword="true"/> when the adapter was returned by the native callback; otherwise <see langword="false"/>.</returns>
-    private static bool TryRequestAdapter(
+    /// <returns>The requested adapter.</returns>
+    private static Adapter* RequestAdapter(
         WebGPU api,
         Instance* instance,
-        Surface* surface,
-        out Adapter* adapter,
-        out string? error)
+        Surface* surface)
     {
         RequestAdapterStatus callbackStatus = RequestAdapterStatus.Unknown;
         Adapter* callbackAdapter = null;
@@ -559,20 +547,15 @@ void Callback(RequestAdapterStatus status, Adapter* adapterPtr, byte* message, v
         api.InstanceRequestAdapter(instance, in options, callbackPtr, null);
         if (!callbackReady.Wait(CallbackTimeoutMilliseconds))
         {
-            adapter = null;
-            error = "Timed out while waiting for the WebGPU adapter request callback.";
-            return false;
+            throw new InvalidOperationException("Timed out while waiting for the WebGPU adapter request callback.");
         }
 
-        adapter = callbackAdapter;
         if (callbackStatus != RequestAdapterStatus.Success || callbackAdapter is null)
         {
-            error = $"WebGPU adapter request failed with status '{callbackStatus}'.";
-            return false;
+            throw new InvalidOperationException($"The WebGPU runtime failed to acquire a surface-compatible adapter. Status: '{callbackStatus}'.");
         }
 
-        error = null;
-        return true;
+        return callbackAdapter;
     }
 
     /// <summary>
@@ -583,21 +566,15 @@ void Callback(RequestAdapterStatus status, Adapter* adapterPtr, byte* message, v
     /// <param name="api">The shared WebGPU API loader.</param>
     /// <param name="adapter">The adapter the device is requested from.</param>
     /// <param name="requiredFeature">The feature to enable on the requested device, or <see cref="FeatureName.Undefined"/> for none.</param>
-    /// <param name="device">Receives the requested device on success.</param>
-    /// <param name="error">Receives the failure reason when the device request cannot complete.</param>
-    /// <returns><see langword="true"/> when the device was returned by the native callback; otherwise <see langword="false"/>.</returns>
-    private static bool TryRequestDevice(
+    /// <returns>The requested device.</returns>
+    private static Device* RequestDevice(
         WebGPU api,
         Adapter* adapter,
-        FeatureName requiredFeature,
-        out Device* device,
-        out string? error)
+        FeatureName requiredFeature)
     {
         if (requiredFeature != FeatureName.Undefined && !api.AdapterHasFeature(adapter, requiredFeature))
         {
-            device = null;
-            error = $"The selected adapter does not support required feature '{requiredFeature}'.";
-            return false;
+            throw new NotSupportedException($"The selected WebGPU adapter does not support required feature '{requiredFeature}'.");
         }
 
         RequestDeviceStatus callbackStatus = RequestDeviceStatus.Unknown;
@@ -628,20 +605,15 @@ void Callback(RequestDeviceStatus status, Device* devicePtr, byte* message, void
         api.AdapterRequestDevice(adapter, in descriptor, callbackPtr, null);
         if (!callbackReady.Wait(CallbackTimeoutMilliseconds))
         {
-            device = null;
-            error = "Timed out while waiting for the WebGPU device request callback.";
-            return false;
+            throw new InvalidOperationException("Timed out while waiting for the WebGPU device request callback.");
         }
 
-        device = callbackDevice;
         if (callbackStatus != RequestDeviceStatus.Success || callbackDevice is null)
         {
-            error = $"WebGPU device request failed with status '{callbackStatus}'.";
-            return false;
+            throw new InvalidOperationException($"The WebGPU runtime failed to acquire a device. Status: '{callbackStatus}'.");
         }
 
-        error = null;
-        return true;
+        return callbackDevice;
     }
 
     /// <summary>