@woosh/meep-engine 3.56.0 → 3.58.0

package/src/shade/renderer/shadow/vsm/VSMPageManager.d.ts

@@ -42,8 +42,13 @@ export class VSMPageManager {
      * @param {number} options.pool_size texels on the pool's side
      * @param {number} options.request_capacity requests a reading holds at most
      * @param {number} options.protect_frames frames a touched page is safe from eviction for
+     * @param {number} [options.max_load_factor=DEFAULT_VSM_MAX_LOAD_FACTOR] high-watermark pool demand ratio in `[0, 1]`; `0` disables dynamic throttling
+     * @param {number} [options.low_load_factor=DEFAULT_VSM_LOW_LOAD_FACTOR] low-watermark pool demand ratio in `[0, 1]` below which dynamic LOD bias steps back down
+     * @param {number} [options.max_lod_bias=DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS] maximum dynamic LOD bias added under load; `0` disables dynamic throttling
+     * @param {number} [options.lod_bias_step_up=DEFAULT_VSM_LOD_BIAS_STEP_UP] minimum step added when demand exceeds `max_load_factor`
+     * @param {number} [options.lod_bias_step_down=DEFAULT_VSM_LOD_BIAS_STEP_DOWN] step subtracted when demand falls below `low_load_factor`
      */
-    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, }: {
+    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, max_load_factor, low_load_factor, max_lod_bias, lod_bias_step_up, lod_bias_step_down, }: {
         level_count: number;
         pages_per_level: number;
         first_texel_size: number;
@@ -52,6 +57,11 @@ export class VSMPageManager {
         pool_size: number;
         request_capacity: number;
         protect_frames: number;
+        max_load_factor?: number;
+        low_load_factor?: number;
+        max_lod_bias?: number;
+        lod_bias_step_up?: number;
+        lod_bias_step_down?: number;
     });
     /**
      * @type {number}
@@ -106,6 +116,10 @@ export class VSMPageManager {
     stats: {
         /** wants in the latest reading */
         wants: number;
+        /** pool demand ratio in the latest reading: `(wants + requests_dropped) / slots.capacity` */
+        load: number;
+        /** dynamic LOD bias currently added to coarsen requested pages under pool pressure */
+        dynamic_lod_bias: number;
         /** wants the latest {@link select} found with nothing resident to stand in for them */
         uncovered: number;
         /** candidates the latest {@link select} left for later frames, those it found no slot for included */
@@ -126,6 +140,66 @@ export class VSMPageManager {
         invalidations: number;
         re_rendered: number;
     };
+    /**
+     * @param {number} v in `[0, 1]`; `0` disables dynamic throttling
+     */
+    set max_load_factor(v: number);
+    /**
+     * High-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` above which
+     * {@link dynamic_lod_bias} steps up to coarsen requested pages (UE 5.4+ `MaxPagePoolLoadFactor`).
+     * `0` disables dynamic resolution throttling.
+     * @returns {number}
+     */
+    get max_load_factor(): number;
+    /**
+     * @param {number} v in `[0, 1]`
+     */
+    set low_load_factor(v: number);
+    /**
+     * Low-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` below which
+     * an active {@link dynamic_lod_bias} steps back down toward zero.
+     * @returns {number}
+     */
+    get low_load_factor(): number;
+    /**
+     * @param {number} v non-negative; `0` disables dynamic throttling
+     */
+    set max_lod_bias(v: number);
+    /**
+     * Ceiling on {@link dynamic_lod_bias} (UE 5.4+ `MaxResolutionLodBias`). `0` disables dynamic
+     * resolution throttling.
+     * @returns {number}
+     */
+    get max_lod_bias(): number;
+    /**
+     * @param {number} v positive
+     */
+    set lod_bias_step_up(v: number);
+    /**
+     * Minimum LOD bias step added when pool demand exceeds {@link max_load_factor}.
+     * @returns {number}
+     */
+    get lod_bias_step_up(): number;
+    /**
+     * @param {number} v positive
+     */
+    set lod_bias_step_down(v: number);
+    /**
+     * LOD bias step subtracted when pool demand falls below {@link low_load_factor}.
+     * @returns {number}
+     */
+    get lod_bias_step_down(): number;
+    /**
+     * Pool demand ratio from the latest applied reading: `(wants + requests_dropped) / slots.capacity`.
+     * @returns {number}
+     */
+    get load(): number;
+    /**
+     * Dynamic LOD bias in `[0, max_lod_bias]` added on top of the user LOD bias to keep pool
+     * demand within capacity.
+     * @returns {number}
+     */
+    get dynamic_lod_bias(): number;
     /**
      * Cells of every level: the length of the page table.
      * @returns {number}
@@ -194,6 +268,11 @@ export class VSMPageManager {
      * @returns {boolean} whether the pages were invalidated
      */
     set_light_space(view: ArrayLike<number>, near: number, far: number, frame: number): boolean;
