Remove HybridCanvasFrame and hybrid APIs

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND.md

@@ -24,7 +24,7 @@ The public WebGPU surface area around this backend is small and target-first:
 - `WebGPUDeviceContext<TPixel>` wraps a shared or caller-owned device and queue and creates native-only or hybrid frames and canvases over external textures
 - `WebGPUNativeSurfaceFactory` is the low-level escape hatch for caller-owned native targets
 
-Those types all exist to get a `DrawingCanvas<TPixel>` over a native WebGPU target, sometimes paired with a CPU region through `HybridCanvasFrame<TPixel>`. Once the canvas flushes, `WebGPUDrawingBackend` becomes the execution boundary.
+Those types all exist to get a `DrawingCanvas<TPixel>` over a native WebGPU target. Once the canvas flushes, `WebGPUDrawingBackend` becomes the execution boundary.
 
 The support probes also live outside the backend:
 

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

@@ -2,7 +2,6 @@
 // Licensed under the Six Labors Split License.
 
 using Silk.NET.WebGPU;
-using SixLabors.ImageSharp.Memory;
 using SixLabors.ImageSharp.PixelFormats;
 
 namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
@@ -167,74 +166,6 @@ public NativeCanvasFrame<TPixel> CreateFrame(
         int height)
         => new(CreateBounds(width, height), this.CreateSurface(textureHandle, textureViewHandle, format, width, height));
 
-    /// <summary>
-    /// Creates a hybrid frame over an externally-owned WebGPU texture and a caller-provided CPU region.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="width">The frame width in pixels.</param>
-    /// <param name="height">The frame height in pixels.</param>
-    /// <param name="cpuRegion">The CPU region to expose alongside the native surface.</param>
-    /// <returns>A hybrid canvas frame.</returns>
-    public HybridCanvasFrame<TPixel> CreateHybridFrame(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        int width,
-        int height,
-        Buffer2DRegion<TPixel> cpuRegion)
-        => new(CreateBounds(width, height), cpuRegion, this.CreateSurface(textureHandle, textureViewHandle, format, width, height));
-
-    /// <summary>
-    /// Creates a hybrid frame over an externally-owned WebGPU texture and the root frame of a CPU image.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="image">The CPU image that backs the frame's CPU region.</param>
-    /// <returns>A hybrid canvas frame.</returns>
-    public HybridCanvasFrame<TPixel> CreateHybridFrame(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        Image<TPixel> image)
-    {
-        Guard.NotNull(image, nameof(image));
-        return this.CreateHybridFrame(
-            textureHandle,
-            textureViewHandle,
-            format,
-            image.Width,
-            image.Height,
-            GetImageRegion(image));
-    }
-
-    /// <summary>
-    /// Creates a hybrid frame over an externally-owned WebGPU texture and a CPU image frame.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="imageFrame">The CPU image frame that backs the frame's CPU region.</param>
-    /// <returns>A hybrid canvas frame.</returns>
-    public HybridCanvasFrame<TPixel> CreateHybridFrame(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        ImageFrame<TPixel> imageFrame)
-    {
-        Guard.NotNull(imageFrame, nameof(imageFrame));
-        Rectangle bounds = imageFrame.Bounds;
-        return this.CreateHybridFrame(
-            textureHandle,
-            textureViewHandle,
-            format,
-            bounds.Width,
-            bounds.Height,
-            GetImageRegion(imageFrame));
-    }
-
     /// <summary>
     /// Creates a drawing canvas over an externally-owned WebGPU texture.
     /// </summary>
@@ -271,110 +202,6 @@ public DrawingCanvas<TPixel> CreateCanvas(
         DrawingOptions options)
         => new(this.Configuration, this.Backend, this.CreateFrame(textureHandle, textureViewHandle, format, width, height), options);
 
