@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -24,8 +24,13 @@ import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 import { RenderTarget } from "../../texture/RenderTarget.js";
 import { View } from "../../view/View.js";
 import { ViewManager } from "../../view/ViewManager.js";
-import { CSM_CASTER_RANGE_UNKNOWN, CSM_CASTER_RANGE_UNKNOWN_BITS } from "./csm/CSM_CASTER_RANGE_STRUCT.js";
-import { SHADOWMAP_CSM_CASCADE_COUNT } from "./csm/SHADOWMAP_CSM_CASCADE_COUNT.js";
+import { generate_record_writer } from "../../buffer/table/serde/generate_record_writer.js";
+import {
+    CSM_CASCADE_STRUCT,
+    CSM_CASTER_RANGE_UNKNOWN,
+    CSM_CASTER_RANGE_UNKNOWN_BITS
+} from "./csm/CSM_CASCADE_STRUCT.js";
+import { SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT } from "./csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.js";
 import {
     CSM_CASTER_RANGE_SETTINGS_STRUCT,
     CSM_CASTER_RANGE_WORKGROUP_SIZE,
@@ -58,6 +63,13 @@ import { ShadowmapDrawSelector } from "./ShadowmapDrawSelector.js";
 import { ShadowmapRegistry } from "./ShadowmapRegistry.js";
 import { ShadowmapResolutionPolicy } from "./ShadowmapResolutionPolicy.js";
 import { SpotLightShadowmap } from "./SpotLightShadowmap.js";
+import { DEFAULT_VSM_FIRST_TEXEL_SIZE } from "../vsm/DEFAULT_VSM_FIRST_TEXEL_SIZE.js";
+import { DEFAULT_VSM_PAGE_BUDGET } from "../vsm/DEFAULT_VSM_PAGE_BUDGET.js";
+import { graph_vsm_feedback } from "../vsm/graph_vsm_feedback.js";
+import { VirtualShadowMap } from "../vsm/VirtualShadowMap.js";
+import { VSMMoverTracker } from "../vsm/VSMMoverTracker.js";
+import { VSM_DEFAULT_REQUEST_CAPACITY } from "../vsm/VSM_FEEDBACK_LAYOUT.js";
+import { VSM_SLOT_EMPTY } from "../vsm/VSM_SLOT_STRUCT.js";
 
 /**
  * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
@@ -67,6 +79,7 @@ import { SpotLightShadowmap } from "./SpotLightShadowmap.js";
  * @typedef {import("../../light/model/Light.js").Light} Light
  * @typedef {import("../../scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
  * @typedef {import("./Shadowmap.js").Shadowmap} Shadowmap
+ * @typedef {import("../../buffer/table/serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
  */
 
 const DEFAULT_SHADOWMAP_ATLAS_RESOLUTION = 4096 * 2;
@@ -88,6 +101,49 @@ const DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION = [
  */
 const DEFAULT_SHADOWMAP_LOCAL_RESOLUTION = 128;
 
+/**
+ * How every shadow caster is culled: as the main view culls it, so a caster's front faces are what
+ * reach the shadow map and acne is the shared rasterizer slope bias's to prevent
+ * ({@link DEPTH_STENCIL_STATE_SHADOW}). Casting back faces on top of that bias pushed a caster's
+ * steep far face past the ground at its base, a gap of 1–1.5 shadow texels at every contact.
+ * @type {Readonly<Record<number, GPUCullMode>>}
+ */
+const SHADOW_CULL_POLICY = CullPolicy.Standard;
+
+/**
+ * Writes the CPU's half of a `shadow_cascade` row and leaves `caster_near`, the GPU's, alone.
+ * @type {GPURecordWriter}
+ */
+const CASCADE_VIEW_WRITER = generate_record_writer(CSM_CASCADE_STRUCT, ['atlas', 'projection']);
+
+/**
+ * A virtual shadow map's clipmap: levels, and pages on a side of each level's window. Twelve levels
+ * of 64² pages at the default 1 cm first texel reach from 41 m windows at level 0 to 168 km at the
+ * coarsest; see {@link VirtualShadowMap}.
+ */
+const VSM_LEVEL_COUNT = 12;
+const VSM_PAGES_PER_LEVEL = 64;
+
+/**
+ * Texels on a side of a virtual shadow map page — the reference's and UE's 128 — and of the pool
+ * the map claims in the atlas for them, 30 × 30 slots of 128 plus {@link SHADOWMAP_ATLAS_BORDER}
+ * each side. A device whose atlas is smaller gets a pool of what fits.
+ */
+const VSM_PAGE_SIZE = 128;
+const VSM_POOL_SIZE = 30 * (VSM_PAGE_SIZE + 2 * SHADOWMAP_ATLAS_BORDER);
+
+/**
+ * How far either side of the camera's snapped depth along the light a virtual shadow map's depth
+ * range reaches, in metres. Casters further toward the light than this are clipped.
+ */
+const VSM_DEPTH_EXTENT = 1000;
+
+/**
+ * Frames a page something looked at is safe from eviction for: longer than a reading takes to come
+ * back with three readbacks in flight.
+ */
+const VSM_PROTECT_FRAMES = 6;
+
 /**
  * Shadows for a single scene
  */
@@ -177,6 +233,102 @@ export class GPUSceneShadowmapContext {
      */
     use_tetrahedron_point_shadows = false;
 
+    /**
+     * Gives directional lights virtual shadow maps instead of cascades. The renderer pushes this
+     * from its `feature_virtual_shadow_maps` flag before each light update, alongside
+     * {@link enabled}; a flip is picked up in {@link process_lights}, which rebuilds every
+     * directional map of the other kind on the same pass, as it does for the point-light generator.
+     * @type {boolean}
+     */
+    use_virtual_shadow_maps = false;
+
+    /**
+     * Pages the scene's virtual shadow maps may render per frame. See {@link virtual_page_budget}.
+     * @type {number}
+     */
+    #virtual_page_budget = DEFAULT_VSM_PAGE_BUDGET;
+
+    /**
+     * @returns {number} pages per frame, across the scene's virtual shadow maps
+     */
+    get virtual_page_budget() {
+        return this.#virtual_page_budget;
+    }
+
+    /**
+     * The renderer pushes this from {@link Renderer.shadow_virtual_page_budget} every frame. Pages a
+     * frame wants beyond it wait, best first, for the next.
+     *
+     * @param {number} v pages per frame; zero draws none and leaves every page as it is
+     */
+    set virtual_page_budget(v) {
+        assert.isNonNegativeInteger(v, 'virtual_page_budget');
+
+        this.#virtual_page_budget = v;
+    }
+
+    /**
+     * Added to the level every point of a virtual shadow map selects; positive is coarser. Pushed by
+     * the renderer every frame and written into each map's record, so a change takes effect on the
+     * next frame's demand and sampling alike.
+     * @type {number}
+     */
+    virtual_lod_bias = 0;
+
+    /**
+     * World size of a virtual shadow map's level-0 texel. See {@link virtual_first_texel_size}.
+     * @type {number}
+     */
+    #virtual_first_texel_size = DEFAULT_VSM_FIRST_TEXEL_SIZE;
+
+    /**
+     * @returns {number}
+     */
+    get virtual_first_texel_size() {
+        return this.#virtual_first_texel_size;
+    }
+
+    /**
+     * Pushed from {@link Renderer.shadow_virtual_first_texel_size}. A change rebuilds every virtual
+     * shadow map in {@link process_lights}: every page of the clipmap changes size.
+     *
+     * @param {number} v metres, positive
+     */
+    set virtual_first_texel_size(v) {
+        assert.isNumber(v, 'virtual_first_texel_size');
+        assert.greaterThan(v, 0, 'virtual_first_texel_size');
+
+        this.#virtual_first_texel_size = v;
+    }
+
+    /**
+     * How many cascades a directional shadow map is built with. See {@link cascade_count}.
+     * @type {number}
+     */
+    #cascade_count = SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT;
+
+    /**
+     * @returns {number} cascades per directional shadow map
+     */
+    get cascade_count() {
+        return this.#cascade_count;
+    }
+
+    /**
+     * The renderer pushes this from {@link Renderer.shadow_cascade_count} before each light update,
+     * alongside {@link enabled}. A change is picked up in {@link process_lights}: every directional
+     * map built with another count is evicted and rebuilt with this one in the same pass, which
+     * gives its atlas rects back first. A rebuilt map has no caster range until its first readback
+     * lands, two frames on, so its near planes are its slices' own until then.
+     *
+     * @param {number} v at least one
+     */
+    set cascade_count(v) {
+        assert.isPositiveInteger(v, 'cascade_count');
+
+        this.#cascade_count = v;
+    }
+
     /**
      * Frame index of the most recent {@link select_for_draw} call. Passed to {@link draw} via
      * this field so we don't have to thread it through the call again — draw() stamps
@@ -247,36 +399,56 @@ export class GPUSceneShadowmapContext {
     #scene_ctx;
 
     /**
-     * Rows of the light database's `shadow_csm_caster_range` table given back by evicted maps,
-     * to be claimed again before a new row is.
-     * @type {number[]}
+     * One word per row of the light database's `shadow_cascade` table, the accumulate pass's
+     * scratch, holding plain f32 bit patterns seeded to {@link CSM_CASTER_RANGE_UNKNOWN} and reset
+     * to it by each publish.
+     * @type {GPUBuffer|null}
      */
-    #caster_rows_free = [];
+    #caster_scratch = null;
 
     /**
-     * Rows ever claimed; the next new row.
+     * Cascade rows {@link #caster_scratch} has words for.
      * @type {number}
      */
-    #caster_row_count = 0;
+    #caster_scratch_rows = 0;
 
     /**
-     * One word per cascade per claimed row, the accumulate pass's scratch, holding plain f32 bit
-     * patterns seeded to {@link CSM_CASTER_RANGE_UNKNOWN} and reset to it by each publish.
-     * @type {GPUBuffer|null}
+     * The readback service's handle for the `shadow_cascade` table, taken on first use.
+     * @type {number}
      */
-    #caster_scratch = null;
+    #cascade_table = -1;
 
     /**
-     * Rows {@link #caster_scratch} has words for.
-     * @type {number}
+     * Scratch for {@link #write_shadow_records}: the CPU's half of one cascade row.
+     * @type {{atlas: number[], projection: ArrayLike<number>}}
      */
-    #caster_scratch_rows = 0;
+    #cascade_record = { atlas: [0, 0, 0, 0], projection: null };
+
+    /**
+     * Scratch for {@link #write_virtual_rows}: one `shadow_virtual_slot` row, and one window corner.
+     */
+    #virtual_slot_record = { level: 0, x: 0, y: 0 };
+    #virtual_level_record = [0, 0];
+
+    /**
+     * Where the scene's casters were last frame, for the virtual shadow maps' mover pass. Made on the
+     * first frame a virtual map asks for feedback.
+     * @type {VSMMoverTracker|null}
+     */
+    #vsm_movers = null;
 
     /**
-     * The readback service's handle for the caster range table, taken on first use.
+     * Which virtual map's turn it is to take the first of the page budget's remainder; advanced by
+     * every {@link select_for_draw}.
      * @type {number}
      */
-    #caster_range_table = -1;
+    #virtual_budget_turn = 0;
+
+    /**
+     * Scratch for {@link graph_virtual_feedback}: the scene's virtual maps this frame.
+     * @type {VirtualShadowMap[]}
+     */
+    #vsm_feedback_maps = [];
 
     /**
      * @returns {number} number of shadowmaps rasterized in the most recent draw pass
@@ -405,45 +577,54 @@ export class GPUSceneShadowmapContext {
     }
 
     /**
-     * The readback service's handle for the light database's `shadow_csm_caster_range` table —
-     * what a directional map asks its range through.
+     * The readback service's handle for the light database's `shadow_cascade` table — what a
+     * directional map asks its caster range through.
      *
      * @returns {number}
      */
-    get caster_range_table() {
-        if (this.#caster_range_table === -1) {
-            this.#caster_range_table = this.#owner.readback.table('shadow_csm_caster_range');
+    get cascade_table() {
+        if (this.#cascade_table === -1) {
+            this.#cascade_table = this.#owner.readback.table('shadow_cascade');
         }
 
-        return this.#caster_range_table;
+        return this.#cascade_table;
     }
 
     /**
-     * Give a directional map its row of the caster range table and its words of the scratch.
+     * Give a directional map a run of `shadow_cascade` rows, one per cascade, and their words of
+     * the scratch.
      *
      * @param {DirectionalLightShadowmap} map
      */
-    #claim_caster_row(map) {
-        const free = this.#caster_rows_free;
-        const row = free.length > 0 ? free.pop() : this.#caster_row_count++;
+    #claim_cascades(map) {
+        const count = map.cascade_count;
+        const records = new Array(count);
+
+        for (let i = 0; i < count; i++) {
+            // The CPU writes the whole row once, its range unknown; from here on it writes only its
+            // own fields and the GPU writes the range. The atlas and projection are written by the
+            // map's first draw, before anything samples them.
+            records[i] = {
+                atlas: [0, 0, 0, 0],
+                projection: new Float32Array(16),
+                caster_near: CSM_CASTER_RANGE_UNKNOWN,
+            };
+        }
 
-        // the CPU writes the row once, as unknown; the GPU writes it from here on
-        this.#owner.database.get('shadow_csm_caster_range').set(row, {
-            near: new Float32Array(SHADOWMAP_CSM_CASCADE_COUNT).fill(CSM_CASTER_RANGE_UNKNOWN),
-        });
+        const first = this.#owner.database.get('shadow_cascade').add_run(records);
 
-        map.caster_row = row;
-        map.caster_settings.base = row * SHADOWMAP_CSM_CASCADE_COUNT;
+        map.first_cascade = first;
+        map.caster_settings.base = first;
         map.caster_range_valid = false;
         map.caster_range.fill(NaN);
 
-        const rows_needed = row + 1;
+        const rows_needed = first + count;
 
         if (rows_needed > this.#caster_scratch_rows) {
             // Grown by replacement rather than copied: every claimed row's words are unknown
             // between frames — the publish resets them — so a fresh seed loses nothing.
             const rows = Math.max(rows_needed, this.#caster_scratch_rows * 2, 4);
-            const words = new Uint32Array(rows * SHADOWMAP_CSM_CASCADE_COUNT).fill(CSM_CASTER_RANGE_UNKNOWN_BITS);
+            const words = new Uint32Array(rows).fill(CSM_CASTER_RANGE_UNKNOWN_BITS);
             const device = this.#graphics.device;
 
             if (this.#caster_scratch !== null) {
@@ -463,27 +644,281 @@ export class GPUSceneShadowmapContext {
     }
 
     /**
-     * Take a directional map's caster range row back.
+     * Take a directional map's cascade rows back. A readback still in flight for one of them is
+     * dropped, its row's generation having moved.
      *
      * @param {DirectionalLightShadowmap} map
      */
-    #release_caster_row(map) {
-        const row = map.caster_row;
+    #release_cascades(map) {
+        const first = map.first_cascade;
 
-        if (row === -1) {
+        if (first === -1) {
             return;
         }
 
-        this.#owner.database.get('shadow_csm_caster_range').remove(row);
-        this.#caster_rows_free.push(row);
+        const table = this.#owner.database.get('shadow_cascade');
 
-        map.caster_row = -1;
+        for (let i = 0; i < map.cascade_count; i++) {
+            table.remove(first + i);
+        }
+
+        map.first_cascade = -1;
         map.caster_range_valid = false;
     }
 
     /**
-     * Measure this frame's casters against the map's cascades and publish the result to its row,
-     * for the readback to carry to the next frame's fit.
+     * Give a virtual shadow map its rows of the light database: its `shadow_virtual` record, and its
+     * runs of window corners, page-table entries — every cell empty — and slots — every slot empty.
+     * The record is written for real by the map's first draw, before anything samples it.
+     *
+     * @param {VirtualShadowMap} map
+     */
+    #claim_virtual(map) {
+        const database = this.#owner.database;
+        const manager = map.manager;
+
+        const levels = new Array(manager.level_count);
+
+        for (let i = 0; i < levels.length; i++) {
+            levels[i] = [0, 0];
+        }
+
+        const pages = new Array(manager.cell_count).fill(0);
+        const slots = new Array(manager.slots.capacity);
+
+        for (let i = 0; i < slots.length; i++) {
+            slots[i] = { level: VSM_SLOT_EMPTY, x: 0, y: 0 };
+        }
+
+        map.first_level = database.get('shadow_virtual_level').add_run(levels);
+        map.first_page = database.get('shadow_virtual_page').add_run(pages);
+        map.first_slot = database.get('shadow_virtual_slot').add_run(slots);
+        map.record_row = database.get('shadow_virtual').add(map.make_virtual_record());
+
+        // zeroed at creation: no slot has a mover over it yet
+        map.stale_flags = this.#graphics.device.createBuffer({
+            label: 'VSM / stale flags',
+            size: manager.slots.capacity * Uint32Array.BYTES_PER_ELEMENT,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+    }
+
+    /**
+     * Take a virtual shadow map's rows back. The page and slot rows the GPU reads go with the
+     * record that names them.
+     *
+     * @param {VirtualShadowMap} map
+     */
+    #release_virtual(map) {
+        if (map.record_row === -1) {
+            return;
+        }
+
+        const database = this.#owner.database;
+        const manager = map.manager;
+
+        const t_levels = database.get('shadow_virtual_level');
+        const t_pages = database.get('shadow_virtual_page');
+        const t_slots = database.get('shadow_virtual_slot');
+
+        for (let i = 0; i < manager.level_count; i++) {
+            t_levels.remove(map.first_level + i);
+        }
+
+        for (let i = 0; i < manager.cell_count; i++) {
+            t_pages.remove(map.first_page + i);
+        }
+
+        for (let i = 0; i < manager.slots.capacity; i++) {
+            t_slots.remove(map.first_slot + i);
+        }
+
+        database.get('shadow_virtual').remove(map.record_row);
+
+        map.record_row = -1;
+        map.first_level = -1;
+        map.first_page = -1;
+        map.first_slot = -1;
+    }
+
+    /**
+     * Write the rows of a virtual shadow map that changed since the last frame — page-table entries
+     * of cells installed, evicted or scrolled away, slots that changed hands, and window corners —
+     * and then its record.
+     *
+     * @param {VirtualShadowMap} map
+     * @param {GPUDatabase} database
+     */
+    #write_virtual_rows(map, database) {
+        const manager = map.manager;
+
+        const t_pages = database.get('shadow_virtual_page');
+        const t_slots = database.get('shadow_virtual_slot');
+
+        for (let i = 0; i < manager.dirty_cell_count; i++) {
+            const cell = manager.dirty_cell(i);
+
+            t_pages.set(map.first_page + cell, manager.cell_entry(cell));
+        }
+
+        const slot_record = this.#virtual_slot_record;
+
+        for (let i = 0; i < manager.dirty_slot_count; i++) {
+            const slot = manager.dirty_slot(i);
+            const level = manager.slot_level(slot);
+
+            slot_record.level = level === -1 ? VSM_SLOT_EMPTY : level;
+            slot_record.x = manager.slot_x(slot);
+            slot_record.y = manager.slot_y(slot);
+
+            t_slots.set(map.first_slot + slot, slot_record);
+        }
+
+        if (manager.levels_dirty) {
+            const t_levels = database.get('shadow_virtual_level');
+            const corner = this.#virtual_level_record;
+
+            for (let level = 0; level < manager.level_count; level++) {
+                corner[0] = manager.origin_x(level);
+                corner[1] = manager.origin_y(level);
+
+                t_levels.set(map.first_level + level, corner);
+            }
+        }
+
+        manager.clear_dirty();
+
+        database.get('shadow_virtual').set(map.record_row, map.make_virtual_record());
+    }
+
+    /**
+     * Record this frame's virtual shadow map feedback — the casters that moved, the pages they made
+     * stale, the pages the view's pixels ask for — into the frame's `Shading` graph once the main
+     * view's depth exists, and read it back for the maps' next frames. Does nothing in a scene
+     * without virtual shadow maps. See {@link graph_vsm_feedback}.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {import("../../view/GPUViewContext.js").GPUViewContext} options.view the main view
+     * @param {number} options.depth graph handle of the main view's depth
+     */
+    graph_virtual_feedback({ graph, view, depth }) {
+        const maps = this.#vsm_feedback_maps;
+        const all = this.#registry.maps;
+
+        maps.length = 0;
+
+        for (let i = 0; i < all.length; i++) {
+            if (all[i].isVirtualShadowMap === true) {
+                maps.push(all[i]);
+            }
+        }
+
+        if (maps.length === 0) {
+            // no virtual map to feed: the casters' memory goes, and starts afresh with the next map
+            if (this.#vsm_movers !== null) {
+                this.#vsm_movers.destroy();
+                this.#vsm_movers = null;
+            }
+
+            return;
+        }
+
+        if (this.#vsm_movers === null) {
+            this.#vsm_movers = new VSMMoverTracker(this.#graphics.device);
+        }
+
+        graph_vsm_feedback({
+            graph,
+            view,
+            depth,
+            maps,
+            tracker: this.#vsm_movers,
+            light_database: this.#owner.database,
+        });
+
+        // the graph holds what it needs; don't keep the maps reachable from here until next frame
+        maps.length = 0;
+    }
+
+    /**
+     * Rasterize the pages a virtual shadow map chose this frame, each into its slot of the pool
+     * through a pooled view aimed at the page — the {@link #draw_direct} path, with the Fast
+     * pipeline: a pooled view's last depth belongs to some other page, and occlusion buys nothing on
+     * a slot.
+     *
+     * @param {VirtualShadowMap} map
+     * @param {ShadeGPUCommandContext} command_ctx
+     */
+    #draw_virtual(map, command_ctx) {
+        const manager = map.manager;
+        const count = manager.job_count;
+
+        if (count === 0) {
+            return;
+        }
+
+        const views = map.views;
+
+        while (views.length < count) {
+            const camera = new OrthographicCamera();
+            camera.update();
+
+            const view = new View(camera, this.#scene);
+            view.label = `Virtual Shadow Page ${views.length}`;
+
+            views.push(view);
+        }
+
+        const graph = new FrameGraph("virtual shadow pages");
+        const jobs = new Array(count);
+
+        const pool = map.layout[0];
+        const slot_size = map.slot_size;
+        const per_axis = manager.slots.slots_per_axis;
+
+        for (let i = 0; i < count; i++) {
+            const view = views[i];
+
+            map.aim_page_camera(view.camera, manager.job_level(i), manager.job_x(i), manager.job_y(i));
+
+            const view_ctx = this.shadow_view_manager.obtain(view);
+
+            view_ctx.update(this.#graphics);
+            view_ctx.setViewportSize(slot_size, slot_size);
+
+            const slot = manager.job_slot(i);
+
+            const job = new RasterizationJob();
+            job.pipeline_type = RasterizationPipelineType.Fast;
+            job.opaque_pass = shadow_rasterization_pass_descriptor;
+            job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
+            job.cull_policy = SHADOW_CULL_POLICY;
+            job.render_target = this.#render_target;
+            job.view_ctx = view_ctx;
+            job.viewport = [
+                pool.x0 + (slot % per_axis) * slot_size,
+                pool.y0 + ((slot / per_axis) | 0) * slot_size,
+                slot_size,
+                slot_size,
+            ];
+
+            jobs[i] = job;
+        }
+
+        execute_rasterization_jobs({
+            jobs,
+            limits: this.#graphics.collection_limits,
+            command_ctx,
+            graph,
+        });
+
+        command_ctx.encodeGraph(graph);
+    }
+
+    /**
+     * Measure this frame's casters against the map's cascades and publish the result to their
+     * rows, for the readback to carry to the next frame's fit.
      *
      * @param {DirectionalLightShadowmap} map
      * @param {ShadeGPUCommandContext} command_ctx
@@ -494,14 +929,24 @@ export class GPUSceneShadowmapContext {
         const group_count = meshes.dispatch_group_count(CSM_CASTER_RANGE_WORKGROUP_SIZE);
 
         if (group_count === 0) {
-            // nothing to cast: the row keeps what it holds, which is unknown
+            // nothing to measure: the rows keep the last range published into them — unknown if
+            // there never was one, and otherwise stale, which pushes the near planes back further
+            // than they need to go and costs nothing but depth precision
             return;
         }
 
         const ranges = this.#caster_scratch;
+        const caster_settings = map.caster_settings;
+        const planes_words = caster_settings.planes_words;
 
         // transient: the frusta differ every frame, so there is nothing worth keeping between them
-        const settings = command_ctx.allocateTransientValueBuffer(CSM_CASTER_RANGE_SETTINGS_STRUCT, map.caster_settings);
+        const settings = command_ctx.allocateTransientValueBuffer(CSM_CASTER_RANGE_SETTINGS_STRUCT, caster_settings);
+        const planes = command_ctx.allocateTransientBufferAndLoad(
+            planes_words.buffer,
+            GPUBufferUsage.STORAGE,
+            planes_words.byteOffset,
+            planes_words.byteLength
+        );
 
         shader_csm_caster_range_accumulate.dispatch({
             encoder: command_ctx,
@@ -509,6 +954,7 @@ export class GPUSceneShadowmapContext {
             bindings: {
                 scene_database: scene_ctx.scene_database_buffer,
                 settings,
+                planes,
                 ranges,
             },
         });
@@ -520,9 +966,8 @@ export class GPUSceneShadowmapContext {
                 ranges,
                 light_database: this.#owner.database.buffer,
                 publish: {
-                    row: map.caster_row,
-                    base: map.caster_settings.base,
-                    cascade_count: map.caster_settings.cascade_count,
+                    first_cascade: map.first_cascade,
+                    cascade_count: map.cascade_count,
                 },
             },
         });
@@ -607,7 +1052,8 @@ export class GPUSceneShadowmapContext {
      *     up (no forced redraw).
      *  4. **Score + select.** Delegated to {@link ShadowmapDrawSelector}, which sets `should_draw`
      *     on the winners and reports the view spend and whether any candidate went unmet:
-     *        - **Directional** → always selected (infinite score); view cost still charged.
+     *        - **Directional** → always selected (infinite score); its views are counted in the
+     *          frame's spend but not charged against the budget the local lights compete for.
      *        - **Local, off-screen** (`projected_area_px <= 0`) → skipped entirely.
      *        - **Local, in-view, invalid** → MUST draw. `is_invalid` means the committed layout
      *          has never held valid depth (freshly created map); sampling it would display
@@ -654,9 +1100,44 @@ export class GPUSceneShadowmapContext {
 
         // Step 2: recompute projected areas. Writing onto the map so the policy + scorer can
         // just read `map.projected_area_px` without threading a parallel array through.
+        let virtual_maps = 0;
+
         for (let i = 0; i < n; i++) {
             const m = shadowmaps[i];
             m.projected_area_px = compute_light_projected_area_px(m.light, main_camera, view_resolution);
+
+            if (m.isVirtualShadowMap === true) {
+                virtual_maps++;
+            }
+        }
+
+        if (virtual_maps > 0) {
+            // the scene's page budget, shared out between its virtual maps: all of it to the one
+            // map of a scene with one sun; with several, the pages that do not divide evenly go
+            // round them a frame at a time, so a budget below the suns' count starves none
+            const budget = this.#virtual_page_budget;
+            const share = Math.floor(budget / virtual_maps);
+            const remainder = budget - share * virtual_maps;
+            const first_extra = this.#virtual_budget_turn++ % virtual_maps;
+
+            let k = 0;
+
+            for (let i = 0; i < n; i++) {
+                const m = shadowmaps[i];
+
+                if (m.isVirtualShadowMap !== true) {
+                    continue;
+                }
+
+                const turn = (k - first_extra + virtual_maps) % virtual_maps;
+
+                // what its update works with this frame
+                m.page_budget = share + (turn < remainder ? 1 : 0);
+                m.lod_bias = this.virtual_lod_bias;
+                m.view_height = view_resolution[1];
+
+                k++;
+            }
         }
 
         // Step 2b: a cached map whose last cut of virtual geometry was clamped, and under which pages
@@ -724,6 +1205,9 @@ export class GPUSceneShadowmapContext {
         const t_point = database.get('shadow_point');
         const t_spot = database.get('shadow_spot');
         const t_directional = database.get('shadow_directional');
+        const t_cascade = database.get('shadow_cascade');
+
+        const cascade_record = this.#cascade_record;
 
         const maps = this.#registry.maps;
         let pc = 0;
@@ -749,26 +1233,57 @@ export class GPUSceneShadowmapContext {
                 continue;
             }
 
+            if (map.isVirtualShadowMap === true) {
+                // its rows change with its pages, whether or not anything else about it did
+                this.#write_virtual_rows(map, database);
+            }
+
             if (map.metadata_changed) {
                 table.set(slot, map.make_record());
+
+                if (light.isDirectionalLight && map.isVirtualShadowMap !== true) {
+                    // the record names the cascades; their rows hold what to sample — written a
+                    // field at a time, since the GPU owns the rest of the row
+                    for (let j = 0; j < map.cascade_count; j++) {
+                        t_cascade.set_fields(map.first_cascade + j, map.make_cascade_record(j, cascade_record), CASCADE_VIEW_WRITER);
+                    }
+                }
+
                 map.metadata_changed = false;
             }
         }
 
-        // trim trailing slots from previous frames so disused entries don't leak
-        for (let i = pc; i < this.#prev_point_count; i++) {
+        this.#trim_shadow_records(database, pc, sc, dc);
+    }
+
+    /**
+     * Free the shadow_* slots past the counts given — slots a previous write filled that no map
+     * holds any more — so disused entries don't leak. A `shadow_directional` slot left standing
+     * would go on naming cascade rows its map gave back.
+     *
+     * @param {GPUDatabase} database
+     * @param {number} point_count slots of `shadow_point` still in use
+     * @param {number} spot_count slots of `shadow_spot` still in use
+     * @param {number} directional_count slots of `shadow_directional` still in use
+     */
+    #trim_shadow_records(database, point_count, spot_count, directional_count) {
+        const t_point = database.get('shadow_point');
+        const t_spot = database.get('shadow_spot');
+        const t_directional = database.get('shadow_directional');
+
+        for (let i = point_count; i < this.#prev_point_count; i++) {
             t_point.remove(i);
         }
-        for (let i = sc; i < this.#prev_spot_count; i++) {
+        for (let i = spot_count; i < this.#prev_spot_count; i++) {
             t_spot.remove(i);
         }
-        for (let i = dc; i < this.#prev_directional_count; i++) {
+        for (let i = directional_count; i < this.#prev_directional_count; i++) {
             t_directional.remove(i);
         }
 
-        this.#prev_point_count = pc;
-        this.#prev_spot_count = sc;
-        this.#prev_directional_count = dc;
+        this.#prev_point_count = point_count;
+        this.#prev_spot_count = spot_count;
+        this.#prev_directional_count = directional_count;
     }
 
     /**
@@ -834,7 +1349,9 @@ export class GPUSceneShadowmapContext {
 
             const light = map.light;
 
-            if (light.isDirectionalLight || light.isSpotLight) {
+            if (map.isVirtualShadowMap === true) {
+                this.#draw_virtual(map, command_ctx);
+            } else if (light.isDirectionalLight || light.isSpotLight) {
                 this.#draw_direct(map, command_ctx);
             } else if (light.isPointLight) {
                 if (map.isTetrahedron) {
@@ -899,7 +1416,7 @@ export class GPUSceneShadowmapContext {
      * @param {ShadeGPUCommandContext} command_ctx
      */
     #draw_direct(map, command_ctx) {
-        if (map.light.isDirectionalLight === true && map.caster_row !== -1) {
+        if (map.light.isDirectionalLight === true && map.first_cascade !== -1) {
             // this frame's casters against this frame's cascades, for next frame's fit
             this.#measure_caster_range(map, command_ctx);
         }
@@ -924,7 +1441,7 @@ export class GPUSceneShadowmapContext {
             const job = new RasterizationJob();
             job.opaque_pass = shadow_rasterization_pass_descriptor;
             job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
-            job.cull_policy = CullPolicy.Reversed;
+            job.cull_policy = SHADOW_CULL_POLICY;
             job.render_target = this.#render_target;
             job.view_ctx = view_ctx;
             job.viewport = [atlas_aabb.x0, atlas_aabb.y0, atlas_aabb.width, atlas_aabb.height];
@@ -1042,7 +1559,7 @@ export class GPUSceneShadowmapContext {
             job.pipeline_type = RasterizationPipelineType.Fast;
             job.opaque_pass = shadow_rasterization_pass_descriptor;
             job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
-            job.cull_policy = CullPolicy.Reversed;
+            job.cull_policy = SHADOW_CULL_POLICY;
             job.render_target = null;
             job.view_ctx = view_ctx;
             job.viewport = [
@@ -1188,7 +1705,7 @@ export class GPUSceneShadowmapContext {
             job.pipeline_type = RasterizationPipelineType.Fast;
             job.opaque_pass = shadow_rasterization_pass_descriptor;
             job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
-            job.cull_policy = CullPolicy.Reversed;
+            job.cull_policy = SHADOW_CULL_POLICY;
             job.render_target = null;
             job.view_ctx = view_ctx;
             job.viewport = [
@@ -1320,8 +1837,13 @@ export class GPUSceneShadowmapContext {
         // free the per-view/-camera GPU contexts — without this an evicted map's buffers leak
         this.#release_map_gpu_contexts(map);
 
-        if (map.light.isDirectionalLight === true) {
-            this.#release_caster_row(map);
+        if (map.isVirtualShadowMap === true) {
+            this.#release_virtual(map);
+
+            // a reading of its feedback still on its way back finds the map gone and drops itself
+            map.destroy();
+        } else if (map.light.isDirectionalLight === true) {
+            this.#release_cascades(map);
         }
 
         map.light._gpu_shadowmap_id = -1;
@@ -1362,6 +1884,12 @@ export class GPUSceneShadowmapContext {
                 this.#evict_map(shadowmaps[i]);
             }
             registry.clear();
+
+            // No draw runs while shadows are off, and the draw is what frees disused slots — so
+            // they are freed here, or a directional slot would name the cascade rows just given
+            // back for as long as shadows stay off.
+            this.#trim_shadow_records(this.#owner.database, 0, 0, 0);
+
             return had_maps;
         }
 
@@ -1370,8 +1898,42 @@ export class GPUSceneShadowmapContext {
         let changed = false;
 
         const use_tetra = this.use_tetrahedron_point_shadows;
+        const use_virtual = this.use_virtual_shadow_maps;
+        const cascade_count = this.#cascade_count;
+        const first_texel_size = this.#virtual_first_texel_size;
         const newcomers = this.#reconcile_newcomers;
 
+        /**
+         * Whether a map was built under settings that no longer hold — a point map by the other
+         * generator (cube vs tetra), whose face count and draw path no longer match, a directional
+         * map of the other kind (cascades vs virtual), one with another number of cascades, or a
+         * virtual one with another first texel — and so must be rebuilt.
+         *
+         * @param {Shadowmap} map
+         * @returns {boolean}
+         */
+        const is_outdated = (map) => {
+            const light = map.light;
+
+            if (light.isPointLight) {
+                return Boolean(map.isTetrahedron) !== use_tetra;
+            }
+
+            if (light.isDirectionalLight) {
+                const is_virtual = map.isVirtualShadowMap === true;
+
+                if (is_virtual !== use_virtual) {
+                    return true;
+                }
+
+                return is_virtual
+                    ? map.manager.first_texel_size !== first_texel_size
+                    : map.cascade_count !== cascade_count;
+            }
+
+            return false;
+        };
+
         registry.begin_reconcile();
         newcomers.length = 0;
 
@@ -1395,10 +1957,10 @@ export class GPUSceneShadowmapContext {
                 continue;
             }
 
-            // A point map built by the other generator (cube vs tetra) must be rebuilt when the
-            // flag flips — its face count and draw path no longer match. Pass 2 drops it on the
-            // same test; queueing the rebuild here lands it in this pass rather than the next.
-            if (light.isPointLight && Boolean(map.isTetrahedron) !== use_tetra) {
+            // A map built under settings that have since changed must be rebuilt. Pass 2 drops it
+            // on the same test, giving its atlas rects back first; queueing the rebuild here lands
+            // it in this pass rather than the next.
+            if (is_outdated(map)) {
                 newcomers.push(light);
             }
         }
@@ -1408,12 +1970,8 @@ export class GPUSceneShadowmapContext {
         // splice indices stay stable.
         for (let i = shadowmaps.length - 1; i >= 0; i--) {
             const map = shadowmaps[i];
-            const light = map.light;
-
-            const generator_mismatch = light.isPointLight
-                && Boolean(map.isTetrahedron) !== use_tetra;
 
-            if (registry.is_marked(map) && !generator_mismatch) {
+            if (registry.is_marked(map) && !is_outdated(map)) {
                 continue;
             }
             this.#evict_map(map);
@@ -1422,12 +1980,12 @@ export class GPUSceneShadowmapContext {
         }
 
         const add_directional = (light) => {
-            const map = new DirectionalLightShadowmap();
+            const map = new DirectionalLightShadowmap(cascade_count);
             map.light = light;
 
             const bound = [];
             try {
-                for (let j = 0; j < SHADOWMAP_CSM_CASCADE_COUNT; j++) {
+                for (let j = 0; j < cascade_count; j++) {
                     const resolution_index = Math.min(j, DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION.length - 1);
                     const resolution = DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION[resolution_index];
 
@@ -1452,7 +2010,44 @@ export class GPUSceneShadowmapContext {
                 throw e;
             }
 
-            this.#claim_caster_row(map);
+            this.#claim_cascades(map);
+            registry.add(map);
+        };
+
+        const add_virtual = (light) => {
+            // the pool: as many whole slots as fit the default pool, or the atlas when it is smaller
+            const slot_size = VSM_PAGE_SIZE + 2 * SHADOWMAP_ATLAS_BORDER;
+            const pool_side = Math.floor(Math.min(VSM_POOL_SIZE, this.atlas.size.x, this.atlas.size.y) / slot_size) * slot_size;
+
+            // the pool first: an atlas without room for it throws here, every frame the sun is
+            // retried, and the map's page bookkeeping — megabytes — is not built for nothing
+            const pool = this.bind(pool_side);
+
+            let map;
+
+            try {
+                map = new VirtualShadowMap({
+                    level_count: VSM_LEVEL_COUNT,
+                    pages_per_level: VSM_PAGES_PER_LEVEL,
+                    first_texel_size,
+                    page_size: VSM_PAGE_SIZE,
+                    border: SHADOWMAP_ATLAS_BORDER,
+                    pool_size: pool_side,
+                    request_capacity: VSM_DEFAULT_REQUEST_CAPACITY,
+                    protect_frames: VSM_PROTECT_FRAMES,
+                    depth_extent: VSM_DEPTH_EXTENT,
+                });
+
+                map.light = light;
+                map.layout[0] = pool;
+
+                this.#claim_virtual(map);
+            } catch (e) {
+                // nothing registered the map: give its pool back rather than leave an orphan rect
+                this.atlas.remove(pool);
+                throw e;
+            }
+
             registry.add(map);
         };
 
@@ -1515,7 +2110,11 @@ export class GPUSceneShadowmapContext {
             }
 
             if (light.isDirectionalLight) {
-                add_directional(light);
+                if (use_virtual) {
+                    add_virtual(light);
+                } else {
+                    add_directional(light);
+                }
                 changed = true;
             } else if (light.isSpotLight) {
                 add_spot(light);
@@ -1599,6 +2198,11 @@ export class GPUSceneShadowmapContext {
             this.#caster_scratch = null;
         }
 
+        if (this.#vsm_movers !== null) {
+            this.#vsm_movers.destroy();
+            this.#vsm_movers = null;
+        }
+
         this.texture.destroy();
 
         const maps = this.#registry.maps;