@woosh/meep-engine 3.32.0 → 3.34.0

package/src/shade/renderer/geometry/virtual/runtime/SHADOW_PLAN_2026_09_28.md

@@ -0,0 +1,536 @@
+# Virtual geometry casts shadows — the plan
+
+**Closed 2026-09-29.** Everything below is done, withdrawn or measured moot, and §5 is what it
+deliberately leaves out.
+
+**2026-09-28, revision 3**, after an adversarial pass over revision 2 (three reviewers against the
+code; §6 is the ledger, and the sections it changed say so). **S1–S5 are done, S6 is withdrawn, and shadow
+views cut at twice the camera's τ; §7 is what each step measured.** It changes no decision in
+`VIRTUAL_GEOMETRY_DESIGN.md` — §4 already pins one cut per view and withdrew the claim that shadow
+views could reuse the camera's — and it takes `RUNTIME_PLAN.md` §9's "no shadow-view cuts" out of
+the list of things v1 does not do.
+
+## Decided
+
+1. **One cut per view, and a shadow view is a view.** Cascades, spots and a point light's cube faces
+   go through the same seam, the same per-view state and the same rules as the main view. Nothing in
+   the VG runtime knows which kind of view it is cutting for.
+2. **The engine owns the VG frame.** It is a core feature; a host does not open, read or close it.
+3. **VG shadows are not optional.** How is open; whether is not.
+4. **Proxies are not built now, and the architecture leaves room for them.** Nanite-style proxies
+   drawn in place of a cut for some views, behind a switch, may come later; §2.6 is where they would
+   go and what this work must not close off.
+5. **The order is §4's.**
+6. **Shadow views cut at twice the camera's τ** *(after S4)*. The shadow context sets
+   `tau_scale` to 2 on every view it owns (`SHADOWMAP_VGEO_TAU_SCALE`); §7.2 is the price.
+7. **No batched cascade cut** *(after S5)*. Cascades are boxes fitted to separate slices of the view
+   frustum — misaligned, overlapping only at the blend margins — so one descent over all three
+   shares no traversal work, only dispatches. §3 item 2 and S6 are withdrawn.
+
+Revision 1 argued from a measured match between a cascade's texel and the screen pixel at the far end
+of its slice. That argument is withdrawn: what a view's cut needs is a function of what projects into
+*that* view, and §1 says why the camera's view says nothing about it.
+
+## 0. What is true today — measured
+
+### 0.1 Virtual geometry receives shadows and never casts them
+
+Measured on `playground/vgeo_scene` with the textured Zorah rebuild (1,012 containers, 12,597
+instances, the scene's own sun), headless Chrome on the 4090, 1556×592. Each condition is a
+32-frame average after TAA has settled; the column is the fraction of pixels that go more than 16
+luma darker when shadows are switched on.
+
+| view | only VG in view | plus two ordinary `BoxGeometry` casters |
+|---|---:|---:|
+| authored | 0 | 0.110% |
+| oblique | 0 | 0.076% |
+| plan | 0 | 0.106% |
+
+Two identical captures differ by the same 0 at that threshold, so the VG column is noise. The boxes'
+shadows land on VG ground and are the only thing in the on/off difference; the dome and the
+greenhouse, under a sun 52° above the horizon, leave nothing on it.
+
+Before the far-plane fix of 2026-09-28 the page hid every shadow, not only VG's: `look()` set
+`camera.far = distance × 2000`, and `DirectionalLightShadowmap.update` takes `camera.far` as its
+shadow distance, so from the authored viewpoint the nearest cascade spanned 0–5.8 km. The page now
+fits the far plane to the world's bounding sphere, capped at twenty times the orbit distance, and
+the numbers above are from that version.
+
+### 0.2 Why, in the code
+
+Three things each stop it, in the order a frame meets them:
+
+- **The frame is not open yet.** `Renderer.render` calls `sm.select_for_draw` / `sm.draw` before it
+  creates the `Shading` graph, and the VG frame is opened by the host's `RenderExtension` at
+  `FramePhase.FrameStart` — on that graph. Every shadow view is recorded while
+  `runtime.feedback === -1`, and `graph_vgeo_expand_if_enabled` returns at its first check.
+- **The graph is not the frame's.** Each shadow map records on a `new FrameGraph("shadows")` of its
+  own, and the feedback buffer is a transient of the `Shading` graph. Were the frame open, the
+  second check (`runtime.frame_graph !== graph`, REVIEW_LEDGER M13) would skip anyway, and must:
+  the handle names a resource that graph has never heard of.
+- **An orthographic view has no projection the cut can take.** `VGeoViewCut.set_projection` reads
+  `view.camera.camera.fov`; a cascade's `OrthographicCamera` has none, and `vg_project` divides by a
+  distance that means nothing to a parallel projection.
+
+Nothing else stops it. The seam already sits in both rasterization paths shadow views use —
+`graph_rasterize_scene` for cascades and spots, `graph_rasterize_scene_fast` for a point light's cube faces — and
+every `GPUViewContext`, shadow views included, already owns a `VGeoViewCut`. The cascade fit's
+caster range (`shader_csm_caster_range`) already reads every `meshes` row's world bounds, VG rows
+among them, so the near planes already reach VG casters.
+
+### 0.3 What a cut costs now
+
+`GPUProfileSession` at `TIMING`, 90 frames, medians, the same page, `max_iterations` 16 (escalated),
+`descent_steps` 24:
+
+| | authored | oblique |
+|---|---:|---:|
+| GPU frame, sum of spans | 2,903 µs | 2,931 µs |
+| `VGeo cut traverse`, 48 dispatches | 984 µs | 814 µs |
+| `VGeo cut queue prepare`, 48 dispatches | 60 µs | 60 µs |
+| collect + seed, 3 each | 29 µs | 35 µs |
+| per site: traverse | 815 / 120 / 46 µs | 630 / 98 / 70 µs |
+
+The main view records **three cut sites** — the per-opaque-bucket seam of
+`graph_rasterize_partial_opaque` plus the one in `graph_rasterize_remaining_opaque` — and the work
+is almost all in the first. A site with nothing to do still pays its ladder: sixteen traverse
+dispatches at ~3 µs, sixteen prepares, collect, seed, the scan and the remainder, about **80 µs**.
+The cut is already the largest line in the frame, over a third of it.
+
+## 1. Why a shadow view needs its own cut
+
+**A cut is a function of what projects into the view it is drawn into, and a caster's projection into
+a shadow map has nothing to do with its projection onto the screen.** A small object high above the
+observer is a speck to the camera — or outside its frustum altogether — and throws a large shadow on
+the ground in front of it. That shadow needs the caster's fine levels; the camera's cut holds its
+coarse ones where the camera sees it at all, and nothing where the camera does not. No property of
+the camera's view bounds what a shadow view needs, so a shadow view gets its own cut exactly as the
+main view does, with its own projection and its own threshold in the units of its own render target.
+
+It follows that **a shadow view is a streaming client in its own right.** Its demand is not a subset
+of the camera's — the speck in the sky wants pages the camera will never ask for — so its wants reach
+residency on the same terms as the main view's (§2.4), and residency, which is already scene-wide,
+arbitrates between them.
+
+**This is what the references do.** Unreal's Nanite renders every virtual-shadow-map view with its
+own culling and LOD, against that view's resolution; Bevy's meshlet renderer runs a full cull and
+raster per shadow view, and its LOD test reads the bound view's own projection and viewport. Neither
+reuses the camera's cut. The one reference that does, NVIDIA's `vk_lod_clusters`, traces its shadow
+rays against the camera's cut and documents the cost: off-screen instances cast from a coarser level,
+and their shadows change when they come into view.
+
+**Self-shadowing is measured, not argued.** A surface that is both receiver and caster is drawn at
+the camera's level in the G-buffer and at the shadow view's level in the map. The receiver bias in
+`chunk_sample_shadowmap_atlas_for_light` is a normal offset and a slope-scaled depth offset in texels,
+over a 5×5 filter; whether that absorbs the mismatch is S3's measurement (§4), and a new bias term is
+added only if it fails.
+
+## 2. What changes
+
+### 2.1 The engine owns the VG frame *(rev 3)*
+
+The renderer opens the frame for a scene with virtual geometry enabled, **before the shadow block and
+outside its `if`** — so a frame with shadows off still opens and closes — and schedules the readback
+and closes the frame inside the `Shading` graph's recording, after the last phase and before
+`encodeGraph`, in a `finally` so a throwing phase cannot leave it open. `VGeoFrameStart` and
+`VGeoFrameEnd` are deleted from **all three** hosts — `vgeo_scene`, `vgeo_runtime` and `caldera`. That
+closes REVIEW_LEDGER U1: `GPUSceneContext` constructs the runtime, residency and `VGeoFeedbackLoop`
+today, and nothing in the engine drives them. The frame is opened *for* the view being rendered, which
+takes slot 0 (§2.4); that is the frame's own view, not a kind of view.
+
+The feedback buffer stops being a graph transient. It becomes a buffer the runtime owns
+(`STORAGE | COPY_SRC | COPY_DST`), re-made when its layout grows, and **imported** into each graph that
+cuts via `FrameGraph.import_resource` — a write to an imported resource marks the pass side-effecting,
+so nothing is culled. The seam asks the runtime for the graph's handle (`feedback_in(graph)`), and the
+first graph of a frame to import it records a pass that **clears the counter and touch words in-stream**
+(`clearBuffer`, no upload; the want records need no clearing). M13's hazard — a handle from one graph
+named in another — then cannot be written. Ordering between graphs needs nothing: `encodeGraph`
+compiles and executes each graph into the frame's one encoder as it is handed over, and there is one
+submit per render.
+
+`GraphicsEngine.render_to_sampler` renders eight times per call and each is a frame, which is the
+right semantics — each is a render of a view — and it advances the residency's protect clock eight
+times; noted, not changed.
+
+### 2.2 The cut takes an orthographic projection *(rev 3)*
+
+**One derivation, from the projection matrix the view actually draws with** — no camera-type branch in
+the seam, and no widths the old setter could not take:
+
+    k = ½ · max(width · |P[0]|, height · |P[5]|)      w = −P[11]
+
+For this engine's infinite reverse-Z perspective that is `height / (2 tan(fov/2))` and `w = 1`; for its
+reverse-Z orthographic, `height / (top − bottom)` on the finer axis and `w = 0`. Anything else asserts.
+`vg_project` divides by `w · d + (1 − w)` and tests **that** for `≤ 0`, so an orthographic camera whose
+transform sits inside a root sphere — a cascade's centre usually does — is not taken as an eye inside
+the sphere.
+
+The weight lives **in the instance record** (`VGEO_INSTANCE_OFFSET.DISTANCE_WEIGHT`), not only in the
+params, so the traversal never reads a per-view uniform for it. The collect's scale term is
+`k · σmax / (w · σmin + 1 − w)`: σmax/σmin in perspective, as today, and σmax alone orthographically,
+where no distance cancels a scale. `vgeo_select_cut` gets the same term.
+
+**The proof has to discriminate the scale term, not just the formula** *(rev 3)*: the oracle has no
+instance transform, so agreement alone would check the GPU against the same formula it was given. S1
+adds a direct collect check at a uniform scale of 7 (σmax = 7 against σmax/σmin = 1) and a metamorphic
+one — an instance scaled by s in an orthographic view cuts exactly like an unscaled one at s times the
+extent — plus the orthographic frustum held against `construct_frustum_planes`.
+
+Bevy's `lod_error_is_imperceptible` has this shape, and its orthographic arm is where its bug was: PR
+#19318 fixed a metric that had left shadows visibly faceted.
+
+### 2.3 τ is the runtime's, scaled per view *(rev 3)*
+
+Revision 2 made τ an absolute per-view value. That splits the one quality lever — the playgrounds'
+slider sets `runtime.tau`, and an absolute shadow τ of 2 becomes *finer* than the main view the moment
+the slider goes to 4 — and the reference it cited is relative. So a view carries **`tau_scale`**,
+default 1, and cuts at `runtime.tau × tau_scale`. Whoever owns a view may set it; nothing in the runtime
+knows what kind of view it is. Unreal's `r.Shadow.NaniteLODBias` (default 1, scale 2^−bias) is the
+data point for shadow views; S4 measures before anything but 1 is set.
+
+**Shadow views default to 2** *(after S4)*: the shadow context sets it on every view it owns
+(`SHADOWMAP_VGEO_TAU_SCALE`), and the runtime still knows nothing of what kind of view it cuts for.
+At 2 the cascades draw 39% of the clusters they do at 1, and false light against a fine reference
+rises 2.3–4.7× (§7.2).
+
+### 2.4 Feedback is per view *(rev 3)*
+
+Each view that cuts in a frame takes a **slot**. Per slot, the layout carries a header — the want
+counter and the stats block — and a want slice; the touch bits after the headers stay shared, since a
+page any view draws from is a page in use. The view's params hold its offsets (`stats_base`,
+`want_count_offset`, `want_base`, `want_capacity`), so this is parameters, not bindings: every kernel
+that writes feedback already binds `params`, and the traverse is at its tenth storage buffer with no
+eleventh. `want_capacity` keeps its meaning — pages one frame may ask for across every view — and is
+divided evenly among the slots, so the readback does not grow with the view count.
+
+- **Slots.** The frame's own view is slot 0. Other views take the next slot the first time they cut
+  in the frame. The layout is sized to a **high-water mark** of slots used, like `max_iterations`: a
+  view beyond it shares the last slot for that frame, and the next frame has room. The mark is capped,
+  so a frame that draws many point lights for the first time — first draws bypass the shadow budget —
+  cannot grow the buffer without bound.
+- **Wants: one stamp tag per (frame, slot).** The stamp was taken *before* the capacity check, so a
+  full shadow slice burned the stamp of every page it could not write and the main view, recording
+  later, could not ask for it that frame; and the recorded priority was the first writer's. With a
+  tag per view, each view dedups its own wants and records them in its own slice; a page two views want
+  appears twice, and `VGeoResidency` already collapses the second (the page is pending or resident by
+  then).
+- **Priority is error over the view's own τ**, so a want at twice its view's threshold ranks the same
+  whether that view counts screen pixels or texels. Eviction stays LRU over touches; refusals per slot
+  are what S4 measures.
+- **Escalation is per view.** `max_iterations` moves from the runtime onto `VGeoViewCut`, starting
+  from the runtime's and raised from that view's own slot. One far cascade or one cube face of a point light that
+  needed more wavefronts must not double every site's ladder for the life of the scene. The readback
+  closes over the slot → view table with the layout, since it lands frames later and the set of views
+  changes.
+- **Stats** are per slot; `VGeoFeedbackLoop.stats` is slot 0's, which is what the panels show, and each
+  view's last reading is on its `VGeoViewCut`.
+
+### 2.5 What does not change
+
+The seam's call sites, the record type, the HZB meshlet filter, the draw, the shadow atlas, the
+cascade fit and the caster range.
+
+**Cached local maps** *(rev 3)*. A spot or point map drawn once is kept until `shadowmap_update_score`
+re-selects it. Its first draw is forced at creation, when little but the roots is resident, and between
+redraws it touches nothing, so the LRU evicts exactly the pages only it needs. Left alone it would keep
+a root-level cut indefinitely. So a map whose own views' last reading was **clamped**, and under which
+pages have installed since, is re-selected like an invalid one. That keys on the map's own incomplete
+cut rather than on every LOD change, which is what keeps it clear of the invalidation storm Unreal's
+`r.Nanite.VSMInvalidateOnLODDelta` warns about.
+
+### 2.6 Room for proxies — not built
+
+A proxy is a fixed, cheap stand-in for a whole geometry — Nanite's fallback mesh — drawn **instead of**
+a cut for a view that does not justify one. If it comes, it comes as a per-view choice, and this work
+keeps the two places it would need open:
+
+- **The choice is made per (instance, view).** Today that is the seam, which already receives the view:
+  it would either cut or append the instances' proxy meshlets.
+- **A proxy's meshlets would hang off the VG geometry row, never off `VirtualGeometry.meshlets`.**
+  `meshlets.count` is zero for a virtual geometry, and that is what keeps static expansion from
+  drawing a VG instance in every view; filling it with a proxy would draw the proxy *and* the cut
+  everywhere.
+
+That room is for **raster** views *(rev 3)*: ray-traced shadows read `geometries.blas`, built from
+static meshlets, so a proxy for RT needs the BLAS builder to take an input from the VG row as well.
+
+## 3. Cost *(rev 3)*
+
+**Sites** *(before S5)*. A view cuts once per active opaque bucket in phase one plus once in phase two (standard
+path: cascades and spots, ~3 sites each), and once per active bucket in the fast path (a point light's cube faces:
+two active buckets make 12 sites for a cube light and 8 for a tetrahedral one). S5 made it two per
+standard view and one per face (§7.3). An empty site is ~80 µs at
+`max_iterations` 16 and ~225 µs at the ceiling of 64.
+
+**Work.** The three cascades are 1740² + 2 × 1440² ≈ 7.3 Mpx against the 0.92 Mpx main view that §0.3
+measured, and a cut is a function of pixels, so "a cascade costs what the camera's cut does" is a floor
+rather than an estimate. S4 measures it, with the raster cost of the extra clusters beside it.
+
+1. **One cut per view** — CUT_PLAN §7 6b, decided and not done, and **extended to the fast path**:
+   filter instances once, cut once, sort the meshlets by bucket, then loop the buckets for raster
+   alone. That is two sites per standard view and one per cube face.
+2. **One ladder for the cascades — withdrawn.** It would have run one descent over all three
+   cascades. They are not one frustum and not nested ones: each is a box fitted to its own slice of
+   the view frustum, misaligned with the others and overlapping only at the blend margins, so a shared
+   descent shares no traversal work. What it would share is dispatch overhead — 0.2–0.3 ms after S5
+   (§7.4) — for a change inside the traverse.
+
+## 4. Order, and what each step leaves proved *(rev 3)*
+
+**Correctness first, on by default, then cost.** VG shadows are not optional, so they land for every
+scene with virtual geometry with no switch to turn them off. Each step is red-then-green against a spec
+or a scripted headless measurement.
+
+- **S1 — orthographic projection (§2.2).** Agreement spec: orthographic views against the oracle; the
+  σmax collect check; the metamorphic scale check; the orthographic frustum. `VGeoViewCut` derives k and
+  w from the projection matrix, with its own spec. The seam takes it from the view's camera.
+- **S2 — the engine owns the frame; feedback is per view (§2.1, §2.3, §2.4).** This is the step that
+  turns shadow cuts on. Emulator tier: two views in one run write their own stats and want slices, a
+  full slice does not stop another view asking for the same page, and priority is over τ. Recording
+  tier: the seam on a second graph within an open frame records its cut against the same imported
+  buffer, and only the first graph clears it. Headless: all three playgrounds still stream.
+- **S3 — the shadows are right.** Proved against the tree before S2, where every one of these is red.
+  TAA off and single frames, the shadow term measured against a reference with shadow views at a
+  quarter of the τ: false-shadow and false-lit pixels on light-facing receivers.
+  - a caster outside the camera frustum (behind the camera) casts into view;
+  - spot, cube and tetrahedral point lights over VG, including a cached map converging (§2.5);
+  - a yaw sweep over a still scene: frame-to-frame XOR of the shadow mask, VG against an ordinary
+    mesh of the same size, since unstabilized cascades refit — and change `k` — every frame;
+  - per slot: `QUEUE_DROPPED`, `INSTANCES_DROPPED`, `MESHLETS_DROPPED` all zero, `QUEUE_REMAINING`
+    zero after escalation.
+- **S4 — measure.** Per view (the cut's scope and the `VGeoViewCut` label carry the view's name): cut
+  time, drawn clusters, wants, refusals; spot, cube and tetra lights; a frame spawning N point lights;
+  shadow views at `tau_scale` 1, 2, 4 — a default other than 1 only if S3's checks pass at it.
+- **S5 — one cut per view (6b), standard and fast paths.**
+- **S6 — one ladder for the cascades: withdrawn** (§3 item 2).
+
+## 5. Not in this
+
+- **Proxies** (§2.6), beyond keeping the room.
+- **Non-opaque VG casters.** An alpha-tested VG instance draws nothing in the main view either
+  (design §9); the shadow path's alpha-tested bucket inherits that.
+- **Ray-traced and SDF shadows** (`shadow/ray`, `shadow/sdf`). VG × RT is design §9's future work.
+- **Screen-space contact shadows** already see VG — they trace the depth buffer.
+- **Releasing VG on scene teardown** was a defect of its own. It was fixed separately:
+  `GPUSceneContext.destroy()` releases what `enable_virtual_geometry` built (7a9e14fea, and
+  REVIEW_LEDGER U1).
+
+## 6. Adversarial review of revision 2 — the ledger
+
+Three reviewers, one each on the frame and feedback, the kernel, and the shadow path and cost; each
+finding checked against the code before it was taken.
+
+| # | finding | disposition |
+|---|---|---|
+| 1 | want stamp taken before the capacity check: a full shadow slice silences the main view's want for that page; first writer's priority wins (all three) | §2.4: stamp tag per (frame, slot); priority over the view's τ |
+| 2 | absolute per-view τ splits the one lever and inverts at a raised slider | §2.3: `tau_scale` |
+| 3 | one `max_iterations` for the frame lets one hungry view double every site forever | §2.4: per view |
+| 4 | S2 already turns shadows on, so S3 cannot be red after it; the software device cannot prove a readback | §4: S3 proved against the pre-S2 tree; slot writes proved at the emulator tier |
+| 5 | Caldera is a third host; a second `begin_frame` mid-render would split `frame_tag` | §2.1 |
+| 6 | the oracle has no instance transform, so agreement cannot catch a wrong scale term; the seam still reads `fov` | §2.2, S1: σmax and metamorphic checks; projection from the matrix |
+| 7 | `vg_project`'s eye-inside test must be on the denominator — a cascade's centre sits inside root spheres | §2.2 |
+| 8 | "no change inside the traverse" for a batched cut is false; cascades and local maps are in separate graphs; the multi-view collect moves the proxy choice | §3.2 scoped to cascades and called a traverse change; §2.6 restated per (instance, view) |
+| 9 | a point light's cube faces cut per bucket in the fast path, first draws bypass the budget, cascades are 7.3 Mpx | §3 |
+| 10 | 6b as written covers only the standard path | §3.1: and the fast path |
+| 11 | a cached local map keeps its first, root-level cut | §2.5: re-select a map whose cut was clamped once pages have installed |
+| 12 | the S3 probe cannot see speckle through TAA, never looks for leaks, sweeps the wrong τ, and misses off-frustum casters, local lights and stability | §4 S3 |
+| 13 | clearing by `writeBuffer` uploads the whole buffer, and the usage lacks `COPY_DST` | §2.1: in-stream clear of the counter and touch words |
+| 14 | `end_frame` needs a `finally`; the open has to sit outside the shadows-enabled `if` | §2.1 |
+| 15 | per-view attribution impossible: identical scope names, `VGeoViewCut` labelled before its view is | §4 S4 |
+| 16 | proxies as described are raster-only | §2.6 |
+| 17 | unstabilized cascades change `k` every frame, so shadow LOD may pop under camera motion | **measured, no action (§7.6)**: `k` moves and the cut follows, but the picture does not flicker beyond what a frozen-`k` cut — an ordinary mesh, to the map — does. `k` is not quantized |
+| 18 | a point light's cube faces render at a fixed 512² each and are then remapped into the light's octahedral atlas slot, 128² by default and sized by the resolution policy — so each face cuts for texels the slot does not keep | **withdrawn, not a VG issue.** It is the remap's resolution match between cube faces and the octahedral encoding, and a VG knob would only paper over it |
+| 19 | the orthographic far plane is finite and skipped: casters behind a slice's receivers refine and want pages | **withdrawn, measured (§7.5)**: a cascade's far plane is the far corner of its view slice in light space, and testing it culls nothing worth having |
+| 20 | the exact orthographic factor is the largest singular value of the projected 2×3 | declined: σmax is a conservative bound and exact for uniform scale |
+
+## 7. What the steps found
+
+All of it is Zorah (§0.1's page, scene and viewpoints) on the 4090 in headless Chrome, at 1556×592.
+Costs come from `GPUProfileSession` at `TIMING`, as medians over 48 frames. **This GPU runs in two
+modes about 2× apart.** It switches between launches and now and then mid-run, so absolute numbers do
+not compare across runs, or even across the rows of one table. Every cost claimed here is a
+difference within a pair taken in one Chrome, and only pairs taken in one mode are quoted.
+
+### 7.1 Shadows are cast (S3)
+
+The table is §0.1's: the fraction of pixels that go more than 16 luma darker when shadows are switched
+on, only VG in view, against the tree before S2.
+
+| view | before | after |
+|---|---:|---:|
+| authored | 0 | 3.99% |
+| oblique | 0 | 0.31% |
+| plan | 0 | 1.95% |
+
+- **A caster behind the camera casts into view.** From inside the throne room, 39% of the pixels
+  darken.
+- **Local lights, with the sun off.** Pixels darkened: 4.5% under a cube point light, 4.1% under a
+  tetrahedral one, 0.22% under a spot. In every slot `QUEUE_DROPPED`, `INSTANCES_DROPPED`,
+  `MESHLETS_DROPPED` and `QUEUE_REMAINING` are zero.
+- **Cached maps (§2.5).** Twelve point lights spawned in one frame reach zero clamped maps within
+  14 s, with nothing else fetching.
+- **At rest, nothing moves.** Across consecutive settled frames, no pixel changes in the authored view.
+  In the plan view, fewer than one pixel in 100,000 changes by more than 4 luma, and that holds with
+  shadows on and off alike.
+- **Under camera motion, VG shadows flicker no more than ordinary geometry's** (§7.6).
+- **Self-shadowing (§1) needs no new bias.** The main view's `tau_scale` was swept 1 → 8, which makes
+  the G-buffer up to 8× coarser than the maps.
+  - Authored: the fraction of darker pixels holds at 6.98–6.99%, with no isolated acne.
+  - Oblique: 0.79% at 1 and 0.89% at 2, then 1.17% at 4 and 2.29% at 8.
+  - Isolated dark pixels do not grow anywhere in the sweep.
+
+  So the existing bias absorbs about a 2× mismatch, and the default adds none beyond what the two
+  projections make. Measured the other way round, against shadow views at τ × ¼, shadow views at τ × 1
+  leave 0.003–0.012% false shadow and 0.006–0.154% false light.
+
+### 7.2 What shadows cost, and τ (S4)
+
+**The first S4 run found a defect in S2**, fixed in 3f9cce3cc. The first frames were laid out for one
+slot, so the cascades shared slot 0 with the frame's view. The sum of their remainders escalated the
+main view to 32 wavefronts, for good. Now the floor is two slots, a view past the layout never shares
+slot 0, and a shared slot escalates nobody.
+
+**Where the time goes**, read within single frames so the modes cannot move it. The frame is the
+authored view with shadows on, after S5:
+
+- The cut is half of it: 2.67 of 5.27 ms.
+- Of that cut, the three cascades take 1.88 ms and the camera 0.74 ms.
+- Cascade 0 alone is 0.82 ms and draws 113k clusters, against the camera's 32k.
+
+Per-site ladders are the smaller part (§7.4).
+
+**`tau_scale` on the cascades** (`shadow_tau`, TAA and auto exposure off; the reference is every
+cascade at τ × ¼):
+
+| view | false light ×1 | ×2 | ×4 |
+|---|---:|---:|---:|
+| authored | 0.006% | 0.028% | 0.040% |
+| oblique | 0.154% | 0.349% | 0.454% |
+| plan | 0.153% | 0.400% | 0.530% |
+
+×2 draws 36% of ×1's clusters in cascade 0 and cuts the depth raster by about 60%. Across the three
+views it also multiplies the false light by 2.3–4.7×, and false light is sunlit ground under a caster.
+**Shadow views default to 2** — Alex's call on these numbers. The clusters and raster are the saving,
+and the false light is the price.
+
+### 7.3 One cut per view (S5)
+
+- **Standard path, phase one.** The HZB filter appends every opaque bucket to one positive set, as it
+  already did the maybe set. That set is expanded, cut and meshlet-filtered once, then sorted by bucket
+  and drawn a bucket at a time (`graph_meshlets_rasterize_by_bucket`).
+- **Fast path.** The opaque buckets are not neighbours in its bucket-sorted meshes, so it gathers them
+  into one collection first (`shader_gather_bucket`). Each bucket lands after the gathered buckets
+  below it, read off their headers, with no atomics.
+- **Both paths, and phase two,** sort only when there is more than one bucket to separate.
+
+Paired, before (3f9cce3cc) and after in one Chrome, ABBA twice. The ranges are over the pairs taken in
+the fast mode, and the slow mode's pairs save proportionally the same.
+
+| | cut sites | frame saved | cut saved |
+|---|---:|---:|---:|
+| authored, shadows on | 12 → 8 | 1.0–1.1 ms of 6.2 | 0.9–1.2 ms |
+| oblique, shadows on | 12 → 8 | 0.6–1.6 ms of 10.2 | 1.2–1.7 ms |
+| authored, shadows off | 3 → 2 | 0.3–1.0 ms | 0.2–0.7 ms |
+| oblique, shadows off | 3 → 2 | 0.02–0.13 ms | 0.09–0.11 ms |
+
+**Nothing else changed:**
+
+- The two trees' pictures differ by nothing at any threshold, in all four conditions.
+- Every view draws the same number of clusters.
+- Every counter of every face of a cube and a tetrahedral point light is the same, from drawn to
+  culled-by-LOD.
+
+The second bucket's site disappears and the first barely grows, because nearly all of what the second
+site cost was its ladder. Cascade 0 goes from [807, 328, 71] µs to [820, 69] µs.
+
+### 7.4 S6 is withdrawn
+
+After S5 each view is left with **one ladder per phase**, and an empty ladder costs 40–75 µs. That
+ladder is all a batched cascade cut could have shared: the cascades are disjoint boxes over separate
+slices of the view frustum (§3 item 2), so the descent's own work — where the cascades' cost is —
+would be the same.
+
+What would reduce that work is fewer clusters per cascade. Two levers exist:
+
+- `tau_scale` — now 2 on shadow views (§7.2).
+- Starting each view's descent from its previous frontier. `VGeoViewCut` already keeps a frontier
+  (CUT_PLAN 6c), and the seam does not read it.
+
+Neither is proposed here.
+
+### 7.5 A cascade's far plane culls nothing worth having
+
+Ledger 19 said the untested orthographic far plane lets casters behind a cascade's receivers refine.
+That was argued, not measured. A cascade's far plane is `extents.z1`, the far corner of its view
+slice in light space, so anything behind it sits below everything the slice covers.
+
+Measured with shadow views at `tau_scale` 2. The collect's fifth plane was swapped for orthographic
+views only, one Chrome launch per arm: the near plane as shipped, no plane, the far plane, then the
+near plane again.
+
+- **The near plane culls nothing either.** The caster range pushes it behind every caster by
+  construction, so "no plane" matches "near" on every counter.
+- **So the far arm is the far plane's whole effect.** Across the three viewpoints and three cascades,
+  every counter — drawn, items, pages, clusters tested, frustum culls — is identical in all four arms,
+  but one: oblique cascade 0, which draws 65 clusters, draws 14.
+- **The pictures are identical to the pixel** in every arm.
+
+### 7.6 Cascade refits do not make VG shadows flicker (ledger 17)
+
+Cascades are not stabilized, so every camera move refits them and changes each cascade's `k`. The
+question was whether VG's shadow cuts re-selecting on every refit make the shadows flicker more than
+an ordinary caster's.
+
+**Method.** A moving view camera would put its own motion into every frame-to-frame difference, so
+the view stands still and only the camera the cascades are fitted from moves. It yaws
+A·sin(2πk/48), one step per rendered frame, so every change in the picture comes from the refit.
+
+- **Two arms over the identical sequence.** In one, VG's shadow cuts are live. In the other, every
+  shadow view's `k` is frozen at the unwobbled fit: `set_projection` becomes a no-op. A cut with
+  `k` frozen is an ordinary mesh as far as the map is concerned, so live minus frozen is VG's own
+  flicker. Freezing `k` is also exactly the remedy this ledger row named.
+- **Measurement conditions.** TAA and auto exposure are off, and shadow views are at `tau_scale` 2.
+  Each frame is captured inside the render wrapper, so the two arms' phases line up. Metrics cover the
+  central 80% of the screen. A second live arm reproduced the first to the pixel.
+
+Per frame, the fraction of pixels that change by more than 8 luma:
+
+| view | ±3°: live | ±3°: frozen | ±10°: live | ±10°: frozen |
+|---|---:|---:|---:|---:|
+| authored | 0 | 0 | 0.0002% | 0 |
+| oblique | 0.033% | 0.033% | — | — |
+| plan | 0.009% | 0.006% | 0.018% | 0.013% |
+
+Over the ±3° sweep, cascade 0's `k` runs 67–78 and it draws 35k–47k clusters, so the cut does follow
+the refit — and the picture barely notices. At ±10°, about 1.3° a frame and roughly a fast turn, VG's
+own share is 0.005% of the screen per frame.
+
+**The metric can see VG flicker when there is some.** As a positive control, with no wobble, every
+shadow view's `tau_scale` alternated between 2 and 16 each frame: cascade 0 drew 3.7k and 42k clusters
+in turn. That flickers 0.17% of the screen per frame in the authored view and 0.33% in the plan view.
+
+## References
+
+Read 2026-09-28. Unreal's source is not public; its facts here come from Epic's documentation and
+from a UE 5.4.4 console-variable reference that reproduces source locations.
+
+- Epic, *Virtual Shadow Maps in Unreal Engine* — per-view Nanite rendering, one pass per light
+  class, 17 directional clipmap levels, page caching and invalidation.
+  https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-shadow-maps-in-unreal-engine
+- `r.Shadow.NaniteLODBias`, default 1, scale 2^−bias (ShadowSceneRenderer.cpp:50, :103 in 5.4.4).
+  https://indxzero.github.io/ue544cvarwiki/articles/r.shadow.nanitelodbias/
+- `r.Nanite.VSMInvalidateOnLODDelta`, default 0, experimental (NaniteCullRaster.cpp:117).
+  https://indxzero.github.io/ue544cvarwiki/articles/r.nanite.vsminvalidateonloddelta/
+- Epic, *Hardware Ray Tracing* — ray-traced shadows trace the Nanite fallback mesh.
+  https://dev.epicgames.com/documentation/en-us/unreal-engine/hardware-ray-tracing-in-unreal-engine
+- Bevy, `crates/bevy_pbr/src/meshlet/cull_shared.wesl` (`lod_error_is_imperceptible`) and
+  `visibility_buffer_raster_node.rs` (one full cull and raster per shadow view).
+  https://github.com/bevyengine/bevy/tree/main/crates/bevy_pbr/src/meshlet
+- Bevy PR #19318, the orthographic LOD metric fix. https://github.com/bevyengine/bevy/pull/19318
+- jms55, *Virtual Geometry in Bevy 0.15* — "render all views at once" listed as shadow performance
+  work. https://jms55.github.io/posts/2024-11-14-virtual-geometry-bevy-0-15/
+- NVIDIA `vk_lod_clusters` — one traversal from the camera, shadow rays traced against it; and
+  `vk_tessellated_clusters`' README on off-screen shadows changing when instances become visible.
+  https://github.com/nvpro-samples/vk_lod_clusters · https://github.com/nvpro-samples/vk_tessellated_clusters
+- **Not found in any primary source:** whether and how Nanite's shadow views issue streaming
+  requests. §2.4 does not rest on it.

package/src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.d.ts

@@ -1,5 +1,6 @@
 /**
  * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("./VGeoViewCut.js").VGeoViewCut} VGeoViewCut
  * @typedef {import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
  * @typedef {import("./VGeoResidency.js").VGeoResidency} VGeoResidency
  * @typedef {import("./cut/vgeo_cut_feedback_layout.js").vgeo_cut_feedback_layout} vgeo_cut_feedback_layout
@@ -82,10 +83,12 @@ export class VGeoFeedbackLoop {
      */
     abort(): void;
     /**
-     * Give up on this loop: the same as {@link abort}, under the name a host tears things down by.
+     * Give up on this loop: {@link abort}, and drop every reading still in flight.
      *
      * The loop owns no device resource, so there is nothing else to release — what it owns is
-     * outstanding *work*.
+     * outstanding *work*, and a reading is some: it lands frames after its cut, by which time the
+     * views it is about and the residency it feeds may be torn down, and the mapping it waits on may
+     * have been aborted by that teardown. A destroyed loop schedules nothing more.
      *
      * @returns {void}
      */
@@ -93,6 +96,7 @@ export class VGeoFeedbackLoop {
     #private;
 }
 export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type VGeoViewCut = import("./VGeoViewCut.js").VGeoViewCut;
 export type GPUVirtualGeometryRuntime = import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime;
 export type VGeoResidency = import("./VGeoResidency.js").VGeoResidency;
 export type vgeo_cut_feedback_layout = typeof import("./cut/vgeo_cut_feedback_layout.js").vgeo_cut_feedback_layout;

package/src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoFeedbackLoop.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAqCI;;;;;;OAMG;IACH;QAL8C,OAAO,EAA1C,yBAAyB;QACF,SAAS,EAAhC,aAAa;QACI,aAAa,GAA9B,MAAM;OAUhB;IAED;;OAEG;IACH,4DAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;OAKG;IACH,YAHW,UAAU,GACR,OAAO,CAuDnB;IAwBD;;;;OAIG;IACH,SAFa,IAAI,CAIhB;IAED;;;;;;;OAOG;IACH,WAFa,IAAI,CAIhB;;CACJ;yBA1OY,OAAO,iEAAiE,EAAE,UAAU;wCACpF,OAAO,gCAAgC,EAAE,yBAAyB;4BAClE,OAAO,oBAAoB,EAAE,aAAa"}
+{"version":3,"file":"VGeoFeedbackLoop.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IA4CI;;;;;;OAMG;IACH;QAL8C,OAAO,EAA1C,yBAAyB;QACF,SAAS,EAAhC,aAAa;QACI,aAAa,GAA9B,MAAM;OAUhB;IAED;;OAEG;IACH,4DAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;OAKG;IACH,YAHW,UAAU,GACR,OAAO,CAwEnB;IA4CD;;;;OAIG;IACH,SAFa,IAAI,CAIhB;IAED;;;;;;;;;OASG;IACH,WAFa,IAAI,CAMhB;;CACJ;yBA3RY,OAAO,iEAAiE,EAAE,UAAU;0BACpF,OAAO,kBAAkB,EAAE,WAAW;wCACtC,OAAO,gCAAgC,EAAE,yBAAyB;4BAClE,OAAO,oBAAoB,EAAE,aAAa"}