-    /// <summary>
-    /// Creates a hybrid drawing canvas over an externally-owned WebGPU texture and a caller-provided CPU region.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="width">The frame width in pixels.</param>
-    /// <param name="height">The frame height in pixels.</param>
-    /// <param name="cpuRegion">The CPU region to expose alongside the native surface.</param>
-    /// <returns>A drawing canvas targeting the external texture and CPU region.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        int width,
-        int height,
-        Buffer2DRegion<TPixel> cpuRegion)
-        => new(this.Configuration, this.Backend, this.CreateHybridFrame(textureHandle, textureViewHandle, format, width, height, cpuRegion), new DrawingOptions());
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over an externally-owned WebGPU texture and a caller-provided CPU region.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="width">The frame width in pixels.</param>
-    /// <param name="height">The frame height in pixels.</param>
-    /// <param name="cpuRegion">The CPU region to expose alongside the native surface.</param>
-    /// <param name="options">The initial drawing options.</param>
-    /// <returns>A drawing canvas targeting the external texture and CPU region.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        int width,
-        int height,
-        Buffer2DRegion<TPixel> cpuRegion,
-        DrawingOptions options)
-        => new(this.Configuration, this.Backend, this.CreateHybridFrame(textureHandle, textureViewHandle, format, width, height, cpuRegion), options);
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over an externally-owned WebGPU texture and the root frame of a CPU image.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="image">The CPU image that backs the frame's CPU region.</param>
-    /// <returns>A drawing canvas targeting the external texture and CPU image.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        Image<TPixel> image)
-        => new(this.Configuration, this.Backend, this.CreateHybridFrame(textureHandle, textureViewHandle, format, image), new DrawingOptions());
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over an externally-owned WebGPU texture and a CPU image frame.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="imageFrame">The CPU image frame that backs the frame's CPU region.</param>
-    /// <returns>A drawing canvas targeting the external texture and CPU image frame.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        ImageFrame<TPixel> imageFrame)
-        => new(this.Configuration, this.Backend, this.CreateHybridFrame(textureHandle, textureViewHandle, format, imageFrame), new DrawingOptions());
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over an externally-owned WebGPU texture and the root frame of a CPU image.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="image">The CPU image that backs the frame's CPU region.</param>
-    /// <param name="options">The initial drawing options.</param>
-    /// <returns>A drawing canvas targeting the external texture and CPU image.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        Image<TPixel> image,
-        DrawingOptions options)
-        => new(this.Configuration, this.Backend, this.CreateHybridFrame(textureHandle, textureViewHandle, format, image), options);
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over an externally-owned WebGPU texture and a CPU image frame.
-    /// </summary>
-    /// <param name="textureHandle">The opaque <c>WGPUTexture*</c> handle.</param>
-    /// <param name="textureViewHandle">The opaque <c>WGPUTextureView*</c> handle.</param>
-    /// <param name="format">The texture format identifier.</param>
-    /// <param name="imageFrame">The CPU image frame that backs the frame's CPU region.</param>
-    /// <param name="options">The initial drawing options.</param>
-    /// <returns>A drawing canvas targeting the external texture and CPU image frame.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(
-        nint textureHandle,
-        nint textureViewHandle,
-        WebGPUTextureFormatId format,
-        ImageFrame<TPixel> imageFrame,
-        DrawingOptions options)
-        => new(this.Configuration, this.Backend, this.CreateHybridFrame(textureHandle, textureViewHandle, format, imageFrame), options);
-
     /// <summary>
     /// Disposes the drawing backend owned by this context.
     /// </summary>
@@ -446,10 +273,4 @@ private static Rectangle CreateBounds(int width, int height)
 
         return new Rectangle(0, 0, width, height);
     }
-
-    private static Buffer2DRegion<TPixel> GetImageRegion(Image<TPixel> image)
-        => new(image.Frames.RootFrame.PixelBuffer, image.Bounds);
-
-    private static Buffer2DRegion<TPixel> GetImageRegion(ImageFrame<TPixel> imageFrame)
-        => new(imageFrame.PixelBuffer, imageFrame.Bounds);
 }

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

@@ -165,40 +165,6 @@ public NativeCanvasFrame<TPixel> CreateFrame()
         return this.NativeFrame;
     }
 
-    /// <summary>
-    /// Creates a hybrid frame over this render target and a caller-provided CPU region.
-    /// </summary>
-    /// <param name="cpuRegion">The CPU region to expose alongside the native surface.</param>
-    /// <returns>A hybrid frame.</returns>
-    public HybridCanvasFrame<TPixel> CreateHybridFrame(Buffer2DRegion<TPixel> cpuRegion)
-    {
-        this.ThrowIfDisposed();
-        this.Graphics.ThrowIfDisposed();
-        return new HybridCanvasFrame<TPixel>(this.Bounds, cpuRegion, this.Surface);
-    }
-
-    /// <summary>
-    /// Creates a hybrid frame over this render target and the root frame of a CPU image.
-    /// </summary>
-    /// <param name="image">The CPU image that backs the frame's CPU region.</param>
-    /// <returns>A hybrid frame.</returns>
-    public HybridCanvasFrame<TPixel> CreateHybridFrame(Image<TPixel> image)
-    {
-        Guard.NotNull(image, nameof(image));
-        return this.CreateHybridFrame(new Buffer2DRegion<TPixel>(image.Frames.RootFrame.PixelBuffer, image.Bounds));
-    }
-
-    /// <summary>
-    /// Creates a hybrid frame over this render target and a CPU image frame.
-    /// </summary>
-    /// <param name="imageFrame">The CPU image frame that backs the frame's CPU region.</param>
-    /// <returns>A hybrid frame.</returns>
-    public HybridCanvasFrame<TPixel> CreateHybridFrame(ImageFrame<TPixel> imageFrame)
-    {
-        Guard.NotNull(imageFrame, nameof(imageFrame));
-        return this.CreateHybridFrame(new Buffer2DRegion<TPixel>(imageFrame.PixelBuffer, imageFrame.Bounds));
-    }
-
     /// <summary>
     /// Creates a drawing canvas over this native-only render target.
     /// </summary>
