Add ReleaseFrameResources and WebGPU CPU cache key

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WebGPUDrawingBackend.cs

@@ -300,6 +300,16 @@ public void FlushCompositions<TPixel>(
             compositionBounds);
     }
 
+    /// <inheritdoc />
+    public void ReleaseFrameResources<TPixel>(
+        Configuration configuration,
+        ICanvasFrame<TPixel> target)
+        where TPixel : unmanaged, IPixel<TPixel>
+    {
+        nint targetIdentity = (nint)RuntimeHelpers.GetHashCode(target);
+        WebGPUFlushContext.ReleaseCpuTargetEntries(targetIdentity);
+    }
+
     /// <summary>
     /// Checks whether all scene commands are directly composable by WebGPU.
     /// </summary>

src/ImageSharp.Drawing.WebGPU/WebGPUFlushContext.cs

@@ -237,7 +237,8 @@ private WebGPUFlushContext(
             }
 
             context = new WebGPUFlushContext(lease, device, queue, in bounds, expectedTextureFormat, memoryAllocator, deviceState);
-            context.InitializeCpuTarget(cpuRegion, pixelSizeInBytes, initialUploadBounds);
+            nint targetIdentity = (nint)RuntimeHelpers.GetHashCode(frame);
+            context.InitializeCpuTarget(cpuRegion, pixelSizeInBytes, targetIdentity, initialUploadBounds);
             return context;
         }
         catch
@@ -308,6 +309,18 @@ public static void ClearFallbackStagingCache()
         FallbackStagingCache.Clear();
     }
 
+    /// <summary>
+    /// Releases all cached CPU target resources associated with the specified target identity.
+    /// </summary>
+    /// <param name="targetIdentity">The target frame identity whose cached resources should be released.</param>
+    public static void ReleaseCpuTargetEntries(nint targetIdentity)
+    {
+        foreach (DeviceSharedState state in DeviceStateCache.Values)
+        {
+            state.ReleaseCpuTargetEntries(targetIdentity);
+        }
+    }
+
     /// <summary>
     /// Clears all cached device-scoped shared state.
     /// </summary>
@@ -621,6 +634,7 @@ private void InitializeNativeTarget(WebGPUSurfaceCapability capability)
     private void InitializeCpuTarget<TPixel>(
         Buffer2DRegion<TPixel> cpuRegion,
         int pixelSizeInBytes,
+        nint targetIdentity,
         Rectangle? initialUploadBounds)
         where TPixel : unmanaged
     {
@@ -630,7 +644,8 @@ private void InitializeCpuTarget<TPixel>(
             this.TextureFormat,
             width,
             height,
-            pixelSizeInBytes);
+            pixelSizeInBytes,
+            targetIdentity);
         Texture* targetTexture = lease.TargetTexture;
         TextureView* targetView = lease.TargetView;
         WgpuBuffer* readbackBuffer = lease.ReadbackBuffer;
@@ -894,18 +909,36 @@ private static HashSet<FeatureName> EnumerateDeviceFeatures(WebGPU api, Device*
         /// <param name="width">The destination width.</param>
         /// <param name="height">The destination height.</param>
         /// <param name="pixelSizeInBytes">The destination pixel size in bytes.</param>
+        /// <param name="targetIdentity">Identity of the target frame to prevent cache collisions.</param>
         /// <returns>A lease for staging resources.</returns>
         public CpuTargetLease RentCpuTarget(
             TextureFormat textureFormat,
             int width,
             int height,
-            int pixelSizeInBytes)
+            int pixelSizeInBytes,
+            nint targetIdentity)
         {
-            CpuTargetCacheKey key = new(textureFormat, width, height, pixelSizeInBytes);
+            CpuTargetCacheKey key = new(textureFormat, width, height, pixelSizeInBytes, targetIdentity);
             CpuTargetEntry entry = this.cpuTargetCache.GetOrAdd(key, static _ => new CpuTargetEntry());
             return entry.Rent(this.Api, this.Device, in key);
         }
 
