@woosh/meep-engine 3.59.0 → 3.60.1

package/src/shade/renderer/global_illumination/probe_clipmap/PROBE_RAYS_VARIABLE_AND_SORTED_SCOPE_2026_10_30.md

@@ -0,0 +1,410 @@
+# Probe rays: a variable count per probe, sorted for coherence — scope
+
+2026-10-30. Scoped against master at `309823e49`. Since built: stage 1 (`0ec7a5fc3`), stage 2
+(`b825bd46c`, its as-built note in the proposal's §8.6) and the sort's generalisation (`053a1c8ba`).
+The sorted rays were built, measured on both GPUs on Sponza and Emerald Square, and not shipped
+("Measured" under §2). Nor were the local sorts that followed (chunks, bins, a hash control, within
+each probe, position bits); the trace list in the probes' Morton order ships instead ("Local sorts,
+measured" under §2).
+
+## What was asked
+
+1. **A variable number of rays per probe update, as Enshrouded does it.**
+   - A probe whose short-term mean dominates (it is changing) takes more rays.
+   - A converged probe sips rays, except at the regular uniform updates that keep its depth and its
+     estimator fed.
+   - A DEAD probe shoots the minimum.
+2. **Rays sorted (binned) for coherence** by one key: a short Morton code of the origin together
+   with the octahedral direction.
+
+Enshrouded, as §2.1 records it from the talk's captions:
+- a new probe asks for 512 rays and decays fast to 16, rising again when it sees change;
+- requests are scaled down to the frame's budget, and rays are batched by a probe-index scan;
+- rays are sorted by position and direction, and hits by kind;
+- DEAD probes still trace 16 rays a frame.
+
+Sorting hits by kind was not asked for and stays out.
+
+## Where the fixed R lives today
+
+Every pass that touches rays assumes R rays for each listed probe, at offset `k·R`.
+
+| Where | What assumes R |
+|---|---|
+| schedule, due | `U = ⌊ray_budget / R⌋` probes a frame; `T = ⌈P_w / U⌉` |
+| `shader_probe_clipmap_trace_command` | the ray dispatch is `traced × R` |
+| trace, light, shade, want_hits | ray thread → probe `ray / R`, its ray `ray % R` |
+| accumulate | `first_ray = k·R`; uniform rounds `R / n_r²`; guided runs inside `[0, R)` |
+| guide (weights, starts) | the hold `(64 − 2 − R/n_r²)/R`; the starts walk `R` rays |
+| `chunk_probe_clipmap_ray_texel` | the uniform ray↔texel map: powers of two, `R ∈ [n_r²/4, 4·n_r²]` |
+| project | classification's "was this update guided" test takes R |
+| `probe_rays` | sized `U·R` = the budget |
+
+The per-probe passes (relocate, the guide's three, accumulate, project, publish) cost by listed
+probe, not by ray. Accumulate was 0.43–0.68 ms on the iGPU at 512 probes. U keeps bounding them.
+
+## 1. A variable ray count
+
+### The update kinds and their rays
+
+| Update | Rays | Why |
+|---|---|---|
+| a probe's first (NEW) | `R_new` (Enshrouded 512, two a texel at n_r = 16), uniform | a new probe sees its whole sphere at once |
+| uniform: every 5th, every DEAD one | `R_u = n_r²`, one a texel, as today | keeps depth, classification and every texel's estimator fed |
+| guided | the probe's request, in `[R_min, R_max]` | change takes rays, a converged probe sips |
+| DEAD | `R_min`, uniform | see fork F4 |
+
+### The request: from the probe, not the texel (measured)
+
+The estimator's per-texel inconsistency is the natural reading of "short-term mean dominates", but it
+cannot carry the request. Measured on the emulator through the shipped accumulate pass, eight streams,
+short blend 0.18:
+- a steady one-ray texel (σ = μ) reads 0.27 on average, 0.41 at p90;
+- after a ×2 step it reads 0.35 over updates 10–40, and after +30% it reads 0.29, both inside its
+  own noise;
+- a texel lit by one ray in five reads 0.29 steady and 0.35–0.37 after either step;
+- at the blend of a texel the guide passes over (0.63) it reads 0.87 whatever happens.
+
+**Recommended signal: the same gap test, over the whole probe.** Take Σ over the probe's texels of
+(sample − long mean), luminance-weighted, against that sum's own noise, √Σ deviation².
+- Over 256 texels its noise is 16× smaller. A probe-wide +30% shift on one-ray texels is about
+  0.3·√256 ≈ 4.8 noise units in one update. That figure is derived, not measured; stage 0 measures it.
+- The accumulate thread already holds the sample, the mean and the deviation.
+- Projection's rows pass and probe pass already reduce per probe; they would carry the sum into the
+  probe.
+- A NEW probe's request decays with its texels' count, Enshrouded's "decays fast".
+- The constants come from the measured distributions of this signal (steady against changed), not
+  from round numbers.
+
+Changing probes then take more rays, so their samples' deviation shrinks as 1/√rays. That is what
+the estimator's own catch-up needs to engage sooner on the post-load shift measured on 2026-10-30. It
+only helps if the request sees the change, which per-texel inconsistency does not.
+
+### The budget, the offsets, the dispatch
+
+- **U stays `⌊budget / R_u⌋`**, so a frame of all-uniform updates fits exactly as it does today, and
+  the period `T = ⌈P_w/U⌉` is unchanged.
+- **Guided requests fill what's left, scaled down when over budget** (Enshrouded's "requests scaled to
+  the budget"). The scale comes from the previous frame's demand, so one scan suffices.
+- **Offsets come from one exclusive scan** of the listed probes' ray counts (Enshrouded's
+  "probe-index scan"):
+  - `graph_prefix_scan_csdldf`, ≤ U elements, indirect over the list's count;
+  - it gives each probe's first ray and the frame's total;
+  - the ray dispatch is built from the total, the way the mesh expansion does it with
+    `shader_prefix_sum_to_command`.
+- **A ray finds its probe by `lower_bound_branchless` over the offsets**: the mesh expansion's chunk,
+  at most log₂U + 1 steps.
+- **The request's storage:** the record is full (64 B; `sh` takes bytes 32–63), and `screen` is a u32
+  holding one bit. The request packs into its upper bits (fork F6).
+- **In a converged scene, guided updates run at R_min**, so the frame traces fewer rays than the
+  budget. The saving is trace time: 6.8–7.6 ms on the iGPU and 0.34–0.47 ms on the 4090 at Sponza
+  today (guiding's paired numbers).
+
+### Forks
+
+- **F1. Schedule: keep the period, vary rays per update (recommended)**, rather than Enshrouded's
+  every probe every frame. The per-probe passes scale with listed probes. Accumulate at 512 probes on
+  the iGPU is 0.43–0.68 ms, so all 4,600 of Sponza's probes every frame would be about 4–6 ms
+  (derived).
+- **F2. Over budget: scale the guided requests (recommended)**, rather than stretching T. Scaling
+  keeps every probe's cadence, including the changing ones'.
+- **F3. Weigh a sample by its rays in the estimator (recommended, same stage).** Measured in the
+  review: one one-ray uniform sample every 5th update, mixed into a 16-ray guided stream, raised the
+  long mean's error 4.1 → 7.3% at β 0.18. Variable rays widen the spread from 0 to 64 rays a texel.
+  The reference estimator has no weights, so this is measured on the emulator before it lands.
+- **F4. DEAD: every period at R_min (recommended)**, against today's every 8 periods at R.
+  - It reacts 8× sooner for fewer rays.
+  - R_min comes from the classification's tolerance. The back-face share's binomial deviation at the
+    25% threshold is ±11% at 16 rays, ±6% at 48 and ±5% at 64.
+  - Below n_r²/4 rays the uniform map's assertion lifts; the spread map already covers every texel
+    over n_r²/R updates.
+- **F5. R_max:** bounded by the 64-a-texel gather (`PROBE_TEXEL_RAYS`), by the depth limit
+  `R ≤ 64·n_d²`, and by the budget. Its value comes from stage 2's measurement.
+- **F6. The request's storage:** pack it into `screen` (recommended), or grow the record to 80 B.
+
+## 2. Sorted rays
+
+### Design
+
+- **Key, one u32:**
+  - origin: the Morton code of the probe's lattice coordinate inside its cascade's window (32³:
+    15 bits) plus its cascade (5 cascades: 3 bits);
+  - direction: the ray's octahedral texel, coarsened to 8×8 bins (6 bits, UE's count);
+  - 24 bits in all.
+- **Key pass:** a thread a ray over the frame's live total. The probe comes from `lower_bound` over
+  the offsets, and the texel from the update's map (the uniform map, or the guide's search the trace
+  already does). The value is the ray's index.
+- **Sort: `graph_radix_sort`, generalised, not copied.** It is the engine's sort, and the LBVH
+  build is its one caller. Two changes:
+  - it dispatches over a host element count today, which here would be the budget's capacity; it
+    must follow the live total, indirect (the rule that GPU work follows the live count);
+  - it always runs four 8-bit digit passes, 12 dispatches; a key-width option makes a 24-bit key
+    three passes, 9 dispatches.
+  - The batch pass's bitonic sort (≤ 64 rows in workgroup memory, inside a dispatch that runs anyway)
+    is a different scale and is not a candidate.
+- **Consumers:** trace, light and shade take `ray = order[thread]`. Their outputs stay at the ray's
+  index, so want_hits, accumulate and projection do not change.
+- **Layout fork, measured in stage 0:**
+  - direction-major: UE's `SortProbeTraceTilesCS` bins 64 directions, with Morton position a todo;
+  - origin-major: today's grouping by probe, with directions ordered within it;
+  - interleaved.
+
+### Not known; stage 0 measures it
+
+- The sort's cost at the budget, 131,072 keys, on both GPUs. No measurement is recorded.
+- Trace, light and shade time in sorted order against today's. Today a 64-lane wave is one probe's
+  origin over four octahedral rows (uniform) or a run of the walk (guided).
+- The scattered writes: sorted threads write 28-B records at the ray's index.
+- Context: S3f's incoherent rays cost about 18× a coherent screen ray on the 4090 and about 5× on the
+  iGPU. That benchmark predates the probe ray layout.
+
+### Key layouts to measure (Alex, 2026-10-30)
+
+Four keys, plus today's unsorted order as the baseline. Each is timed as its whole cost: key pass,
+sort, trace, light and shade. Both GPUs, paired in one process (the key pass swapped by pipeline),
+Sponza with the caches resident. The direction bin is fixed at 8×8 octahedral bins (6 bits) for all
+four.
+
+**Two origin encodings:**
+- **O1, per cascade:** the Morton code of the probe's lattice coordinate inside its own cascade's
+  window, 5 bits an axis at 32³ (15 bits), with the cascade's 3 bits above it. 18 bits.
+- **O2, one domain:** the Morton code of the probe's position inside the coarsest cascade's window,
+  with no cascade bits.
+  - That window spans 2^(C−1)·32 cascade-0 spacings: 512 at C = 5.
+  - Telling cascade-0 probes apart takes 9 bits an axis (27). Beside 6 direction bits that is 33, so
+    O2 takes 8 bits an axis (24): a cell of two cascade-0 spacings, where a pair of cascade-0 probes
+    can share a code.
+
+**Two direction placements:**
+- **D-high, `[direction | origin]`:** rays bucket by direction across probes, as UE's 64 bins do.
+- **D-low, `[origin | direction]`:** rays bucket by probe position, in direction order within each.
+
+| Key | Bits | Radix passes |
+|---|---|---|
+| O1 D-high | 24 | 3 |
+| O1 D-low | 24 | 3 |
+| O2 D-high | 30 | 4 |
+| O2 D-low | 30 | 4 |
+
+The pass counts differ, so the sort's own cost is part of each key's comparison.
+
+### Measured (2026-10-30): no key beats unsorted, so none ships
+
+Built as stage 3 lays it out, on top of stage 2's variable rays:
+- a key pass, a thread of the rays' launch, which finds each ray's texel as the trace does;
+- `graph_radix_sort` over the launch's threads, counted on the device (the ray command writes them),
+  with the threads past the last ray keyed past every ray, so that they sort to the end in their own
+  order;
+- trace, shade and light take `ray = order[thread]`.
+
+**How it was measured.** Sponza, and NVIDIA's Emerald Square (day, 2.69M triangles, 230 m a side;
+textures held to 1024² on the iGPU). The caches were resident, the clock at 60 Hz, and the camera and
+the light still. Emerald was measured from two views: down an avenue at 1.7 m, and from 29 m over the
+square. Each round ran every arm once in a seeded shuffled order: 8 frames unmeasured, then 24
+measured. There were 8 rounds on the 4090 and 4 on the iGPU. Two of the arms are unsorted, and their
+agreement is the noise. "Unsorted" runs the key pass as an identity, writing each thread's own index.
+
+The figures are the GPU's busy time from relocation's start to the light pass's end, a frame, in µs,
+as means. A frame's rays swing with the schedule's turn, between about 30k and 105k on Emerald. A
+median taken category by category picks a different kind of frame for each category, and this
+section's first tables, medians, read a 3× faster trace beside a 13× slower sort. The sorted arms are
+given against the mean of the two unsorted runs.
+
+**At the rays variable rays leave** (a still scene, most probes sipping):
+
+| Scene, GPU | Rays a frame | Unsorted (two runs) | O1 D-high | O1 D-low | O2 D-high | O2 D-low |
+|---|---|---|---|---|---|---|
+| Emerald avenue, 4090 | ~33k | 588.6 / 600.3 | +76 | +75 | +103 | +112 |
+| Emerald overview, 4090 | ~29k | 412.0 / 407.7 | +91 | +79 | +96 | +101 |
+| Sponza, 4090 | ~51k | 834.1 / 880.7 | +90 | +130 | +205 | +190 |
+| Emerald avenue, iGPU | ~32k | 6,848 / 6,110 | +1,830 | +1,049 | +1,821 | +1,232 |
+| Sponza, iGPU | ~59k | 5,651 / 5,653 | +2,466 | +624 | +2,607 | +547 |
+
+**At about 120k rays a frame**, every update asked for at least 256 rays (one a texel at n_r = 16; a
+measurement-only floor), the budget's 131,072 scaling the rest:
+
+| Scene, GPU | Rays a frame | Unsorted (two runs) | O1 D-high | O1 D-low | O2 D-high | O2 D-low |
+|---|---|---|---|---|---|---|
+| Emerald avenue, 4090 | ~127k | 767.7 / 772.1 | +15 | +16 | +65 | +84 |
+| Emerald overview, 4090 | ~117k | 943.3 / 919.4 | +189 | +161 | +298 | +743 |
+| Sponza, 4090 | ~120k | 1,507 / 1,426 | +340 | +324 | +40 | +342 |
+| Emerald avenue, iGPU | ~125k | 15,317 / 15,358 | +2,877 | +429 | +4,101 | +1,521 |
+| Sponza, iGPU | ~123k | 11,603 / 11,546 | +4,485 | +1,248 | +4,401 | +1,803 |
+
+- **No key beats unsorted, on either GPU, in any scene or view, at either count.**
+- **The trace does gain at the higher count, on Emerald's avenue.** On the 4090 it drops 11% with O1
+  D-high (618.5 → 549.5 µs; the unsorted runs agree within 0.5 µs). On the iGPU it drops 6% with O1
+  D-low, and shade 11% (−763 and −232 µs).
+  - Keying and sorting cost more than that: about 75 µs on the 4090 (13 dispatches, latency-bound), and
+    on the iGPU 1.49 ms (the key pass 328 µs past the identity's, the sort 1.13 ms).
+  - At the lower count the trace does not move on either GPU.
+- **Direction-major keys (D-high) slow shade and light on both GPUs**: on the iGPU by 20–70% across
+  trace, shade and light. A ray's record, 28 bytes when measured (`PROBE_RAY_STRUCT`; 24 since its light became one RGB9E5
+  word), stays at the ray's own index.
+  - Sorted threads read and write those records out of order, about twice the 32-byte sectors a
+    record.
+  - A wave of one direction also reads the origins and records of many probes, and the light pass's
+    probe taps around many hits.
+- **The 4090's overview and Sponza read high at 120k for every key:** their shade, sort and scans
+  measure 2–4× the avenue's at the same count, with 30–170 µs of idle gaps inside the stretch. The
+  direction of the result holds in every case; those cases' size is uncertain.
+- **A lead, since shipped** (below). Origin-major order's gain could be had without sorting rays: order the trace
+  list, at most U probes, by the probes' Morton codes, and the rays' layout follows it.
+  - Its measured upper bound is O1 D-low's change to trace, shade and light. On Emerald's avenue at
+    125k rays that is −1.0 ms of the iGPU's 15.3 ms, and −49 µs on the 4090. At the lower count, and
+    on Sponza, it is about none.
+- **Not shipped.** The wiring is reverted. It is kept, with the measurement-only floor, as
+  `stage3b_sorted_rays_v2.patch` and `stage3b_shader_probe_clipmap_ray_keys.js` in the session's
+  scratchpad. The harness is `device/sortab.js` there. The sort's generalisation landed first
+  (`053a1c8ba`: `key_bits` and the device count). The BVH build is its only caller, and that caller
+  uses neither.
+
+### Local sorts, measured (2026-10-30): every one loses; the probes' order ships
+
+After the global keys, cheaper orders were tried: sorting the rays inside a chunk of the launch, one
+workgroup a chunk, and sorting the trace list instead of the rays. All were measured the same way as
+above, at the 256-ray floor (131,072 rays a frame, every frame, so the arms compare like for like), 96
+to 120 measured frames an arm, as means against the mean of two unsorted runs. Unless a table says
+otherwise, the figures are the busy time from relocation to the light pass's end.
+
+**The local sort.** A workgroup takes a chunk of the launch's threads, packs each ray's key above its
+place in the chunk, and sorts them with the radix scatter's stable binary split, a bit a round. The
+rays move only within their chunk. Keyed by the ray's direction bin, as the trace finds its texel:
+8×8 bins of the octahedral map (6 bits, the bins of UE's `SortProbeTraceTilesCS`) or 4×4 (4 bits).
+"Probe order, then" runs the trace-list sort below first. iGPU, Emerald avenue / Sponza:
+
+| Order | 2048-ray chunks | 1024 | 512 |
+|---|---|---|---|
+| 8×8 bins | +19.0% / +21.1% | +14.9% / +16.3% | +9.9% / +13.8% |
+| 4×4 bins | +14.4% / +12.6% | +11.8% / +12.9% | +9.2% / +10.8% |
+| Probe order, then 8×8 | +9.9% / +12.9% | +7.8% / +9.4% | +8.0% / +5.6% |
+| Probe order, then 4×4 | +7.0% / +9.4% | +7.7% / +6.5% | +4.9% / +5.0% |
+
+Unsorted: 13,324 / 12,095 µs, its two runs 0.3% / 1.6% apart. The probes' order alone: −1.9% / −4.0%.
+- **Coarser bins and smaller chunks help, step by step, and none reaches unsorted.**
+- What the order costs, before the trace sees it: on the iGPU, the key pass takes 280–330 µs (each ray's
+  texel found a second time; 15–34 µs as an identity), and the sort 114–123 µs at 6 bits and 86–92 at
+  4, rising to 179 and 130 at 512-ray chunks. On the 4090 the sort takes 7–10 µs, less at smaller chunks.
+- **The 4090 does not care.** Every arm is within ±60 µs of its 618–630 µs, both scenes.
+
+**The control: a hash key.** The same local sort keyed by a hash of the ray (PCG), as many bits as the
+bins: the same scatter of records and the same mixing of probes in a wave, and no grouping by
+direction. The trace on the iGPU, Emerald / Sponza, against unsorted's 11,473 / 8,581 µs:
+
+| Chunk and bins | Direction key | Hash key |
+|---|---|---|
+| 8×8, 2048 | +15% / +20% | +52% / +57% |
+| 4×4, 512 | +8% / +8% | +34% / +36% |
+| Probe order, then 4×4, 512 | +1% / +3% | +29% / +30% |
+
+- **Direction coherence is worth 2.3–4.2 ms of the iGPU's trace here.** What loses is mixing several
+  probes' rays in one wave, which every chunk of more than one probe does.
+- Under the hash, shade and light slow too (shade +0.7 to +1.2 ms, Sponza's light up to +1.9 ms): their
+  records and hits scatter with the rays. On the 4090 hash and direction are within ±60 µs of each
+  other.
+
+**Within each probe.** Keyed by the probe's place in the list (4 bits) above the bin, in 512-ray chunks,
+so that each probe's rays sort by direction and no wave mixes probes. The trace on the iGPU moved
+−0.6% to +1.4% at 131k rays, and +1.0% on Sponza's own schedule (57k rays): noise. The key and sort
+passes cost 470–680 µs on top. **The rays of one probe already share their waves, walking the map's
+texels in rows** (a uniform update `ray % texels`, a guided one the guide's walk), so a ray sort has
+nothing left to gain.
+
+**Position bits above the bin (Alex).** Probe order first, then a local sort in 2048-ray chunks keyed by
+12 bits of the probe's Morton code past its low b bits, above the 8×8 bin: the probes of one 2^b-point
+block of the lattice mix and sort by direction together, and no others. Measured on `f12f7858c`
+(hits shadowed by traced rays). iGPU, Sponza / Emerald, busy (trace):
+
+| Mixing | Busy | Trace |
+|---|---|---|
+| b = 0, no probes mix | +4.1% / +3.4% | −0.6% / −1.7% |
+| b = 3, 2×2×2 blocks | +5.6% / +4.3% | +1.0% / −0.8% |
+| b = 6, 4×4×4 blocks | +9.6% / +8.4% | +4.9% / +3.4% |
+| Direction only | +13.0% / +11.2% | +10.1% / +7.9% |
+| Probe order alone | −1.9% / −1.4% | −1.5% / −1.4% |
+
+The trace follows the mixing and tops out at the probes' order's own; the key pass (about 300 µs) and the
+18-bit sort (about 325 µs) come on top. 4090: every arm −1.7% to +7.1%.
+
+**With traced hit shadows** (`f12f7858c`: a sun ray and a local light's ray from every hit), the local
+sorts were measured again: iGPU Sponza / Emerald, 8×8 in 2048s +22.1% / +18.4%, probe order then 4×4 in
+512s +5.9% / +6.3%, within each probe +5.2% / +4.1%, probe order alone −2.2% / −1.0%; 4090 +1% to +7%,
+probe order −0.4% to −1.8%. Unchanged: the secondary rays gain nothing from grouping the primaries.
+
+**The probes' order ships** (`shader_probe_clipmap_order.js`). After the due passes list the frame's
+updates, a workgroup a run of 1,024 listed probes sorts its run in place by the cascade and the Morton
+code of the probe's lattice point in the cascade's window (the bitonic workgroup sort,
+`chunk_sort_bitonic_workgroup`), dispatched through `PROBE_DISPATCH_ORDER`, which the update's command
+writes over the live count. Every pass after it reads the sorted list, the rays' layout among them, so
+neighbouring probes' rays run in neighbouring waves: the same blocks of the bricks and caches, a wave
+apart. Past one run the list is ordered within each run, not across them. The ray budget scales the
+requests in proportion, so the order changes no probe's rays.
+
+What it measured before shipping, iGPU at 131k rays, across five batches: Emerald −249, −510, −311,
+−130, −181 µs (1.0–3.6%); Sponza −479, −340, −267, −226 µs, and one batch +475. On the schedule's own
+counts, Sponza −109 and −171 µs. On the 4090, −58 to +37 µs: level. Its cost, a one-workgroup split sort
+in the measurement, was 14–18 µs.
+
+**As shipped, on the schedule's own counts** (no floor; 6 rounds, 144 frames an arm; the pass dispatched
+or skipped, each twice; the busy stretch, mean of each pair):
+
+| Scene, GPU | Rays a frame | Skipped | Ordered | Change | Pairs apart (skipped / ordered) |
+|---|---|---|---|---|---|
+| Sponza, iGPU | ~54k | 5,618 | 5,438 | −180 µs (−3.2%), trace −2.4% | 47 / 35 |
+| Emerald avenue, iGPU | 40–59k | 5,485 | 5,510 | +25 µs, noise | 390 / 150 |
+| Emerald avenue, 4090 | ~51k | 495 | 479 | −16 µs (−3.2%) | 19 / 19 |
+| Sponza, 4090 | ~55k | 500 | 508 | +7 µs, noise | 4 / 46 |
+
+- The pass takes 10.4–12.7 µs on both GPUs.
+- Read back on both GPUs after a frame, every run is in its keys' order and a permutation of the list
+  (512 of 512 distinct).
+- Emerald's rays swing with the schedule's turn (40–59k between its blocks), which is why its
+  floor-free pairs sit hundreds of µs apart.
+
+The measurement wiring is kept in the session's scratchpad, not the tree: `stage3e_local_sort_control_within.patch`
+(chunks, bins, the hash control, within-probe; for `c4d54e2cb`), `stage3f_sorts_on_f12f7858c.patch` and
+`stage3g_morton_bits_on_f12f7858c.patch` (the same and the position bits, for `f12f7858c`); the harness is
+`device/sortab.js`, and `device/orderab.js` A/Bs the shipped pass by skipping its dispatch.
+
+## Stages
+
+0. **Measure.** Scratchpad one-offs, both GPUs:
+   - (a) the radix sort at 131,072 keys, 24 against 32 bits;
+   - (b) the key pass, sort and permuted trace/light/shade, for the four keys of "Key layouts to
+     measure" against today's order;
+   - (c) the probe-level signal on the emulator: steady against +30% and ×2, one-ray and
+     one-in-five texels.
+
+   Decides whether sorting goes ahead, its layout, and the request's constants.
+1. **Plumbing, with no behaviour change.**
+   - A per-probe ray count and offset through every pass in the table above, and the ray dispatch
+     over the live total.
+   - Every request at R: bytes identical to master on the device.
+   - The specs move to per-probe counts.
+2. **Requests.**
+   - NEW, uniform, guided and DEAD counts; the probe-level signal; budget scaling; the estimator's
+     weighting by rays.
+   - On the device: the post-residency dark spell (`timeline.mjs`), steady noise, and rays and
+     trace time a frame.
+3. **Sorting, if stage 0 says go.**
+   - The radix sort's generalisation (indirect count, key width), pinned in its specs.
+   - The key pass, and the permuted trace, light and shade.
+   - A device A/B of the four keys against unsorted; the fastest key ships, and only if it beats
+     unsorted on both GPUs.
+
+## Reuse map
+
+| Need | Reused | Change |
+|---|---|---|
+| ray offsets and the frame's total | `graph_prefix_scan_csdldf` (out of place, indirect) | none |
+| the ray dispatch from the total | the mesh expansion's `shader_prefix_sum_to_command` pattern, `chunk_folded_dispatch` | none |
+| ray → probe | `chunk_lower_bound_branchless` | none |
+| the sort | `graph_radix_sort` | generalised: indirect count, key width |
+| origin Morton | `chunk_v3_morton_encode` | none |
+| direction bin | the probe's own octahedral texel | none |
+| the per-probe signal | projection's rows pass and probe pass | one more sum |
+| the request's storage | the record's `screen` word | packed |
+| the guided walk at R_k | the guide's three passes | R per probe |
+
+Duplication found along the way: the trace's `probe_trace_guided_position` is a binary search the
+lower-bound chunk could serve.

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.d.ts

@@ -8,8 +8,9 @@
  * - the row → card set table readers find a row's card set in: the pair's once it is resident,
  *   `GPU_DATABASE_NULL` until then and for a row out of the SDF world.
  *
- * A row is in the SDF world when its `flags` carry `MESH_FLAG_SDF_WORLD`; a virtual geometry is absent,
- * served by its own provider. A skinned row draws a clone: the hold and the pair are its source's,
+ * A row is in the SDF world when its `flags` carry `MESH_FLAG_SDF_WORLD`, whatever its geometry: a
+ * virtual geometry's cache is held as a mesh's is, and comes from its own source (`VGeoSDFProxies`).
+ * A skinned row draws a clone: the hold and the pair are its source's,
  * whose unskinned field and cards the clone's header is aliased to (§6.3). A row written again moves
  * its hold and its pair, the new ones taken before the old ones go, so a cache or card set a row keeps
  * drawing is never let go in between.

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProbeClipmapSceneHolds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAwEI;;;OAGG;IACH,mBAHW,eAAe,YACf,eAAe,EASzB;IAED;;OAEG;IACH,sEAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,qCAEC;IAED,0BAEC;IAED;;;;;;OAMG;IACH,oBAJW,mBAAmB,YACnB,aAAa,GACX,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,6BAIC;IAED,eAiBC;IAED,eAuCC;IAED;;OAEG;IACH,cAiBC;;CA4TJ;8BAzmBY,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;4BACnE,OAAO,iCAAiC,EAAE,aAAa;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;8BAC1F,OAAO,0BAA0B,EAAE,eAAe"}
+{"version":3,"file":"ProbeClipmapSceneHolds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAwEI;;;OAGG;IACH,mBAHW,eAAe,YACf,eAAe,EASzB;IAED;;OAEG;IACH,sEAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,qCAEC;IAED,0BAEC;IAED;;;;;;OAMG;IACH,oBAJW,mBAAmB,YACnB,aAAa,GACX,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,6BAIC;IAED,eAiBC;IAED,eAuCC;IAED;;OAEG;IACH,cAiBC;;CA4TJ;8BA1mBY,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;4BACnE,OAAO,iCAAiC,EAAE,aAAa;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;8BAC1F,OAAO,0BAA0B,EAAE,eAAe"}

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js

@@ -64,8 +64,9 @@ class Pair {
  * - the row → card set table readers find a row's card set in: the pair's once it is resident,
  *   `GPU_DATABASE_NULL` until then and for a row out of the SDF world.
  *
- * A row is in the SDF world when its `flags` carry `MESH_FLAG_SDF_WORLD`; a virtual geometry is absent,
- * served by its own provider. A skinned row draws a clone: the hold and the pair are its source's,
+ * A row is in the SDF world when its `flags` carry `MESH_FLAG_SDF_WORLD`, whatever its geometry: a
+ * virtual geometry's cache is held as a mesh's is, and comes from its own source (`VGeoSDFProxies`).
+ * A skinned row draws a clone: the hold and the pair are its source's,
  * whose unskinned field and cards the clone's header is aliased to (§6.3). A row written again moves
  * its hold and its pair, the new ones taken before the old ones go, so a cache or card set a row keeps
  * drawing is never let go in between.
@@ -325,7 +326,7 @@ export class ProbeClipmapSceneHolds {
         let record;
         let pair;
 
-        if ((flags & MESH_FLAG_SDF_WORLD) !== 0 && geometry.isVirtualGeometry !== true) {
+        if ((flags & MESH_FLAG_SDF_WORLD) !== 0) {
             record = geometries.get_metadata(geometry);
         }
 

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.d.ts

@@ -151,11 +151,42 @@ export class ProbeClipmapSettings {
      * GPU with another load of 40–73%, which is in the medians: the least loaded frames cost 0.11 ms at
      * 16,384. At the default Sponza's cards are captured in 10 frames.
      *
-     * On the AMD iGPU (RDNA2) a page costs 0.78 µs: 16,384 pages cost 33.5 ms at the median, and
-     * about 1,290 fit 1 ms (1,024 cost 0.80 ms).
+     * Re-derived once the material reads became trilinear at a texel's footprint (2026-10-30), which
+     * costs 1.30× at the median, timed on the same pages in the same frame: 16,384 pages cost 0.54 and
+     * 0.55 ms at the median in two runs (the old capture 0.54 ms beside them), 32,768 cost 1.48 and
+     * 1.52 ms, and the least loaded frames 0.15 ms at 16,384.
+     *
+     * On the AMD iGPU (RDNA2), measured before that, a page costs 0.78 µs: 16,384 pages cost 33.5 ms at
+     * the median, and about 1,290 fit 1 ms (1,024 cost 0.80 ms).
+     *
+     * Derived for {@link MeshCardCaptureMode.Trace}. A rastered card set is taken whole, the frame's
+     * last past the budget, and a frame also stops at what its scratch holds: at the largest budget
+     * Sponza's recapture took 13 frames on the iGPU, 2.5 ms of capture a frame on average.
      * @returns {number}
      */
     get card_capture_budget(): number;
+    /**
+     * @param {MeshCardCaptureMode} v
+     */
+    set card_capture_mode(v: number);
+    /**
+     * How card pages are captured: each card drawn through its material's own template and textures,
+     * or a ray a texel against the geometry's BLAS with the path tracer's material sampling. A change
+     * captures every card set again.
+     *
+     * Raster is the default. The trace took one level-0 tap of the material's 64² resident copy a
+     * texel and kept it, which aliased: on Sponza's outer wall the brick texture's dark band, every
+     * 12.8 card texels, landed on a row of texels once and between rows at its other repeats, a seam
+     * across the wall. The raster samples the texture's mips at the card texel's footprint, as UE's
+     * card capture does, and since 2026-10-30 the trace reads the resident copy's mips there too,
+     * trilinearly, at 1.30× its cost (see {@link card_capture_budget}). Against the one-tap trace, the
+     * cards' colours agreed with the raster's to 3 codes on average over Sponza's wall, floor, ceiling
+     * and banners, and recapturing all of Sponza (154,138 pages) at the largest budget, the two
+     * interleaved in one process, cost the trace 9.1–12.7 ms and the raster 0.6 ms on the RTX 4090,
+     * and 335 ms against 33 ms on the AMD iGPU (RDNA2).
+     * @returns {MeshCardCaptureMode}
+     */
+    get card_capture_mode(): number;
     /**
      * @param {number} v integer, 1 to {@link PROBE_CLIPMAP_CASCADE_COUNT_MAX}
      */
@@ -231,25 +262,18 @@ export class ProbeClipmapSettings {
      */
     get ray_budget(): number;
     /**
-     * @param {number} v seconds, positive and finite
-     */
-    set response_time(v: number);
-    /**
-     * Seconds of the exponential blend a probe's radiance follows a change by: an update blends by
-     * `1 − e^(−Δt / response_time)`. DDGI's hysteresis of 0.97 a frame at 60 fps is 0.55 s.
-     * @returns {number}
-     */
-    get response_time(): number;
-    /**
-     * @param {number} v seconds, positive and finite
+     * @param {number} v frames, positive and finite
      */
-    set retention_time(v: number);
+    set response_frames(v: number);
     /**
-     * Seconds a probe no pixel wants keeps its slot before it is freed, so a probe that leaves the screen
-     * and comes back within it keeps its history.
+     * Frames of the short mean a probe's radiance follows a change by, in its multi-scale mean: an update
+     * blends the short mean by `1 − e^(−Δt / response_frames)`, Δt the frames since the probe's last update,
+     * and the mean catches up with it once the two disagree past the texel's noise. The depth's moments
+     * blend by the same. Frames, not seconds: an update happens in a frame, and the records count them.
+     * 30 is half a second at 60 fps; DDGI's hysteresis of 0.97 a frame is 33.
      * @returns {number}
      */
-    get retention_time(): number;
+    get response_frames(): number;
     /**
      * @param {ProbeClipmapDebugView} v
      */

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProbeClipmapSettings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js"],"names":[],"mappings":"AAMA;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,gDAFU,cAAc,MAAM,CAAC,CAE8C;AAE7E;;;GAGG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;GAEG;AACH,sDAFU,MAAM,CAE0C;AAE1D;;;GAGG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;GAKG;AACH,sDAFU,MAAM,CAE0C;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH;IAaI;;OAEG;IACH,mCAKC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;OAEG;IACH,wCAIC;IAfD;;;OAGG;IACH,uCAEC;IAuBD;;OAEG;IACH,gCAKC;IAlBD;;;;;OAKG;IACH,+BAEC;IAuBD;;OAEG;IACH,kCAKC;IAjBD;;;;OAIG;IACH,iCAEC;IAwBD;;OAEG;IACH,mCAKC;IAlBD;;;;;OAKG;IACH,kCAEC;IAyBD;;;OAGG;IACH,mCAOC;IAtBD;;;;;;OAMG;IACH,kCAEC;IAqCD;;;OAGG;IACH,oCAKC;IA7BD;;;;;;;;;;;;;;;OAeG;IACH,mCAEC;IAoCD;;;OAGG;IACH,mCAKC;IA9BD;;;;;;;;;;;;;;;;OAgBG;IACH,kCAEC;IAwBD;;OAEG;IACH,mCAKC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;OAEG;IACH,wCAIC;IAfD;;;OAGG;IACH,uCAEC;IAuBD;;OAEG;IACH,6BAKC;IAlBD;;;;;OAKG;IACH,4BAEC;IAuBD;;;OAGG;IACH,mCAOC;IApBD;;;;OAIG;IACH,kCAEC;IA0BD;;;OAGG;IACH,gCAOC;IApBD;;;;OAIG;IACH,+BAEC;IA0BD;;;OAGG;IACH,8BAKC;IAlBD;;;;OAIG;IACH,6BAEC;IAyBD;;OAEG;IACH,0BAIC;IAjBD;;;;;OAKG;IACH,yBAEC;IAsBD;;OAEG;IACH,6BAKC;IAjBD;;;;OAIG;IACH,4BAEC;IAuBD;;OAEG;IACH,8BAKC;IAjBD;;;;OAIG;IACH,6BAEC;IAuBD;;OAEG;IACH,0BAIC;IAhBD;;;;OAIG;IACH,yBAEC;;CAUJ"}
+{"version":3,"file":"ProbeClipmapSettings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,gDAFU,cAAc,MAAM,CAAC,CAE8C;AAE7E;;;GAGG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;GAEG;AACH,sDAFU,MAAM,CAE0C;AAE1D;;;GAGG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;GAKG;AACH,sDAFU,MAAM,CAE0C;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH;IAaI;;OAEG;IACH,mCAKC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;OAEG;IACH,wCAIC;IAfD;;;OAGG;IACH,uCAEC;IAuBD;;OAEG;IACH,gCAKC;IAlBD;;;;;OAKG;IACH,+BAEC;IAuBD;;OAEG;IACH,kCAKC;IAjBD;;;;OAIG;IACH,iCAEC;IAwBD;;OAEG;IACH,mCAKC;IAlBD;;;;;OAKG;IACH,kCAEC;IAyBD;;;OAGG;IACH,mCAOC;IAtBD;;;;;;OAMG;IACH,kCAEC;IAqCD;;;OAGG;IACH,oCAKC;IA7BD;;;;;;;;;;;;;;;OAeG;IACH,mCAEC;IA6CD;;;OAGG;IACH,mCAKC;IAvCD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kCAEC;IAoCD;;OAEG;IACH,iCAIC;IA5BD;;;;;;;;;;;;;;;;OAgBG;IACH,gCAEC;IAsBD;;OAEG;IACH,mCAKC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;OAEG;IACH,wCAIC;IAfD;;;OAGG;IACH,uCAEC;IAuBD;;OAEG;IACH,6BAKC;IAlBD;;;;;OAKG;IACH,4BAEC;IAuBD;;;OAGG;IACH,mCAOC;IApBD;;;;OAIG;IACH,kCAEC;IA0BD;;;OAGG;IACH,gCAOC;IApBD;;;;OAIG;IACH,+BAEC;IA0BD;;;OAGG;IACH,8BAKC;IAlBD;;;;OAIG;IACH,6BAEC;IAyBD;;OAEG;IACH,0BAIC;IAjBD;;;;;OAKG;IACH,yBAEC;IAyBD;;OAEG;IACH,+BAKC;IApBD;;;;;;;OAOG;IACH,8BAEC;IAuBD;;OAEG;IACH,0BAIC;IAhBD;;;;OAIG;IACH,yBAEC;;CAUJ"}