Use WebGPUNativeTarget and refactor native surface

Author: JimBobSquarePants

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

@@ -33,19 +33,23 @@ public void ReadRegion<TPixel>(
         Guard.NotNull(destination.Buffer, nameof(destination));
 
         // Readback is only available for native WebGPU targets with valid interop handles.
-        if (!target.TryGetNativeSurface(out NativeSurface? nativeSurface) ||
-            !nativeSurface.TryGetCapability(out WebGPUSurfaceCapability? capability) ||
-            capability.DeviceHandle.IsInvalid ||
-            capability.QueueHandle.IsInvalid ||
-            capability.TargetTextureHandle.IsInvalid)
+        if (!target.TryGetNativeSurface(out NativeSurface? nativeSurface))
         {
-            throw new NotSupportedException("The target does not expose a native WebGPU surface with valid device, queue, and texture handles for readback.");
+            throw new NotSupportedException("The target does not expose a native surface for readback.");
+        }
+
+        WebGPUNativeTarget nativeTarget = nativeSurface.GetNativeTarget<WebGPUNativeTarget>();
+        if (nativeTarget.DeviceHandle.IsInvalid ||
+            nativeTarget.QueueHandle.IsInvalid ||
+            nativeTarget.TargetTextureHandle.IsInvalid)
+        {
+            throw new NotSupportedException("The target does not expose valid WebGPU device, queue, and texture handles for readback.");
         }
 
         if (!TryGetCompositeTextureFormat<TPixel>(out WebGPUTextureFormatId expectedFormat, out FeatureName requiredFeature) ||
-            expectedFormat != capability.TargetFormat)
+            expectedFormat != nativeTarget.TargetFormat)
         {
-            throw new NotSupportedException($"Pixel type '{typeof(TPixel).Name}' cannot be read back from target format '{capability.TargetFormat}'.");
+            throw new NotSupportedException($"Pixel type '{typeof(TPixel).Name}' cannot be read back from target format '{nativeTarget.TargetFormat}'.");
         }
 
         // Convert canvas-local source coordinates to absolute native-surface coordinates.
@@ -55,7 +59,7 @@ public void ReadRegion<TPixel>(
             sourceRectangle.Width,
             sourceRectangle.Height);
 
-        Rectangle surfaceBounds = new(0, 0, capability.Width, capability.Height);
+        Rectangle surfaceBounds = new(0, 0, nativeTarget.Width, nativeTarget.Height);
         Rectangle source = Rectangle.Intersect(surfaceBounds, absoluteSource);
 
         if (source.Width <= 0 || source.Height <= 0)
@@ -65,14 +69,14 @@ public void ReadRegion<TPixel>(
 
         WebGPU api = WebGPURuntime.GetApi();
         Wgpu wgpuExtension = WebGPURuntime.GetWgpuExtension();
-        using WebGPUHandle.HandleReference deviceReference = capability.DeviceHandle.AcquireReference();
-        using WebGPUHandle.HandleReference queueReference = capability.QueueHandle.AcquireReference();
-        using WebGPUHandle.HandleReference textureReference = capability.TargetTextureHandle.AcquireReference();
+        using WebGPUHandle.HandleReference deviceReference = nativeTarget.DeviceHandle.AcquireReference();
+        using WebGPUHandle.HandleReference queueReference = nativeTarget.QueueHandle.AcquireReference();
+        using WebGPUHandle.HandleReference textureReference = nativeTarget.TargetTextureHandle.AcquireReference();
 
         Device* device = (Device*)deviceReference.Handle;
 
         if (requiredFeature != FeatureName.Undefined
-            && !WebGPURuntime.GetOrCreateDeviceState(api, capability.DeviceHandle).HasFeature(requiredFeature))
+            && !WebGPURuntime.GetOrCreateDeviceState(api, nativeTarget.DeviceHandle).HasFeature(requiredFeature))
         {
             throw new NotSupportedException($"The target device does not support WebGPU feature '{requiredFeature}' required to read back pixel type '{typeof(TPixel).Name}'.");
         }

src/ImageSharp.Drawing.WebGPU/WebGPUFlushContext.cs

