@woosh/meep-engine 3.30.0 → 3.32.0

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { shadowmap_budget_carry_over } from "./shadowmap_budget_carry_over.js";
 import AABB2 from "../../../../core/geom/2d/aabb/AABB2.js";
 import { MaxRectanglesPacker } from "../../../../core/geom/packing/max-rect/MaxRectanglesPacker.js";
 import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
@@ -627,15 +628,15 @@ export class GPUSceneShadowmapContext {
             selected[i].update(main_camera, scene);
         }
 
-        // Carry over the unused pool only when there was demand we couldn't meet. When the whole
-        // scene's demand was satisfied, reset to 0 so idle frames don't inflate the pool. If
-        // must-draw bypasses over-spent the pool (views_spent > budget_total), clamp at zero —
-        // we can't owe future frames for past over-spend, that way lies runaway starvation.
-        if (selector.had_unfit_candidates) {
-            this.#budget_carry_over = Math.max(0, budget_total - selector.views_spent);
-        } else {
-            this.#budget_carry_over = 0;
-        }
+        // Carry over the unused pool only when there was demand we couldn't meet — see
+        // shadowmap_budget_carry_over for why this accumulates rather than being re-derived from a
+        // total that already contains it, and why it is measured against the budgeted spend.
+        this.#budget_carry_over = shadowmap_budget_carry_over(
+            budget_total,
+            selector.views_spent_budgeted,
+            selector.had_unfit_candidates,
+            this.#update_budget
+        );
     }
 
     /**

package/src/shade/renderer/shadow/map/ShadowmapDrawSelector.d.ts

@@ -40,6 +40,14 @@ export class ShadowmapDrawSelector {
      * @type {number}
      */
     views_spent: number;
