@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -1,43 +1,154 @@
-export class VirtualShadowMap {
-    tile_resolution: number;
+/**
+ * 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 {GPUTextureContext}
+     * @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
      */
-    physical_texture: GPUTextureContext;
+    constructor({ level_count, pages_per_level, first_texel_size, page_size, border, pool_size, request_capacity, protect_frames, depth_extent, }: {
+        level_count: number;
+        pages_per_level: number;
+        first_texel_size: number;
+        page_size: number;
+        border: number;
+        pool_size: number;
+        request_capacity: number;
+        protect_frames: number;
+        depth_extent: number;
+    });
     /**
-     *
+     * @type {VSMPageManager}
+     * @readonly
+     */
+    readonly manager: VSMPageManager;
+    /**
+     * Distance either side of the snapped camera depth that the light's depth range reaches.
+     * @type {number}
+     * @readonly
+     */
+    readonly depth_extent: number;
+    /**
+     * The map's row of `shadow_virtual`, claimed by the shadow context with the map; -1 before.
      * @type {number}
      */
-    resolution_in_tiles: number;
+    record_row: number;
     /**
-     * @type {AbstractLight}
+     * 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}
      */
-    light: AbstractLight;
+    first_level: number;
+    first_page: number;
+    first_slot: number;
     /**
-     * @type {GPUCameraContext[]}
+     * 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: 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.
+     */
+    page_budget: number;
+    lod_bias: number;
+    view_height: number;
+    /**
+     * 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: GPUBuffer | null;
+    /**
+     * Readbacks of this map's feedback on their way back.
+     * @type {number}
      */
-    light_views: GPUCameraContext[];
+    readbacks_in_flight: number;
     /**
-     * @type {GPUBuffer}
+     * Set once the map is torn down: a reading still in flight is then dropped.
+     * @type {boolean}
      */
-    buffer_uniforms: GPUBuffer;
+    destroyed: boolean;
     /**
-     * Quad-tree (implicit) containing references into physical texture
-     * We use buffer because writing into a texture in WebGPU can only be done one LOD at a time
-     * @see https://www.w3.org/TR/WGSL/#texturestore
-     * @type {GPUBuffer}
+     * The light camera at the world origin; its view matrix is light space.
+     * @type {OrthographicCamera}
      */
-    buffer_lookup: GPUBuffer;
-    get total_tile_count(): number;
+    light_camera: OrthographicCamera;
     /**
+     * The light's depth range this frame, as distances along the light from light space's origin.
+     * @type {number}
+     */
+    near: number;
+    far: number;
+    /**
+     * Texels on a slot's side: a page and its border.
+     * @returns {number}
+     */
+    get slot_size(): 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.
+     *
+     * @param {Camera} main_camera
+     * @param {GPUSceneContext} scene_ctx
+     */
+    update(main_camera: Camera, scene_ctx: GPUSceneContext): void;
+    /**
+     * 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(): {
+        first_cascade: number;
+        cascade_count: number;
+        virtual_map: number;
+    };
+    /**
+     * The `shadow_virtual` record as of the last {@link update}.
+     * @returns {object}
+     */
+    make_virtual_record(): object;
+    /**
+     * 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 {GPUDevice} device
-     * @param {number} [virtual_resolution]
-     * @param {number} [physical_resolution]
-     * @param {number} [tile_size]
+     * @param {OrthographicCamera} camera
+     * @param {number} level
+     * @param {number} x world page
+     * @param {number} y world page
+     */
+    aim_page_camera(camera: OrthographicCamera, level: number, x: number, y: number): void;
+    /**
+     * @readonly
+     * @type {boolean}
      */
-    initialize({ device, virtual_resolution, physical_resolution, tile_resolution }: GPUDevice): void;
-    destroy(): void;
+    readonly isVirtualShadowMap: boolean;
+    #private;
 }
-import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
+import { Shadowmap } from "../map/Shadowmap.js";
+import { VSMPageManager } from "./VSMPageManager.js";
+import { OrthographicCamera } from "../../camera/OrthographicCamera.js";
 //# sourceMappingURL=VirtualShadowMap.d.ts.map

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":"AAMA;IAEI,wBAAsB;IAEtB;;OAEG;IACH,kBAFU,iBAAiB,CAEV;IAGjB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,qBAAM;IAEN;;OAEG;IACH,aAFU,kBAAkB,CAEX;IAEjB;;OAEG;IACH,2BAAgB;IAGhB;;;;;OAKG;IACH,yBAAa;IAEb,+BAIC;IAED;;;;;;OAMG;IACH,kGAgFC;IAED,gBAYC;CACJ;kCAvJiC,oCAAoC"}
+{"version":3,"file":"VirtualShadowMap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowMap.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH;IAuHI;;;;;;;;;;;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;IA7JD;;;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;IAmFR;;;OAGG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,8DA2DC;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;0BArUyB,qBAAqB;+BAChB,qBAAqB;mCAFjB,oCAAoC"}

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

