# Volumetric Color Plan — colored multi-light + medium color

Design + dev-tracking doc for the volumetric in-scatter color work.
Canonical task list lives in GitHub issues; this doc is the design backing.

- Tracking issue: **#176**
- Slices: **A #177**, **B #178**, **C #179**, **D #180 (future)**, **E #181 (GPU)**
- Branch: `feat/volumetric-light-color`
- Companion roadmap: `Docs/Lighting-FX-Roadmap.md`

---

## 1. Problem

FF already has volumetric in-scatter (single-scattering Beer–Lambert god-rays,
`VolumeSteps` / `FogDensity` / FBM cloud noise; #172). But the in-scatter loop
colors the fog from **`Light1.Color` only**:

- `Engine/Rendering/Lighting/ShadingPipeline.cs`
  - byte `Shade` block ~L225–L272 (`Lr/Lg/Lb = Light1.Color`)
  - generic `Shade<TDe>` block ~L685–L740 (same)

Surface shading (`AccumulateLight`) already sums Light1/2/3. The fog does not.
FF also has:

- **no phase function** — in-scatter is isotropic (no view/light angular term),
  so god-rays lack the forward-scatter "punch" real shafts have;
- **no medium color** — the fog cannot have its own tint independent of the
  lights.

## 2. How standard volumetric renderers color fog

Physically-based single scattering (Unreal, Unity HDRP, Frostbite froxel —
Hillaire, *Physically Based and Unified Volumetric Rendering*, 2015) colors
fog from **two independent inputs**, shaped by a phase function:

```
inScatter += transmittance * density * stepSize
           * scatteringAlbedo          // the medium's own color
           * Σ_lights ( lightColor_i * lightIntensity_i
                        * shadow_i
                        * phase(cosθ_i, g) )   // θ = angle(view, light)
```

- **light color** — every light tints the fog it lights (all lights, not one).
- **scattering albedo** — the medium's own color, separate from any light.
- **phase function** — Henyey-Greenstein `p(cosθ)=(1-g²)/(4π(1+g²-2g·cosθ)^1.5)`;
  `g>0` forward-scatters (bright toward the light), `g<0` back-scatters,
  `g=0` isotropic.

Where FF sits: current Light1-only isotropic in-scatter is *behind* this model.
Slices A–C bring FF **up to** the standard; slice D (Opt 3) is a deliberate
non-PBR art extension.

## 3. Slices

### A — Opt 1: multi-light colored in-scatter (#177)

Loop Light1/2/3 into the in-scatter accumulation. Per light, gated by
`Intensity > 0`, with per-step `SoftShadow` toward that light gated by the
matching `ShadowLightMask` bit (mirrors the surface-shadow convention).

- Shared per-step walk (position, base density, transmittance `T`) stays once.
- Only the scatter **color** term is per-light: `T * scatter * lightColor_i`.
- Factor the per-light body into a private helper to avoid triplicating.

**Bit-identity.** Light2/Light3 default `Intensity = 0` → skipped → identical
to today's single-light output.

### B — Henyey-Greenstein phase function (#178)

New `LightingFxData.VolumeAnisotropy` (double, `[-1, 1]`, **default 0**).
Per step per light, multiply scatter by the HG phase of
`cosθ = dot(viewDir, lightDir_i)` with `g = VolumeAnisotropy`, normalized so
`g = 0` reproduces the current constant term (× 1) → bit-identical.

UI: knob in the volumetric expander; tooltip — negative = back-scatter halo,
positive = forward god-rays.

### C — Opt 2: medium color / scattering albedo (#179)

New `LightingFxData.FogColor` (uint packed BGRA, **default 0xFFFFFFFF white**).
Multiply the accumulated in-scatter RGB by the normalized `FogColor` (composes
with per-light color from A and phase from B). White → ×1 → bit-identical.

UI: color picker in the volumetric expander; tooltip — tint of the fog medium
itself, independent of the lights.

### D — Opt 3: palette-mapped volumetric (#180) — DONE

Map the in-scatter through the active 3D color-theme gradient so fog picks up
the same palette as the fractal surface. Explicitly **not** PBR — a
stylized/NPR deviation consistent with FF's non-PBR surface color themes.
New knob `VolumePaletteStrength` `[0,1]`, default 0 = off.

Implementation (CPU):
- `LightingFxData.VolumePaletteStrength` (double, default 0) + runtime-only
  `VolumePalette` (uint[] LUT, default null — not serialized; a reference
  field on the value type).
- `VolumePaletteBaker.Bake(ref fx, colorMap)` (Engine, IColorMap-aware) bakes
  the theme's iteration sweep into a 256-entry ARGB LUT once per frame when
  strength > 0; all 8 CPU 3D calculators call it after taking their local `fx`.
  ShadingPipeline never sees `IColorMap` — only the baked `uint[]`, keeping the
  shading kernel decoupled from the theme machinery.
- `ShadingPipeline.VolumetricInScatter` samples the LUT by optical depth
  (`1 − T`) and does an **energy-preserving hue remap** of the accumulated
  in-scatter (redistribute its own brightness across the palette hue), then
  cross-fades by `VolumePaletteStrength`. Strength 0 or null LUT → unchanged
  (bit-identical with slice C).

GPU parity for D is **DONE** (follow-on to slice E). The baked theme LUT is
uploaded as a separate `ArrayView<uint>` kernel arg (it can't ride on the
blittable `GpuShadingParams`; a length-1 dummy `GpuKernelUtils.PaletteOff` keeps
the kernel arity fixed when the feature is off). New
`GpuShadingParams.VolumePaletteStrength` gates it; `GpuKernelUtils.SamplePalette`
+ `PaletteRemapInScatter` mirror the CPU energy-preserving remap. All 8
per-fractal kernels + Render signatures thread the palette; the 8 CPU
calculators pass `fx.VolumePalette`. Strength 0 / dummy LUT → bit-identical with
slice E. UserBulb's separate GPU path stays cheap-palette (no volumetric), same
scope boundary as slice E. On-device pixel parity = CLI probe + user smoke.

### E — GPU parity (#181) — follow-up

Mirror A/B/C into the 8 per-fractal GPU volumetric kernels + `GpuShadingParams`
/ `GpuKernelUtils`. CPU path (default, `UseGpuRender = false`) ships first.
UserBulb GPU stays on `UserBulbGpuCalculator` — confirm CPU fallback when the
new knobs are active.

## 4. Cross-cutting rules

- **Bit-identity gating.** Every new knob defaults to a pass-through value
  (L2/L3 intensity 0, `VolumeAnisotropy` 0, `FogColor` white). Default renders
  stay pixel-identical.
- **`LightingFxData` is a value type.** Copy-mutate-write-back through the
  auto-property (see the CS8156 note in `Docs/Lighting-FX-Roadmap.md`).
- **Two Shade paths.** Every math change lands in *both* the byte `Shade`
  block and the generic `Shade<TDe>` block in `ShadingPipeline.cs`.
- **Commit per slice.** A, then B, then C. Push + PR after C. D and E are
  separate future sessions.

## 5. Touch points

- `Abstractions/Rendering/Lighting/LightingFxData.cs` — new fields + defaults.
- `Engine/Rendering/Lighting/ShadingPipeline.cs` — both in-scatter blocks.
- `UI.Avalonia/ViewModels/FractalParamsViewModel.Lighting.cs` — bindings.
- `UI.Avalonia/Views/FractalParamsView.axaml` — volumetric expander controls.
- `Engine/Models/LightingFxPresetData.cs` — preset round-trip (if present).
- `Server.Tests/` — bit-identity + per-slice behavior tests.