@woosh/meep-engine 3.57.0 → 3.58.0

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

@@ -1,338 +1,418 @@
-import { assert } from "../../../../core/assert.js";
-import { quantize_hysteretic } from "../../../../core/geom/clipmap/quantize_hysteretic.js";
-import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
-import { OrthographicCamera } from "../../camera/OrthographicCamera.js";
-import { Shadowmap } from "../map/Shadowmap.js";
-import { VSMPageManager } from "./VSMPageManager.js";
-
-/**
- * A directional light's virtual shadow map: a clipmap of world-anchored pages around the main
- * camera, rendered into a region of the shadow atlas as the GPU asks for them and as movers make
- * them stale, under a budget of pages per frame.
- *
- * The page bookkeeping is {@link VSMPageManager}'s; this holds what ties it to the light and to the
- * shadow context: the light space, the depth range, the main view's numbers the record carries, the
- * rows the context claimed for it in the light database, and the pooled views pages are drawn with
- * ({@link views}, one per page a frame may draw).
- *
- * Built and owned by {@link GPUSceneShadowmapContext} when its renderer asks for virtual shadow maps.
- *
- * @extends {Shadowmap}
- */
-export class VirtualShadowMap extends Shadowmap {
-
-    /**
-     * @type {VSMPageManager}
-     * @readonly
-     */
-    manager;
-
-    /**
-     * Distance either side of the snapped camera depth that the light's depth range reaches.
-     * @type {number}
-     * @readonly
-     */
-    depth_extent;
-
-    /**
-     * The map's row of `shadow_virtual`, claimed by the shadow context with the map; -1 before.
-     * @type {number}
-     */
-    record_row = -1;
-
-    /**
-     * First rows of the map's runs of `shadow_virtual_level`, `shadow_virtual_page` and
-     * `shadow_virtual_slot`; -1 before they are claimed.
-     * @type {number}
-     */
-    first_level = -1;
-    first_page = -1;
-    first_slot = -1;
-
-    /**
-     * The map's own frame count, advanced by every {@link update}: what its pages, touches and
-     * readings are stamped with. The map's own because it has to keep rising whichever view the
-     * frame was rendered for — a view's count starts again at zero with each new camera, and a
-     * reading stamped from it would be refused as older than the last one applied.
-     * @type {number}
-     */
-    frame_index = 0;
-
-    /**
-     * 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.
-     */
-    page_budget = 0;
-    lod_bias = 0;
-    view_height = 1;
-
-    /**
-     * One word per pool slot, set on the GPU when a mover crosses the slot and cleared when a
-     * readback lists it — persistent, so a frame whose readback was skipped loses nothing. Created
-     * by the shadow context with the map's rows; null before.
-     * @type {GPUBuffer|null}
-     */
-    stale_flags = null;
-
-    /**
-     * Readbacks of this map's feedback on their way back.
-     * @type {number}
-     */
-    readbacks_in_flight = 0;
-
-    /**
-     * Set once the map is torn down: a reading still in flight is then dropped.
-     * @type {boolean}
-     */
-    destroyed = false;
-
-    /**
-     * The light camera at the world origin; its view matrix is light space.
-     * @type {OrthographicCamera}
-     */
-    light_camera = new OrthographicCamera();
-
-    /**
-     * The light's depth range this frame, as distances along the light from light space's origin.
-     * @type {number}
-     */
-    near = 0;
-    far = 0;
-
-    /**
-     * Where the depth range is centred, along the light, in steps of a quarter of
-     * {@link depth_extent}; set by the first {@link update}.
-     */
-    #depth_index = 0;
-    #depth_centred = false;
-
-    /**
-     * The `shadow_virtual` record, written whole every frame.
-     */
-    #record = {
-        view: new Float32Array(16),
-        camera_position: new Float32Array(3),
-        pixel_angle: 0,
-        near: 0,
-        far: 0,
-        first_texel_size: 0,
-        lod_bias: 0,
-        first_level: 0,
-        level_count: 0,
-        pages_per_level: 0,
-        page_size: 0,
-        border: 0,
-        pool_origin: new Uint32Array(2),
-        slots_per_axis: 0,
-        first_page: 0,
-        page_count: 0,
-        first_slot: 0,
-        slot_count: 0,
-    };
-
-    /**
-     * The `shadow_directional` record: no cascades, and this map.
-     */
-    #directional_record = {
-        first_cascade: GPU_DATABASE_NULL,
-        cascade_count: 0,
-        virtual_map: GPU_DATABASE_NULL,
-    };
-
-    /**
-     * @param {Object} options
-     * @param {number} options.level_count
-     * @param {number} options.pages_per_level
-     * @param {number} options.first_texel_size
-     * @param {number} options.page_size
-     * @param {number} options.border
-     * @param {number} options.pool_size texels on the pool's side
-     * @param {number} options.request_capacity
-     * @param {number} options.protect_frames
-     * @param {number} options.depth_extent
-     */
-    constructor({
-                    level_count,
-                    pages_per_level,
-                    first_texel_size,
-                    page_size,
-                    border,
-                    pool_size,
-                    request_capacity,
-                    protect_frames,
-                    depth_extent,
-                }) {
-        super();
-
-        assert.isNumber(depth_extent, 'depth_extent');
-        assert.greaterThan(depth_extent, 0, 'depth_extent');
-
-        this.manager = new VSMPageManager({
-            level_count,
-            pages_per_level,
-            first_texel_size,
-            page_size,
-            border,
-            pool_size,
-            request_capacity,
-            protect_frames,
-        });
-
-        this.depth_extent = depth_extent;
-    }
-
-    /**
-     * Texels on a slot's side: a page and its border.
-     * @returns {number}
-     */
-    get slot_size() {
-        return this.manager.slots.slot_size;
-    }
-
-    /**
-     * 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.
-     *
-     * @param {Camera} main_camera
-     * @param {GPUSceneContext} scene_ctx
-     */
-    update(main_camera, scene_ctx) {
-        assert.defined(main_camera, 'main_camera');
-
-        const t = this.light.transform;
-        const light_camera = this.light_camera;
-
-        // turned as the light, at the origin: its view matrix is world to light space
-        light_camera.transform.setRotation(t.rotation_x, t.rotation_y, t.rotation_z, t.rotation_w);
-        light_camera.transform.setTranslation(0, 0, 0);
-        light_camera.update();
-
-        const view = light_camera.view_matrix;
-
-        const c = main_camera.transform;
-        const cx = c.translation_x;
-        const cy = c.translation_y;
-        const cz = c.translation_z;
-
-        const light_x = view[0] * cx + view[4] * cy + view[8] * cz + view[12];
-        const light_y = view[1] * cx + view[5] * cy + view[9] * cz + view[13];
-        const light_depth = -(view[2] * cx + view[6] * cy + view[10] * cz + view[14]);
-
-        // snapped, so the range moves — and every page with it — only when the camera has gone a
-        // quarter of it along the light from where the range is centred: a camera standing on the
-        // plane between two snaps does not move it back and forth. Half a step of hysteresis on
-        // top of the half step makes that threshold a whole step.
-        const snap = this.depth_extent / 4;
-
-        this.#depth_index = quantize_hysteretic(light_depth, this.#depth_index, snap, snap * 0.5, this.#depth_centred);
-        this.#depth_centred = true;
-
-        const depth_centre = this.#depth_index * snap;
-
-        this.near = depth_centre - this.depth_extent;
-        this.far = depth_centre + this.depth_extent;
-
-        const manager = this.manager;
-        const frame = ++this.frame_index;
-
-        manager.set_light_space(view, this.near, this.far, frame);
-        manager.update_windows(light_x, light_y);
-        manager.select(frame, this.page_budget);
-
-        const record = this.#record;
-
-        record.view.set(view);
-        record.camera_position[0] = cx;
-        record.camera_position[1] = cy;
-        record.camera_position[2] = cz;
-
-        // a perspective view's pixel at unit distance; a view without a field of view selects the
-        // finest level everywhere
-        const fov = main_camera.fov;
-        record.pixel_angle = fov === undefined ? 0 : 2 * Math.tan(fov * 0.5) / Math.max(1, this.view_height);
-
-        record.near = this.near;
-        record.far = this.far;
-        record.lod_bias = this.lod_bias;
-
-        this.metadata_changed = true;
-    }
-
-    /**
-     * The `shadow_directional` record: an empty cascade range, and this map's `shadow_virtual` row.
-     * @returns {{first_cascade: number, cascade_count: number, virtual_map: number}}
-     */
-    make_record() {
-        this.#directional_record.virtual_map = this.record_row;
-
-        return this.#directional_record;
-    }
-
-    /**
-     * The `shadow_virtual` record as of the last {@link update}.
-     * @returns {object}
-     */
-    make_virtual_record() {
-        const record = this.#record;
-        const manager = this.manager;
-        const pool = this.layout[0];
-
-        record.first_texel_size = manager.first_texel_size;
-        record.first_level = this.first_level;
-        record.level_count = manager.level_count;
-        record.pages_per_level = manager.pages_per_level;
-        record.page_size = manager.page_size;
-        record.border = manager.border;
-        record.pool_origin[0] = pool.x0;
-        record.pool_origin[1] = pool.y0;
-        record.slots_per_axis = manager.slots.slots_per_axis;
-        record.first_page = this.first_page;
-        record.page_count = manager.cell_count;
-        record.first_slot = this.first_slot;
-        record.slot_count = manager.slots.capacity;
-
-        return record;
-    }
-
-    /**
-     * Point a page camera at a page: turned as the light, at the origin, its planes the page's
-     * square widened by its border on every side, the light's depth range.
-     *
-     * @param {OrthographicCamera} camera
-     * @param {number} level
-     * @param {number} x world page
-     * @param {number} y world page
-     */
-    aim_page_camera(camera, level, x, y) {
-        const manager = this.manager;
-        const size = manager.page_world_size(level);
-        const border = size * manager.border / manager.page_size;
-
-        camera.transform.copy(this.light_camera.transform);
-
-        camera.left = x * size - border;
-        camera.right = (x + 1) * size + border;
-        camera.bottom = y * size - border;
-        camera.top = (y + 1) * size + border;
-        camera.near = this.near;
-        camera.far = this.far;
-
-        camera.update();
-    }
-
-    destroy() {
-        this.destroyed = true;
-
-        if (this.stale_flags !== null) {
-            this.stale_flags.destroy();
-            this.stale_flags = null;
-        }
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-VirtualShadowMap.prototype.isVirtualShadowMap = true;
+import { assert } from "../../../../core/assert.js";
+import { quantize_hysteretic } from "../../../../core/geom/clipmap/quantize_hysteretic.js";
+import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import { OrthographicCamera } from "../../camera/OrthographicCamera.js";
+import { Shadowmap } from "../map/Shadowmap.js";
+import { VSMPageManager } from "./VSMPageManager.js";
+
+/**
+ * A directional light's virtual shadow map: a clipmap of world-anchored pages around the main
+ * camera, rendered into a region of the shadow atlas as the GPU asks for them and as movers make
+ * them stale, under a budget of pages per frame.
+ *
+ * The page bookkeeping is {@link VSMPageManager}'s; this holds what ties it to the light and to the
+ * shadow context: the light space, the depth range, the main view's numbers the record carries, the
+ * rows the context claimed for it in the light database, and the pooled views pages are drawn with
+ * ({@link views}, one per page a frame may draw).
+ *
+ * Built and owned by {@link GPUSceneShadowmapContext} when its renderer asks for virtual shadow maps.
+ *
+ * @extends {Shadowmap}
+ */
+export class VirtualShadowMap extends Shadowmap {
+
+    /**
+     * @type {VSMPageManager}
+     * @readonly
+     */
+    manager;
+
+    /**
+     * Distance either side of the snapped camera depth that the light's depth range reaches.
+     * @type {number}
+     * @readonly
+     */
+    depth_extent;
+
+    /**
+     * The map's row of `shadow_virtual`, claimed by the shadow context with the map; -1 before.
+     * @type {number}
+     */
+    record_row = -1;
+
+    /**
+     * First rows of the map's runs of `shadow_virtual_level`, `shadow_virtual_page` and
+     * `shadow_virtual_slot`; -1 before they are claimed.
+     * @type {number}
+     */
+    first_level = -1;
+    first_page = -1;
+    first_slot = -1;
+
+    /**
+     * The map's own frame count, advanced by every {@link update}: what its pages, touches and
+     * readings are stamped with. The map's own because it has to keep rising whichever view the
+     * frame was rendered for — a view's count starts again at zero with each new camera, and a
+     * reading stamped from it would be refused as older than the last one applied.
+     * @type {number}
+     */
+    frame_index = 0;
+
+    /**
+     * What this frame's {@link update} works with, set by the shadow context before it: how many
+     * 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 = 0;
+    lod_bias = 0;
+    view_height = 1;
+
+    /**
+     * One word per pool slot, set on the GPU when a mover crosses the slot and cleared when a
+     * readback lists it — persistent, so a frame whose readback was skipped loses nothing. Created
+     * by the shadow context with the map's rows; null before.
+     * @type {GPUBuffer|null}
+     */
+    stale_flags = null;
+
+    /**
+     * Readbacks of this map's feedback on their way back.
+     * @type {number}
+     */
+    readbacks_in_flight = 0;
+
+    /**
+     * Set once the map is torn down: a reading still in flight is then dropped.
+     * @type {boolean}
+     */
+    destroyed = false;
+
+    /**
+     * The light camera at the world origin; its view matrix is light space.
+     * @type {OrthographicCamera}
+     */
+    light_camera = new OrthographicCamera();
+
+    /**
+     * The light's depth range this frame, as distances along the light from light space's origin.
+     * @type {number}
+     */
+    near = 0;
+    far = 0;
+
+    /**
+     * Where the depth range is centred, along the light, in steps of a quarter of
+     * {@link depth_extent}; set by the first {@link update}.
+     */
+    #depth_index = 0;
+    #depth_centred = false;
+
+    /**
+     * The `shadow_virtual` record, written whole every frame.
+     */
+    #record = {
+        view: new Float32Array(16),
+        camera_position: new Float32Array(3),
+        pixel_angle: 0,
+        near: 0,
+        far: 0,
+        first_texel_size: 0,
+        lod_bias: 0,
+        first_level: 0,
+        level_count: 0,
+        pages_per_level: 0,
+        page_size: 0,
+        border: 0,
+        pool_origin: new Uint32Array(2),
+        slots_per_axis: 0,
+        first_page: 0,
+        page_count: 0,
+        first_slot: 0,
+        slot_count: 0,
+    };
+
+    /**
+     * The `shadow_directional` record: no cascades, and this map.
+     */
+    #directional_record = {
+        first_cascade: GPU_DATABASE_NULL,
+        cascade_count: 0,
+        virtual_map: GPU_DATABASE_NULL,
+    };
+
+    /**
+     * @param {Object} options
+     * @param {number} options.level_count
+     * @param {number} options.pages_per_level
+     * @param {number} options.first_texel_size
+     * @param {number} options.page_size
+     * @param {number} options.border
+     * @param {number} options.pool_size texels on the pool's side
+     * @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,
+                    max_load_factor,
+                    low_load_factor,
+                    max_lod_bias,
+                    lod_bias_step_up,
+                    lod_bias_step_down,
+                }) {
+        super();
+
+        assert.isNumber(depth_extent, 'depth_extent');
+        assert.greaterThan(depth_extent, 0, 'depth_extent');
+
+        this.manager = new VSMPageManager({
+            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,
+        });
+
+        this.depth_extent = depth_extent;
+    }
+
+    /**
+     * Texels on a slot's side: a page and its border.
+     * @returns {number}
+     */
+    get slot_size() {
+        return this.manager.slots.slot_size;
+    }
+
+    /**
+     * 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() {
+        return this.manager.max_load_factor;
+    }
+
+    /**
+     * @param {number} v in `[0, 1]`
+     */
+    set max_load_factor(v) {
+        this.manager.max_load_factor = v;
+    }
+
+    /**
+     * Low-watermark pool demand ratio below which {@link dynamic_lod_bias} steps back down.
+     * @returns {number}
+     */
+    get low_load_factor() {
+        return this.manager.low_load_factor;
+    }
+
+    /**
+     * @param {number} v in `[0, 1]`
+     */
+    set low_load_factor(v) {
+        this.manager.low_load_factor = v;
+    }
+
+    /**
+     * Ceiling on {@link dynamic_lod_bias} (`0` disables dynamic throttling).
+     * @returns {number}
+     */
+    get max_lod_bias() {
+        return this.manager.max_lod_bias;
+    }
+
+    /**
+     * @param {number} v non-negative
+     */
+    set max_lod_bias(v) {
+        this.manager.max_lod_bias = v;
+    }
+
+    /**
+     * Dynamic LOD bias added by {@link manager} under pool pressure.
+     * @returns {number}
+     */
+    get dynamic_lod_bias() {
+        return this.manager.dynamic_lod_bias;
+    }
+
+    /**
+     * Total LOD bias written to the GPU `shadow_virtual` record: {@link lod_bias} plus
+     * {@link dynamic_lod_bias}.
+     * @returns {number}
+     */
+    get effective_lod_bias() {
+        return this.lod_bias + this.manager.dynamic_lod_bias;
+    }
+
+    /**
+     * 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, 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
+     */
+    update(main_camera, scene_ctx) {
+        assert.defined(main_camera, 'main_camera');
+
+        const t = this.light.transform;
+        const light_camera = this.light_camera;
+
+        // turned as the light, at the origin: its view matrix is world to light space
+        light_camera.transform.setRotation(t.rotation_x, t.rotation_y, t.rotation_z, t.rotation_w);
+        light_camera.transform.setTranslation(0, 0, 0);
+        light_camera.update();
+
+        const view = light_camera.view_matrix;
+
+        const c = main_camera.transform;
+        const cx = c.translation_x;
+        const cy = c.translation_y;
+        const cz = c.translation_z;
+
+        const light_x = view[0] * cx + view[4] * cy + view[8] * cz + view[12];
+        const light_y = view[1] * cx + view[5] * cy + view[9] * cz + view[13];
+        const light_depth = -(view[2] * cx + view[6] * cy + view[10] * cz + view[14]);
+
+        // snapped, so the range moves — and every page with it — only when the camera has gone a
+        // quarter of it along the light from where the range is centred: a camera standing on the
+        // plane between two snaps does not move it back and forth. Half a step of hysteresis on
+        // top of the half step makes that threshold a whole step.
+        const snap = this.depth_extent / 4;
+
+        this.#depth_index = quantize_hysteretic(light_depth, this.#depth_index, snap, snap * 0.5, this.#depth_centred);
+        this.#depth_centred = true;
+
+        const depth_centre = this.#depth_index * snap;
+
+        this.near = depth_centre - this.depth_extent;
+        this.far = depth_centre + this.depth_extent;
+
+        const manager = this.manager;
+        const frame = ++this.frame_index;
+
+        manager.set_light_space(view, this.near, this.far, frame);
+        manager.update_windows(light_x, light_y);
+        manager.select(frame, this.page_budget);
+
+        const record = this.#record;
+
+        record.view.set(view);
+        record.camera_position[0] = cx;
+        record.camera_position[1] = cy;
+        record.camera_position[2] = cz;
+
+        // a perspective view's pixel at unit distance; a view without a field of view selects the
+        // finest level everywhere
+        const fov = main_camera.fov;
+        record.pixel_angle = fov === undefined ? 0 : 2 * Math.tan(fov * 0.5) / Math.max(1, this.view_height);
+
+        record.near = this.near;
+        record.far = this.far;
+        record.lod_bias = this.lod_bias + manager.dynamic_lod_bias;
+
+        this.metadata_changed = true;
+    }
+
+    /**
+     * The `shadow_directional` record: an empty cascade range, and this map's `shadow_virtual` row.
+     * @returns {{first_cascade: number, cascade_count: number, virtual_map: number}}
+     */
+    make_record() {
+        this.#directional_record.virtual_map = this.record_row;
+
+        return this.#directional_record;
+    }
+
+    /**
+     * The `shadow_virtual` record as of the last {@link update}.
+     * @returns {object}
+     */
+    make_virtual_record() {
+        const record = this.#record;
+        const manager = this.manager;
+        const pool = this.layout[0];
+
+        record.first_texel_size = manager.first_texel_size;
+        record.first_level = this.first_level;
+        record.level_count = manager.level_count;
+        record.pages_per_level = manager.pages_per_level;
+        record.page_size = manager.page_size;
+        record.border = manager.border;
+        record.pool_origin[0] = pool.x0;
+        record.pool_origin[1] = pool.y0;
+        record.slots_per_axis = manager.slots.slots_per_axis;
+        record.first_page = this.first_page;
+        record.page_count = manager.cell_count;
+        record.first_slot = this.first_slot;
+        record.slot_count = manager.slots.capacity;
+
+        return record;
+    }
+
+    /**
+     * Point a page camera at a page: turned as the light, at the origin, its planes the page's
+     * square widened by its border on every side, the light's depth range.
+     *
+     * @param {OrthographicCamera} camera
+     * @param {number} level
+     * @param {number} x world page
+     * @param {number} y world page
+     */
+    aim_page_camera(camera, level, x, y) {
+        const manager = this.manager;
+        const size = manager.page_world_size(level);
+        const border = size * manager.border / manager.page_size;
+
+        camera.transform.copy(this.light_camera.transform);
+
+        camera.left = x * size - border;
+        camera.right = (x + 1) * size + border;
+        camera.bottom = y * size - border;
+        camera.top = (y + 1) * size + border;
+        camera.near = this.near;
+        camera.far = this.far;
+
+        camera.update();
+    }
+
+    destroy() {
+        this.destroyed = true;
+
+        if (this.stale_flags !== null) {
+            this.stale_flags.destroy();
+            this.stale_flags = null;
+        }
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+VirtualShadowMap.prototype.isVirtualShadowMap = true;