Skip to content

LightCraft: An open-source non-destructive photo editor written by scratch in pure Rust

M5.2: GPU pipeline design note (wgpu compute, CPU oracle, stage-cache mapping)

Brandon Thomas419555655171
diff --git a/docs/gpu-pipeline.md b/docs/gpu-pipeline.md
new file mode 100644
index 000000000..94b99179d
--- /dev/null
+++ b/docs/gpu-pipeline.md
@@ -0,0 +1,67 @@
+# GPU develop pipeline — design note (M5.2, not implemented yet)
+
+The CPU pipeline (`crates/pipeline`) is the reference ("oracle"). A `lightcraft-gpu` crate (L3) will
+evaluate the same stages with wgpu compute shaders (WGSL), on native (Metal/Vulkan/DX12) and on the
+web (WebGPU). This note records the plan so the CPU work in M5 stays compatible with it.
+
+## Why, and what the CPU path already does
+- CPU numbers (24 MP source, 2560 px preview, ~2.5 MP loupe; see `crates/engine/examples/render_bench.rs`):
+ the per-pixel stage (`finish`) costs ~50 ns/px of CPU time with typical edits (+~65 ns/px with
+ vibrance/saturation: the OkLCh round trip), noise reduction + spatial planes another ~80 ns/px
+ when they have to be recomputed. With all cores and the stage cache this meets the CPU budgets
+ for tone/colour drags (~7 ms draft, ~18 ms full at 2.5 MP); a GPU makes cold full-quality
+ renders, NR drags, 4–8K displays and 1:1 zoom of 60 MP files interactive, and frees the CPU for
+ previews/import.
+- The CPU path is already structured the way the GPU path wants it:
+ - **Stage cache** (`StageCache`): resampled source → white-balanced/denoised image → spatial
+ planes (log luminance, guided base, clarity/texture bands, dark channel) → per-pixel stage. Each
+ stage is keyed by the settings that feed it. On the GPU the same keys decide which textures are
+ still valid; a tone/colour/exposure drag re-runs one full-screen compute pass.
+ - **Exposure after the spatial filters** (shift-equivariant on log luminance), so exposure is a
+ per-pixel uniform, not a cache invalidation.
+ - **Draft quality** during drags (smaller output, capped base radius), full on release.
+
+## Architecture
+- `lightcraft-gpu` owns a `wgpu::Device` (shared with eframe's when running in the desktop app, so
+ the loupe texture never leaves the GPU; headless device for CLI/MCP/export).
+- Resident per-photo state: the source pyramid as `rgba16float` textures (levels /2, /4, … down to
+ the thumbnail), uploaded once per photo; the stage textures mirror `StageCache` entries
+ (`r32float` planes, `rgba16float` images).
+- Kernels (one WGSL module each, workgroups of 16×16, storage textures):
+ 1. `sample`: orientation + crop/rotate + flips from the nearest pyramid level (bilinear on the
+ level ≥ output scale — matches the CPU's area-prefiltered resample within tolerance).
+ 2. `wb`: 3×3 matrix (+ spots as instanced quads: copy/blend from the source offset).
+ 3. `nr`: guided filter on log luminance (box sums via two-pass separable running sums in shared
+ memory, or a summed-area table for large radii) + chroma Gaussian.
+ 4. `planes`: log luminance; guided base / clarity (fast guided filter: coefficients on a /s
+ subsampled grid, bilinear upsample — exactly the CPU `guided_fast` structure); texture
+ Gaussian (3 box passes); dark channel Gaussian + airlight (parallel reduction: histogram of the
+ dark channel → 99.5th percentile).
+ 5. `masks`: one pass per mask shape (analytic shapes evaluate per pixel; brushes rasterized as
+ instanced soft discs; range masks read the image/planes).
+ 6. `finish`: the per-pixel stage, a straight port of `finish.rs` (tone LUT and curve LUTs as 1D
+ textures, colour ops in OkLCh, gamut map, sRGB encode, grain hash). Output `rgba8unorm` for
+ display, `rgba16float`/`rgba32float` for export.
+ 7. `histogram`: atomics into a storage buffer (256 bins × 4).
+- Readback only for export and for `ui.screenshot`/MCP renders.
+
+## Correctness: CPU oracle and equivalence tests
+- Every kernel has a CPU twin; tests render the synthetic scenes (`lightcraft-scenes`) on both and
+ require max |Δ| ≤ 1/1023 in display-encoded values (architecture §1.6), plus the existing pipeline
+ tests run against the GPU renderer behind a feature flag. Tests skip (not fail) when no adapter is
+ available (CI machines), with a software adapter (wgpu's GL/lavapipe) where possible.
+- Float determinism: avoid fast-math-sensitive constructs (fused multiply-add differences are within
+ tolerance); reductions (airlight, histogram) use integer atomics.
+
+## Scheduling
+- One render queue per view; a new revision cancels queued work for the old one (CPU already drops
+ superseded jobs per slot). Drafts during drags at display size (GPU can afford full size), full
+ quality (larger NR/guided radii at source resolution for 1:1) on release.
+- Fallback order: GPU → CPU (`render_cached`) when no adapter, on device loss, or for wasm builds
+ without WebGPU.
+
+## Open questions
+- f16 vs f32 storage for planes (bandwidth vs. guided-filter precision: start with f32).
+- Sharing the device with eframe on the web (single WebGPU device per canvas).
+- Large exports (60 MP+) exceed texture limits on some adapters (8192/16384): tile with overlap
+ equal to the largest filter radius (the planes' radii are known per settings).