+        /// <summary>
+        /// Releases and removes all CPU target cache entries matching the specified target identity.
+        /// </summary>
+        /// <param name="targetIdentity">The target frame identity whose entries should be released.</param>
+        public void ReleaseCpuTargetEntries(nint targetIdentity)
+        {
+            foreach (KeyValuePair<CpuTargetCacheKey, CpuTargetEntry> pair in this.cpuTargetCache)
+            {
+                if (pair.Key.TargetIdentity == targetIdentity &&
+                    this.cpuTargetCache.TryRemove(pair.Key, out CpuTargetEntry? entry))
+                {
+                    entry.Dispose(this.Api);
+                }
+            }
+        }
+
         /// <summary>
         /// Gets or creates a graphics pipeline used for composite rendering.
         /// </summary>
@@ -1438,7 +1471,8 @@ internal readonly struct CpuTargetCacheKey(
             TextureFormat textureFormat,
             int width,
             int height,
-            int pixelSizeInBytes) : IEquatable<CpuTargetCacheKey>
+            int pixelSizeInBytes,
+            nint targetIdentity) : IEquatable<CpuTargetCacheKey>
         {
             /// <summary>
             /// Gets the texture format for the cached CPU target.
@@ -1460,22 +1494,29 @@ internal readonly struct CpuTargetCacheKey(
             /// </summary>
             public int PixelSizeInBytes { get; } = pixelSizeInBytes;
 
+            /// <summary>
+            /// Gets the identity of the target frame to prevent different targets
+            /// with the same dimensions from sharing GPU texture content.
+            /// </summary>
+            public nint TargetIdentity { get; } = targetIdentity;
+
             /// <summary>
             /// Determines whether this key equals another CPU target cache key.
             /// </summary>
             /// <param name="other">The key to compare.</param>
-            /// <returns><see langword="true"/> if all dimensions and format match; otherwise <see langword="false"/>.</returns>
+            /// <returns><see langword="true"/> if all fields match; otherwise <see langword="false"/>.</returns>
             public bool Equals(CpuTargetCacheKey other)
                 => this.TextureFormat == other.TextureFormat &&
                    this.Width == other.Width &&
                    this.Height == other.Height &&
-                   this.PixelSizeInBytes == other.PixelSizeInBytes;
+                   this.PixelSizeInBytes == other.PixelSizeInBytes &&
+                   this.TargetIdentity == other.TargetIdentity;
 
             /// <inheritdoc/>
             public override bool Equals(object? obj) => obj is CpuTargetCacheKey other && this.Equals(other);
 
             /// <inheritdoc/>
-            public override int GetHashCode() => HashCode.Combine((int)this.TextureFormat, this.Width, this.Height, this.PixelSizeInBytes);
+            public override int GetHashCode() => HashCode.Combine((int)this.TextureFormat, this.Width, this.Height, this.PixelSizeInBytes, this.TargetIdentity);
         }
 
         /// <summary>

src/ImageSharp.Drawing/Processing/Backends/DefaultDrawingBackend.cs

@@ -71,6 +71,15 @@ public void FlushCompositions<TPixel>(
         }
     }
 
+    /// <inheritdoc />
+    public void ReleaseFrameResources<TPixel>(
+        Configuration configuration,
+        ICanvasFrame<TPixel> target)
+        where TPixel : unmanaged, IPixel<TPixel>
+    {
+        // No cached resources to release for CPU-only backend.
+    }
+
     /// <inheritdoc />
     public bool TryReadRegion<TPixel>(
         Configuration configuration,

src/ImageSharp.Drawing/Processing/Backends/IDrawingBackend.cs

@@ -40,4 +40,15 @@ public bool TryReadRegion<TPixel>(
         Rectangle sourceRectangle,
         [NotNullWhen(true)] out Image<TPixel>? image)
         where TPixel : unmanaged, IPixel<TPixel>;
+
+    /// <summary>
+    /// Releases any backend resources cached against the specified target frame.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    /// <param name="configuration">Active processing configuration.</param>
+    /// <param name="target">The target frame whose resources should be released.</param>
+    public void ReleaseFrameResources<TPixel>(
+        Configuration configuration,
+        ICanvasFrame<TPixel> target)
+        where TPixel : unmanaged, IPixel<TPixel>;
 }

