M4: lighting, L1 additions and L2
Lighting: the atmosphere, clouds, a sharper Earth, materials and terrain. Each issue holds its own design, tests and measurements. This is the plan across them, decided with Connor on 2026-10-17.
Tiers, split by cost
- L1/C1 is the high-fidelity tier that still runs in under 10 ms on the GPU, aiming to stay under about 8 ms end to end (1920 x 1080 RGB,
submittowait_view). At the start of M4 it is 4.1-5.2 ms, of which the GPU's work is about 3.8 ms on the Landsat 8 scene: Earth and Moon 1.33 ms, blur 1.01, mesh 0.69, sensor 0.48, shadow 0.15, Earthshine 0.04. That leaves about 3 ms of GPU time for everything M4 adds to L1. - Each issue measures its cost and goes to L1 if it fits what is left of that budget. Otherwise it goes to L2, or splits: the cheap part in L1, the full version in L2.
- L2 holds the expensive lighting: volumetric clouds (#62), terrain (#33), finer settings for L1's methods (#55), and whatever does not fit L1.
Order (the atmosphere and clouds first; done: #59, #31)
- #59 gallery deltas. Before and after images of the example scenes between two commits, to review each change by eye. Small, and it helps with everything after it.
- #31 atmosphere: Earth's disk and limb. Precomputed scattering tables; replaces the haze stand-in in the bodies and Earthshine passes.
- #63 higher-resolution Earth. Blue Marble at about 460 m per texel, tiled and BC6H-compressed. Moved up (2026-10-17) after comparing the atmosphere with an ISS photograph: the coarse map was much of the difference.
- #60 sunlight through the atmosphere. The target reddening and dimming at orbital sunset, the Sun and Moon at the limb; possibly the eclipsed Moon's red glow (needs refraction).
- #32 cloud layer. A thin layer from a static global map, lit inside the atmosphere, with shadows on the ground; Earthshine sees it too.
- #61 cloud maps by date. An option, not the default: maps fetched ahead of time for the dates a run will request, never at render time.
- #62 volumetric clouds (L2).
- #56 anisotropic filtering and #57 pole artifacts, the rest of the map work.
- #50 Earthshine on the Moon's night side.
- #29 parametric BRDF, then #30 spectral materials.
- #33 Moon limb from LOLA terrain.
- #55 finer settings for L1's methods at L2.
- L1/L2 checkpoint: the readme rows and sample images, and the movie.
Gallery during the milestone
- From the first L2 feature,
scripts/make-gallery.shrenders L2 as well, and the gallery shows it. The gallery is the quickest way to see what each change adds, so it keeps up with each issue. The readme rows and the movie wait for the checkpoint.
GPU and CPU (#64)
- The contract stays "same shaders, same results, slower on the CPU". A feature becomes device-dependent only where a device cannot do it at all, not because it is slow there.
- A device that cannot run a setting falls back to the nearest lesser one and the renderer reports it; the CLI prints it. A setting asked for by name that the device cannot run is an error.
- GPU-against-CPU tests use settings both support. The readme gets a "GPU and CPU differences" section.
- Measured 2026-10-17: lavapipe's limits are per texture (16384 on a side, 128 MB per storage binding), not total memory (it uses system RAM); it has 2048-layer texture arrays and BC compression. So the sharper Earth (#63) may well run on both devices, tiled.
Risks to measure early
- #31: the cost of the limb glow, which needs work on pixels that miss Earth but cross its shell; and how many wavelengths the tables need for broad channels.
- #31 setup: building the tables on lavapipe.
- #63: memory (about 5 GB of BC6H with mips), setup time, and BC6H decoding speed on lavapipe.
- Performance: each pass on the RTX 3060 and lavapipe at 1920 x 1080, against the L1 budget above.
Working rules (as in M1-M3)
- One issue per change, left uncommitted for Connor to review and commit.
- After the commit, comment on the issue: what was done, measurements, limitations, what was tried first and why it was wrong. Leave the issue open.
- Update
docs/optics.mdfor readers who aren't optics specialists. - Zero warnings everywhere; plain prose; US English.
- Keep the pre-push hook near 30 s (33 s warm at the end of M3; move slow GPU tests out of it before adding many more).
No due date
94% Completed