@@ -172,17 +172,25 @@ private WebGPUFlushContext(
         MemoryAllocator memoryAllocator)
         where TPixel : unmanaged, IPixel<TPixel>
     {
-        WebGPUSurfaceCapability? nativeCapability = TryGetNativeSurfaceCapability(frame, expectedTextureFormat);
-        if (nativeCapability is null)
+        if (!frame.TryGetNativeSurface(out NativeSurface? nativeSurface))
         {
             return null;
         }
 
+        WebGPUNativeTarget nativeTarget = nativeSurface.GetNativeTarget<WebGPUNativeTarget>();
         WebGPU api = WebGPURuntime.GetApi();
-        TextureFormat textureFormat = WebGPUTextureFormatMapper.ToSilk(nativeCapability.TargetFormat);
+        TextureFormat textureFormat = WebGPUTextureFormatMapper.ToSilk(nativeTarget.TargetFormat);
         Rectangle bounds = frame.Bounds;
-        Rectangle nativeBounds = new(0, 0, nativeCapability.Width, nativeCapability.Height);
-        WebGPURuntime.DeviceSharedState deviceState = WebGPURuntime.GetOrCreateDeviceState(api, nativeCapability.DeviceHandle);
+        Rectangle nativeBounds = new(0, 0, nativeTarget.Width, nativeTarget.Height);
+        WebGPURuntime.DeviceSharedState deviceState = WebGPURuntime.GetOrCreateDeviceState(api, nativeTarget.DeviceHandle);
+
+        if (nativeTarget.DeviceHandle.IsInvalid ||
+            nativeTarget.QueueHandle.IsInvalid ||
+            nativeTarget.TargetTextureViewHandle.IsInvalid ||
+            textureFormat != expectedTextureFormat)
+        {
+            return null;
+        }
 
         if (requiredFeature != FeatureName.Undefined && !deviceState.HasFeature(requiredFeature))
         {
@@ -200,10 +208,10 @@ private WebGPUFlushContext(
         return new WebGPUFlushContext(
             api,
             WebGPURuntime.GetWgpuExtension(),
-            nativeCapability.DeviceHandle,
-            nativeCapability.QueueHandle,
-            nativeCapability.TargetTextureHandle,
-            nativeCapability.TargetTextureViewHandle,
+            nativeTarget.DeviceHandle,
+            nativeTarget.QueueHandle,
+            nativeTarget.TargetTextureHandle,
+            nativeTarget.TargetTextureViewHandle,
             in bounds,
             textureFormat,
             memoryAllocator,
@@ -486,42 +494,6 @@ public void Dispose()
         this.disposed = true;
     }
 
-    /// <summary>
-    /// Tries to obtain a native WebGPU surface capability from the canvas frame.
-    /// </summary>
-    /// <typeparam name="TPixel">The pixel type of the canvas frame.</typeparam>
-    /// <param name="frame">The frame being flushed.</param>
-    /// <param name="expectedTextureFormat">The texture format required by the current WebGPU path.</param>
-    /// <returns>The compatible surface capability, or <see langword="null"/> when the frame cannot expose one.</returns>
-    private static WebGPUSurfaceCapability? TryGetNativeSurfaceCapability<TPixel>(ICanvasFrame<TPixel> frame, TextureFormat expectedTextureFormat)
-        where TPixel : unmanaged, IPixel<TPixel>
-    {
-        if (!frame.TryGetNativeSurface(out NativeSurface? nativeSurface) ||
-            !nativeSurface.TryGetCapability(out WebGPUSurfaceCapability? capability))
-        {
-            return null;
-        }
-
-        if (capability.DeviceHandle.IsInvalid ||
-            capability.QueueHandle.IsInvalid ||
-            capability.TargetTextureViewHandle.IsInvalid ||
-            WebGPUTextureFormatMapper.ToSilk(capability.TargetFormat) != expectedTextureFormat)
-        {
-            return null;
-        }
-
-        Rectangle bounds = frame.Bounds;
-        if (bounds.X < 0 ||
-            bounds.Y < 0 ||
-            bounds.Right > capability.Width ||
-            bounds.Bottom > capability.Height)
-        {
-            return null;
-        }
-
-        return capability;
-    }
-
     /// <summary>
     /// Uploads a source region into the destination texture starting at the origin.
     /// </summary>

src/ImageSharp.Drawing.WebGPU/WebGPUNativeSurface.cs

@@ -1,35 +1,31 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
 
-using System.Diagnostics.CodeAnalysis;
-
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 
 /// <summary>
 /// WebGPU native drawing target exposed through the backend-agnostic <see cref="NativeSurface"/> contract.
 /// </summary>
 internal sealed class WebGPUNativeSurface : NativeSurface
 {
-    private readonly WebGPUSurfaceCapability capability;
+    private readonly WebGPUNativeTarget target;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="WebGPUNativeSurface"/> class.
     /// </summary>
-    /// <param name="capability">The WebGPU capability exposed by this surface.</param>
-    internal WebGPUNativeSurface(WebGPUSurfaceCapability capability)
-        => this.capability = capability;
+    /// <param name="target">The WebGPU target exposed by this surface.</param>
+    internal WebGPUNativeSurface(WebGPUNativeTarget target)
+        => this.target = target;
 
     /// <inheritdoc />
-    public override bool TryGetCapability<TCapability>([NotNullWhen(true)] out TCapability? capability)
-        where TCapability : class
+    public override TNativeTarget GetNativeTarget<TNativeTarget>()
+        where TNativeTarget : class
     {
-        if (this.capability is TCapability typed)
+        if (this.target is TNativeTarget typed)
         {
-            capability = typed;
-            return true;
+            return typed;
         }
 
-        capability = null;
-        return false;
+        throw new NotSupportedException($"The native surface does not expose a native target of type '{typeof(TNativeTarget).Name}'.");
     }
 }

src/ImageSharp.Drawing.WebGPU/WebGPUNativeSurfaceFactory.cs

@@ -69,7 +69,7 @@ internal static NativeSurface Create<TPixel>(
         Guard.MustBeGreaterThan(height, 0, nameof(height));
         ValidatePixelCompatibility<TPixel>(targetFormat);
 
-        return new WebGPUNativeSurface(new WebGPUSurfaceCapability(
+        return new WebGPUNativeSurface(new WebGPUNativeTarget(
             deviceHandle,
             queueHandle,
             targetTextureHandle,

…rawing.WebGPU/WebGPUSurfaceCapability.cs …arp.Drawing.WebGPU/WebGPUNativeTarget.cssrc/ImageSharp.Drawing.WebGPU/WebGPUSurfaceCapability.cs renamed to src/ImageSharp.Drawing.WebGPU/WebGPUNativeTarget.cs src/ImageSharp.Drawing.WebGPU/WebGPUSurfaceCapability.cs renamed to src/ImageSharp.Drawing.WebGPU/WebGPUNativeTarget.cs

@@ -4,19 +4,19 @@
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 
 /// <summary>
-/// Native WebGPU surface capability exposed by a <see cref="NativeSurface"/>.
+/// Native WebGPU target exposed by a <see cref="NativeSurface"/>.
 /// </summary>
 /// <remarks>
 /// The backing WebGPU device, queue, texture, and texture view must remain valid while canvases target this surface.
 /// </remarks>
-internal sealed class WebGPUSurfaceCapability
+internal sealed class WebGPUNativeTarget
 {
     private readonly WebGPUDeviceHandle deviceHandle;
     private readonly WebGPUQueueHandle queueHandle;
     private readonly WebGPUTextureHandle targetTextureHandle;
     private readonly WebGPUTextureViewHandle targetTextureViewHandle;
 
-    internal WebGPUSurfaceCapability(
+    public WebGPUNativeTarget(
         WebGPUDeviceHandle deviceHandle,
         WebGPUQueueHandle queueHandle,
         WebGPUTextureHandle targetTextureHandle,
@@ -42,35 +42,35 @@ internal WebGPUSurfaceCapability(
     /// <summary>
     /// Gets the wrapped device handle that owns the target texture.
     /// </summary>
-    internal WebGPUDeviceHandle DeviceHandle => this.deviceHandle;
+    public WebGPUDeviceHandle DeviceHandle => this.deviceHandle;
 
     /// <summary>
     /// Gets the wrapped queue handle used to submit work against the target texture.
     /// </summary>
-    internal WebGPUQueueHandle QueueHandle => this.queueHandle;
+    public WebGPUQueueHandle QueueHandle => this.queueHandle;
 
     /// <summary>
-    /// Gets the wrapped target texture handle exposed by this surface capability.
+    /// Gets the wrapped target texture handle.
     /// </summary>
-    internal WebGPUTextureHandle TargetTextureHandle => this.targetTextureHandle;
+    public WebGPUTextureHandle TargetTextureHandle => this.targetTextureHandle;
 
     /// <summary>
-    /// Gets the wrapped target texture-view handle exposed by this surface capability.
+    /// Gets the wrapped target texture-view handle.
     /// </summary>
-    internal WebGPUTextureViewHandle TargetTextureViewHandle => this.targetTextureViewHandle;
+    public WebGPUTextureViewHandle TargetTextureViewHandle => this.targetTextureViewHandle;
 
     /// <summary>
     /// Gets the native render target texture format identifier.
     /// </summary>
-    internal WebGPUTextureFormatId TargetFormat { get; }
+    public WebGPUTextureFormatId TargetFormat { get; }
 
     /// <summary>
     /// Gets the surface width in pixels.
     /// </summary>
-    internal int Width { get; }
+    public int Width { get; }
 
     /// <summary>
     /// Gets the surface height in pixels.
     /// </summary>
-    internal int Height { get; }
+    public int Height { get; }
 }

src/ImageSharp.Drawing/Processing/Backends/NativeSurface.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>
@@ -18,11 +16,10 @@ protected NativeSurface()
     }
 
     /// <summary>
-    /// Attempts to get a backend capability by type.
+    /// Gets a backend-specific native target by type.
     /// </summary>
-    /// <typeparam name="TCapability">Capability type.</typeparam>
-    /// <param name="capability">Capability instance when available.</param>
-    /// <returns><see langword="true"/> when found.</returns>
-    public abstract bool TryGetCapability<TCapability>([NotNullWhen(true)] out TCapability? capability)
-        where TCapability : class;
+    /// <typeparam name="TNativeTarget">Native target type.</typeparam>
+    /// <returns>The native target.</returns>
+    public abstract TNativeTarget GetNativeTarget<TNativeTarget>()
+        where TNativeTarget : class;
 }

tests/ImageSharp.Drawing.Tests/Processing/DrawingCanvasTests.Process.cs

@@ -64,7 +64,7 @@ public void Process_Path_MatchesReference<TPixel>(TestImageProvider<TPixel> prov
 
     [Theory]
     [WithBlankImage(220, 160, PixelTypes.Rgba32)]
-    public void Process_NoCpuFrame_WithReadbackCapability_MatchesReference<TPixel>(TestImageProvider<TPixel> provider)
+    public void Process_NoCpuFrame_UsesBackendReadback_MatchesReference<TPixel>(TestImageProvider<TPixel> provider)
         where TPixel : unmanaged, IPixel<TPixel>
     {
         using Image<TPixel> target = provider.GetImage();
@@ -74,7 +74,7 @@ public void Process_NoCpuFrame_WithReadbackCapability_MatchesReference<TPixel>(T
         MemoryCanvasFrame<TPixel> proxyFrame = new(new Buffer2DRegion<TPixel>(target.Frames.RootFrame.PixelBuffer));
         MirroringCpuReadbackTestBackend<TPixel> mirroringBackend = new(proxyFrame, target);
 
-        NativeSurface nativeSurface = new NoCapabilityNativeSurface();
+        NativeSurface nativeSurface = new UnsupportedNativeSurface();
         Configuration configuration = provider.Configuration.Clone();
         configuration.SetDrawingBackend(mirroringBackend);
 
@@ -158,14 +158,10 @@ private static IPath CreatePixelateTrianglePath()
         return pathBuilder.Build();
     }
 
-    private sealed class NoCapabilityNativeSurface : NativeSurface
+    private sealed class UnsupportedNativeSurface : NativeSurface
     {
-        public override bool TryGetCapability<TCapability>(out TCapability capability)
-            where TCapability : class
-        {
-            capability = null!;
-            return false;
-        }
+        public override TNativeTarget GetNativeTarget<TNativeTarget>()
+            => throw new NotSupportedException();
     }
 
     /// <summary>