Introduce safe WebGPU handle wrappers

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WebGPUAdapterHandle.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+using Silk.NET.WebGPU;
+
+namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+/// <summary>
+/// Safe-handle wrapper for a WebGPU adapter handle.
+/// </summary>
+internal sealed unsafe class WebGPUAdapterHandle : WebGPUHandle
+{
+    private readonly WebGPU? api;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebGPUAdapterHandle"/> class.
+    /// </summary>
+    /// <param name="adapterHandle">The WebGPU adapter handle value.</param>
+    /// <param name="ownsHandle">
+    /// <see langword="true"/> when this wrapper owns the adapter and must release it;
+    /// <see langword="false"/> when the caller retains ownership.
+    /// </param>
+    internal WebGPUAdapterHandle(nint adapterHandle, bool ownsHandle)
+        : this(ownsHandle ? WebGPURuntime.GetApi() : null, adapterHandle, ownsHandle)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebGPUAdapterHandle"/> class.
+    /// </summary>
+    /// <param name="api">
+    /// The WebGPU API facade used to release the handle when this wrapper owns it,
+    /// or <see langword="null"/> when the wrapper is non-owning.
+    /// </param>
+    /// <param name="adapterHandle">The WebGPU adapter handle value.</param>
+    /// <param name="ownsHandle">
+    /// <see langword="true"/> when this wrapper owns the adapter and must release it;
+    /// <see langword="false"/> when the caller retains ownership.
+    /// </param>
+    internal WebGPUAdapterHandle(WebGPU? api, nint adapterHandle, bool ownsHandle)
+        : base(adapterHandle, ownsHandle)
+        => this.api = api;
+
+    /// <inheritdoc />
+    protected override bool ReleaseHandle()
+    {
+        try
+        {
+            this.api?.AdapterRelease((Adapter*)this.handle);
+            return true;
+        }
+        catch
+        {
+            return false;
+        }
+        finally
+        {
+            this.handle = IntPtr.Zero;
+        }
+    }
+}

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

@@ -0,0 +1,61 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+using Silk.NET.WebGPU;
+
+namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+/// <summary>
+/// Safe-handle wrapper for a WebGPU device handle.
+/// </summary>
+internal sealed unsafe class WebGPUDeviceHandle : WebGPUHandle
+{
+    private readonly WebGPU? api;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebGPUDeviceHandle"/> class.
+    /// </summary>
+    /// <param name="deviceHandle">The WebGPU device handle value.</param>
+    /// <param name="ownsHandle">
+    /// <see langword="true"/> when this wrapper owns the device and must release it;
+    /// <see langword="false"/> when the caller retains ownership.
+    /// </param>
+    internal WebGPUDeviceHandle(nint deviceHandle, bool ownsHandle)
+        : this(ownsHandle ? WebGPURuntime.GetApi() : null, deviceHandle, ownsHandle)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WebGPUDeviceHandle"/> class.
+    /// </summary>
+    /// <param name="api">
+    /// The WebGPU API facade used to release the handle when this wrapper owns it,
+    /// or <see langword="null"/> when the wrapper is non-owning.
+    /// </param>
+    /// <param name="deviceHandle">The WebGPU device handle value.</param>
+    /// <param name="ownsHandle">
+    /// <see langword="true"/> when this wrapper owns the device and must release it;
+    /// <see langword="false"/> when the caller retains ownership.
+    /// </param>
+    internal WebGPUDeviceHandle(WebGPU? api, nint deviceHandle, bool ownsHandle)
+        : base(deviceHandle, ownsHandle)
+        => this.api = api;
+
+    /// <inheritdoc />
+    protected override bool ReleaseHandle()
+    {
+        try
+        {
+            this.api?.DeviceRelease((Device*)this.handle);
+            return true;
+        }
+        catch
+        {
+            return false;
+        }
+        finally
+        {
+            this.handle = IntPtr.Zero;
+        }
+    }
+}

