@woosh/meep-engine 3.39.0 → 3.40.0

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

@@ -63,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
@@ -94,12 +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
  */
@@ -189,6 +233,74 @@ 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}
@@ -312,6 +424,32 @@ export class GPUSceneShadowmapContext {
      */
     #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;
+
+    /**
+     * 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}
+     */
+    #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
      */
@@ -528,6 +666,256 @@ export class GPUSceneShadowmapContext {
         map.caster_range_valid = false;
     }
 
+    /**
+     * 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.
@@ -712,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
@@ -810,10 +1233,15 @@ 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) {
+                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++) {
@@ -921,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) {
@@ -1011,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];
@@ -1129,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 = [
@@ -1275,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 = [
@@ -1407,7 +1837,12 @@ 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) {
+        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);
         }
 
@@ -1463,13 +1898,16 @@ 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, or a
-         * directional map with another number of cascades — and so must be rebuilt.
+         * 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}
@@ -1482,7 +1920,15 @@ export class GPUSceneShadowmapContext {
             }
 
             if (light.isDirectionalLight) {
-                return map.cascade_count !== cascade_count;
+                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;
@@ -1568,6 +2014,43 @@ export class GPUSceneShadowmapContext {
             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);
+        };
+
         const add_spot = (light) => {
             const map = new SpotLightShadowmap();
             map.light = light;
@@ -1627,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);
@@ -1711,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;

package/src/shade/renderer/shadow/map/Shadowmap.d.ts

@@ -159,8 +159,9 @@ export class Shadowmap {
      * scene's GPU database. Shape matches the table's element type:
      *   - point      → vec4f (atlas rect; sampling is direction-based, no projection needed)
      *   - spot       → SHADOWMAP_VIEW_METADATA_STRUCT (atlas + projection)
-     *   - directional → CSM_SHADOWMAP_STRUCT (where its cascades are: a range over the
-     *     `shadow_cascade` table, whose rows the shadow context writes separately)
+     *   - directional → DIRECTIONAL_SHADOWMAP_STRUCT (where its cascades are: a range over the
+     *     `shadow_cascade` table, whose rows the shadow context writes separately; or which
+     *     `shadow_virtual` row is its virtual shadow map)
      * @returns {*}
      */
     make_record(): any;

package/src/shade/renderer/shadow/map/Shadowmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Shadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/Shadowmap.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;IACI,WAAO;IAEP;;OAEG;IACH,OAFU,KAAK,CAEV;IAEL;;;;OAIG;IACH,QAFU,KAAK,EAAE,CAEL;IAEZ;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAFU,KAAK,EAAE,GAAG,IAAI,CAEF;IAEtB;;;OAGG;IACH,OAFU,IAAI,EAAE,CAEL;IAEX;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,0BAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,yBAFU,MAAM,CAEa;IAE7B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAFU,OAAO,CAEC;IAElB;;;;;;;OAOG;IACH,uBAFU,OAAO,CAEa;IAE9B;;;;OAIG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;;OAQG;IACH,aAFU,OAAO,CAEG;IAEpB;;;;;;;;;;;;;;OAcG;IACH,kBAFU,OAAO,CAEO;IAExB;;;;;;;;;;;OAWG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,oBAHW,MAAM,aACN,eAAe,QAIzB;IAED;;;;;;;;OAQG;IACH,mBAEC;IAED,gBAEC;CACJ;oBA7LY,OAAO,wCAAwC,EAAE,OAAO;qBACxD,OAAO,wBAAwB,EAAE,MAAM;oBACvC,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;mBACxD,OAAO,oBAAoB,EAAE,IAAI"}
+{"version":3,"file":"Shadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/Shadowmap.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;IACI,WAAO;IAEP;;OAEG;IACH,OAFU,KAAK,CAEV;IAEL;;;;OAIG;IACH,QAFU,KAAK,EAAE,CAEL;IAEZ;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAFU,KAAK,EAAE,GAAG,IAAI,CAEF;IAEtB;;;OAGG;IACH,OAFU,IAAI,EAAE,CAEL;IAEX;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,0BAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,yBAFU,MAAM,CAEa;IAE7B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAFU,OAAO,CAEC;IAElB;;;;;;;OAOG;IACH,uBAFU,OAAO,CAEa;IAE9B;;;;OAIG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;;OAQG;IACH,aAFU,OAAO,CAEG;IAEpB;;;;;;;;;;;;;;OAcG;IACH,kBAFU,OAAO,CAEO;IAExB;;;;;;;;;;;OAWG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,oBAHW,MAAM,aACN,eAAe,QAIzB;IAED;;;;;;;;;OASG;IACH,mBAEC;IAED,gBAEC;CACJ;oBA9LY,OAAO,wCAAwC,EAAE,OAAO;qBACxD,OAAO,wBAAwB,EAAE,MAAM;oBACvC,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;mBACxD,OAAO,oBAAoB,EAAE,IAAI"}

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

@@ -177,8 +177,9 @@ export class Shadowmap {
      * scene's GPU database. Shape matches the table's element type:
      *   - point      → vec4f (atlas rect; sampling is direction-based, no projection needed)
      *   - spot       → SHADOWMAP_VIEW_METADATA_STRUCT (atlas + projection)
-     *   - directional → CSM_SHADOWMAP_STRUCT (where its cascades are: a range over the
-     *     `shadow_cascade` table, whose rows the shadow context writes separately)
+     *   - directional → DIRECTIONAL_SHADOWMAP_STRUCT (where its cascades are: a range over the
+     *     `shadow_cascade` table, whose rows the shadow context writes separately; or which
+     *     `shadow_virtual` row is its virtual shadow map)
      * @returns {*}
      */
     make_record() {

package/src/shade/renderer/shadow/map/shader/chunk_sample_shadowmap_atlas_for_light.d.ts

@@ -1,6 +1,14 @@
 /**
  * Samples the shadow atlas for a given light, using the supplied shadow projection matrix and
  * atlas rect. Applies receiver normal-offset bias to reduce self-shadowing.
+ *
+ * Two entry points: `sample_shadowmap_atlas_for_light` sizes the bias by a texel's world size as
+ * read off the matrix, and `sample_shadowmap_atlas_with_texel` takes that size from a caller that
+ * knows it exactly — a virtual shadow map's page, whose texel is fixed by its level, where the
+ * matrix's reading grows with the depth range as the light turns toward a world axis.
+ *
+ * A receiver past the far plane is shadowed only by what was drawn in front of it: its reference
+ * depth is held just above the cleared value, which would otherwise compare as shadowed.
  * @type {CodeChunk}
  */
 export const chunk_sample_shadowmap_atlas_for_light: CodeChunk;