Update docs.

Author: JimBobSquarePants

THIRD-PARTY-NOTICES

@@ -12,6 +12,7 @@ License: MIT
 
 Portions of this software were developed with reference to the Blaze
 project, including rasterization and related implementation techniques.
+See also: src/ImageSharp.Drawing/Processing/Backends/DEFAULT_RASTERIZER.MD
 
 Copyright (c) 2023 Aurimas Gasiulis
 
@@ -26,6 +27,9 @@ License: Apache-2.0 OR MIT
 Portions of this software were developed with reference to the Vello project,
 including GPU rasterization pipeline structure, shader stages, and related
 implementation techniques.
+See also:
+  - src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND.md
+  - src/ImageSharp.Drawing.WebGPU/WEBGPU_RASTERIZER.md
 
 Copyright 2020 the Vello Authors
 

src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND.md

@@ -0,0 +1,244 @@
+# WebGPU Backend
+
+`WebGPUDrawingBackend` is the GPU execution backend for ImageSharp.Drawing. It receives one flush worth of prepared drawing commands, decides whether that flush can stay on the staged GPU path, and if so creates and dispatches the staged scene pipeline against a native WebGPU target.
+
+The WebGPU backend and staged scene pipeline are based on ideas and implementation techniques from Vello:
+
+- https://github.com/linebender/vello
+
+This document explains the backend as a newcomer would need to understand it:
+
+- 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
+
+## 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.
+
+The backend still has to decide:
+
+- whether the target and scene are eligible for the GPU path
+- whether the staged scene can be created safely and legally on the current device
+- when the backend should remain on the GPU and when it should fall back
+- how GPU-only concerns such as native targets, flush-scoped resources, and device-scoped caches fit around the staged raster pipeline
+
+That is why the backend layer exists separately from the staged scene pipeline itself.
+
+The raster pipeline solves "how to rasterize this encoded scene on the GPU".  
+`WebGPUDrawingBackend` solves "should this flush go there, and how does the system manage that decision cleanly".
+
+## The Core Idea
+
+The WebGPU backend is a policy and orchestration layer around a staged GPU rasterizer.
+
+Its central idea is:
+
+> decide at the backend boundary whether the flush can stay on the GPU, then either run the staged scene pipeline as one flush-scoped unit of work or fall back cleanly
+
+That means `WebGPUDrawingBackend` is responsible for entry-point orchestration, not for every low-level GPU detail.
+
+## The Most Important Terms
+
+### Backend
+
+`WebGPUDrawingBackend` is the top-level GPU executor. It owns:
+
+- per-flush diagnostic state
+- staged-scene creation attempts
+- the decision to run the staged path or fall back
+- GPU layer composition when that path is eligible
+
+It is the policy boundary of the GPU path.
+
+### Flush Context
+
+`WebGPUFlushContext` is the flush-scoped execution context for one GPU flush.
+
+It owns:
+
+- the runtime lease
+- device and queue access
+- the target texture and target view
+- the command encoder and optional compute pass encoder
+- the native resources created during the flush
+
+The important lifetime rule is simple:
+
+unless something is explicitly cached in `WebGPURuntime.DeviceSharedState`, it is flush-scoped.
+
+### Staged Scene
+
+A staged scene is the GPU-oriented representation of one flush.
+
+It is produced by the encoder and then consumed by the staged raster pipeline. The staged scene itself is explained in the rasterizer document; from the backend point of view, it is the unit of GPU work that either succeeds as a whole or causes fallback.
+
+### Fallback
+
+Fallback means the backend gives the flush to `DefaultDrawingBackend` and then uploads the CPU result into the native target.
+
+Fallback is part of the design, not an error-handling afterthought. The backend is built to decide as early and cleanly as possible when the staged GPU path cannot or should not run.
+
+## The Big Picture Flow
+
+The easiest way to understand the backend is to follow one normal flush from entry to backend decision.
+
+```mermaid
+flowchart TD
+    A[DrawingCanvas.Flush] --> B[WebGPUDrawingBackend.FlushCompositions]
+    B --> C[Clear diagnostics]
+    C --> D[Try create staged scene]
+    D -->|Succeeded| E[Run staged scene pipeline]
+    D -->|Failed or unsupported| F[CPU fallback]
+    E --> G[Flush completes on GPU]
+    F --> H[CPU result uploaded to native target]
+```
+
+The staged scene pipeline itself is described in [`WEBGPU_RASTERIZER.md`](d:/GitHub/SixLabors/ImageSharp.Drawing/src/ImageSharp.Drawing.WebGPU/WEBGPU_RASTERIZER.md). The important backend point is that the whole GPU flush is treated as one coherent attempt.
+
+## What `WebGPUDrawingBackend` Owns
+
+`WebGPUDrawingBackend` is deliberately smaller than the total amount of GPU code around it. It owns orchestration and policy, not the full details of scene encoding or dispatch.
+
+Its responsibilities are:
+
+- clear per-flush diagnostics
+- try to create a staged scene
+- run the staged path if scene creation succeeds
+- fall back cleanly if any stage fails
+- run GPU layer composition when that path is eligible
+
+The expensive staged work is delegated:
+
+- `WebGPUSceneEncoder` owns scene encoding
+- `WebGPUSceneConfig` owns planning data
+- `WebGPUSceneResources` owns flush-scoped GPU resources
+- `WebGPUSceneDispatch` owns the staged compute pipeline
+
+## The Flush Boundary
+
+`FlushCompositions<TPixel>(...)` in `WebGPUDrawingBackend.cs` is the top-level scene flush entry point.
+
+Its job is intentionally narrow:
+
+- clear the previous diagnostics
+- try to build a staged GPU scene for the current flush
+- run the staged pipeline if that creation succeeds
+- fall back if creation, validation, or dispatch cannot complete safely
+
+Keeping those decisions at the boundary is important. The backend is designed to avoid discovering halfway through execution that one part of the scene ran on the GPU and another must suddenly fall back.
+
+## Scene Eligibility
+
+Before the expensive GPU work begins, the backend performs a scene-level eligibility check through the encoder path.
+
+That check answers the first important question:
+
+"is this flush even a candidate for the staged WebGPU path"
+
+This is distinct from later GPU planning checks. At this stage the backend is only trying to rule out unsupported scene features early, before it starts creating resources or recording dispatches.
+
+## Flush Context Creation
+
+If the scene is eligible, the backend creates a `WebGPUFlushContext`.
+
+This is the point where the abstract prepared scene becomes tied to:
+
+- a concrete device
+- a concrete queue
+- a concrete native target
+- a concrete command encoder
+
+The flush context is also the ownership boundary for flush-scoped GPU resources. When the flush ends, those resources leave with the context unless they are part of device-shared runtime state.
+
+## Fallback As Part Of The Architecture
+
+If any stage fails, `FlushCompositionsFallback(...)` runs the scene on `DefaultDrawingBackend` and uploads the CPU result into the native target.
+
+Fallback covers cases such as:
+
+- unsupported scene features
+- unsupported target or format conditions
+- binding-limit failures
+- resource-creation failures
+- dispatch failures
+
+The architectural goal is simple:
+
+decide as much as possible up front, fall back cleanly, and avoid leaving the flush half-executed across two backends.
+
+## Layer Composition
+
+GPU layer composition is a separate path from staged scene rasterization.
+
+That path lives in:
+
+- `WebGPUDrawingBackend.ComposeLayer.cs`
+- `ComposeLayerComputeShader.cs`
+
+Its job is smaller and different. It composites already-rasterized layer pixels rather than running the full vector scene pipeline.
+
+```mermaid
+flowchart TD
+    A[Saved layer] --> B[TryComposeLayerGpu]
+    B -->|Native destination supports it| C[ComposeLayer compute shader]
+    B -->|Unsupported| D[CPU compose path]
+```
+
+Keeping layer composition separate from staged scene rasterization makes the backend easier to reason about.
+
+## Runtime And Caching
+
+`WebGPURuntime` and `WebGPURuntime.DeviceSharedState` hold the resources that outlive a single flush.
+
+They cache things such as:
+
+- device access
+- compute pipelines
+- composite pipelines
+- a small amount of reusable device-scoped support state
+
+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.
+
+## Relationship To The Rasterizer Doc
+
+This document stops at the backend boundary and the high-level flush flow.
+
+The staged scene pipeline itself is described in [`WEBGPU_RASTERIZER.md`](d:/GitHub/SixLabors/ImageSharp.Drawing/src/ImageSharp.Drawing.WebGPU/WEBGPU_RASTERIZER.md), including:
+
+- scene encoding
+- planning
+- resource creation
+- scheduling passes
+- fine rasterization
+- chunked oversized-scene execution
+- copy and submission
+
+## Reading Guide
+
+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`
+
+That order mirrors the newcomer view of the system:
+
+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:
+
+- `WebGPUDrawingBackend` orchestrates and decides policy
+- `WebGPUFlushContext` owns one flush's execution state
+- `WebGPURuntime` owns longer-lived device state
+- the staged scene pipeline is a separate subsystem described in the rasterizer doc