src/ImageSharp.Drawing.WebGPU/WebGPUDeviceHandle.cs

@@ -58,9 +58,9 @@ public bool TryReadRegion<TPixel>(
         // Readback is only available for native WebGPU targets with valid interop handles.
         if (!target.TryGetNativeSurface(out NativeSurface? nativeSurface) ||
             !nativeSurface.TryGetCapability(out WebGPUSurfaceCapability? capability) ||
-            capability.Device == 0 ||
-            capability.Queue == 0 ||
-            capability.TargetTexture == 0)
+            capability.DeviceHandle.IsInvalid ||
+            capability.QueueHandle.IsInvalid ||
+            capability.TargetTextureHandle.IsInvalid)
         {
             error = "The target does not expose a native WebGPU surface with valid device, queue, and texture handles for readback.";
             return false;
@@ -91,16 +91,21 @@ public bool TryReadRegion<TPixel>(
 
         WebGPU api = WebGPURuntime.GetApi();
         Wgpu wgpuExtension = WebGPURuntime.GetWgpuExtension();
-        Device* device = (Device*)capability.Device;
+        using WebGPUHandle.HandleReference deviceReference = capability.DeviceHandle.AcquireReference();
+        using WebGPUHandle.HandleReference queueReference = capability.QueueHandle.AcquireReference();
+        using WebGPUHandle.HandleReference textureReference = capability.TargetTextureHandle.AcquireReference();
+
+        Device* device = (Device*)deviceReference.Handle;
 
         if (requiredFeature != FeatureName.Undefined
-            && !WebGPURuntime.GetOrCreateDeviceState(api, device).HasFeature(requiredFeature))
+            && !WebGPURuntime.GetOrCreateDeviceState(api, capability.DeviceHandle).HasFeature(requiredFeature))
         {
             error = $"The target device does not support WebGPU feature '{requiredFeature}' required to read back pixel type '{typeof(TPixel).Name}'.";
             return false;
         }
 
-        Queue* queue = (Queue*)capability.Queue;
+        Queue* queue = (Queue*)queueReference.Handle;
+        Texture* texture = (Texture*)textureReference.Handle;
 
         int pixelSizeInBytes = Unsafe.SizeOf<TPixel>();
         int packedRowBytes = checked(source.Width * pixelSizeInBytes);
@@ -139,7 +144,7 @@ public bool TryReadRegion<TPixel>(
             // Copy only the requested source rect from the target texture into the readback buffer.
             ImageCopyTexture sourceCopy = new()
             {
-                Texture = (Texture*)capability.TargetTexture,
+                Texture = texture,
                 MipLevel = 0,
                 Origin = new Origin3D((uint)source.X, (uint)source.Y, 0),
                 Aspect = TextureAspect.All

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

@@ -236,8 +236,11 @@ private void FlushCompositionsFallback<TPixel>(
         Rectangle? compositionBounds)
         where TPixel : unmanaged, IPixel<TPixel>
     {
-        _ = target.TryGetNativeSurface(out NativeSurface? nativeSurface);
-        _ = nativeSurface!.TryGetCapability(out WebGPUSurfaceCapability? capability);
+        if (!target.TryGetNativeSurface(out NativeSurface? nativeSurface) ||
+            !nativeSurface.TryGetCapability(out WebGPUSurfaceCapability? capability))
+        {
+            return;
+        }
 
         Rectangle targetBounds = target.Bounds;
         using Buffer2D<TPixel> stagingBuffer =
@@ -258,17 +261,20 @@ private void FlushCompositionsFallback<TPixel>(
         this.fallbackBackend.FlushCompositions(configuration, stagingFrame, compositionScene);
 
         WebGPU api = WebGPURuntime.GetApi();
+        using WebGPUHandle.HandleReference queueReference = capability.QueueHandle.AcquireReference();
+
         Buffer2DRegion<TPixel> uploadRegion = compositionBounds is Rectangle cb && cb.Width > 0 && cb.Height > 0
             ? stagingRegion.GetSubRegion(cb)
             : stagingRegion;
 
         uint destX = compositionBounds is Rectangle cbx ? (uint)cbx.X : 0;
         uint destY = compositionBounds is Rectangle cby ? (uint)cby.Y : 0;
 
+        using WebGPUHandle.HandleReference textureReference = capability.TargetTextureHandle.AcquireReference();
         WebGPUFlushContext.UploadTextureFromRegion(
             api,
-            (Queue*)capability!.Queue,
-            (Texture*)capability.TargetTexture,
+            (Queue*)queueReference.Handle,
+            (Texture*)textureReference.Handle,
             uploadRegion,
             configuration.MemoryAllocator,
             destX,

src/ImageSharp.Drawing.WebGPU/WebGPUDrawingBackend.cs

@@ -31,6 +31,14 @@ internal sealed unsafe class WebGPUFlushContext : IDisposable
     private bool disposed;
     private bool ownsTargetTexture;
     private bool ownsTargetView;
+    private readonly WebGPUDeviceHandle deviceHandle;
+    private readonly WebGPUQueueHandle queueHandle;
+    private readonly WebGPUTextureHandle targetTextureHandle;
+    private readonly WebGPUTextureViewHandle targetTextureViewHandle;
+    private WebGPUHandle.HandleReference? deviceReference;
+    private WebGPUHandle.HandleReference? queueReference;
+    private WebGPUHandle.HandleReference? targetTextureReference;
+    private WebGPUHandle.HandleReference? targetTextureViewReference;
     private readonly List<nint> transientBindGroups = [];
     private readonly List<nint> transientBuffers = [];
     private readonly List<nint> transientTextureViews = [];
@@ -44,17 +52,21 @@ internal sealed unsafe class WebGPUFlushContext : IDisposable
     private WebGPUFlushContext(
         WebGPU api,
         Wgpu wgpuExtension,
-        Device* device,
-        Queue* queue,
+        WebGPUDeviceHandle deviceHandle,
+        WebGPUQueueHandle queueHandle,
+        WebGPUTextureHandle targetTextureHandle,
+        WebGPUTextureViewHandle targetTextureViewHandle,
         in Rectangle targetBounds,
         TextureFormat textureFormat,
         MemoryAllocator memoryAllocator,
         WebGPURuntime.DeviceSharedState deviceState)
     {
         this.Api = api;
         this.WgpuExtension = wgpuExtension;
-        this.Device = device;
-        this.Queue = queue;
+        this.deviceHandle = deviceHandle;
+        this.queueHandle = queueHandle;
+        this.targetTextureHandle = targetTextureHandle;
+        this.targetTextureViewHandle = targetTextureViewHandle;
         this.TargetBounds = targetBounds;
         this.TextureFormat = textureFormat;
         this.MemoryAllocator = memoryAllocator;
@@ -74,12 +86,12 @@ private WebGPUFlushContext(
     /// <summary>
     /// Gets the device used to create and execute GPU resources.
     /// </summary>
-    public Device* Device { get; }
+    public Device* Device { get; private set; }
 
     /// <summary>
     /// Gets the queue used to submit GPU work.
     /// </summary>
-    public Queue* Queue { get; }
+    public Queue* Queue { get; private set; }
 
     /// <summary>
     /// Gets the target bounds for this flush context.
@@ -168,12 +180,10 @@ private WebGPUFlushContext(
         }
 
         WebGPU api = WebGPURuntime.GetApi();
-        Device* device = (Device*)nativeCapability.Device;
-        Queue* queue = (Queue*)nativeCapability.Queue;
         TextureFormat textureFormat = WebGPUTextureFormatMapper.ToSilk(nativeCapability.TargetFormat);
         Rectangle bounds = frame.Bounds;
         Rectangle nativeBounds = new(0, 0, nativeCapability.Width, nativeCapability.Height);
-        WebGPURuntime.DeviceSharedState deviceState = WebGPURuntime.GetOrCreateDeviceState(api, device);
+        WebGPURuntime.DeviceSharedState deviceState = WebGPURuntime.GetOrCreateDeviceState(api, nativeCapability.DeviceHandle);
 
         if (requiredFeature != FeatureName.Undefined && !deviceState.HasFeature(requiredFeature))
         {
@@ -191,13 +201,28 @@ private WebGPUFlushContext(
         WebGPUFlushContext context = new(
             api,
             WebGPURuntime.GetWgpuExtension(),
-            device,
-            queue,
+            nativeCapability.DeviceHandle,
+            nativeCapability.QueueHandle,
+            nativeCapability.TargetTextureHandle,
+            nativeCapability.TargetTextureViewHandle,
             in bounds,
             textureFormat,
             memoryAllocator,
             deviceState);
-        context.InitializeNativeTarget(nativeCapability);
+        try
+        {
+            if (!context.InitializeNativeTarget())
+            {
+                context.Dispose();
+                return null;
+            }
+        }
+        catch
+        {
+            context.Dispose();
+            throw;
+        }
+
         return context;
     }
 
@@ -486,20 +511,46 @@ public void Dispose()
         this.TargetTexture = null;
         this.ownsTargetView = false;
         this.ownsTargetTexture = false;
+        this.DisposeNativeHandleReferences();
 
         this.disposed = true;
     }
 
     /// <summary>
     /// Adopts the texture and texture view provided by a native WebGPU surface capability.
     /// </summary>
-    /// <param name="capability">The native surface capability describing the externally owned target.</param>
-    private void InitializeNativeTarget(WebGPUSurfaceCapability capability)
+    /// <returns><see langword="true"/> when all required native handles were acquired successfully; otherwise, <see langword="false"/>.</returns>
+    private bool InitializeNativeTarget()
     {
-        this.TargetTexture = (Texture*)capability.TargetTexture;
-        this.TargetView = (TextureView*)capability.TargetTextureView;
+        // The flush context caches raw native pointers and reuses them across the full flush,
+        // so each safe handle must stay add-ref'd until the context is disposed. These fields are
+        // assigned immediately so Dispose can unwind partial initialization if a later acquire throws.
+        this.deviceReference = this.deviceHandle.AcquireReference();
+        this.queueReference = this.queueHandle.AcquireReference();
+        this.targetTextureReference = this.targetTextureHandle.AcquireReference();
+        this.targetTextureViewReference = this.targetTextureViewHandle.AcquireReference();
+        this.Device = (Device*)this.deviceReference.Handle;
+        this.Queue = (Queue*)this.queueReference.Handle;
+        this.TargetTexture = (Texture*)this.targetTextureReference.Handle;
+        this.TargetView = (TextureView*)this.targetTextureViewReference.Handle;
         this.ownsTargetTexture = false;
         this.ownsTargetView = false;
+        return true;
+    }
+
+    /// <summary>
+    /// Releases the scoped safe-handle references that keep the cached raw pointers valid for this flush.
+    /// </summary>
+    private void DisposeNativeHandleReferences()
+    {
+        this.targetTextureViewReference?.Dispose();
+        this.targetTextureViewReference = null;
+        this.targetTextureReference?.Dispose();
+        this.targetTextureReference = null;
+        this.queueReference?.Dispose();
+        this.queueReference = null;
+        this.deviceReference?.Dispose();
+        this.deviceReference = null;
     }
 
     /// <summary>
@@ -518,9 +569,9 @@ private void InitializeNativeTarget(WebGPUSurfaceCapability capability)
             return null;
         }
 
-        if (capability.Device == 0 ||
-            capability.Queue == 0 ||
-            capability.TargetTextureView == 0 ||
+        if (capability.DeviceHandle.IsInvalid ||
+            capability.QueueHandle.IsInvalid ||
+            capability.TargetTextureViewHandle.IsInvalid ||
             WebGPUTextureFormatMapper.ToSilk(capability.TargetFormat) != expectedTextureFormat)
         {
             return null;