@@ -218,67 +184,6 @@ public DrawingCanvas<TPixel> CreateCanvas(DrawingOptions options)
         return new DrawingCanvas<TPixel>(this.Graphics.Configuration, this.Graphics.Backend, this.NativeFrame, options);
     }
 
-    /// <summary>
-    /// Creates a hybrid drawing canvas over this render target and a caller-provided CPU region.
-    /// </summary>
-    /// <param name="cpuRegion">The CPU region to expose alongside the native surface.</param>
-    /// <returns>A drawing canvas targeting this render target and CPU region.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(Buffer2DRegion<TPixel> cpuRegion)
-        => this.CreateHybridCanvas(cpuRegion, new DrawingOptions());
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over this render target and a caller-provided CPU region.
-    /// </summary>
-    /// <param name="cpuRegion">The CPU region to expose alongside the native surface.</param>
-    /// <param name="options">The initial drawing options.</param>
-    /// <returns>A drawing canvas targeting this render target and CPU region.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(Buffer2DRegion<TPixel> cpuRegion, DrawingOptions options)
-    {
-        this.ThrowIfDisposed();
-        this.Graphics.ThrowIfDisposed();
-        return new DrawingCanvas<TPixel>(this.Graphics.Configuration, this.Graphics.Backend, this.CreateHybridFrame(cpuRegion), options);
-    }
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over this render target and the root frame of a CPU image.
-    /// </summary>
-    /// <param name="image">The CPU image that backs the frame's CPU region.</param>
-    /// <returns>A drawing canvas targeting this render target and CPU image.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(Image<TPixel> image)
-        => this.CreateHybridCanvas(image, new DrawingOptions());
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over this render target and the root frame of a CPU image.
-    /// </summary>
-    /// <param name="image">The CPU image that backs the frame's CPU region.</param>
-    /// <param name="options">The initial drawing options.</param>
-    /// <returns>A drawing canvas targeting this render target and CPU image.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(Image<TPixel> image, DrawingOptions options)
-    {
-        Guard.NotNull(image, nameof(image));
-        return this.CreateHybridCanvas(new Buffer2DRegion<TPixel>(image.Frames.RootFrame.PixelBuffer, image.Bounds), options);
-    }
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over this render target and a CPU image frame.
-    /// </summary>
-    /// <param name="imageFrame">The CPU image frame that backs the frame's CPU region.</param>
-    /// <returns>A drawing canvas targeting this render target and CPU image frame.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(ImageFrame<TPixel> imageFrame)
-        => this.CreateHybridCanvas(imageFrame, new DrawingOptions());
-
-    /// <summary>
-    /// Creates a hybrid drawing canvas over this render target and a CPU image frame.
-    /// </summary>
-    /// <param name="imageFrame">The CPU image frame that backs the frame's CPU region.</param>
-    /// <param name="options">The initial drawing options.</param>
-    /// <returns>A drawing canvas targeting this render target and CPU image frame.</returns>
-    public DrawingCanvas<TPixel> CreateHybridCanvas(ImageFrame<TPixel> imageFrame, DrawingOptions options)
-    {
-        Guard.NotNull(imageFrame, nameof(imageFrame));
-        return this.CreateHybridCanvas(new Buffer2DRegion<TPixel>(imageFrame.PixelBuffer, imageFrame.Bounds), options);
-    }
-
     /// <summary>
     /// Attempts to read the current GPU texture contents back into a new CPU image.
     /// </summary>

src/ImageSharp.Drawing/Processing/Backends/HybridCanvasFrame{TPixel}.cs

@@ -119,7 +119,7 @@ That abstraction lets the same canvas target:
 
 - pure CPU memory with `MemoryCanvasFrame<TPixel>`
 - a native or GPU surface with `NativeCanvasFrame<TPixel>`
-- a combined CPU plus native target with `HybridCanvasFrame<TPixel>`
+- a combined CPU plus native target
 - a clipped view over another frame with `CanvasRegionFrame<TPixel>`
 
 The point is not to hide all differences. The point is to express the minimum target contract the backends need.