fix(lpc-engine): 16-bit gamma — remove the 8-bit choke in the 16-bit pipeline

[Yona-Appletree]

The defect

The render pipeline is unorm16 end to end — shader read_sample_out returns Vec<u16> → brightness in u16 → gamma → power limit in u16 → Unorm16 control product → DisplayPipeline ("16-bit in, 8-bit out", interpolation + temporal dithering at the wire) — but the gamma step truncated to 8 bits internally:

r = apply_gamma((r >> 8) as u8).to_q32().to_u16_saturating();

apply_gamma indexed the canonical Adafruit GAMMA8: [u8; 256] table (exactly round(255·(i/255)^2.8)), a survivor from before the pipeline went 16-bit. Measured on 2026-08-01:

• only 163 distinct output levels survive the u8 round-trip
• the bottom 28/256 of input collapses to hard 0
• at fixture brightness 38 — the real desk project quad-strips-v3 — full white lands on GAMMA8[38]=1, so the whole project's post-gamma range was {0, 257}: binary pixels
• the 16-bit dithering downstream cannot recover information gamma already destroyed

Full write-up: docs/defects/2026-08-01-gamma-8bit-choke.md.

The fix

apply_gamma16(u16) -> u16 in lpc-engine/src/nodes/fixture/gamma.rs: a const LUT evaluated by linear interpolation, the same shape as the white-point LUT in display_pipeline/lut.rs (index = high bits, alpha = low bits, final entry one segment step past the domain so the top lands exactly without an edge clamp). γ=2.8 kept for visual continuity with the legacy table. Shared .rodata, no heap, no per-channel storage. All three call sites in fixture_node.rs updated; ordering untouched (brightness → gamma → power scale → color order — power scale after gamma, see power_limit).

One deliberate deviation from the agreed sketch: the table is [u32; 513] with 2 fractional bits (~2 KB) instead of [u16; 257] (~514 B). The 257×u16 shape cannot meet its own accuracy bar: the top table node sits at input 65536 whose true curve value is ~65537.8 — doesn't fit u16, and clamping sags the whole top segment ~3 counts; separately, 256-segment chord error (0.63) plus node and output rounding measures ~1.4 counts. With 512 segments + fractional bits, measured max error is 0.75 counts in 65535, monotone, endpoints exact. u32 entries also match the white-point LUT's shape exactly.

Tests

• exact regeneration of the checked-in literal from the formula (hand-edits impossible)
• full-domain oracle vs libm pow: max abs error ≤ 1 count across all 65536 inputs
• monotone non-decreasing, exact endpoints (0→0, 65535→65535)
• regression for the motivating case: brightness 38 keeps ≥250 distinct post-gamma levels (measured 318; old path produced 2)

Baseline audit

This intentionally changes output for any fixture with gamma_correction=true (engine default when unspecified). A thorough sweep found no checked-in expected values need regeneration: every harness asserting numeric channel output pins gamma off (engine test helpers bind gamma_correction=false; ProjectBuilder::fixture() hard-codes Some(false); shader-oracle's examples/shader-oracle/fixture.json sets false and stores no golden bytes; the lp-ws281x goldens encode a fixed byte array that never touches the engine; story PNGs never render through the engine gamma path; filetests are shader-compilation only). The S3 device-vs-host comparison computes both sides live, so it shifts together and stays bit-exact. The one gamma-on artifact in the tree is examples/fast/fixture.json, a manual demo not referenced by any test.

Relation to D7

Independent of D7 (whether to remove DisplayPipeline's per-channel white-point tables — still open with Yona in the classic-ESP32 bring-up plan). This PR doesn't touch DisplayPipeline, Esp32OutputProvider, or anything on PR #239. It does strengthen D7 option A: gamma turns out to want a const shared table, not the per-channel heap machinery.

🤖 Generated with Claude Code