@woosh/meep-engine 3.39.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_resolution]
+     * @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":"AAIA;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,+BAGC;IAED;;;;;;OAMG;IACH,kGAuFC;IAED,gBAsBC;CACJ;kCAvKiC,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,169 +1,335 @@
-import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.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;
 
     /**
-     * @type {GPUTextureContext}
+     * The map's row of `shadow_virtual`, claimed by the shadow context with the map; -1 before.
+     * @type {number}
      */
-    physical_texture;
+    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}
      */
-    resolution_in_tiles = 0;
+    frame_index = 0;
 
     /**
-     * @type {AbstractLight}
+     * 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.
      */
-    light;
+    page_budget = 0;
+    lod_bias = 0;
+    view_height = 1;
 
     /**
-     * @type {GPUCameraContext[]}
+     * 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}
      */
-    light_views = [];
+    stale_flags = null;
 
     /**
-     * @type {GPUBuffer}
+     * Readbacks of this map's feedback on their way back.
+     * @type {number}
      */
-    buffer_uniforms;
+    readbacks_in_flight = 0;
 
+    /**
+     * Set once the map is torn down: a reading still in flight is then dropped.
+     * @type {boolean}
+     */
+    destroyed = false;
 
     /**
-     * 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
+    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; set by the first {@link update}.
+     */
+    #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,
+    };
+
+    /**
+     * @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;
+    }
 
-    get total_tile_count() {
-        // Sum of the square grids at every level: 1 + 4 + ... + resolution_in_tiles^2.
-        return this.resolution_in_tiles === 0 ? 0 : (4 * this.resolution_in_tiles ** 2 - 1) / 3;
+    /**
+     * 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_resolution]
-     */
-    initialize({
-                   device,
-                   virtual_resolution = 4096,
-                   physical_resolution = 1024,
-                   tile_resolution = 128
-               }) {
-
-        if (!Number.isSafeInteger(virtual_resolution) || virtual_resolution <= 0
-            || virtual_resolution > 0xffffffff || !Number.isInteger(Math.log2(virtual_resolution))) {
-            throw new RangeError(`virtual_resolution must be a positive u32 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 (!Number.isSafeInteger(tile_resolution) || tile_resolution <= 0
-            || tile_resolution > virtual_resolution || !Number.isInteger(Math.log2(tile_resolution))) {
-            throw new RangeError(`tile_resolution must be a positive power of two no larger than virtual_resolution, instead was ${tile_resolution}`);
-        }
+        const t = this.light.transform;
+        const light_camera = this.light_camera;
 
-        if (!Number.isSafeInteger(physical_resolution) || physical_resolution <= 0) {
-            throw new RangeError(`physical_resolution must be a positive integer, instead was ${physical_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;
-        // Pages cannot straddle the edge of the physical atlas, including after device clamping.
-        const physical_tiles_per_side = Math.floor(Math.min(physical_resolution, resolution_limit) / tile_resolution);
-        const _actual_physical_resolution = physical_tiles_per_side * tile_resolution;
-        if (physical_tiles_per_side === 0) {
-            throw new RangeError('The physical atlas must fit at least one tile within the device texture limit');
-        }
+        const view = light_camera.view_matrix;
 
-        const resolution_in_tiles = virtual_resolution / tile_resolution;
-        const total_tile_count = (4 * resolution_in_tiles ** 2 - 1) / 3;
-        const lookup_size = total_tile_count * Uint32Array.BYTES_PER_ELEMENT;
-        // The shaders spread at most sixteen bits and dispatch one invocation per tree node.
-        if (resolution_in_tiles > 32768 || lookup_size > device.limits.maxBufferSize
-            || lookup_size > device.limits.maxStorageBufferBindingSize
-            || Math.ceil(total_tile_count / 256) > device.limits.maxComputeWorkgroupsPerDimension) {
-            throw new RangeError('The virtual tile tree exceeds the shader or device buffer/dispatch limits');
-        }
+        const c = main_camera.transform;
+        const cx = c.translation_x;
+        const cy = c.translation_y;
+        const cz = c.translation_z;
 
-        // Validate first so an invalid replacement leaves the existing map intact.
-        this.destroy();
-        this.tile_resolution = tile_resolution;
-        this.resolution_in_tiles = resolution_in_tiles;
+        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
+        const snap = this.depth_extent / 4;
 
-        // initialize physical texture
-        this.physical_texture = new GPUTextureContext(device);
-        const physical_descriptor = this.physical_texture.descriptor;
+        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;
+        }
 
-        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;
+        this.near = this.#depth_centre - this.depth_extent;
+        this.far = this.#depth_centre + this.depth_extent;
 
-        //
-        this.buffer_uniforms = device.createBuffer({
-            label: "Virtual Shadow Map / uniforms",
-            size: VSM_UNIFORMS_STRUCT.size,
-            usage: GPUBufferUsage.UNIFORM,
-            mappedAtCreation: true
-        });
+        const manager = this.manager;
+        const frame = ++this.frame_index;
 
-        const buffer_uniforms_data = this.buffer_uniforms.getMappedRange();
+        manager.set_light_space(view, this.near, this.far, frame);
+        manager.update_windows(light_x, light_y);
+        manager.select(frame, this.page_budget);
 
-        const buffer_uniforms_view = new DataView(buffer_uniforms_data);
+        const record = this.#record;
 
-        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());
-        buffer_uniforms_view.setUint32(VSM_UNIFORMS_STRUCT.get('physical_tile_count').offset, physical_tiles_per_side ** 2, platform_compute_endianness());
+        record.view.set(view);
+        record.camera_position[0] = cx;
+        record.camera_position[1] = cy;
+        record.camera_position[2] = cz;
 
-        this.buffer_uniforms.unmap();
+        // 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;
 
-        // One entry per node of the implicit quadtree.
-        this.buffer_lookup = device.createBuffer({
-            label:"VSM / lookup",
-            size: Uint32Array.BYTES_PER_ELEMENT * this.total_tile_count,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            mappedAtCreation: true
-        });
-        // Page zero is a valid allocation, so a zero-initialized table would claim that every
-        // virtual tile already has a page before the first allocation pass has run.
-        new Uint32Array(this.buffer_lookup.getMappedRange()).fill(0xffffffff);
-        this.buffer_lookup.unmap();
+        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;
     }
 
-    destroy() {
+    /**
+     * 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;
+    }
 
-        for (const v of this.light_views) {
-            v.destroy();
-        }
+    /**
+     * 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;
 
-        this.light_views.splice(0, this.light_views.length);
+        camera.transform.copy(this.light_camera.transform);
 
-        if (this.physical_texture !== undefined) {
-            this.physical_texture.destroy();
-            this.physical_texture = undefined;
-        }
+        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;
 
-        if (this.buffer_uniforms !== undefined) {
-            this.buffer_uniforms.destroy();
-            this.buffer_uniforms = undefined;
-        }
-        if (this.buffer_lookup !== undefined) {
-            this.buffer_lookup.destroy();
-            this.buffer_lookup = undefined;
+        camera.update();
+    }
+
+    destroy() {
+        this.destroyed = true;
+
+        if (this.stale_flags !== null) {
+            this.stale_flags.destroy();
+            this.stale_flags = null;
         }
-        this.resolution_in_tiles = 0;
     }
 }
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+VirtualShadowMap.prototype.isVirtualShadowMap = true;