+    /**
+     * Views the most recent {@link select} committed out of the budget it was given — everything
+     * in {@link views_spent} except the directionals, which are refreshed unconditionally and so
+     * never compete for the pool. This is what the budget bounds and what the caller's carry-over
+     * is measured against.
+     * @type {number}
+     */
+    views_spent_budgeted: number;
     /**
      * True when the most recent {@link select} left at least one in-view candidate unrefreshed
      * because the pool could not cover its view cost. Drives the caller's carry-over: unused
@@ -54,8 +62,10 @@ export class ShadowmapDrawSelector {
      *
      *   - **Directional** — always refreshes. Scores Infinity, so it would head the ordering
      *     anyway; it is settled during the scoring pass instead of being pushed onto the heap
-     *     because the outcome cannot depend on where it lands. Its view cost is still charged, so
-     *     local lights see a reduced pool.
+     *     because the outcome cannot depend on where it lands. Its view cost counts towards
+     *     {@link views_spent} but NOT towards {@link views_spent_budgeted}: it cannot be refused,
+     *     so charging it against the pool the local lights compete for can only shrink that pool,
+     *     and once the directionals' fixed cost met the budget it shrank it to nothing, for good.
      *   - **Local, off-screen** (`projected_area_px <= 0`) — skipped entirely. Not demand, and not
      *     carry-over fuel: the map keeps its flags and springs back when it returns to view.
      *   - **Local, in-view, invalid** — must draw. `is_invalid` means the committed layout has

package/src/shade/renderer/shadow/map/ShadowmapDrawSelector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadowmapDrawSelector.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/ShadowmapDrawSelector.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACI;;;;OAIG;IACH,UAFU,WAAW,CAEP;IAEd;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,sBAFU,OAAO,CAEY;IAsC7B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,mBALW,WAAW,eAEX,MAAM,gBACN,MAAM,QA+EhB;;CACJ"}
+{"version":3,"file":"ShadowmapDrawSelector.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/ShadowmapDrawSelector.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACI;;;;OAIG;IACH,UAFU,WAAW,CAEP;IAEd;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;;OAMG;IACH,sBAFU,MAAM,CAES;IAEzB;;;;;OAKG;IACH,sBAFU,OAAO,CAEY;IAsC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,mBALW,WAAW,eAEX,MAAM,gBACN,MAAM,QAkFhB;;CACJ"}

package/src/shade/renderer/shadow/map/ShadowmapDrawSelector.js

@@ -1,196 +1,210 @@
-import { IndexedFloatMaxHeap } from "../../../../core/collection/heap/IndexedFloatMaxHeap.js";
-import { compute_shadowmap_update_score } from "./shadowmap_update_score.js";
-
-/**
- * Picks which shadowmaps get rasterized this frame, given a view budget.
- *
- * This is the score-and-select half of {@link GPUSceneShadowmapContext.select_for_draw}, split out
- * so it can be measured without a GPU device — the scoring is arithmetic over plain fields, and
- * the only reason it used to need a renderer was that it lived on the class that owns the atlas.
- *
- * **Why a heap and not a sort.** The budget is a handful of views and a scene can hold hundreds of
- * candidates, so a full ordering is thrown away almost entirely: it sorts N to consume ~K. Popping
- * a max-heap K times is O(N + K log N) against the sort's O(N log N), and skips the N `{map,
- * score}` objects the sorted version allocated every frame. Measured at 512 lights: 30us per frame
- * for the sort, 2.6us for the heap. Removing just the allocation and keeping the sort gets 8.3us,
- * so roughly a third of the win is the allocation and the rest is not ordering the tail. See
- * benchmark/select.spec.js.
- *
- * **Ordering is load-bearing, so the heap is drained in score order rather than partitioned.**
- * A map that has never been drawn must refresh whether or not the budget can cover it, but WHEN it
- * charges its views against the pool decides whether a lower-priority map still fits. Settling all
- * the must-draws up front would be cheaper and would change which maps draw, so they compete in
- * the same ordered drain as everything else.
- *
- * **Ties resolve differently than a sort.** `Array.sort` is stable, so equal scores kept array
- * order; a heap has no such guarantee, and it compares float32 where the sort compared float64.
- * Maps with equal scores are interchangeable by construction — the scorer is the definition of
- * which map deserves the slot, and it rated them the same — so what the benchmark asserts is that
- * the selection is equally good (same view spend, same carry-over signal, same multiset of
- * selected scores), not that it is the same maps. Ties are common rather than exotic here: every
- * light the camera sits inside reports the full viewport as its projected area.
- */
-export class ShadowmapDrawSelector {
-    /**
-     * Maps chosen by the most recent {@link select}, in the order they were selected. Reused
-     * across frames — read it before the next call, don't retain it.
-     * @type {Shadowmap[]}
-     */
-    selected = [];
-
-    /**
-     * Views the most recent {@link select} committed, counting must-draws that bypassed the
-     * budget. Can exceed the budget it was given.
-     * @type {number}
-     */
-    views_spent = 0;
-
-    /**
-     * True when the most recent {@link select} left at least one in-view candidate unrefreshed
-     * because the pool could not cover its view cost. Drives the caller's carry-over: unused
-     * budget is only worth carrying forward when there was demand it could not meet.
-     * @type {boolean}
-     */
-    had_unfit_candidates = false;
-
-    /**
-     * Heap of budget candidates, keyed by index into the shadowmap array the current
-     * {@link select} was handed. Held across frames so the id table and slot storage are
-     * allocated once rather than per frame.
-     * @type {IndexedFloatMaxHeap}
-     */
-    #heap = new IndexedFloatMaxHeap(0);
-
-    /**
-     * Id capacity of {@link #heap}. Ids are shadowmap array indices, so this has to cover the
-     * largest map count seen so far.
-     * @type {number}
-     */
-    #heap_capacity = 0;
-
-    /**
-     * Resize the heap to hold ids up to `count`. IndexedFloatMaxHeap sizes its id table at
-     * construction, so growing means a new heap — safe here because the heap is empty between
-     * frames and carries nothing worth migrating.
-     *
-     * Rounded up to a power of two so a scene that gains lights one at a time reallocates a
-     * handful of times rather than every frame.
-     *
-     * @param {number} count
-     */
-    #ensure_capacity(count) {
-        if (count <= this.#heap_capacity) {
-            return;
-        }
-
-        const capacity = Math.max(64, 1 << (32 - Math.clz32(count - 1)));
-
-        this.#heap = new IndexedFloatMaxHeap(capacity);
-        this.#heap_capacity = capacity;
-    }
-
-    /**
-     * Score every shadowmap and mark the winners with `should_draw`.
-     *
-     * Categories, in the order the drain encounters them:
-     *
-     *   - **Directional** — always refreshes. Scores Infinity, so it would head the ordering
-     *     anyway; it is settled during the scoring pass instead of being pushed onto the heap
-     *     because the outcome cannot depend on where it lands. Its view cost is still charged, so
-     *     local lights see a reduced pool.
-     *   - **Local, off-screen** (`projected_area_px <= 0`) — skipped entirely. Not demand, and not
-     *     carry-over fuel: the map keeps its flags and springs back when it returns to view.
-     *   - **Local, in-view, invalid** — must draw. `is_invalid` means the committed layout has
-     *     never held valid depth, so sampling it would show garbage. Bypasses the budget but is
-     *     visited in score order, because its charge against the pool is what decides whether the
-     *     candidates below it still fit.
-     *   - **Local, in-view, valid** — competes for what is left, highest score first.
-     *
-     * Results land on {@link selected}, {@link views_spent} and {@link had_unfit_candidates}.
-     * `map.update()` is deliberately NOT called here — that needs the camera and the scene, and
-     * keeping it out is what keeps this side GPU-free. The caller walks {@link selected}.
-     *
-     * @param {Shadowmap[]} shadowmaps every map in the scene; `projected_area_px` must already be
-     *        current for this frame
-     * @param {number} frame_index monotonically increasing frame counter, used for staleness
-     * @param {number} budget_total views available this frame, including any carry-over
-     */
-    select(shadowmaps, frame_index, budget_total) {
-        const n = shadowmaps.length;
-
-        const selected = this.selected;
-        selected.length = 0;
-
-        let views_spent = 0;
-        let had_unfit_candidates = false;
-
-        this.#ensure_capacity(n);
-
-        const heap = this.#heap;
-        heap.clear();
-
-        // Number of must-draw maps still in the heap. Tracked rather than looked for, because it
-        // is the only thing that can stop the drain from exiting early — see below.
-        let invalid_in_heap = 0;
-
-        for (let i = 0; i < n; i++) {
-            const map = shadowmaps[i];
-
-            map.should_draw = false;
-
-            if (map.light.isDirectionalLight) {
-                map.should_draw = true;
-                selected.push(map);
-                views_spent += map.views.length;
-                continue;
-            }
-
-            if (map.projected_area_px <= 0) {
-                continue;
-            }
-
-            if (map.is_invalid) {
-                invalid_in_heap++;
-            }
-
-            heap.insert(i, compute_shadowmap_update_score(map, frame_index));
-        }
-
-        while (heap.size > 0) {
-            // Every map costs at least one view, so once the pool is gone nothing left can fit and
-            // the remainder are unfit by definition — provided none of them is a must-draw, which
-            // would have to be visited regardless. In steady state there are none (`is_invalid` is
-            // cleared by the first successful raster) and this fires after about `budget_total`
-            // pops, which is what bounds K. During a cold start it degrades to a full drain, i.e.
-            // to a heapsort, still ahead of the comparator sort it replaced.
-            if (views_spent >= budget_total && invalid_in_heap === 0) {
-                had_unfit_candidates = true;
-                break;
-            }
-
-            const map = shadowmaps[heap.pop_max()];
-            const cost = map.views.length;
-
-            if (map.is_invalid) {
-                invalid_in_heap--;
-                map.should_draw = true;
-                selected.push(map);
-                views_spent += cost;
-                continue;
-            }
-
-            if (views_spent + cost <= budget_total) {
-                map.should_draw = true;
-                selected.push(map);
-                views_spent += cost;
-            } else {
-                // Wanted to refresh but the pool could not cover its view cost. Keep going — a
-                // cheaper candidate further down may still fit.
-                had_unfit_candidates = true;
-            }
-        }
-
-        this.views_spent = views_spent;
-        this.had_unfit_candidates = had_unfit_candidates;
-    }
-}
+import { IndexedFloatMaxHeap } from "../../../../core/collection/heap/IndexedFloatMaxHeap.js";
+import { compute_shadowmap_update_score } from "./shadowmap_update_score.js";
+
+/**
+ * Picks which shadowmaps get rasterized this frame, given a view budget.
+ *
+ * This is the score-and-select half of {@link GPUSceneShadowmapContext.select_for_draw}, split out
+ * so it can be measured without a GPU device — the scoring is arithmetic over plain fields, and
+ * the only reason it used to need a renderer was that it lived on the class that owns the atlas.
+ *
+ * **Why a heap and not a sort.** The budget is a handful of views and a scene can hold hundreds of
+ * candidates, so a full ordering is thrown away almost entirely: it sorts N to consume ~K. Popping
+ * a max-heap K times is O(N + K log N) against the sort's O(N log N), and skips the N `{map,
+ * score}` objects the sorted version allocated every frame. Measured at 512 lights: 30us per frame
+ * for the sort, 2.6us for the heap. Removing just the allocation and keeping the sort gets 8.3us,
+ * so roughly a third of the win is the allocation and the rest is not ordering the tail. See
+ * benchmark/select.spec.js.
+ *
+ * **Ordering is load-bearing, so the heap is drained in score order rather than partitioned.**
+ * A map that has never been drawn must refresh whether or not the budget can cover it, but WHEN it
+ * charges its views against the pool decides whether a lower-priority map still fits. Settling all
+ * the must-draws up front would be cheaper and would change which maps draw, so they compete in
+ * the same ordered drain as everything else.
+ *
+ * **Ties resolve differently than a sort.** `Array.sort` is stable, so equal scores kept array
+ * order; a heap has no such guarantee, and it compares float32 where the sort compared float64.
+ * Maps with equal scores are interchangeable by construction — the scorer is the definition of
+ * which map deserves the slot, and it rated them the same — so what the benchmark asserts is that
+ * the selection is equally good (same view spend, same carry-over signal, same multiset of
+ * selected scores), not that it is the same maps. Ties are common rather than exotic here: every
+ * light the camera sits inside reports the full viewport as its projected area.
+ */
+export class ShadowmapDrawSelector {
+    /**
+     * Maps chosen by the most recent {@link select}, in the order they were selected. Reused
+     * across frames — read it before the next call, don't retain it.
+     * @type {Shadowmap[]}
+     */
+    selected = [];
+
+    /**
+     * Views the most recent {@link select} committed, counting must-draws that bypassed the
+     * budget. Can exceed the budget it was given.
+     * @type {number}
+     */
+    views_spent = 0;
+
+    /**
+     * Views the most recent {@link select} committed out of the budget it was given — everything
+     * in {@link views_spent} except the directionals, which are refreshed unconditionally and so
+     * never compete for the pool. This is what the budget bounds and what the caller's carry-over
+     * is measured against.
+     * @type {number}
+     */
+    views_spent_budgeted = 0;
+
+    /**
+     * True when the most recent {@link select} left at least one in-view candidate unrefreshed
+     * because the pool could not cover its view cost. Drives the caller's carry-over: unused
+     * budget is only worth carrying forward when there was demand it could not meet.
+     * @type {boolean}
+     */
+    had_unfit_candidates = false;
+
+    /**
+     * Heap of budget candidates, keyed by index into the shadowmap array the current
+     * {@link select} was handed. Held across frames so the id table and slot storage are
+     * allocated once rather than per frame.
+     * @type {IndexedFloatMaxHeap}
+     */
+    #heap = new IndexedFloatMaxHeap(0);
+
+    /**
+     * Id capacity of {@link #heap}. Ids are shadowmap array indices, so this has to cover the
+     * largest map count seen so far.
+     * @type {number}
+     */
+    #heap_capacity = 0;
+
+    /**
+     * Resize the heap to hold ids up to `count`. IndexedFloatMaxHeap sizes its id table at
+     * construction, so growing means a new heap — safe here because the heap is empty between
+     * frames and carries nothing worth migrating.
+     *
+     * Rounded up to a power of two so a scene that gains lights one at a time reallocates a
+     * handful of times rather than every frame.
+     *
+     * @param {number} count
+     */
+    #ensure_capacity(count) {
+        if (count <= this.#heap_capacity) {
+            return;
+        }
+
+        const capacity = Math.max(64, 1 << (32 - Math.clz32(count - 1)));
+
+        this.#heap = new IndexedFloatMaxHeap(capacity);
+        this.#heap_capacity = capacity;
+    }
+
+    /**
+     * Score every shadowmap and mark the winners with `should_draw`.
+     *
+     * Categories, in the order the drain encounters them:
+     *
+     *   - **Directional** — always refreshes. Scores Infinity, so it would head the ordering
+     *     anyway; it is settled during the scoring pass instead of being pushed onto the heap
+     *     because the outcome cannot depend on where it lands. Its view cost counts towards
+     *     {@link views_spent} but NOT towards {@link views_spent_budgeted}: it cannot be refused,
+     *     so charging it against the pool the local lights compete for can only shrink that pool,
+     *     and once the directionals' fixed cost met the budget it shrank it to nothing, for good.
+     *   - **Local, off-screen** (`projected_area_px <= 0`) — skipped entirely. Not demand, and not
+     *     carry-over fuel: the map keeps its flags and springs back when it returns to view.
+     *   - **Local, in-view, invalid** — must draw. `is_invalid` means the committed layout has
+     *     never held valid depth, so sampling it would show garbage. Bypasses the budget but is
+     *     visited in score order, because its charge against the pool is what decides whether the
+     *     candidates below it still fit.
+     *   - **Local, in-view, valid** — competes for what is left, highest score first.
+     *
+     * Results land on {@link selected}, {@link views_spent} and {@link had_unfit_candidates}.
+     * `map.update()` is deliberately NOT called here — that needs the camera and the scene, and
+     * keeping it out is what keeps this side GPU-free. The caller walks {@link selected}.
+     *
+     * @param {Shadowmap[]} shadowmaps every map in the scene; `projected_area_px` must already be
+     *        current for this frame
+     * @param {number} frame_index monotonically increasing frame counter, used for staleness
+     * @param {number} budget_total views available this frame, including any carry-over
+     */
+    select(shadowmaps, frame_index, budget_total) {
+        const n = shadowmaps.length;
+
+        const selected = this.selected;
+        selected.length = 0;
+
+        let views_spent = 0;
+        let views_spent_mandatory = 0;
+        let had_unfit_candidates = false;
+
+        this.#ensure_capacity(n);
+
+        const heap = this.#heap;
+        heap.clear();
+
+        // Number of must-draw maps still in the heap. Tracked rather than looked for, because it
+        // is the only thing that can stop the drain from exiting early — see below.
+        let invalid_in_heap = 0;
+
+        for (let i = 0; i < n; i++) {
+            const map = shadowmaps[i];
+
+            map.should_draw = false;
+
+            if (map.light.isDirectionalLight) {
+                map.should_draw = true;
+                selected.push(map);
+                views_spent += map.views.length;
+                views_spent_mandatory += map.views.length;
+                continue;
+            }
+
+            if (map.projected_area_px <= 0) {
+                continue;
+            }
+
+            if (map.is_invalid) {
+                invalid_in_heap++;
+            }
+
+            heap.insert(i, compute_shadowmap_update_score(map, frame_index));
+        }
+
+        while (heap.size > 0) {
+            // Every map costs at least one view, so once the pool is gone nothing left can fit and
+            // the remainder are unfit by definition — provided none of them is a must-draw, which
+            // would have to be visited regardless. In steady state there are none (`is_invalid` is
+            // cleared by the first successful raster) and this fires after about `budget_total`
+            // pops, which is what bounds K. During a cold start it degrades to a full drain, i.e.
+            // to a heapsort, still ahead of the comparator sort it replaced.
+            if (views_spent - views_spent_mandatory >= budget_total && invalid_in_heap === 0) {
+                had_unfit_candidates = true;
+                break;
+            }
+
+            const map = shadowmaps[heap.pop_max()];
+            const cost = map.views.length;
+
+            if (map.is_invalid) {
+                invalid_in_heap--;
+                map.should_draw = true;
+                selected.push(map);
+                views_spent += cost;
+                continue;
+            }
+
+            if (views_spent - views_spent_mandatory + cost <= budget_total) {
+                map.should_draw = true;
+                selected.push(map);
+                views_spent += cost;
+            } else {
+                // Wanted to refresh but the pool could not cover its view cost. Keep going — a
+                // cheaper candidate further down may still fit.
+                had_unfit_candidates = true;
+            }
+        }
+
+        this.views_spent = views_spent;
+        this.views_spent_budgeted = views_spent - views_spent_mandatory;
+        this.had_unfit_candidates = had_unfit_candidates;
+    }
+}