@@ -1,155 +1,335 @@
-import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
-import { split_by_2 } from "../../../../core/binary/split_by_2.js";
-import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
-import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
-import { VSM_UNIFORMS_STRUCT } from "./VSM_UNIFORMS_STRUCT.js";
+import { assert } from "../../../../core/assert.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 {
 
-export class VirtualShadowMap {
+    /**
+     * @type {VSMPageManager}
+     * @readonly
+     */
+    manager;
 
-    tile_resolution = 128;
+    /**
+     * 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;
 
     /**
-     * @type {GPUTextureContext}
+     * 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}
      */
-    physical_texture;
+    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}
      */
-    resolution_in_tiles = 0;
+    readbacks_in_flight = 0;
+
+    /**
+     * Set once the map is torn down: a reading still in flight is then dropped.
+     * @type {boolean}
+     */
+    destroyed = false;
 
     /**
-     * @type {AbstractLight}
+     * The light camera at the world origin; its view matrix is light space.
+     * @type {OrthographicCamera}
      */
-    light;
+    light_camera = new OrthographicCamera();
 
     /**
-     * @type {GPUCameraContext[]}
+     * The light's depth range this frame, as distances along the light from light space's origin.
+     * @type {number}
      */
-    light_views = [];
+    near = 0;
+    far = 0;
 
     /**
-     * @type {GPUBuffer}
+     * Where the depth range is centred, along the light; set by the first {@link update}.
      */
-    buffer_uniforms;
+    #depth_centre = 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,
+    };
 
     /**
-     * Quad-tree (implicit) containing references into physical texture
-     * We use buffer because writing into a texture in WebGPU can only be done one LOD at a time
-     * @see https://www.w3.org/TR/WGSL/#texturestore
-     * @type {GPUBuffer}
+     * @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
      */
-    buffer_lookup
+    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,
+        });
 
-    get total_tile_count(){
-        const max_mip_level = Math.log2(this.resolution_in_tiles);
+        this.depth_extent = depth_extent;
+    }
 
-        return split_by_2((1 << (max_mip_level + 1)) - 1);
+    /**
+     * 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 {GPUDevice} device
-     * @param {number} [virtual_resolution]
-     * @param {number} [physical_resolution]
-     * @param {number} [tile_size]
-     */
-    initialize({
-                   device,
-                   virtual_resolution = 4096,
-                   physical_resolution = 1024,
-                   tile_resolution = 128
-               }) {
-
-        if (!isPowerOfTwo(virtual_resolution)) {
-            throw new Error(`virtual_resolution must be a power of two, instead was ${virtual_resolution}`);
-        }
+     * @param {Camera} main_camera
+     * @param {GPUSceneContext} scene_ctx
+     */
+    update(main_camera, scene_ctx) {
+        assert.defined(main_camera, 'main_camera');
 
-        if (!isPowerOfTwo(tile_resolution)) {
-            throw new Error(`tile_resolution must be a power of two, instead was ${tile_resolution}`);
-        }
+        const t = this.light.transform;
+        const light_camera = this.light_camera;
 
-        this.tile_resolution = tile_resolution;
+        // 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 resolution_limit = device.limits.maxTextureDimension2D;
+        const view = light_camera.view_matrix;
 
-        let _actual_physical_resolution;
+        const c = main_camera.transform;
+        const cx = c.translation_x;
+        const cy = c.translation_y;
+        const cz = c.translation_z;
 
-        if (physical_resolution > resolution_limit) {
-            _actual_physical_resolution = resolution_limit;
-            console.warn(`Requested physical resolution (=${physical_resolution}) exceeds device limit (=${resolution_limit}), defaulting to limit instead`);
-        } else {
-            _actual_physical_resolution = physical_resolution;
-        }
+        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]);
 
-        if (virtual_resolution <= _actual_physical_resolution) {
-            console.warn(`physical_resolution(=${_actual_physical_resolution}) >= virtual_resolution(=${virtual_resolution}), this is a pointless configuration. Likely a mistake`);
+        // 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
+        const snap = this.depth_extent / 4;
+
+        if (!this.#depth_centred || Math.abs(light_depth - this.#depth_centre) > snap) {
+            this.#depth_centre = Math.round(light_depth / snap) * snap;
+            this.#depth_centred = true;
         }
 
-        this.resolution_in_tiles = Math.floor(virtual_resolution / this.tile_resolution);
+        this.near = this.#depth_centre - this.depth_extent;
+        this.far = this.#depth_centre + this.depth_extent;
 
+        const manager = this.manager;
+        const frame = ++this.frame_index;
 
-        // initialize physical texture
-        this.physical_texture = new GPUTextureContext(device);
-        const physical_descriptor = this.physical_texture.descriptor;
+        manager.set_light_space(view, this.near, this.far, frame);
+        manager.update_windows(light_x, light_y);
+        manager.select(frame, this.page_budget);
 
-        physical_descriptor.format = "depth16unorm";
-        physical_descriptor.dimension = "2d";
-        physical_descriptor.size = [_actual_physical_resolution, _actual_physical_resolution];
-        physical_descriptor.mipLevelCount = 1;
-        physical_descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT;
+        const record = this.#record;
 
-        //
-        this.buffer_uniforms = device.createBuffer({
-            label: "Virtual Shadow Map / uniforms",
-            size: VSM_UNIFORMS_STRUCT.size,
-            usage: GPUBufferUsage.UNIFORM,
-            mappedAtCreation: true
-        });
+        record.view.set(view);
+        record.camera_position[0] = cx;
+        record.camera_position[1] = cy;
+        record.camera_position[2] = cz;
 
-        const buffer_uniforms_data = this.buffer_uniforms.getMappedRange();
+        // 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;
+    }
 