+    /**
+     * Give back every resident page: what a light-space change does, and what the shadow context
+     * does when the atlas the pool lives in is replaced by a larger one, whose texels hold nothing.
+     */
+    evict_all(): void;
     /**
      * Take a frame's feedback: the pages wanted, which become the want set, and the slots a mover
      * crossed. A reading recorded under a light space that has since been replaced has its wants

package/src/shade/renderer/shadow/vsm/VSMPageManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VSMPageManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VSMPageManager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"VSMPageManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VSMPageManager.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/shadow/vsm/VSMPageManager.js

@@ -8,6 +8,17 @@ import { VTPhysicalSlots } from "../../texture/virtual/VTPhysicalSlots.js";
 import { VSM_COVER_LEVEL_STEP } from "./VSM_COVER_LEVEL_STEP.js";
 import { VSM_FEEDBACK_LAYOUT, vsm_feedback_stale_offset } from "./VSM_FEEDBACK_LAYOUT.js";
 import { VSM_LEVEL_LIMIT } from "./VSM_LEVEL_LIMIT.js";
+import { DEFAULT_VSM_LOW_LOAD_FACTOR } from "./DEFAULT_VSM_LOW_LOAD_FACTOR.js";
+import { DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS } from "./DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS.js";
+import { DEFAULT_VSM_MAX_LOAD_FACTOR } from "./DEFAULT_VSM_MAX_LOAD_FACTOR.js";
+
+/**
+ * Default minimum LOD bias increment applied when pool demand exceeds {@link VSMPageManager#max_load_factor},
+ * and the recovery decrement applied when demand falls below {@link VSMPageManager#low_load_factor}.
+ * A slower step-down than step-up avoids oscillation when demand hovers near the deadband.
+ */
+const DEFAULT_VSM_LOD_BIAS_STEP_UP = 0.25;
+const DEFAULT_VSM_LOD_BIAS_STEP_DOWN = 0.125;
 
 /**
  * Candidate kinds. A **cover** — a page several levels up that gives pixels with nothing resident
@@ -315,12 +326,34 @@ export class VSMPageManager {
     #dirty_slot_count = 0;
     #levels_dirty = false;
 
+    /**
+     * Dynamic resolution throttling (UE 5.4+ `MaxPagePoolLoadFactor` / `MaxResolutionLodBias` with
+     * hysteresis deadband and readback-latency gating).
+     */
+    #max_load_factor = DEFAULT_VSM_MAX_LOAD_FACTOR;
+    #low_load_factor = DEFAULT_VSM_LOW_LOAD_FACTOR;
+    #max_lod_bias = DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS;
+    #lod_bias_step_up = DEFAULT_VSM_LOD_BIAS_STEP_UP;
+    #lod_bias_step_down = DEFAULT_VSM_LOD_BIAS_STEP_DOWN;
+    #load = 0;
+    #dynamic_lod_bias = 0;
+    #bias_level_shift = 0;
+    #pre_step_level = 0;
+    #last_step_delta = 0;
+    #awaiting_step_response = false;
+    #bias_effective_frame = -Infinity;
+    #last_select_frame = -Infinity;
+
     /**
      * What the manager did, cumulative since construction except where noted.
      */
     stats = {
         /** wants in the latest reading */
         wants: 0,
+        /** pool demand ratio in the latest reading: `(wants + requests_dropped) / slots.capacity` */
+        load: 0,
+        /** dynamic LOD bias currently added to coarsen requested pages under pool pressure */
+        dynamic_lod_bias: 0,
         /** wants the latest {@link select} found with nothing resident to stand in for them */
         uncovered: 0,
         /** candidates the latest {@link select} left for later frames, those it found no slot for included */
@@ -352,6 +385,11 @@ export class VSMPageManager {
      * @param {number} options.pool_size texels on the pool's side
      * @param {number} options.request_capacity requests a reading holds at most
      * @param {number} options.protect_frames frames a touched page is safe from eviction for
+     * @param {number} [options.max_load_factor=DEFAULT_VSM_MAX_LOAD_FACTOR] high-watermark pool demand ratio in `[0, 1]`; `0` disables dynamic throttling
+     * @param {number} [options.low_load_factor=DEFAULT_VSM_LOW_LOAD_FACTOR] low-watermark pool demand ratio in `[0, 1]` below which dynamic LOD bias steps back down
+     * @param {number} [options.max_lod_bias=DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS] maximum dynamic LOD bias added under load; `0` disables dynamic throttling
+     * @param {number} [options.lod_bias_step_up=DEFAULT_VSM_LOD_BIAS_STEP_UP] minimum step added when demand exceeds `max_load_factor`
+     * @param {number} [options.lod_bias_step_down=DEFAULT_VSM_LOD_BIAS_STEP_DOWN] step subtracted when demand falls below `low_load_factor`
      */
     constructor({
                     level_count,
@@ -362,6 +400,11 @@ export class VSMPageManager {
                     pool_size,
                     request_capacity,
                     protect_frames,
+                    max_load_factor = DEFAULT_VSM_MAX_LOAD_FACTOR,
+                    low_load_factor = DEFAULT_VSM_LOW_LOAD_FACTOR,
+                    max_lod_bias = DEFAULT_VSM_MAX_DYNAMIC_LOD_BIAS,
+                    lod_bias_step_up = DEFAULT_VSM_LOD_BIAS_STEP_UP,
+                    lod_bias_step_down = DEFAULT_VSM_LOD_BIAS_STEP_DOWN,
                 }) {
         assert.isPositiveInteger(level_count, 'level_count');
         assert.lessThanOrEqual(level_count, VSM_LEVEL_LIMIT, 'level_count');
@@ -383,6 +426,11 @@ export class VSMPageManager {
         this.border = border;
         this.request_capacity = request_capacity;
         this.protect_frames = protect_frames;
+        this.max_load_factor = max_load_factor;
+        this.low_load_factor = low_load_factor;
+        this.max_lod_bias = max_lod_bias;
+        this.lod_bias_step_up = lod_bias_step_up;
+        this.lod_bias_step_down = lod_bias_step_down;
 
         const slots = this.slots = new VTPhysicalSlots({ atlas_size: pool_size, page_size, border });
 
@@ -436,6 +484,250 @@ export class VSMPageManager {
         this.#dirty_slot_mark = new Uint8Array(capacity);
     }
 
+    /**
+     * High-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` above which
+     * {@link dynamic_lod_bias} steps up to coarsen requested pages (UE 5.4+ `MaxPagePoolLoadFactor`).
+     * `0` disables dynamic resolution throttling.
+     * @returns {number}
+     */
+    get max_load_factor() {
+        return this.#max_load_factor;
+    }
+
+    /**
+     * @param {number} v in `[0, 1]`; `0` disables dynamic throttling
+     */
+    set max_load_factor(v) {
+        assert.isNumber(v, 'max_load_factor');
+        assert.greaterThanOrEqual(v, 0, 'max_load_factor');
+        assert.lessThanOrEqual(v, 1, 'max_load_factor');
+
+        this.#max_load_factor = v;
+
+        if (v === 0) {
+            this.#reset_dynamic_lod_bias();
+        }
+    }
+
+    /**
+     * Low-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` below which
+     * an active {@link dynamic_lod_bias} steps back down toward zero.
+     * @returns {number}
+     */
+    get low_load_factor() {
+        return this.#low_load_factor;
+    }
+
+    /**
+     * @param {number} v in `[0, 1]`
+     */
+    set low_load_factor(v) {
+        assert.isNumber(v, 'low_load_factor');
+        assert.greaterThanOrEqual(v, 0, 'low_load_factor');
+        assert.lessThanOrEqual(v, 1, 'low_load_factor');
+
+        this.#low_load_factor = v;
+    }
+
+    /**
+     * Ceiling on {@link dynamic_lod_bias} (UE 5.4+ `MaxResolutionLodBias`). `0` disables dynamic
+     * resolution throttling.
+     * @returns {number}
+     */
+    get max_lod_bias() {
+        return this.#max_lod_bias;
+    }
+
+    /**
+     * @param {number} v non-negative; `0` disables dynamic throttling
+     */
+    set max_lod_bias(v) {
+        assert.isNumber(v, 'max_lod_bias');
+        assert.greaterThanOrEqual(v, 0, 'max_lod_bias');
+
+        this.#max_lod_bias = v;
+
+        if (v === 0) {
+            this.#reset_dynamic_lod_bias();
+        } else if (this.#dynamic_lod_bias > v) {
+            this.#dynamic_lod_bias = v;
+            this.stats.dynamic_lod_bias = v;
+            this.#bias_level_shift = Math.min(this.#bias_level_shift, Math.ceil(v));
+        }
+    }
+
+    /**
+     * Minimum LOD bias step added when pool demand exceeds {@link max_load_factor}.
+     * @returns {number}
+     */
+    get lod_bias_step_up() {
+        return this.#lod_bias_step_up;
+    }
+
+    /**
+     * @param {number} v positive
+     */
+    set lod_bias_step_up(v) {
+        assert.isNumber(v, 'lod_bias_step_up');
+        assert.greaterThan(v, 0, 'lod_bias_step_up');
+
+        this.#lod_bias_step_up = v;
+    }
+
+    /**
+     * LOD bias step subtracted when pool demand falls below {@link low_load_factor}.
+     * @returns {number}
+     */
+    get lod_bias_step_down() {
+        return this.#lod_bias_step_down;
+    }
+
+    /**
+     * @param {number} v positive
+     */
+    set lod_bias_step_down(v) {
+        assert.isNumber(v, 'lod_bias_step_down');
+        assert.greaterThan(v, 0, 'lod_bias_step_down');
+
+        this.#lod_bias_step_down = v;
+    }
+
+    /**
+     * Pool demand ratio from the latest applied reading: `(wants + requests_dropped) / slots.capacity`.
+     * @returns {number}
+     */
+    get load() {
+        return this.#load;
+    }
+
+    /**
+     * Dynamic LOD bias in `[0, max_lod_bias]` added on top of the user LOD bias to keep pool
+     * demand within capacity.
+     * @returns {number}
+     */
+    get dynamic_lod_bias() {
+        return this.#dynamic_lod_bias;
+    }
+
+    /**
+     * Clear any active dynamic LOD bias and its step-response tracking.
+     */
+    #reset_dynamic_lod_bias() {
+        this.#dynamic_lod_bias = 0;
+        this.stats.dynamic_lod_bias = 0;
+        this.#bias_level_shift = 0;
+        this.#pre_step_level = 0;
+        this.#last_step_delta = 0;
+        this.#awaiting_step_response = false;
+        this.#bias_effective_frame = -Infinity;
+    }
+
+    /**
+     * Update {@link dynamic_lod_bias} from a reading's demand and mean clipmap level.
+     *
+     * Three mechanisms prevent oscillation:
+     * 1. **Deadband hysteresis**: bias steps up only above {@link max_load_factor} (using a 2-D
+     *    clipmap area estimate `0.5 * log2(load / max_load_factor)` when a larger jump is needed)
+     *    and steps down only below {@link low_load_factor}, holding steady inside the band.
+     * 2. **Discrete-cliff compensation**: in a 2-D clipmap, crossing an integer boundary in
+     *    `floor(log2(footprint) + bias)` merges 2×2 pages into 1, dropping page count by up to 4×
+     *    for the same view. Only the level shift observed on the first reading after a bias change
+     *    ({@link #awaiting_step_response}) is attributed to the bias step (so camera zoom-outs on
+     *    later frames never lock in artificial hysteresis), and only the excess quantization shift
+     *    above the continuous bias (`max(0, bias_level_shift - dynamic_lod_bias)`) scales the low
+     *    watermark by `4^(-excess_shift)`, avoiding double-counting the deadband's own `4^(-step)`.
+     * 3. **Readback-latency gating**: feedback arrives several frames after the GPU recorded it;
+     *    readings recorded before the frame on which the last bias adjustment took effect on the
+     *    GPU ({@link #bias_effective_frame}) cannot trigger another step.
+     *
+     * @param {number} load `(wants + requests_dropped) / slots.capacity`
+     * @param {number} wants valid requests in the reading
+     * @param {number} level_sum sum of requested clipmap levels across `wants`
+     * @param {number} reading_frame frame the reading was recorded in
+     */
+    #update_dynamic_lod_bias(load, wants, level_sum, reading_frame) {
+        this.#load = load;
+        this.stats.load = load;
+
+        const max_load = this.#max_load_factor;
+        const max_bias = this.#max_lod_bias;
+
+        if (max_load <= 0 || max_bias <= 0) {
+            this.#reset_dynamic_lod_bias();
+            return;
+        }
+
+        const mean_level = wants > 0 ? level_sum / wants : 0;
+
+        if (reading_frame < this.#bias_effective_frame) {
+            return;
+        }
+
+        if (this.#awaiting_step_response) {
+            this.#awaiting_step_response = false;
+
+            if (wants > 0) {
+                const delta_level = mean_level - this.#pre_step_level;
+
+                if (this.#last_step_delta > 0 && delta_level > 0) {
+                    const step_shift = Math.min(Math.ceil(this.#last_step_delta), delta_level);
+                    this.#bias_level_shift = Math.min(
+                        Math.ceil(this.#dynamic_lod_bias),
+                        this.#bias_level_shift + step_shift,
+                    );
+                } else if (this.#last_step_delta < 0 && delta_level < 0) {
+                    const step_drop = Math.min(Math.ceil(-this.#last_step_delta), -delta_level);
+                    this.#bias_level_shift = Math.max(0, this.#bias_level_shift - step_drop);
+                }
+            }
+        }
+
+        if (load > max_load) {
+            // In a 2-D clipmap, each +1 of LOD bias halves linear page density and reduces page
+            // count by ~4x (2^(2 * bias)). Step by at least lod_bias_step_up, or proportionally
+            // in log2(area) when severely overloaded.
+            const proportional_step = 0.5 * Math.log2(load / max_load);
+            const step = Math.max(this.#lod_bias_step_up, proportional_step);
+            const next_bias = Math.min(max_bias, this.#dynamic_lod_bias + step);
+
+            if (next_bias > this.#dynamic_lod_bias) {
+                this.#last_step_delta = next_bias - this.#dynamic_lod_bias;
+                this.#pre_step_level = mean_level;
+                this.#awaiting_step_response = wants > 0;
+                this.#dynamic_lod_bias = next_bias;
+                this.stats.dynamic_lod_bias = next_bias;
+                this.#bias_effective_frame = Math.max(reading_frame + 1, this.#last_select_frame + 1);
+            }
+
+            return;
+        }
+
+        if (this.#dynamic_lod_bias <= 0) {
+            return;
+        }
+
+        const low_load = Math.min(this.#low_load_factor, max_load);
+        const effective_low = low_load * (4 ** -this.#bias_level_shift);
+
+        if (load < effective_low) {
+            const next_bias = Math.max(0, this.#dynamic_lod_bias - this.#lod_bias_step_down);
+
+            this.#last_step_delta = next_bias - this.#dynamic_lod_bias;
+            this.#pre_step_level = mean_level;
+            this.#dynamic_lod_bias = next_bias;
+            this.stats.dynamic_lod_bias = next_bias;
+            this.#bias_effective_frame = Math.max(reading_frame + 1, this.#last_select_frame + 1);
+
+            if (next_bias === 0) {
+                this.#bias_level_shift = 0;
+                this.#awaiting_step_response = false;
+            } else {
+                this.#bias_level_shift = Math.min(this.#bias_level_shift, Math.ceil(next_bias));
+                this.#awaiting_step_response = wants > 0;
+            }
+        }
+    }
+
     /**
      * Cells of every level: the length of the page table.
      * @returns {number}
@@ -670,7 +962,7 @@ export class VSMPageManager {
         this.#near = near;
         this.#far = far;
 
-        this.#evict_all();
+        this.evict_all();
 
         this.#remember_light_space(frame);
         this.stats.invalidations++;
@@ -736,9 +1028,10 @@ export class VSMPageManager {
     }
 
     /**
-     * Give back every resident page.
+     * Give back every resident page: what a light-space change does, and what the shadow context
+     * does when the atlas the pool lives in is replaced by a larger one, whose texels hold nothing.
      */
-    #evict_all() {
+    evict_all() {
         const capacity = this.slots.capacity;
 
         for (let slot = 0; slot < capacity; slot++) {
@@ -786,6 +1079,7 @@ export class VSMPageManager {
         this.stats.movers = words[L.MOVER_COUNT];
 
         let wants = 0;
+        let level_sum = 0;
 
         for (let i = 0; i < count; i++) {
             const base = L.HEADER_WORDS + i * L.REQUEST_WORDS;
@@ -808,6 +1102,7 @@ export class VSMPageManager {
             }
 
             this.#want_level[wants] = level;
+            level_sum += level;
             this.#want_x[wants] = x;
             this.#want_y[wants] = y;
             this.#want_importance[wants] = words[base + L.REQUEST_IMPORTANCE];
@@ -832,6 +1127,10 @@ export class VSMPageManager {
         this.#want_count = wants;
         this.stats.wants = wants;
 
+        const load = (wants + this.stats.requests_dropped) / this.slots.capacity;
+
+        this.#update_dynamic_lod_bias(load, wants, level_sum, reading_frame);
+
         const slot_capacity = this.slots.capacity;
         const stale_offset = vsm_feedback_stale_offset(capacity);
         const stale_count = Math.min(words[L.STALE_COUNT], slot_capacity);
@@ -981,6 +1280,7 @@ export class VSMPageManager {
         this.#job_count = 0;
 
         this.#select_index++;
+        this.#last_select_frame = Math.max(this.#last_select_frame, frame);
         this.#stamp = (this.#stamp + 1) >>> 0;
 
         if (this.#stamp === 0) {

package/src/shade/renderer/shadow/vsm/VirtualShadowMap.d.ts

@@ -24,8 +24,13 @@ export class VirtualShadowMap extends Shadowmap {
      * @param {number} options.request_capacity
      * @param {number} options.protect_frames
      * @param {number} options.depth_extent
+     * @param {number} [options.max_load_factor]
+     * @param {number} [options.low_load_factor]
+     * @param {number} [options.max_lod_bias]
+     * @param {number} [options.lod_bias_step_up]
+     * @param {number} [options.lod_bias_step_down]
      */
-    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, depth_extent, }: {
+    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, depth_extent, max_load_factor, low_load_factor, max_lod_bias, lod_bias_step_up, lod_bias_step_down, }: {
         level_count: number;
         pages_per_level: number;
         first_texel_size: number;
@@ -35,6 +40,11 @@ export class VirtualShadowMap extends Shadowmap {
         request_capacity: number;
         protect_frames: number;
         depth_extent: number;
+        max_load_factor?: number;
+        low_load_factor?: number;
+        max_lod_bias?: number;
+        lod_bias_step_up?: number;
+        lod_bias_step_down?: number;
     });
     /**
      * @type {VSMPageManager}
@@ -70,7 +80,8 @@ export class VirtualShadowMap extends Shadowmap {
     frame_index: number;
     /**
      * What this frame's {@link update} works with, set by the shadow context before it: how many
-     * pages it may draw, the bias the record carries, and the main view's height in pixels.
+     * pages it may draw, the base bias the caller asked for (to which {@link dynamic_lod_bias} is
+     * added when writing the GPU record), and the main view's height in pixels.
      */
     page_budget: number;
     lod_bias: number;
@@ -108,10 +119,50 @@ export class VirtualShadowMap extends Shadowmap {
      * @returns {number}
      */
     get slot_size(): number;
+    /**
+     * @param {number} v in `[0, 1]`
+     */
+    set max_load_factor(v: number);
+    /**
+     * High-watermark pool demand ratio `(wants + requests_dropped) / slots.capacity` above which
+     * {@link dynamic_lod_bias} steps up (`0` disables dynamic throttling).
+     * @returns {number}
+     */
+    get max_load_factor(): number;
+    /**
+     * @param {number} v in `[0, 1]`
+     */
+    set low_load_factor(v: number);
+    /**
+     * Low-watermark pool demand ratio below which {@link dynamic_lod_bias} steps back down.
+     * @returns {number}
+     */
+    get low_load_factor(): number;
+    /**
+     * @param {number} v non-negative
+     */
+    set max_lod_bias(v: number);
+    /**
+     * Ceiling on {@link dynamic_lod_bias} (`0` disables dynamic throttling).
+     * @returns {number}
+     */
+    get max_lod_bias(): number;
+    /**
+     * Dynamic LOD bias added by {@link manager} under pool pressure.
+     * @returns {number}
+     */
+    get dynamic_lod_bias(): number;
+    /**
+     * Total LOD bias written to the GPU `shadow_virtual` record: {@link lod_bias} plus
+     * {@link dynamic_lod_bias}.
+     * @returns {number}
+     */
+    get effective_lod_bias(): number;
     /**
      * Fit the light space and the windows to this frame and choose its pages, advancing
      * {@link frame_index}. Reads {@link page_budget}, {@link lod_bias} and {@link view_height}, which
-     * the shadow context sets first.
+     * the shadow context sets first, and combines {@link lod_bias} with the manager's
+     * {@link dynamic_lod_bias} in the published record.
      *
      * @param {Camera} main_camera
      * @param {GPUSceneContext} scene_ctx

package/src/shade/renderer/shadow/vsm/VirtualShadowMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualShadowMap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowMap.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH;IAwHI;;;;;;;;;;;OAWG;IACH;QAV2B,WAAW,EAA3B,MAAM;QACU,eAAe,EAA/B,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,MAAM,EAAtB,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,cAAc,EAA9B,MAAM;QACU,YAAY,EAA5B,MAAM;OA8BhB;IA9JD;;;OAGG;IACH,kBAHU,cAAc,CAGhB;IAER;;;;OAIG;IACH,uBAHU,MAAM,CAGH;IAEb;;;OAGG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEC;IACjB,mBAAgB;IAChB,mBAAgB;IAEhB;;;;;;OAMG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,oBAAgB;IAChB,iBAAa;IACb,oBAAgB;IAEhB;;;;;OAKG;IACH,aAFU,YAAU,IAAI,CAEL;IAEnB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,WAFU,OAAO,CAEC;IAElB;;;OAGG;IACH,cAFU,kBAAkB,CAEY;IAExC;;;OAGG;IACH,MAFU,MAAM,CAEP;IACT,YAAQ;IAoFR;;;OAGG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,8DA4DC;IAED;;;OAGG;IACH,eAFa;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAM/E;IAED;;;OAGG;IACH,uBAFa,MAAM,CAsBlB;IAED;;;;;;;;OAQG;IACH,wBALW,kBAAkB,SAClB,MAAM,KACN,MAAM,KACN,MAAM,QAiBhB;IAYL;;;OAGG;IACH,6BAFU,OAAO,CAE4B;;CAN5C;0BAvUyB,qBAAqB;+BAChB,qBAAqB;mCAFjB,oCAAoC"}
+{"version":3,"file":"VirtualShadowMap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowMap.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH;IAyHI;;;;;;;;;;;;;;;;OAgBG;IACH;QAf2B,WAAW,EAA3B,MAAM;QACU,eAAe,EAA/B,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,MAAM,EAAtB,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACU,cAAc,EAA9B,MAAM;QACU,YAAY,EAA5B,MAAM;QACW,eAAe,GAAhC,MAAM;QACW,eAAe,GAAhC,MAAM;QACW,YAAY,GAA7B,MAAM;QACW,gBAAgB,GAAjC,MAAM;QACW,kBAAkB,GAAnC,MAAM;OAwChB;IA9KD;;;OAGG;IACH,kBAHU,cAAc,CAGhB;IAER;;;;OAIG;IACH,uBAHU,MAAM,CAGH;IAEb;;;OAGG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEC;IACjB,mBAAgB;IAChB,mBAAgB;IAEhB;;;;;;OAMG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAgB;IAChB,iBAAa;IACb,oBAAgB;IAEhB;;;;;OAKG;IACH,aAFU,YAAU,IAAI,CAEL;IAEnB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,WAFU,OAAO,CAEC;IAElB;;;OAGG;IACH,cAFU,kBAAkB,CAEY;IAExC;;;OAGG;IACH,MAFU,MAAM,CAEP;IACT,YAAQ;IAmGR;;;OAGG;IACH,wBAEC;IAWD;;OAEG;IACH,+BAEC;IAdD;;;;OAIG;IACH,8BAEC;IAiBD;;OAEG;IACH,+BAEC;IAbD;;;OAGG;IACH,8BAEC;IAiBD;;OAEG;IACH,4BAEC;IAbD;;;OAGG;IACH,2BAEC;IASD;;;OAGG;IACH,+BAEC;IAED;;;;OAIG;IACH,iCAEC;IAED;;;;;;;;OAQG;IACH,8DA4DC;IAED;;;OAGG;IACH,eAFa;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAM/E;IAED;;;OAGG;IACH,uBAFa,MAAM,CAsBlB;IAED;;;;;;;;OAQG;IACH,wBALW,kBAAkB,SAClB,MAAM,KACN,MAAM,KACN,MAAM,QAiBhB;IAYL;;;OAGG;IACH,6BAFU,OAAO,CAE4B;;CAN5C;0BAvZyB,qBAAqB;+BAChB,qBAAqB;mCAFjB,oCAAoC"}