lightcraft/docs/gpu-pipeline.md

# 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).