Patch test, update docs

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND.md

@@ -8,11 +8,31 @@ The WebGPU backend and staged scene pipeline are based on ideas and implementati
 
 This document explains the backend as a newcomer would need to understand it:
 
+- where the public WebGPU entry points fit
 - what problem the WebGPU backend is solving
 - what `WebGPUDrawingBackend` actually owns
 - how one flush moves through the backend boundary
 - where fallback, layer composition, and runtime caching fit into the design
 
+## Where The Public WebGPU Types Fit
+
+The public WebGPU surface area around this backend is small and target-first:
+
+- `WebGPUEnvironment` exposes explicit support probes for the library-managed WebGPU environment
+- `WebGPUWindow<TPixel>` owns a native window and either runs a render loop or returns `WebGPUWindowFrame<TPixel>` instances through `TryAcquireFrame(...)`
+- `WebGPURenderTarget<TPixel>` owns an offscreen native target for GPU rendering, hybrid CPU plus GPU canvases, and readback
+- `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.
+
+The support probes also live outside the backend:
+
+- `WebGPUEnvironment.TryProbeAvailability(...)` checks whether the library-managed WebGPU device and queue can be acquired
+- `WebGPUEnvironment.TryProbeComputePipelineSupport(...)` runs the crash-isolated trivial compute-pipeline probe
+
+That split keeps support probing separate from flush execution. `WebGPUDrawingBackend` is the flush executor, not the public support API. The WebGPU constructors create their objects directly; callers use `WebGPUEnvironment` when they want explicit preflight checks.
+
 ## The Main Problem
 
 The canvas hands the backend a prepared composition scene. That is already a big simplification, but it does not mean the GPU can render that scene directly.
@@ -52,6 +72,13 @@ That means `WebGPUDrawingBackend` is responsible for entry-point orchestration,
 
 It is the policy boundary of the GPU path.
 
+It does not own:
+
+- public support probing
+- window creation
+- render-target allocation APIs
+- caller-device or caller-surface interop setup
+
 ### Flush Context
 
 `WebGPUFlushContext` is the flush-scoped execution context for one GPU flush.
@@ -116,6 +143,12 @@ The expensive staged work is delegated:
 - `WebGPUSceneResources` owns flush-scoped GPU resources
 - `WebGPUSceneDispatch` owns the staged compute pipeline
 
+The public object graph around those responsibilities is also separate:
+
+- `WebGPUEnvironment` handles explicit support probes
+- `WebGPUWindow<TPixel>`, `WebGPURenderTarget<TPixel>`, and `WebGPUDeviceContext<TPixel>` construct native targets, frames, and canvases
+- `DrawingCanvas<TPixel>` hands a prepared `CompositionScene` to the backend
+
 ## The Flush Boundary
 
 `FlushCompositions<TPixel>(...)` in `WebGPUDrawingBackend.cs` is the top-level scene flush entry point.
@@ -199,6 +232,8 @@ They cache things such as:
 - composite pipelines
 - a small amount of reusable device-scoped support state
 
+`WebGPURuntime` also backs the explicit support probes surfaced by `WebGPUEnvironment`. The probe and runtime layer is where the library-managed device/queue availability and crash-isolated compute-pipeline test are cached.
+
 Everything else in the staged scene path is intentionally flush-scoped.
 
 That split keeps flushes isolated while still allowing truly device-scoped state to be reused.
@@ -221,23 +256,27 @@ The staged scene pipeline itself is described in [`WEBGPU_RASTERIZER.md`](d:/Git
 
 If you want to understand the backend first, read the code in this order:
 
-1. `WebGPUDrawingBackend.cs`
-2. `WebGPUFlushContext.cs`
-3. `WebGPURuntime.cs`
-4. `WebGPURuntime.DeviceSharedState.cs`
-5. `WebGPUDrawingBackend.ComposeLayer.cs`
-6. `WEBGPU_RASTERIZER.md`
+1. `WebGPUEnvironment.cs`
+2. `WebGPUWindow{TPixel}.cs`, `WebGPUWindowFrame{TPixel}.cs`, `WebGPURenderTarget{TPixel}.cs`, and `WebGPUDeviceContext{TPixel}.cs`
+3. `WebGPUDrawingBackend.cs`
+4. `WebGPUFlushContext.cs`
+5. `WebGPURuntime.cs`
+6. `WebGPURuntime.DeviceSharedState.cs`
+7. `WebGPUDrawingBackend.ComposeLayer.cs`
+8. `WEBGPU_RASTERIZER.md`
 
 That order mirrors the newcomer view of the system:
 
-backend policy -> flush context -> runtime lifetime -> layer composition -> staged raster pipeline
+support and target setup -> backend policy -> flush context -> runtime lifetime -> layer composition -> staged raster pipeline
 
 ## The Mental Model To Keep
 
 The easiest way to keep this backend straight is to remember that it is not the rasterizer itself. It is the orchestration and policy layer around a staged GPU rasterizer. It decides whether a flush can stay on the GPU, runs that staged path as one flush-scoped unit of work, and falls back cleanly when it cannot.
 
 If that model is clear, the major types fall into place:
 
+- `WebGPUEnvironment` exposes explicit support probes
+- `WebGPUWindow<TPixel>`, `WebGPURenderTarget<TPixel>`, and `WebGPUDeviceContext<TPixel>` create canvases over native targets
 - `WebGPUDrawingBackend` orchestrates and decides policy
 - `WebGPUFlushContext` owns one flush's execution state
 - `WebGPURuntime` owns longer-lived device state

src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND_PROCESS.md

@@ -3,7 +3,7 @@
 The WebGPU documentation is split into two newcomer-first documents:
 
 - [`WEBGPU_BACKEND.md`](d:/GitHub/SixLabors/ImageSharp.Drawing/src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND.md)
-  Explains what `WebGPUDrawingBackend` owns, how a flush reaches the GPU path, where fallback lives, how layer composition fits in, and how runtime/device-scoped state relates to flush-scoped work.
+  Explains how `WebGPUEnvironment`, the public target types, and `WebGPUDrawingBackend` fit together, how a flush reaches the GPU path, where explicit support probing fits, where fallback lives, how layer composition fits in, and how runtime/device-scoped state relates to flush-scoped work.
 
 - [`WEBGPU_RASTERIZER.md`](d:/GitHub/SixLabors/ImageSharp.Drawing/src/ImageSharp.Drawing.WebGPU/WEBGPU_RASTERIZER.md)
   Explains the staged scene pipeline itself: scene encoding, planning, resource creation, scheduling passes, fine rasterization, chunked oversized-scene execution, and submission.

src/ImageSharp.Drawing.WebGPU/WEBGPU_RASTERIZER.md

@@ -12,6 +12,13 @@ In this codebase, the WebGPU rasterizer is not a single type with one scan-conve
 
 Together, these types turn one prepared flush into a staged GPU scene, schedule that scene into tile-relative work, run the fine raster pass, and write final pixels.
 
+This document starts after two earlier boundaries have already been crossed:
+
+- public WebGPU setup has already selected or created a native target through `WebGPUWindow<TPixel>`, `WebGPURenderTarget<TPixel>`, `WebGPUDeviceContext<TPixel>`, or `WebGPUNativeSurfaceFactory`
+- `WebGPUDrawingBackend` has already decided that the flush should stay on the GPU path
+
+Support probing through `WebGPUEnvironment` also sits outside this document. The rasterizer describes execution of one staged scene, not environment detection or object construction.
+
 The staged GPU rasterizer is based on ideas and implementation techniques from Vello:
 
 - https://github.com/linebender/vello
@@ -285,6 +292,12 @@ The backend decides:
 - how layer composition is handled
 - how flush-scoped work relates to runtime and device-scoped state
 
+The public setup layer decides:
+
+- how a caller acquires or owns the native target
+- whether support should be probed explicitly through `WebGPUEnvironment`
+- whether the caller is using a library-managed device or caller-owned native handles
+
 That separation is why it helps to document them separately.
 
 ## Reading Guide

src/ImageSharp.Drawing/Processing/Backends/DEFAULT_DRAWING_BACKEND.md

@@ -4,11 +4,25 @@
 
 This document explains the backend as a system rather than as a list of methods. The goal is to help a newcomer understand:
 
+- where the CPU backend fits in the canvas/backend selection model
 - what problem the CPU backend is solving
 - why the backend is organized around a flush-scoped execution plan
 - what `FlushScene` means in this architecture
 - how rasterization, brush application, and layer composition fit together
 
+## Where The CPU Backend Fits
+
+`DefaultDrawingBackend` is the standard CPU execution path behind `DrawingCanvas<TPixel>`.
+
+The canvas architecture reaches this backend in two common ways:
+
+- ordinary `DrawingCanvas<TPixel>` construction resolves `IDrawingBackend` from `Configuration`
+- specialized infrastructure can construct a canvas with an explicit backend instance
+
+The CPU path usually uses the first route. The WebGPU helpers use the second route when they need a canvas that targets a native surface through `WebGPUDrawingBackend`.
+
+That means the CPU backend is one backend implementation within the shared canvas architecture, not a separate public drawing model. It executes against any frame that exposes a writable CPU region, whether that frame is pure memory or a hybrid frame that also carries a native surface.
+
 ## The Main Problem
 
 By the time work reaches `DefaultDrawingBackend`, the public drawing API has already been normalized into prepared commands. That is helpful, but it does not make CPU execution trivial.
@@ -57,6 +71,8 @@ If that idea is clear, most of the important types fall into place.
 
 It does not own every detail of geometry planning or scan conversion.
 
+It also does not own backend selection. By the time `FlushCompositions(...)` is called, `DrawingCanvas<TPixel>` has already chosen the backend instance that will receive the prepared scene.
+
 ### Scene
 
 In the canvas architecture, the backend receives a `CompositionScene`. That scene already contains prepared commands and explicit layer boundaries.
@@ -166,6 +182,12 @@ The expensive work is delegated:
 
 That split keeps each type focused on one class of problem.
 
+The canvas layer above that split is also important:
+
+- `DrawingCanvas<TPixel>` records public drawing intent
+- `DrawingCanvasBatcher<TPixel>` prepares commands and constructs `CompositionScene`
+- `DefaultDrawingBackend` executes the prepared scene on a CPU destination
+
 ## Building The Flush Scene
 
 `FlushScene.Create(...)` turns the prepared command stream into an execution plan in several phases. Each phase changes the data into a form that is cheaper for the next phase to consume.
@@ -324,22 +346,25 @@ That ownership model keeps allocation and disposal aligned with real work lifeti
 
 If you are new to this backend, read the code in this order:
 
-1. `DefaultDrawingBackend.cs`
-2. `FlushScene.cs`
-3. `FlushScene.RetainedTypes.cs`
-4. `DefaultDrawingBackend.Helpers.cs`
-5. `DefaultRasterizer.cs`
+1. `DrawingCanvas{TPixel}.cs`
+2. `DrawingCanvasBatcher{TPixel}.cs`
+3. `DefaultDrawingBackend.cs`
+4. `FlushScene.cs`
+5. `FlushScene.RetainedTypes.cs`
+6. `DefaultDrawingBackend.Helpers.cs`
+7. `DefaultRasterizer.cs`
 
 That order mirrors the runtime flow:
 
-backend orchestration -> flush planning -> row execution structures -> worker helpers -> scan conversion
+canvas and backend selection -> backend orchestration -> flush planning -> row execution structures -> worker helpers -> scan conversion
 
 ## The Mental Model To Keep
 
 The easiest way to keep this backend straight is to remember that it is not a command-at-a-time painter. It is a flush executor that converts visible commands into row-local retained raster work and then executes that work with reusable scratch.
 
 If that model is clear, the major types fall into place:
 
+- `DrawingCanvas<TPixel>` records intent and selects the backend
 - `DefaultDrawingBackend` orchestrates
 - `FlushScene` plans
 - `DefaultRasterizer` converts geometry to coverage

…rocessing/Backends/DEFAULT_RASTERIZER.MD …rocessing/Backends/DEFAULT_RASTERIZER.mdsrc/ImageSharp.Drawing/Processing/Backends/DEFAULT_RASTERIZER.MD renamed to src/ImageSharp.Drawing/Processing/Backends/DEFAULT_RASTERIZER.md src/ImageSharp.Drawing/Processing/Backends/DEFAULT_RASTERIZER.MD renamed to src/ImageSharp.Drawing/Processing/Backends/DEFAULT_RASTERIZER.md

@@ -8,11 +8,20 @@ This rasterizer is based on ideas and implementation techniques from the Blaze p
 
 This document explains the rasterizer as a newcomer needs to understand it:
 
+- where the rasterizer fits relative to `DrawingCanvas<TPixel>` and `DefaultDrawingBackend`
 - what problem the rasterizer is solving inside the CPU backend
 - why the rasterizer is split into retained geometry building and band execution
 - what retained geometry, bands, and coverage mean in this architecture
 - how scan conversion stays separate from brush shading and frame ownership
 
+## Where The Rasterizer Fits
+
+`DefaultRasterizer` sits below `DrawingCanvas<TPixel>` and `DefaultDrawingBackend`.
+
+The canvas records commands, the batcher prepares them into a `CompositionScene`, and `DefaultDrawingBackend` chooses the row-oriented execution plan for the flush. `DefaultRasterizer` then handles the narrower geometry-to-coverage problem inside that CPU execution path.
+
+That means the rasterizer does not select the backend, own the destination frame, or interpret the public drawing API directly. It receives already-prepared geometry through the CPU backend pipeline, and the backend later routes its coverage into whichever frame exposes the CPU region for the flush.
+
 ## The Main Problem
 
 The CPU backend does not want to rediscover shape geometry every time it touches a destination row.
@@ -117,13 +126,14 @@ Coverage is the rasterizer's output.
 
 The rasterizer does not decide final pixel colors. It decides how much geometric coverage each pixel receives. The backend later passes that coverage to a `BrushRenderer<TPixel>`, which decides how the destination pixels should be shaded.
 
-## Where The Rasterizer Fits
+## Pipeline Placement
 
 The rasterizer sits in the middle of the CPU backend pipeline.
 
 Upstream:
 
 - `CompositionCommand` preparation produces prepared geometry
+- `DrawingCanvas<TPixel>` and `DrawingCanvasBatcher<TPixel>` have already selected and called the CPU backend
 - `FlushScene` decides which items are visible and when they execute
 
 Downstream:
@@ -411,15 +421,19 @@ That separation is one of the main architectural advantages of the current CPU p
 
 If you are new to this part of the library, read the rasterizer in this order:
 
-1. `CreateRasterizableGeometry(...)` in `DefaultRasterizer.cs`
-2. `Linearizer<TL>` and the concrete linearizers in `DefaultRasterizer.Linearizer.cs`
-3. retained line types in `DefaultRasterizer.RetainedTypes.cs`
-4. `ExecuteRasterizableBand(...)` in `DefaultRasterizer.cs`
-5. `Context` in `DefaultRasterizer.cs`
+1. `DrawingCanvas{TPixel}.cs`
+2. `DrawingCanvasBatcher{TPixel}.cs`
+3. `DefaultDrawingBackend.cs`
+4. `FlushScene.cs`
+5. `CreateRasterizableGeometry(...)` in `DefaultRasterizer.cs`
+6. `Linearizer<TL>` and the concrete linearizers in `DefaultRasterizer.Linearizer.cs`
+7. retained line types in `DefaultRasterizer.RetainedTypes.cs`
+8. `ExecuteRasterizableBand(...)` in `DefaultRasterizer.cs`
+9. `Context` in `DefaultRasterizer.cs`
 
 That order mirrors the data lifecycle:
 
-prepared geometry -> retained storage -> band execution -> coverage emission
+canvas intent -> prepared geometry -> retained storage -> band execution -> coverage emission
 
 ## The Mental Model To Keep
 
@@ -429,6 +443,7 @@ it is a retained fixed-point polygon scanner that transforms prepared geometry i
 
 If that model stays clear, the rest of the code becomes easier to read:
 
+- the canvas and backend docs explain how execution reaches the CPU path
 - the linearizer explains where retained line data comes from
 - `RasterizableGeometry` explains what is stored
 - the `Context` explains how retained data becomes coverage

src/ImageSharp.Drawing/Processing/DRAWING_CANVAS.md

@@ -94,6 +94,15 @@ It is the backend handoff boundary.
 
 The backend receives a scene and a target frame. It decides how to execute that prepared work.
 
+There are two backend-selection paths in the architecture:
+
+- the ordinary public `DrawingCanvas<TPixel>` constructors resolve the backend from `Configuration`
+- specialized infrastructure can construct a canvas with an explicit backend
+
+The ordinary CPU entry points also include the `CreateCanvas(...)` extension methods on `Image<TPixel>` and `ImageFrame<TPixel>`, which route into those same constructors.
+
+That explicit-backend path matters for the WebGPU helpers. `WebGPUWindow<TPixel>`, `WebGPURenderTarget<TPixel>`, and `WebGPUDeviceContext<TPixel>` create canvases that point directly at their owned `WebGPUDrawingBackend` instance instead of storing that backend on the caller's `Configuration`.
+
 ### Frame
 
 `ICanvasFrame<TPixel>` is the target abstraction that the backend renders into.
@@ -110,6 +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 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.
@@ -311,6 +321,14 @@ It benefits from the same canvas-level decisions:
 - layers already exist as explicit boundaries
 - the frame already describes whether a native surface is available
 
+The WebGPU public helpers reach this point in a target-first way:
+
+- `WebGPUWindow<TPixel>` acquires a presentable native target per frame
+- `WebGPURenderTarget<TPixel>` owns an offscreen native target and can pair it with CPU memory through hybrid frames
+- `WebGPUDeviceContext<TPixel>` wraps shared or caller-owned device state and creates native-only or hybrid frames and canvases over native textures
+
+Those helpers all create `DrawingCanvas<TPixel>` instances with an explicit `WebGPUDrawingBackend`, so GPU execution stays attached to the WebGPU object that owns the native target and backend lifetime.
+
 The backend is free to choose a very different execution model because the canvas has already solved the shared semantics problem.
 
 ## The Practical Mental Model
@@ -338,15 +356,18 @@ Once those ideas are clear, the code stops looking like a random collection of t
 If you want to move from the architecture into the code, this is the best order.
 
 1. `DrawingCanvas{TPixel}.cs`
-2. `DrawingCanvasBatcher{TPixel}.cs`
-3. `CompositionCommand.cs`
-4. `CompositionCommandPreparer.cs`
-5. `DefaultDrawingBackend.cs`
-6. `FlushScene.cs`
-7. `WebGPUDrawingBackend` and its scene/dispatch types
+2. `DrawingCanvasExtensions.cs`
+3. `DrawingCanvasBatcher{TPixel}.cs`
+4. `CompositionCommand.cs`
+5. `CompositionCommandPreparer.cs`
+6. `DefaultDrawingBackend.cs`
+7. `FlushScene.cs`
+8. `WebGPUEnvironment.cs`
+9. `WebGPUWindow{TPixel}.cs`, `WebGPURenderTarget{TPixel}.cs`, and `WebGPUDeviceContext{TPixel}.cs`
+10. `WebGPUDrawingBackend` and its scene/dispatch types
 
 That path follows the real runtime flow:
 
-public API -> recorded command -> prepared scene -> backend execution
+public API -> recorded command -> prepared scene -> backend selection -> backend execution
 
 Following the code in that order is much easier than starting from the backend internals first.

tests/ImageSharp.Drawing.Tests/Processing/ProcessWithDrawingCanvasTests.Text.cs

@@ -346,8 +346,8 @@ public void FontShapesAreRenderedCorrectly_WithLineSpacing<TPixel>(
 
         Color color = Color.Black;
 
-        // NET472 is 0.0045 different.
-        ImageComparer comparer = ImageComparer.TolerantPercentage(0.0046F);
+        // Ubuntu on .NET 10 ARM reported a 0.0051% difference
+        ImageComparer comparer = ImageComparer.TolerantPercentage(0.0052F);
 
         provider.VerifyOperation(
             comparer,