src/ImageSharp.Drawing/Processing/DrawingCanvas{TPixel}.cs

@@ -47,6 +47,12 @@ public sealed class DrawingCanvas<TPixel> : IDrawingCanvas
     /// </summary>
     private readonly List<Image<TPixel>> pendingImageResources = [];
 
+    /// <summary>
+    /// Indicates whether this canvas is the root owner of the target frame.
+    /// Only the root canvas releases backend resources on dispose.
+    /// </summary>
+    private readonly bool isRoot;
+
     /// <summary>
     /// Tracks whether this instance has already been disposed.
     /// </summary>
@@ -108,7 +114,8 @@ internal DrawingCanvas(
             backend,
             targetFrame,
             new DrawingCanvasBatcher<TPixel>(configuration, backend, targetFrame),
-            new DrawingCanvasState(options, clipPaths))
+            new DrawingCanvasState(options, clipPaths),
+            isRoot: true)
     {
     }
 
@@ -121,12 +128,14 @@ internal DrawingCanvas(
     /// <param name="targetFrame">The destination frame.</param>
     /// <param name="batcher">The command batcher used for deferred composition.</param>
     /// <param name="defaultState">The default state used when no scoped state is active.</param>
+    /// <param name="isRoot">Whether this canvas is the root owner of the target frame.</param>
     private DrawingCanvas(
         Configuration configuration,
         IDrawingBackend backend,
         ICanvasFrame<TPixel> targetFrame,
         DrawingCanvasBatcher<TPixel> batcher,
-        DrawingCanvasState defaultState)
+        DrawingCanvasState defaultState,
+        bool isRoot)
     {
         Guard.NotNull(configuration, nameof(configuration));
         Guard.NotNull(backend, nameof(backend));
@@ -143,6 +152,7 @@ private DrawingCanvas(
         this.backend = backend;
         this.targetFrame = targetFrame;
         this.batcher = batcher;
+        this.isRoot = isRoot;
 
         // Canvas coordinates are local to the current frame; origin stays at (0,0).
         this.Bounds = new Rectangle(0, 0, targetFrame.Bounds.Width, targetFrame.Bounds.Height);
@@ -277,7 +287,8 @@ public DrawingCanvas<TPixel> CreateRegion(Rectangle region)
             this.backend,
             childFrame,
             this.batcher,
-            this.ResolveState());
+            this.ResolveState(),
+            isRoot: false);
     }
 
     /// <inheritdoc />
@@ -1046,6 +1057,12 @@ public void Dispose()
         finally
         {
             this.DisposePendingImageResources();
+
+            if (this.isRoot)
+            {
+                this.backend.ReleaseFrameResources(this.configuration, this.targetFrame);
+            }
+
             this.isDisposed = true;
         }
     }

tests/ImageSharp.Drawing.Tests/Processing/DrawingCanvasBatcherTests.cs

@@ -173,5 +173,12 @@ public bool TryReadRegion<TPixel>(
             image = null;
             return false;
         }
+
+        public void ReleaseFrameResources<TPixel>(
+            Configuration configuration,
+            ICanvasFrame<TPixel> target)
+            where TPixel : unmanaged, IPixel<TPixel>
+        {
+        }
     }
 }

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

@@ -193,5 +193,12 @@ public bool TryReadRegion<TTargetPixel>(
             image = cropped.CloneAs<TTargetPixel>();
             return true;
         }
+
+        public void ReleaseFrameResources<TTargetPixel>(
+            Configuration configuration,
+            ICanvasFrame<TTargetPixel> target)
+            where TTargetPixel : unmanaged, IPixel<TTargetPixel>
+        {
+        }
     }
 }

tests/ImageSharp.Drawing.Tests/Processing/RasterizerDefaultsExtensionsTests.cs

@@ -65,5 +65,12 @@ public bool TryReadRegion<TPixel>(
             image = null;
             return false;
         }
+
+        public void ReleaseFrameResources<TPixel>(
+            Configuration configuration,
+            ICanvasFrame<TPixel> target)
+            where TPixel : unmanaged, IPixel<TPixel>
+        {
+        }
     }
 }