-        const buffer_uniforms_view = new DataView(buffer_uniforms_data);
+    /**
+     * 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;
 
-        buffer_uniforms_view.setUint32(VSM_UNIFORMS_STRUCT.get('tile_resolution').offset, tile_resolution, platform_compute_endianness());
-        buffer_uniforms_view.setUint32(VSM_UNIFORMS_STRUCT.get('resolution_in_tiles').offset, this.resolution_in_tiles, platform_compute_endianness());
+        return this.#directional_record;
+    }
 
-        this.buffer_uniforms.unmap();
+    /**
+     * 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;
 
-        /*
-         One entry per NODE of the implicit quadtree, which is what total_tile_count computes.
+        camera.transform.copy(this.light_camera.transform);
 
-         The size used to be resolution_in_tiles * 4/3, a side length where a node count belongs.
-         For the 16384 / 256 configuration GPUViewShadowMaps asks for, that is 86 entries against
-         the 5461 the tree has: an indexing shader reads zeros past node 85 where storage access is
-         clamped, and fails buffer-size validation at bind time where it is not. Nothing binds this
-         today because VirtualShadowmapRenderer is never constructed, so the shape of the failure
-         matters more than the count: it would look like a shader bug.
-        */
-        this.buffer_lookup = device.createBuffer({
-            label:"VSM / lookup",
-            size: Uint32Array.BYTES_PER_ELEMENT * this.total_tile_count,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
-        });
+        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;
 
-        for (const v of this.light_views) {
-            v.destroy();
-        }
-
-        this.light_views.splice(0, this.light_views.length);
-
-        if (this.physical_texture !== undefined) {
-            this.physical_texture.destroy();
-            this.physical_texture = undefined;
+        if (this.stale_flags !== null) {
+            this.stale_flags.destroy();
+            this.stale_flags = null;
         }
     }
-}
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+VirtualShadowMap.prototype.isVirtualShadowMap = true;

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

@@ -0,0 +1,39 @@
+/**
+ * Record a frame's virtual shadow map feedback into the `Shading` graph, once the main view's depth
+ * exists, and read it back.
+ *
+ * 1. **Movers**, once for the scene: every mesh row against the box it had last frame, and every
+ *    skinned mesh against the pose it had, into one list ({@link shader_vsm_movers},
+ *    {@link shader_vsm_skinned_movers}).
+ * 2. **Stale**, every frame for every map: the slots under a mover flagged in the map's persistent
+ *    flags ({@link shader_vsm_stale}, sized indirectly to the movers).
+ * 3. **Feedback**, for a map under its readback cap: the pages the view's pixels ask for
+ *    ({@link shader_vsm_demand}) with their pixel counts ({@link shader_vsm_gather_counts}), and the
+ *    flagged slots listed and cleared ({@link shader_vsm_stale_compact}) — read back and handed to
+ *    the map's {@link VSMPageManager#apply_reading} with the frame they were recorded in.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {import("../../view/GPUViewContext.js").GPUViewContext} options.view the view whose depth asks for pages
+ * @param {number} options.depth graph handle of the view's depth
+ * @param {VirtualShadowMap[]} options.maps
+ * @param {VSMMoverTracker} options.tracker the scene's casters as last seen
+ * @param {GPUDatabase} options.light_database
+ */
+export function graph_vsm_feedback({ graph, view, depth, maps, tracker, light_database, }: {
+    graph: FrameGraph;
+    view: import("../../view/GPUViewContext.js").GPUViewContext;
+    depth: number;
+    maps: VirtualShadowMap[];
+    tracker: VSMMoverTracker;
+    light_database: GPUDatabase;
+}): void;
+/**
+ * Readbacks of one map's feedback in flight at most: VT's cap. A frame that would go past it skips
+ * its readback — its wants come again the next frame, and its stale flags stay set until a readback
+ * lists them.
+ *
+ * @type {number}
+ */
+export const VSM_READBACKS_IN_FLIGHT: number;
+//# sourceMappingURL=graph_vsm_feedback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_vsm_feedback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/graph_vsm_feedback.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAP+B,KAAK;IACsC,IAAI,EAAnE,OAAO,8BAA8B,EAAE,cAAc;IACrC,KAAK,EAArB,MAAM;IACsB,IAAI,EAAhC,kBAAkB;IACO,OAAO;IACX,cAAc;SAsG7C;AAnID;;;;;;GAMG;AACH,sCAFU,MAAM,CAEyB"}