@woosh/meep-engine 3.39.0 → 3.41.0

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

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

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

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

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

@@ -0,0 +1,289 @@
+import { assert } from "../../../../core/assert.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { graph_read_buffer } from "../../buffer/graph_read_buffer.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import { shader_vsm_demand, VSM_DEMAND_WORKGROUP_SIZE } from "./shader/shader_vsm_demand.js";
+import { shader_vsm_gather_counts, VSM_GATHER_WORKGROUP_SIZE } from "./shader/shader_vsm_gather_counts.js";
+import { shader_vsm_movers, VSM_MOVERS_WORKGROUP_SIZE } from "./shader/shader_vsm_movers.js";
+import { shader_vsm_skinned_movers } from "./shader/shader_vsm_skinned_movers.js";
+import { shader_vsm_stale, shader_vsm_stale_args, shader_vsm_stale_compact } from "./shader/shader_vsm_stale.js";
+import { vsm_feedback_word_count } from "./VSM_FEEDBACK_LAYOUT.js";
+import { VSM_MOVER_CAPACITY, VSM_MOVERS_BYTE_SIZE } from "./VSM_MOVER_LAYOUT.js";
+
+/**
+ * Readbacks of one map's feedback in flight at most: VT's cap. A frame that would go past it skips
+ * its readback — its wants come again the next frame, and its stale flags stay set until a readback
+ * lists them.
+ *
+ * @type {number}
+ */
+export const VSM_READBACKS_IN_FLIGHT = 3;
+
+/**
+ * Record a frame's virtual shadow map feedback into the `Shading` graph, once the main view's depth
+ * exists, and read it back.
+ *
+ * 1. **Movers**, once for the scene: every mesh row against the box it had last frame, and every
+ *    skinned mesh against the pose it had, into one list ({@link shader_vsm_movers},
+ *    {@link shader_vsm_skinned_movers}).
+ * 2. **Stale**, every frame for every map: the slots under a mover flagged in the map's persistent
+ *    flags ({@link shader_vsm_stale}, sized indirectly to the movers).
+ * 3. **Feedback**, for a map under its readback cap: the pages the view's pixels ask for
+ *    ({@link shader_vsm_demand}) with their pixel counts ({@link shader_vsm_gather_counts}), and the
+ *    flagged slots listed and cleared ({@link shader_vsm_stale_compact}) — read back and handed to
+ *    the map's {@link VSMPageManager#apply_reading} with the frame they were recorded in.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {import("../../view/GPUViewContext.js").GPUViewContext} options.view the view whose depth asks for pages
+ * @param {number} options.depth graph handle of the view's depth
+ * @param {VirtualShadowMap[]} options.maps
+ * @param {VSMMoverTracker} options.tracker the scene's casters as last seen
+ * @param {GPUDatabase} options.light_database
+ */
+export function graph_vsm_feedback({
+                                       graph,
+                                       view,
+                                       depth,
+                                       maps,
+                                       tracker,
+                                       light_database,
+                                   }) {
+    assert.defined(graph, 'graph');
+    assert.defined(view, 'view');
+    assert.isNonNegativeInteger(depth, 'depth');
+    assert.isArray(maps, 'maps');
+    assert.defined(tracker, 'tracker');
+
+    if (maps.length === 0) {
+        return;
+    }
+
+    const scene_ctx = view.scene;
+    const meshes = scene_ctx.scene_database.get('meshes');
+    const elements_per_page = meshes.descriptor.elements_per_page;
+
+    // every row the table has ever had, in whole pages
+    const pages = Math.ceil(Math.max(meshes.element_capacity, tracker.row_count) / elements_per_page);
+
+    tracker.ensure(pages * elements_per_page);
+
+    const row_count = tracker.row_count;
+    const groups_per_page = Math.ceil(elements_per_page / VSM_MOVERS_WORKGROUP_SIZE);
+    const mover_groups = Math.ceil(row_count / elements_per_page) * groups_per_page;
+
+    // folded into rows a dispatch dimension can hold
+    const mover_groups_x = Math.min(mover_groups, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
+    const mover_groups_y = mover_groups > 0 ? Math.ceil(mover_groups / mover_groups_x) : 0;
+
+    const movers_data = {};
+
+    const movers_pass = graph.add("VSM Movers", movers_data, (data, resources, context) => {
+        const encoder = context.encoder;
+        const movers = resources.get(data.movers);
+
+        // only the count needs to start at zero: an entry is read only below it
+        encoder.clearBuffer(movers, 0, 16);
+
+        tracker.encode_growth(encoder);
+
+        if (mover_groups > 0) {
+            shader_vsm_movers.dispatch({
+                encoder,
+                group_count_x: mover_groups_x,
+                group_count_y: mover_groups_y,
+                bindings: {
+                    settings: {
+                        row_count,
+                        capacity: VSM_MOVER_CAPACITY,
+                        groups_x: mover_groups_x,
+                        group_count: mover_groups,
+                    },
+                    scene_database: scene_ctx.scene_database_buffer,
+                    last_seen: tracker.buffer,
+                    movers,
+                },
+            });
+        }
+
+        const skinning = scene_ctx.skinning;
+        const animation = scene_ctx.animation_manager;
+
+        if (skinning.binding_count > 0 && skinning.bindings_buffer !== null) {
+            // a workgroup per skinned mesh
+            assert.lessThanOrEqual(skinning.binding_count, 65535, 'skinning bindings beyond one dispatch row');
+
+            shader_vsm_skinned_movers.dispatch({
+                encoder,
+                group_count_x: skinning.binding_count,
+                bindings: {
+                    settings: { binding_count: skinning.binding_count, capacity: VSM_MOVER_CAPACITY },
+                    scene_database: scene_ctx.scene_database_buffer,
+                    bindings: skinning.bindings_buffer,
+                    // this frame's pose and last frame's, as the matrix prep left them
+                    skin_matrices: animation.skin_matrices_buffer,
+                    prev_skin_matrices: animation.prev_skin_matrices_buffer,
+                    movers,
+                },
+            });
+        }
+    });
+
+    movers_data.movers = movers_pass.create("vsm_movers", BufferResourceDescriptor.from(
+        VSM_MOVERS_BYTE_SIZE,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    ));
+
+    // the bounds it remembers have to move on every frame, whatever reads its list
+    movers_pass.make_side_effect();
+
+    for (let i = 0; i < maps.length; i++) {
+        // stamped with the map's own count, which its update advanced this frame
+        graph_vsm_map_feedback(graph, view, depth, maps[i], movers_data.movers, light_database, maps[i].frame_index);
+    }
+}
+
+/**
+ * @param {FrameGraph} graph
+ * @param {import("../../view/GPUViewContext.js").GPUViewContext} view
+ * @param {number} depth
+ * @param {VirtualShadowMap} map
+ * @param {number} movers graph handle of the scene's mover list
+ * @param {GPUDatabase} light_database
+ * @param {number} frame
+ */
+function graph_vsm_map_feedback(graph, view, depth, map, movers, light_database, frame) {
+    const manager = map.manager;
+    const slot_count = manager.slots.capacity;
+    const request_capacity = manager.request_capacity;
+
+    const read_back = map.readbacks_in_flight < VSM_READBACKS_IN_FLIGHT;
+
+    const data = {};
+
+    const pass = graph.add("VSM Feedback", data, (data, resources, context) => {
+        const encoder = context.encoder;
+
+        const database = light_database.buffer;
+        const mover_list = resources.get(data.movers);
+        const command = resources.get(data.command);
+        const record_row = map.record_row;
+
+        shader_vsm_stale_args.dispatch({
+            encoder,
+            bindings: {
+                settings: { slot_count },
+                movers: mover_list,
+                command,
+            },
+        });
+
+        shader_vsm_stale.dispatchIndirect({
+            encoder,
+            command,
+            bindings: {
+                settings: { record_row },
+                light_database: database,
+                movers: mover_list,
+                stale_flags: map.stale_flags,
+            },
+        });
+
+        if (!read_back) {
+            return;
+        }
+
+        const feedback = resources.get(data.feedback);
+        const counts = resources.get(data.counts);
+        const depth_texture = resources.get(data.depth);
+
+        // pooled buffers arrive holding whatever their last tenant left
+        encoder.clearBuffer(feedback);
+        encoder.clearBuffer(counts);
+
+        const width = depth_texture.size[0];
+        const height = depth_texture.size[1];
+
+        shader_vsm_demand.dispatch({
+            encoder,
+            group_count_x: Math.ceil(width / VSM_DEMAND_WORKGROUP_SIZE),
+            group_count_y: Math.ceil(height / VSM_DEMAND_WORKGROUP_SIZE),
+            bindings: {
+                settings: { record_row, request_capacity },
+                depth: depth_texture.obtainView(),
+                camera: view.camera.gpu_buffer,
+                light_database: database,
+                counts,
+                feedback,
+            },
+        });
+
+        shader_vsm_gather_counts.dispatch({
+            encoder,
+            group_count_x: Math.ceil(request_capacity / VSM_GATHER_WORKGROUP_SIZE),
+            bindings: {
+                settings: { record_row, request_capacity },
+                light_database: database,
+                counts,
+                feedback,
+            },
+        });
+
+        shader_vsm_stale_compact.dispatchThreads({
+            encoder,
+            thread_count_x: slot_count,
+            bindings: {
+                settings: { slot_count, request_capacity },
+                movers: mover_list,
+                stale_flags: map.stale_flags,
+                feedback,
+            },
+        });
+    });
+
+    data.movers = pass.read(movers);
+    data.depth = pass.read(depth);
+    data.command = pass.create("vsm_stale_command", BufferResourceDescriptor.from(
+        16,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+    ));
+
+    // the stale flags it sets outlive the frame
+    pass.make_side_effect();
+
+    if (!read_back) {
+        return;
+    }
+
+    data.feedback = pass.create("vsm_feedback", BufferResourceDescriptor.from(
+        vsm_feedback_word_count(request_capacity, slot_count) * Uint32Array.BYTES_PER_ELEMENT,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+    ));
+
+    data.counts = pass.create("vsm_counts", BufferResourceDescriptor.from(
+        manager.cell_count * Uint32Array.BYTES_PER_ELEMENT,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    ));
+
+    map.readbacks_in_flight++;
+
+    graph_read_buffer({ graph, buffer: data.feedback })
+        .then(ref => {
+            try {
+                // a map torn down since has no pages to apply it to
+                if (!map.destroyed) {
+                    const bytes = ref.getValue();
+
+                    manager.apply_reading(new Uint32Array(bytes), new Float32Array(bytes), frame);
+                }
+            } finally {
+                ref.release();
+            }
+        })
+        .catch(e => {
+            console.error('vsm: feedback readback failed', e);
+        })
+        .finally(() => {
+            map.readbacks_in_flight--;
+        });
+}

package/src/shade/renderer/shadow/vsm/shader/chunk_shadowmap_sample_virtual.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A directional light's shadow from its virtual shadow map: the resident page that shadows the point
+ * — the page the point asked for, or the nearest coarser one standing in for it
+ * ({@link chunk_vsm_find_page}) — sampled as a cascade is, through the atlas sampler cascades use,
+ * with the page's view-projection and its slot's rect in the atlas. Same receiver bias, same filter,
+ * and the slot's border keeps the filter inside what the page's draw wrote.
+ *
+ * The bias is sized by the page's texel, which its level fixes. Read off the page's matrix, as a
+ * cascade's is, it would take in the depth range as the sun turns toward a world axis: straight
+ * overhead, twice the range over the slot's width — about 29 m for any level.
+ *
+ * A point no resident page covers is lit: nothing has been drawn there yet.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_shadowmap_sample_virtual: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_shadowmap_sample_virtual.d.ts.map

package/src/shade/renderer/shadow/vsm/shader/chunk_shadowmap_sample_virtual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_shadowmap_sample_virtual.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/chunk_shadowmap_sample_virtual.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AACH,6CAFU,SAAS,CA0CjB;0BA9DwB,uCAAuC"}

package/src/shade/renderer/shadow/vsm/shader/chunk_shadowmap_sample_virtual.js

@@ -0,0 +1,65 @@
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { INCIDENT_LIGHT_STRUCT } from "../../../shader/chunk/light/INCIDENT_LIGHT_STRUCT.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_sample_shadowmap_atlas_for_light } from "../../map/shader/chunk_sample_shadowmap_atlas_for_light.js";
+import { chunk_vsm_find_page } from "./chunk_vsm_find_page.js";
+import { chunk_vsm_page_view_projection } from "./chunk_vsm_page_view_projection.js";
+
+const RECORD_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual');
+
+/**
+ * A directional light's shadow from its virtual shadow map: the resident page that shadows the point
+ * — the page the point asked for, or the nearest coarser one standing in for it
+ * ({@link chunk_vsm_find_page}) — sampled as a cascade is, through the atlas sampler cascades use,
+ * with the page's view-projection and its slot's rect in the atlas. Same receiver bias, same filter,
+ * and the slot's border keeps the filter inside what the page's draw wrote.
+ *
+ * The bias is sized by the page's texel, which its level fixes. Read off the page's matrix, as a
+ * cascade's is, it would take in the depth range as the sun turns toward a world axis: straight
+ * overhead, twice the range over the slot's width — about 29 m for any level.
+ *
+ * A point no resident page covers is lit: nothing has been drawn there yet.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_shadowmap_sample_virtual = CodeChunk.from(
+    //language=WGSL
+    `
+fn shadowmap_sample_virtual(
+    database: ptr<storage, array<u32>>,
+    virtual_row: u32,
+    position_ws: vec3f,
+    surface_normal_ws: vec3f,
+    light: ${INCIDENT_LIGHT_STRUCT.wgsl_ref},
+) -> f32 {
+    let record = ${RECORD_TABLE.marshalling_method_read}(database, virtual_row);
+
+    let found = vsm_find_resident_page(database, record, position_ws);
+
+    if (found.level == VSM_LEVEL_NONE) {
+        return 1.0;
+    }
+
+    let view_projection = vsm_page_view_projection(record, found.level, found.page);
+
+    let slot_size = f32(record.page_size + 2u * record.border);
+    let slot_origin = vec2f(record.pool_origin) + vec2f(found.phys) * slot_size;
+
+    let texel = vsm_page_world_size(record, found.level) / f32(record.page_size);
+
+    return sample_shadowmap_atlas_with_texel(
+        view_projection,
+        texel,
+        position_ws,
+        surface_normal_ws,
+        light,
+        vec4f(slot_origin, slot_size, slot_size),
+    );
+}
+`, [
+        RECORD_TABLE.chunk_read,
+        chunk_vsm_find_page,
+        chunk_vsm_page_view_projection,
+        chunk_sample_shadowmap_atlas_for_light,
+    ]
+);

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_addressing.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where a world point falls in a virtual shadow map's clipmap — the arithmetic every pass that
+ * addresses the map shares, so that the pass asking for pages and every pass sampling them agree on
+ * which page a point is in. See {@link VSM_RECORD_STRUCT} for the light space and the windows.
+ *
+ * - `vsm_light_space(record, p)` — (x, y) across the light and the depth along it, `d`
+ * - `vsm_page_world_size(record, level)` — world units on a side of a page of the level
+ * - `vsm_desired_level(record, p)` — the level whose texel matches the main view's pixel at `p`
+ * - `vsm_world_page(record, xy, level)` — the world page of the level holding light-space `xy`
+ * - `vsm_window_contains(database, record, page, level)` — whether the level's window holds it
+ * - `vsm_cell_index(record, page, level)` — its row in the map's page table, from `first_page`
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vsm_addressing: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vsm_addressing.d.ts.map

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_addressing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vsm_addressing.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/chunk_vsm_addressing.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,mCAFU,SAAS,CAwDjB;0BAzEwB,uCAAuC"}

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_addressing.js

@@ -0,0 +1,75 @@
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { VSM_RECORD_STRUCT } from "../VSM_RECORD_STRUCT.js";
+
+const LEVEL_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual_level');
+
+/**
+ * Where a world point falls in a virtual shadow map's clipmap — the arithmetic every pass that
+ * addresses the map shares, so that the pass asking for pages and every pass sampling them agree on
+ * which page a point is in. See {@link VSM_RECORD_STRUCT} for the light space and the windows.
+ *
+ * - `vsm_light_space(record, p)` — (x, y) across the light and the depth along it, `d`
+ * - `vsm_page_world_size(record, level)` — world units on a side of a page of the level
+ * - `vsm_desired_level(record, p)` — the level whose texel matches the main view's pixel at `p`
+ * - `vsm_world_page(record, xy, level)` — the world page of the level holding light-space `xy`
+ * - `vsm_window_contains(database, record, page, level)` — whether the level's window holds it
+ * - `vsm_cell_index(record, page, level)` — its row in the map's page table, from `first_page`
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vsm_addressing = CodeChunk.from(
+    //language=WGSL
+    `
+fn vsm_light_space(record: ${VSM_RECORD_STRUCT.wgsl_ref}, position_ws: vec3f) -> vec3f {
+    let v = record.view * vec4f(position_ws, 1.0);
+
+    // the camera looks down its -z, so a depth along the light is -z
+    return vec3f(v.x, v.y, -v.z);
+}
+
+fn vsm_page_world_size(record: ${VSM_RECORD_STRUCT.wgsl_ref}, level: u32) -> f32 {
+    // a power of two times the level-0 page, so every level's page is an exact multiple of the last
+    return f32(record.page_size) * record.first_texel_size * exp2(f32(level));
+}
+
+fn vsm_desired_level(record: ${VSM_RECORD_STRUCT.wgsl_ref}, position_ws: vec3f) -> u32 {
+    // how wide the main view's pixel is where the point is, in level-0 texels
+    let footprint = distance(position_ws, record.camera_position) * record.pixel_angle / record.first_texel_size;
+
+    // the finest level whose texel is no wider than that pixel; the floor of 1e-30 keeps log2 finite
+    let level = floor(log2(max(footprint, 1e-30)) + record.lod_bias);
+
+    return u32(clamp(level, 0.0, f32(record.level_count - 1u)));
+}
+
+fn vsm_world_page(record: ${VSM_RECORD_STRUCT.wgsl_ref}, xy: vec2f, level: u32) -> vec2i {
+    return vec2i(floor(xy / vsm_page_world_size(record, level)));
+}
+
+fn vsm_window_contains(
+    database: ptr<storage, array<u32>>,
+    record: ${VSM_RECORD_STRUCT.wgsl_ref},
+    page: vec2i,
+    level: u32,
+) -> bool {
+    let origin = ${LEVEL_TABLE.marshalling_method_read}(database, record.first_level + level);
+    let relative = page - origin;
+
+    return all(relative >= vec2i(0)) && all(relative < vec2i(i32(record.pages_per_level)));
+}
+
+fn vsm_cell_index(record: ${VSM_RECORD_STRUCT.wgsl_ref}, page: vec2i, level: u32) -> u32 {
+    // the window's side is a power of two, so the mask is a modulo that holds for negative pages too:
+    // u32() of an i32 keeps its bits
+    let mask = record.pages_per_level - 1u;
+    let cell_x = u32(page.x) & mask;
+    let cell_y = u32(page.y) & mask;
+
+    return (level * record.pages_per_level + cell_y) * record.pages_per_level + cell_x;
+}
+`, [
+        VSM_RECORD_STRUCT.declaration_chunk,
+        LEVEL_TABLE.chunk_read,
+    ]
+);

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Append a lane's mover to the scene's mover list — `movers`, a `VSMMovers` the including shader
+ * binds read-write — one atomic per subgroup: the subgroup counts its movers, its first lane
+ * reserves that many entries, and each mover takes its place by its exclusive prefix.
+ *
+ * Every lane of the subgroup must call it, mover or not, from uniform control flow. Past `capacity`
+ * the count still rises — that is how the stale pass knows the list overflowed — but nothing is
+ * written.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vsm_append_mover: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vsm_append_mover.d.ts.map

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vsm_append_mover.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,qCAFU,SAAS,CA8BjB;0BA1CwB,uCAAuC"}

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_append_mover.js

@@ -0,0 +1,45 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+
+/**
+ * Append a lane's mover to the scene's mover list — `movers`, a `VSMMovers` the including shader
+ * binds read-write — one atomic per subgroup: the subgroup counts its movers, its first lane
+ * reserves that many entries, and each mover takes its place by its exclusive prefix.
+ *
+ * Every lane of the subgroup must call it, mover or not, from uniform control flow. Past `capacity`
+ * the count still rises — that is how the stale pass knows the list overflowed — but nothing is
+ * written.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vsm_append_mover = CodeChunk.from(
+    //language=WGSL
+    `
+fn vsm_append_mover(is_mover: bool, box_min: vec3f, box_max: vec3f, capacity: u32) {
+    let want = select(0u, 1u, is_mover);
+
+    let offset = subgroupExclusiveAdd(want);
+    let total = subgroupAdd(want);
+    let elected = subgroupElect();
+
+    var base = 0u;
+
+    if (elected && total > 0u) {
+        base = atomicAdd(&movers.count, total);
+    }
+
+    base = subgroupBroadcastFirst(base);
+
+    if (is_mover) {
+        let index = base + offset;
+
+        if (index < capacity) {
+            movers.boxes[index * 2u] = vec4f(box_min, 0.0);
+            movers.boxes[index * 2u + 1u] = vec4f(box_max, 0.0);
+        }
+    }
+}
+`
+);
+
+chunk_vsm_append_mover.addExtension(WebGPUExtensionType.Subgroups);

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_find_page.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which page of a virtual shadow map a world point asks for, and which resident page shadows it.
+ *
+ * - `vsm_request_page(database, record, p)` — the first level at or above the point's desired level
+ *   whose window holds it, and the world page there. The demand pass asks for exactly this page.
+ * - `vsm_find_resident_page(database, record, p)` — the same walk, carried on up the levels until a
+ *   resident page is found: the requested page itself, or the nearest coarser one standing in for
+ *   it. A sampler reads this one.
+ *
+ * Both walks are bounded by {@link VSM_LEVEL_LIMIT} and stop at the map's level count; a point no
+ * level holds, or no resident page covers, answers with level {@link VSM_LEVEL_NONE}.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vsm_find_page: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vsm_find_page.d.ts.map

package/src/shade/renderer/shadow/vsm/shader/chunk_vsm_find_page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vsm_find_page.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/chunk_vsm_find_page.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;GAaG;AACH,kCAFU,SAAS,CA8EjB;0BAjGwB,uCAAuC"}