package/src/shade/renderer/shadow/map/csm/shader/shader_csm_caster_range.d.ts

@@ -25,9 +25,16 @@ export const CSM_CASTER_RANGE_PUBLISH_STRUCT: WebGPUStruct;
  *
  * The test per cascade is the one the tree walk made: a box survives the four fixed side planes if
  * its corner furthest along each plane's normal is inside; the plane a survivor pushes is the
- * near one, to the box corner nearest along the light's axis. Per-thread CAS minimum rather than
- * a subgroup reduction first, because a scene has hundreds of rows and three cascades, and the
- * same CAS helper already bounds the skinned meshes.
+ * near one, to the box corner nearest along the light's axis.
+ *
+ * **The subgroup reduces first, and one lane merges what it found.** Every row inside a cascade
+ * merges into the same word, so a CAS per row queues every caster in the scene on three words: on
+ * an RTX 4090 that measured ~240 µs a frame at 200k rows, ~800 µs at 2M, and 3.3 ms on Caldera at
+ * 2M placements — more than the four views' instance culls together. Reduced per subgroup, 2M rows
+ * take 161 µs, which is also what the pass takes with every atomic deleted; a workgroup step
+ * through shared memory measured the same, so there is none. A lane with no row, and a row outside
+ * the cascade, reduce with {@link CSM_CASTER_RANGE_UNKNOWN} instead of returning, because every
+ * lane has to reach the reduction.
  *
  * Dispatch with {@link GPUTypedTable#dispatch_group_count} of the `meshes` table at
  * {@link CSM_CASTER_RANGE_WORKGROUP_SIZE}, once per directional shadow map being drawn.

package/src/shade/renderer/shadow/map/csm/shader/shader_csm_caster_range.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_csm_caster_range.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shadow/map/csm/shader/shader_csm_caster_range.js"],"names":[],"mappings":"AAaA,qDAAiF;AAEjF;;;;;GAKG;AACH,+CAFU,YAAY,CAmBc;AAEpC;;;;GAIG;AACH,8CAFU,YAAY,CAQa;AAenC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iDAFU,aAAa,CA2DpB;AAUH;;;;;;;GAOG;AACH,8CAFU,aAAa,CAgCpB;6BA/L0B,yCAAyC;8BAGxC,qCAAqC"}
+{"version":3,"file":"shader_csm_caster_range.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shadow/map/csm/shader/shader_csm_caster_range.js"],"names":[],"mappings":"AAcA,qDAAiF;AAEjF;;;;;GAKG;AACH,+CAFU,YAAY,CAmBc;AAEpC;;;;GAIG;AACH,8CAFU,YAAY,CAQa;AAqFnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iDAFU,aAAa,CAMpB;AAUH;;;;;;;GAOG;AACH,8CAFU,aAAa,CAgCpB;6BAvN0B,yCAAyC;8BAGxC,qCAAqC"}