Light the tray with a photographed room, exposed like a camera

[drehtuer]

Step 2 on feature/realistic-rendering: physically based lighting. Squashed from three rounds; each was tested on the Pixel 10a and fixed what the phone found.

What it does (decision 89):

• Room: a CC0 studio panorama (Poly Haven Brown Photostudio 02, 1k HDR, 1.6 MB) lights and reflects the scene in place of the generated gradient.
  • Decoded and folded into a 6 × 256² cube in Kotlin (Radiance, StudioCube); the file is treated as untrusted and falls back to the gradient.
  • The folded cube is cached in codeCacheDir (StudioCache).
  • Prefiltered by Filament's generatePrefilterMipmap.
  • No filament-utils: it hard-links gltfio into every ABI, which cost +18.8 MB. This costs +1.5 MB.
• Exposure: aperture f/16, shutter 1/125 s, ISO 80, so a white floor lands at 0.95. The first round used the one-argument setExposure, which asked for ~26 stops too much and drew every frame white.
• Tone mapper: linear. PBR Neutral's toe subtracted the felt's smallest channel in Rec.2020 and crushed red to 0.
• The fill lamp is finally drawn. Filament shades one directional light per scene, so the fill never was, on any earlier version. It is now added to the room's irradiance as spherical harmonics.
• Shadows: PCF. PCSS is EVSSM in Filament 1.76 and brought the rim's shadow back as a band along the walls.
• Anti-aliasing: 4× MSAA replaces FXAA.

On the Pixel 10a, with the whole stack (gallery + resin + rounded + this):

• :render:filament device suite 49/49.
• Felt #1f5e3a draws as (34, 89, 58); target ±10 of (31, 94, 58).
• No rim shadow: felt beside each wall is 0.997–1.027 of mid-floor felt, with and without post-processing (new theFeltBesideTheWallsIsTheFeltInTheMiddle, bar 0.9).
• Room build: 582–708 ms on the first launch of a version, 301–388 ms from the cache.
• Gallery: the dice are warmer and more three-dimensional, shadow sides are readable, metal catches the studio's window, there is no band along the walls.

Cost to note: about 0.3–0.4 s on the first frame of every cold start, for the prefilter, which can't be cached through Filament's JNI.

Docs: docs/physics-and-rendering.md ("Rendering (normal mode)"), decision 89, the asset licence record, TODO, STATUS.

Based on #377.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud