@woosh/meep-engine 3.57.0 → 3.59.0

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

@@ -57,6 +57,7 @@ import {
     shader_shadowmap_remap_tetrahedron_to_octahedral
 } from "./shader/shader_shadowmap_remap_tetrahedron_to_octahedral.js";
 import { SHADOWMAP_ATLAS_BORDER } from "./SHADOWMAP_ATLAS_BORDER.js";
+import { SHADOWMAP_PATCH_MIN_SIDE } from "./SHADOWMAP_PATCH_MIN_SIDE.js";
 import { TetrahedronPointLightShadowmap } from "./TetrahedronPointLightShadowmap.js";
 import { compute_light_projected_area_px } from "./shadowmap_update_score.js";
 import { ShadowmapDrawSelector } from "./ShadowmapDrawSelector.js";
@@ -65,9 +66,11 @@ import { ShadowmapResolutionPolicy } from "./ShadowmapResolutionPolicy.js";
 import { SpotLightShadowmap } from "./SpotLightShadowmap.js";
 import { DEFAULT_VSM_FIRST_TEXEL_SIZE } from "../vsm/DEFAULT_VSM_FIRST_TEXEL_SIZE.js";
 import { DEFAULT_VSM_PAGE_BUDGET } from "../vsm/DEFAULT_VSM_PAGE_BUDGET.js";
+import { DEFAULT_VSM_LOW_LOAD_FACTOR } from "../vsm/DEFAULT_VSM_LOW_LOAD_FACTOR.js";
+import { DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS } from "../vsm/DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.js";
+import { DEFAULT_VSM_MAX_LOAD_FACTOR } from "../vsm/DEFAULT_VSM_MAX_LOAD_FACTOR.js";
 import { graph_vsm_feedback } from "../vsm/graph_vsm_feedback.js";
 import { VirtualShadowMap } from "../vsm/VirtualShadowMap.js";
-import { VSMMoverTracker } from "../vsm/VSMMoverTracker.js";
 import { VSM_DEFAULT_REQUEST_CAPACITY } from "../vsm/VSM_FEEDBACK_LAYOUT.js";
 import { VSM_SLOT_EMPTY } from "../vsm/VSM_SLOT_STRUCT.js";
 
@@ -82,6 +85,11 @@ import { VSM_SLOT_EMPTY } from "../vsm/VSM_SLOT_STRUCT.js";
  * @typedef {import("../../buffer/table/serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
  */
 
+/**
+ * Side the shadow atlas starts at, or the device's largest texture when that is smaller. A patch
+ * that does not fit grows it, up to that largest texture ({@link GPUSceneShadowmapContext.bind}).
+ * @type {number}
+ */
 const DEFAULT_SHADOWMAP_ATLAS_RESOLUTION = 4096;
 
 /**
@@ -275,6 +283,87 @@ export class GPUSceneShadowmapContext {
      */
     virtual_lod_bias = 0;
 
+    /**
+     * High-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` above which a
+     * virtual shadow map steps its dynamic LOD bias up (`0` disables dynamic throttling). See
+     * {@link DEFAULT_VSM_MAX_LOAD_FACTOR}.
+     * @type {number}
+     */
+    #virtual_max_load_factor = DEFAULT_VSM_MAX_LOAD_FACTOR;
+
+    /**
+     * @returns {number}
+     */
+    get virtual_max_load_factor() {
+        return this.#virtual_max_load_factor;
+    }
+
+    /**
+     * Pushed from {@link Renderer.shadow_virtual_max_load_factor} each frame.
+     *
+     * @param {number} v in `[0, 1]`; `0` disables dynamic throttling
+     */
+    set virtual_max_load_factor(v) {
+        assert.isNumber(v, 'virtual_max_load_factor');
+        assert.greaterThanOrEqual(v, 0, 'virtual_max_load_factor');
+        assert.lessThanOrEqual(v, 1, 'virtual_max_load_factor');
+
+        this.#virtual_max_load_factor = v;
+    }
+
+    /**
+     * Low-watermark pool demand ratio below which a virtual shadow map's dynamic LOD bias steps
+     * back down toward zero. See {@link DEFAULT_VSM_LOW_LOAD_FACTOR}.
+     * @type {number}
+     */
+    #virtual_low_load_factor = DEFAULT_VSM_LOW_LOAD_FACTOR;
+
+    /**
+     * @returns {number}
+     */
+    get virtual_low_load_factor() {
+        return this.#virtual_low_load_factor;
+    }
+
+    /**
+     * Pushed from {@link Renderer.shadow_virtual_low_load_factor} each frame.
+     *
+     * @param {number} v in `[0, 1]`
+     */
+    set virtual_low_load_factor(v) {
+        assert.isNumber(v, 'virtual_low_load_factor');
+        assert.greaterThanOrEqual(v, 0, 'virtual_low_load_factor');
+        assert.lessThanOrEqual(v, 1, 'virtual_low_load_factor');
+
+        this.#virtual_low_load_factor = v;
+    }
+
+    /**
+     * Maximum dynamic LOD bias a virtual shadow map may add under pool pressure (`0` disables
+     * dynamic throttling). See {@link DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS}.
+     * @type {number}
+     */
+    #virtual_max_dynamic_lod_bias = DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS;
+
+    /**
+     * @returns {number}
+     */
+    get virtual_max_dynamic_lod_bias() {
+        return this.#virtual_max_dynamic_lod_bias;
+    }
+
+    /**
+     * Pushed from {@link Renderer.shadow_virtual_max_dynamic_lod_bias} each frame.
+     *
+     * @param {number} v non-negative; `0` disables dynamic throttling
+     */
+    set virtual_max_dynamic_lod_bias(v) {
+        assert.isNumber(v, 'virtual_max_dynamic_lod_bias');
+        assert.greaterThanOrEqual(v, 0, 'virtual_max_dynamic_lod_bias');
+
+        this.#virtual_max_dynamic_lod_bias = v;
+    }
+
     /**
      * World size of a virtual shadow map's level-0 texel. See {@link virtual_first_texel_size}.
      * @type {number}
@@ -430,13 +519,6 @@ export class GPUSceneShadowmapContext {
     #virtual_slot_record = { level: 0, x: 0, y: 0 };
     #virtual_level_record = [0, 0];
 
-    /**
-     * Where the scene's casters were last frame, for the virtual shadow maps' mover pass. Made on the
-     * first frame a virtual map asks for feedback.
-     * @type {VSMMoverTracker|null}
-     */
-    #vsm_movers = null;
-
     /**
      * Which virtual map's turn it is to take the first of the page budget's remainder; advanced by
      * every {@link select_for_draw}.
@@ -792,17 +874,19 @@ export class GPUSceneShadowmapContext {
     }
 
     /**
-     * Record this frame's virtual shadow map feedback — the casters that moved, the pages they made
-     * stale, the pages the view's pixels ask for — into the frame's `Shading` graph once the main
-     * view's depth exists, and read it back for the maps' next frames. Does nothing in a scene
-     * without virtual shadow maps. See {@link graph_vsm_feedback}.
+     * Record this frame's virtual shadow map feedback — the pages the scene's movers made stale, the
+     * pages the view's pixels ask for — into the frame's `Shading` graph once the main view's depth
+     * exists, and read it back for the maps' next frames. Does nothing in a scene without virtual
+     * shadow maps, and then reads nothing of `movers`. See {@link graph_vsm_feedback}.
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
      * @param {import("../../view/GPUViewContext.js").GPUViewContext} options.view the main view
      * @param {number} options.depth graph handle of the main view's depth
+     * @param {number} options.movers graph handle of the scene's mover list this frame
+     *     ({@link GPUSceneContext#graph_movers})
      */
-    graph_virtual_feedback({ graph, view, depth }) {
+    graph_virtual_feedback({ graph, view, depth, movers }) {
         const maps = this.#vsm_feedback_maps;
         const all = this.#registry.maps;
 
@@ -815,25 +899,16 @@ export class GPUSceneShadowmapContext {
         }
 
         if (maps.length === 0) {
-            // no virtual map to feed: the casters' memory goes, and starts afresh with the next map
-            if (this.#vsm_movers !== null) {
-                this.#vsm_movers.destroy();
-                this.#vsm_movers = null;
-            }
-
+            // no virtual map to feed
             return;
         }
 
-        if (this.#vsm_movers === null) {
-            this.#vsm_movers = new VSMMoverTracker(this.#graphics.device);
-        }
-
         graph_vsm_feedback({
             graph,
             view,
             depth,
             maps,
-            tracker: this.#vsm_movers,
+            movers,
             light_database: this.#owner.database,
         });
 
@@ -1056,9 +1131,9 @@ export class GPUSceneShadowmapContext {
      *          frame's spend but not charged against the budget the local lights compete for.
      *        - **Local, off-screen** (`projected_area_px <= 0`) → skipped entirely.
      *        - **Local, in-view, invalid** → MUST draw. `is_invalid` means the committed layout
-     *          has never held valid depth (freshly created map); sampling it would display
-     *          garbage, so we bypass the budget. Resizes no longer invalidate under the dual-
-     *          layout model — this flag fires only on first-draw.
+     *          holds no valid depth — a map not yet drawn, or every map after the atlas grew
+     *          into a new texture; sampling it would display garbage, so we bypass the budget.
+     *          Resizes do not invalidate under the dual-layout model.
      *        - **Local, in-view, valid** → compete for the remaining budget by score. Ordering
      *          is descending score so the most important (largest-on-screen, stalest) maps win.
      *  5. **Fit the winners.** `map.update()` on each selected map, so its projection matrices
@@ -1134,6 +1209,9 @@ export class GPUSceneShadowmapContext {
                 // what its update works with this frame
                 m.page_budget = share + (turn < remainder ? 1 : 0);
                 m.lod_bias = this.virtual_lod_bias;
+                m.max_load_factor = this.#virtual_max_load_factor;
+                m.low_load_factor = this.#virtual_low_load_factor;
+                m.max_lod_bias = this.#virtual_max_dynamic_lod_bias;
                 m.view_height = view_resolution[1];
 
                 k++;
@@ -1499,7 +1577,9 @@ export class GPUSceneShadowmapContext {
          *
          * 0% error -> 1
          * 1% error -> 0.915
-         * 5% error -> 0.81299
+         * 2% error -> 0.880
+         * 3% error -> 0.854
+         * 5% error -> 0.813
          * 10% error -> 0.739
          * 20% error -> 0.639
          * 30% error -> 0.565
@@ -1508,7 +1588,7 @@ export class GPUSceneShadowmapContext {
          *
          * @type {number}
          */
-        const CUBE_MAPPING_RESOLUTION_SCALE = 1;
+        const CUBE_MAPPING_RESOLUTION_SCALE = 0.880;
 
         const cube_face_resolution = Math.ceil(octahedral_resolution * CUBE_MAPPING_RESOLUTION_SCALE);
 
@@ -1827,12 +1907,7 @@ export class GPUSceneShadowmapContext {
         for (let j = 0; j < map.layout.length; j++) {
             this.atlas.remove(map.layout[j]);
         }
-        if (map.pending_layout !== null) {
-            for (let j = 0; j < map.pending_layout.length; j++) {
-                this.atlas.remove(map.pending_layout[j]);
-            }
-            map.pending_layout = null;
-        }
+        this.#resolution_policy.release_pending(map);
 
         // free the per-view/-camera GPU contexts — without this an evicted map's buffers leak
         this.#release_map_gpu_contexts(map);
@@ -2015,13 +2090,14 @@ export class GPUSceneShadowmapContext {
         };
 
         const add_virtual = (light) => {
-            // the pool: as many whole slots as fit the default pool, or the atlas when it is smaller
+            // the pool: as many whole slots as fit the default pool, or the largest atlas the device
+            // can hold when that is smaller; bind grows the atlas for it, or shrinks it by whole slots
             const slot_size = VSM_PAGE_SIZE + 2 * SHADOWMAP_ATLAS_BORDER;
-            const pool_side = Math.floor(Math.min(VSM_POOL_SIZE, this.atlas.size.x, this.atlas.size.y) / slot_size) * slot_size;
+            const pool_side = Math.floor(Math.min(VSM_POOL_SIZE, this.#graphics.device.limits.maxTextureDimension2D) / slot_size) * slot_size;
 
             // the pool first: an atlas without room for it throws here, every frame the sun is
             // retried, and the map's page bookkeeping — megabytes — is not built for nothing
-            const pool = this.bind(pool_side);
+            const pool = this.bind(pool_side, slot_size);
 
             let map;
 
@@ -2032,7 +2108,7 @@ export class GPUSceneShadowmapContext {
                     first_texel_size,
                     page_size: VSM_PAGE_SIZE,
                     border: SHADOWMAP_ATLAS_BORDER,
-                    pool_size: pool_side,
+                    pool_size: pool.width,
                     request_capacity: VSM_DEFAULT_REQUEST_CAPACITY,
                     protect_frames: VSM_PROTECT_FRAMES,
                     depth_extent: VSM_DEPTH_EXTENT,
@@ -2177,19 +2253,85 @@ export class GPUSceneShadowmapContext {
     }
 
     /**
+     * Place a square patch of `resolution` texels in the atlas. When it does not fit: first the
+     * room pending resizes hold is given back, then the atlas grows, and only when it is as large
+     * as the device allows is the patch shrunk, halving and kept to whole multiples of `step`,
+     * down to {@link SHADOWMAP_PATCH_MIN_SIDE}.
      *
-     * @param {number} resolution
-     * @returns {AABB2}
+     * @param {number} resolution side the patch asks for
+     * @param {number} [step] texels the side must be a multiple of
+     * @returns {AABB2} the patch placed, `resolution` or smaller on a side
+     * @throws {Error} when not even the smallest patch fits
      */
-    bind(resolution) {
+    bind(resolution, step = 1) {
+        const floor = Math.max(step, SHADOWMAP_PATCH_MIN_SIDE);
 
-        const rect = new AABB2(0, 0, resolution, resolution);
+        for (let side = resolution; side >= floor; side = Math.floor(side / (2 * step)) * step) {
+            const rect = new AABB2(0, 0, side, side);
 
-        if (!this.atlas.add(rect)) {
-            throw new Error(`Failed to add shadowmap to atlas`);
+            if (this.#make_room(rect)) {
+                return rect;
+            }
         }
 
-        return rect;
+        throw new Error(`Failed to add shadowmap to atlas`);
+    }
+
+    /**
+     * Add `rect` to the atlas, making room for it if it does not fit: the pending resizes'
+     * reservations go back first, as nothing samples them, then the atlas doubles, up to the
+     * device's largest texture.
+     *
+     * @param {AABB2} rect
+     * @returns {boolean} whether it was placed
+     */
+    #make_room(rect) {
+        const atlas = this.atlas;
+
+        if (atlas.add(rect)) {
+            return true;
+        }
+
+        if (this.#resolution_policy.release_all_pending(this.#registry.maps) && atlas.add(rect)) {
+            return true;
+        }
+
+        // the atlas is square, packer and texture alike
+        const limit = this.#graphics.device.limits.maxTextureDimension2D;
+
+        while (atlas.size.x < limit) {
+            this.#grow_atlas(Math.min(limit, atlas.size.x * 2));
+
+            if (atlas.add(rect)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Make the atlas `side` texels square, packer and texture. Every patch keeps its place, but the
+     * new texture holds no depth, so every map is drawn again before it is sampled and every
+     * virtual map gives its pages back.
+     *
+     * @param {number} side
+     */
+    #grow_atlas(side) {
+        this.atlas.resize(side, side);
+        this.texture.resize(side, side);
+
+        const maps = this.#registry.maps;
+
+        for (let i = 0; i < maps.length; i++) {
+            const map = maps[i];
+
+            map.is_invalid = true;
+
+            if (map.isVirtualShadowMap === true) {
+                map.manager.evict_all();
+            }
+        }
     }
 
     destroy() {
@@ -2198,11 +2340,6 @@ export class GPUSceneShadowmapContext {
             this.#caster_scratch = null;
         }
 
-        if (this.#vsm_movers !== null) {
-            this.#vsm_movers.destroy();
-            this.#vsm_movers = null;
-        }
-
         this.texture.destroy();
 
         const maps = this.#registry.maps;

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

@@ -0,0 +1,8 @@
+/**
+ * Smallest side, in texels, of a patch of the shadow atlas: below it a shadow is too blocky to be
+ * worth drawing. The resolution policy sizes no local light below it, and the shadow context
+ * shrinks no patch below it when the atlas is as large as the device allows.
+ * @type {number}
+ */
+export const SHADOWMAP_PATCH_MIN_SIDE: number;
+//# sourceMappingURL=SHADOWMAP_PATCH_MIN_SIDE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SHADOWMAP_PATCH_MIN_SIDE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/SHADOWMAP_PATCH_MIN_SIDE.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,uCAFU,MAAM,CAE2B"}

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

@@ -0,0 +1,7 @@
+/**
+ * Smallest side, in texels, of a patch of the shadow atlas: below it a shadow is too blocky to be
+ * worth drawing. The resolution policy sizes no local light below it, and the shadow context
+ * shrinks no patch below it when the atlas is as large as the device allows.
+ * @type {number}
+ */
+export const SHADOWMAP_PATCH_MIN_SIDE = 32;

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

@@ -76,17 +76,17 @@ export class Shadowmap {
      */
     last_resize_frame_index: number;
     /**
-     * True when the atlas region backing `layout` has never held valid depth for this map.
+     * True when the atlas region backing `layout` holds no valid depth for this map.
      * Initialised to true at construction (the newly-bound atlas rect contains garbage from a
-     * prior tenant or uninitialised texture memory); cleared by the draw loop after a
-     * successful raster.
+     * prior tenant or uninitialised texture memory), set again on every map when the atlas grows
+     * into a new texture, and cleared by the draw loop after a successful raster.
      *
      * Under the dual-layout model, resizes do NOT set this flag — a pending reservation
      * transitions to the committed layout only when an actual raster runs, so the committed
-     * region always holds last-drawn depth except on a freshly-created map. That keeps the
-     * "invalid + in-view MUST-draw" bypass in {@link GPUSceneShadowmapContext.select_for_draw}
-     * focused purely on "new map catching up" rather than on forced refreshes that drove the
-     * earlier 8/34 dispatch oscillation.
+     * region always holds last-drawn depth except on a freshly-created map or a grown atlas. That
+     * keeps the "invalid + in-view MUST-draw" bypass in
+     * {@link GPUSceneShadowmapContext.select_for_draw} to maps catching up rather than to forced
+     * refreshes that drove the earlier 8/34 dispatch oscillation.
      *
      * Semantics is stronger than "dirty / out-of-date": an invalid map would show garbage
      * if sampled, while a stale-but-valid map just shows yesterday's shadow. Dirty-but-valid

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

@@ -85,17 +85,17 @@ export class Shadowmap {
     last_resize_frame_index = -1;
 
     /**
-     * True when the atlas region backing `layout` has never held valid depth for this map.
+     * True when the atlas region backing `layout` holds no valid depth for this map.
      * Initialised to true at construction (the newly-bound atlas rect contains garbage from a
-     * prior tenant or uninitialised texture memory); cleared by the draw loop after a
-     * successful raster.
+     * prior tenant or uninitialised texture memory), set again on every map when the atlas grows
+     * into a new texture, and cleared by the draw loop after a successful raster.
      *
      * Under the dual-layout model, resizes do NOT set this flag — a pending reservation
      * transitions to the committed layout only when an actual raster runs, so the committed
-     * region always holds last-drawn depth except on a freshly-created map. That keeps the
-     * "invalid + in-view MUST-draw" bypass in {@link GPUSceneShadowmapContext.select_for_draw}
-     * focused purely on "new map catching up" rather than on forced refreshes that drove the
-     * earlier 8/34 dispatch oscillation.
+     * region always holds last-drawn depth except on a freshly-created map or a grown atlas. That
+     * keeps the "invalid + in-view MUST-draw" bypass in
+     * {@link GPUSceneShadowmapContext.select_for_draw} to maps catching up rather than to forced
+     * refreshes that drove the earlier 8/34 dispatch oscillation.
      *
      * Semantics is stronger than "dirty / out-of-date": an invalid map would show garbage
      * if sampled, while a stale-but-valid map just shows yesterday's shadow. Dirty-but-valid

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

@@ -85,6 +85,23 @@ export class ShadowmapResolutionPolicy {
      * @param {number} frame_index monotonically increasing frame counter (drives cooldown)
      */
     adjust(shadowmaps: Shadowmap[], frame_index: number): void;
+    /**
+     * Release a map's pending_layout reservation, unpacking its rect(s) from the atlas. No-op
+     * if the map has no pending.
+     *
+     * @param {Shadowmap} map
+     * @returns {boolean} whether there was one
+     */
+    release_pending(map: Shadowmap): boolean;
+    /**
+     * Release every map's pending reservation: the room in the atlas nothing samples, which the
+     * shadow context takes back before it grows the atlas for a patch that does not fit. A map
+     * that still wants its resize asks again on its own schedule.
+     *
+     * @param {Shadowmap[]} shadowmaps
+     * @returns {boolean} whether any room was given back
+     */
+    release_all_pending(shadowmaps: Shadowmap[]): boolean;
     #private;
 }
 //# sourceMappingURL=ShadowmapResolutionPolicy.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ShadowmapResolutionPolicy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/ShadowmapResolutionPolicy.js"],"names":[],"mappings":"AAsGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IACI;;OAEG;IACH,wCAEC;IAgCD;;;;;;OAMG;IACH,8BAEC;IAED;;;;OAIG;IACH,6BAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAHW,WAAW,eACX,MAAM,QA6EhB;;CAkJJ"}
+{"version":3,"file":"ShadowmapResolutionPolicy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/ShadowmapResolutionPolicy.js"],"names":[],"mappings":"AAuGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IACI;;OAEG;IACH,wCAEC;IAgCD;;;;;;OAMG;IACH,8BAEC;IAED;;;;OAIG;IACH,6BAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAHW,WAAW,eACX,MAAM,QA6EhB;IA0CD;;;;;;OAMG;IACH,iCAFa,OAAO,CAYnB;IAED;;;;;;;OAOG;IACH,gCAHW,WAAW,GACT,OAAO,CAUnB;;CAyFJ"}

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

@@ -1,11 +1,12 @@
 import AABB2 from "../../../../core/geom/2d/aabb/AABB2.js";
+import { SHADOWMAP_PATCH_MIN_SIDE } from "./SHADOWMAP_PATCH_MIN_SIDE.js";
 
 /**
- * Minimum PoT side-length (in texels) for a local-light atlas rect. Below this shadows become
- * too blocky to be useful; we'd rather drop a light from the shadow set than render at 16².
+ * Minimum PoT side-length (in texels) for a local-light atlas rect: the atlas's smallest patch.
+ * We'd rather drop a light from the shadow set than render at 16².
  * @type {number}
  */
-const POT_MIN_SIDE = 32;
+const POT_MIN_SIDE = SHADOWMAP_PATCH_MIN_SIDE;
 
 /**
  * Maximum PoT side-length. Upper-bounded so one huge light can't monopolize the atlas — the
@@ -243,7 +244,7 @@ export class ShadowmapResolutionPolicy {
                     // Off-screen — the pending reservation can't commit (no draw) and shouldn't
                     // hold atlas space for an indefinite return-to-view. Release it; if the
                     // light returns and wants a resize, the policy allocates a fresh one.
-                    this.#release_pending(map);
+                    this.release_pending(map);
                 }
                 continue;
             }
@@ -273,7 +274,7 @@ export class ShadowmapResolutionPolicy {
                 // Projected area has drifted back to match the committed layout. Any pending
                 // reservation is now wasted — release it so atlas space is available elsewhere.
                 if (map.pending_layout !== null) {
-                    this.#release_pending(map);
+                    this.release_pending(map);
                     map.last_resize_frame_index = frame_index;
                 }
                 continue;
@@ -288,7 +289,7 @@ export class ShadowmapResolutionPolicy {
             // before attempting the new reservation — we don't want two pendings on one map,
             // and we'd rather release-then-try than hold the stale one if the new one fails.
             if (map.pending_layout !== null) {
-                this.#release_pending(map);
+                this.release_pending(map);
             }
 
             this.#reserve_pending(map, target_side);
@@ -347,16 +348,36 @@ export class ShadowmapResolutionPolicy {
      * if the map has no pending.
      *
      * @param {Shadowmap} map
+     * @returns {boolean} whether there was one
      */
-    #release_pending(map) {
+    release_pending(map) {
         const pending = map.pending_layout;
         if (pending === null) {
-            return;
+            return false;
         }
         for (let i = 0; i < pending.length; i++) {
             this.#atlas.remove(pending[i]);
         }
         map.pending_layout = null;
+        return true;
+    }
+
+    /**
+     * Release every map's pending reservation: the room in the atlas nothing samples, which the
+     * shadow context takes back before it grows the atlas for a patch that does not fit. A map
+     * that still wants its resize asks again on its own schedule.
+     *
+     * @param {Shadowmap[]} shadowmaps
+     * @returns {boolean} whether any room was given back
+     */
+    release_all_pending(shadowmaps) {
+        let released = false;
+        for (let i = 0; i < shadowmaps.length; i++) {
+            if (this.release_pending(shadowmaps[i])) {
+                released = true;
+            }
+        }
+        return released;
     }
 
     /**

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_get_light_visibility.d.ts

@@ -1,4 +1,3 @@
-export { chunk_sample_shadowmap_atlas_for_light } from "./chunk_sample_shadowmap_atlas_for_light.js";
 /**
  * Per-type shadow visibility helpers. Each reads the appropriate light record
  * from its table, takes the dedicated `shadow_id` field as a pointer into the

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_get_light_visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_shadowmap_get_light_visibility.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/shader/chunk_shadowmap_get_light_visibility.js"],"names":[],"mappings":";AAgBA;;;;;;;GAOG;AACH,mDAFU,SAAS,CAkGjB;0BApHwB,uCAAuC"}
+{"version":3,"file":"chunk_shadowmap_get_light_visibility.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/shader/chunk_shadowmap_get_light_visibility.js"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH,mDAFU,SAAS,CAkGjB;0BAjHwB,uCAAuC"}

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_get_light_visibility.js

@@ -7,9 +7,6 @@ import { chunk_shadowmap_sample_directional } from "./chunk_shadowmap_sample_dir
 import { chunk_shadowmap_sample_point2 } from "./chunk_shadowmap_sample_point2.js";
 import { chunk_shadowmap_sample_spot } from "./chunk_shadowmap_sample_spot.js";
 
-// re-exported for backwards compatibility with existing importers
-export { chunk_sample_shadowmap_atlas_for_light } from "./chunk_sample_shadowmap_atlas_for_light.js";
-
 const POINT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('light_point');
 const SPOT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('light_spot');
 const DIRECTIONAL_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('light_directional');

package/src/shade/renderer/shadow/sdf/SDF_DRAW_SETTINGS_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SDF_DRAW_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/SDF_DRAW_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA,oDAKG;6BAP0B,mCAAmC"}
+{"version":3,"file":"SDF_DRAW_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/SDF_DRAW_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA,oDAEG;6BAJ0B,mCAAmC"}

package/src/shade/renderer/shadow/sdf/SDF_DRAW_SETTINGS_STRUCT.js

@@ -1,9 +1,6 @@
-import { f32, u32, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { f32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 
 export const SDF_DRAW_SETTINGS_STRUCT = WebGPUStruct.from({
-    sdf_tile_resolution: u32,
-    // in tiles
-    sdf_atlas_resolution: vec3u,
     slice: f32
-});
+});

package/src/shade/renderer/shadow/sdf/chunk_geometry_sdf_query_distance.d.ts

@@ -1,3 +1,11 @@
+/**
+ * The signed distance a geometry's sparse field gives at a point of its local space, at level 0: past
+ * the grid box, a lower bound (see `mesh_sdf_sample`). A skinned clone reads its source's field.
+ *
+ * Reads `mesh_sdf_headers`, `mesh_sdf_indirection`, `mesh_sdf_atlas` and `mesh_sdf_sampler`.
+ *
+ * @type {CodeChunk}
+ */
 export const chunk_geometry_sdf_query_distance: CodeChunk;
 /**
  * This is essentially the same as "normal", but since SDF can be sampled anywhere, this is actually gradient (partial derivative) at the given sample point

package/src/shade/renderer/shadow/sdf/chunk_geometry_sdf_query_distance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_geometry_sdf_query_distance.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/chunk_geometry_sdf_query_distance.js"],"names":[],"mappings":"AAaA,0DAmCO;AAGP;;;;GAIG;AACH,gDAFU,SAAS,CAkBjB;0BA/DwB,oCAAoC"}
+{"version":3,"file":"chunk_geometry_sdf_query_distance.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/sdf/chunk_geometry_sdf_query_distance.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,gDAFU,SAAS,CAWZ;AAEP;;;;GAIG;AACH,gDAFU,SAAS,CAkBjB;0BA3CwB,oCAAoC"}