@woosh/meep-engine 3.39.0 → 3.41.0

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

@@ -0,0 +1,100 @@
+import { chunk_vt_page_table_entry } from "../../../texture/virtual/chunk_vt_page_table_entry.js";
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { VSM_LEVEL_LIMIT } from "../VSM_LEVEL_LIMIT.js";
+import { VSM_RECORD_STRUCT } from "../VSM_RECORD_STRUCT.js";
+import { chunk_vsm_addressing } from "./chunk_vsm_addressing.js";
+
+const PAGE_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual_page');
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+const VSM_LEVEL_NONE: u32 = 0xFFFFFFFFu;
+
+struct VSMPageAddress {
+    // the level, or VSM_LEVEL_NONE
+    level: u32,
+    // world page coordinates at that level
+    page: vec2i,
+    // the pool slot holding it, for a resident page
+    phys: vec2u,
+}
+
+fn vsm_request_page(
+    database: ptr<storage, array<u32>>,
+    record: ${VSM_RECORD_STRUCT.wgsl_ref},
+    position_ws: vec3f,
+) -> VSMPageAddress {
+    let light_space = vsm_light_space(record, position_ws);
+
+    var level = vsm_desired_level(record, position_ws);
+
+    for (var step = 0u; step < ${VSM_LEVEL_LIMIT}u; step++) {
+        if (level >= record.level_count) {
+            break;
+        }
+
+        let page = vsm_world_page(record, light_space.xy, level);
+
+        if (vsm_window_contains(database, record, page, level)) {
+            return VSMPageAddress(level, page, vec2u(0u));
+        }
+
+        level += 1u;
+    }
+
+    return VSMPageAddress(VSM_LEVEL_NONE, vec2i(0), vec2u(0u));
+}
+
+fn vsm_find_resident_page(
+    database: ptr<storage, array<u32>>,
+    record: ${VSM_RECORD_STRUCT.wgsl_ref},
+    position_ws: vec3f,
+) -> VSMPageAddress {
+    let light_space = vsm_light_space(record, position_ws);
+
+    var level = vsm_desired_level(record, position_ws);
+
+    for (var step = 0u; step < ${VSM_LEVEL_LIMIT}u; step++) {
+        if (level >= record.level_count) {
+            break;
+        }
+
+        let page = vsm_world_page(record, light_space.xy, level);
+
+        if (vsm_window_contains(database, record, page, level)) {
+            let word = ${PAGE_TABLE.marshalling_method_read}(database, record.first_page + vsm_cell_index(record, page, level));
+            let entry = vt_entry_unpack(word);
+
+            if (entry.valid) {
+                return VSMPageAddress(level, page, entry.phys);
+            }
+        }
+
+        level += 1u;
+    }
+
+    return VSMPageAddress(VSM_LEVEL_NONE, vec2i(0), vec2u(0u));
+}
+`, [
+        VSM_RECORD_STRUCT.declaration_chunk,
+        PAGE_TABLE.chunk_read,
+        chunk_vt_page_table_entry,
+        chunk_vsm_addressing,
+    ]
+);

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

@@ -0,0 +1,15 @@
+/**
+ * The view-projection a page of a virtual shadow map was drawn with: the light view, then the
+ * orthographic projection of the page's square widened by its border on every side — the slot the
+ * page fills, so the matrix maps the slot onto clip space and a sampler handed it with the slot's
+ * atlas rect reads exactly what the page's draw wrote.
+ *
+ * Built the way the CPU builds the page camera's: `OrthographicCamera.update_projection`'s
+ * reverse-Z orthographic matrix, times the light view. The two have to agree to a fraction of a
+ * texel, and the border is what absorbs the f32-against-f64 difference.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vsm_page_view_projection: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vsm_page_view_projection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vsm_page_view_projection.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/chunk_vsm_page_view_projection.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,6CAFU,SAAS,CAgCjB;0BA9CwB,uCAAuC"}

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

@@ -0,0 +1,47 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { VSM_RECORD_STRUCT } from "../VSM_RECORD_STRUCT.js";
+import { chunk_vsm_addressing } from "./chunk_vsm_addressing.js";
+
+/**
+ * The view-projection a page of a virtual shadow map was drawn with: the light view, then the
+ * orthographic projection of the page's square widened by its border on every side — the slot the
+ * page fills, so the matrix maps the slot onto clip space and a sampler handed it with the slot's
+ * atlas rect reads exactly what the page's draw wrote.
+ *
+ * Built the way the CPU builds the page camera's: `OrthographicCamera.update_projection`'s
+ * reverse-Z orthographic matrix, times the light view. The two have to agree to a fraction of a
+ * texel, and the border is what absorbs the f32-against-f64 difference.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vsm_page_view_projection = CodeChunk.from(
+    //language=WGSL
+    `
+fn vsm_page_view_projection(record: ${VSM_RECORD_STRUCT.wgsl_ref}, level: u32, page: vec2i) -> mat4x4f {
+    let size = vsm_page_world_size(record, level);
+    let border = size * f32(record.border) / f32(record.page_size);
+
+    let left = f32(page.x) * size - border;
+    let right = f32(page.x + 1) * size + border;
+    let bottom = f32(page.y) * size - border;
+    let top = f32(page.y + 1) * size + border;
+
+    // ortho_reverse_z: near maps to 1, far to 0
+    let lr = 1.0 / (left - right);
+    let bt = 1.0 / (bottom - top);
+    let nf = 1.0 / (record.far - record.near);
+
+    let projection = mat4x4f(
+        vec4f(-2.0 * lr, 0.0, 0.0, 0.0),
+        vec4f(0.0, -2.0 * bt, 0.0, 0.0),
+        vec4f(0.0, 0.0, nf, 0.0),
+        vec4f((left + right) * lr, (top + bottom) * bt, record.far * nf, 1.0),
+    );
+
+    return projection * record.view;
+}
+`, [
+        VSM_RECORD_STRUCT.declaration_chunk,
+        chunk_vsm_addressing,
+    ]
+);

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

@@ -0,0 +1,26 @@
+export const VSM_DEMAND_WORKGROUP_SIZE: 8;
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_DEMAND_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Ask for the pages the main view's pixels will sample: one thread per pixel of its depth, the
+ * point's world position back from the depth, and the page {@link chunk_vsm_find_page} requests for
+ * it — the same page every sampler starts its walk from.
+ *
+ * Each page-table cell has a counter of the importance of the pixels asking for it: a pixel adds
+ * its weight under the screen importance mask ({@link chunk_screen_importance}, the automatic
+ * exposure's metering mask), so a page wanted in the middle of the screen outweighs one wanted by as
+ * many pixels at its edge. The pixel whose add finds the counter at zero lists the page in the
+ * feedback buffer, so the list holds each page once without a compaction pass.
+ * {@link shader_vsm_gather_counts} writes the final sums into it afterwards.
+ *
+ * Dispatch over the depth texture at {@link VSM_DEMAND_WORKGROUP_SIZE}² with `counts` and the
+ * feedback buffer zeroed.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_demand: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vsm_demand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vsm_demand.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/shader_vsm_demand.js"],"names":[],"mappings":"AAeA,0CAA2C;AAE3C;;GAEG;AACH,yCAFU,YAAY,CAOE;AA6GxB;;;;;;;;;;;;;;;;GAgBG;AACH,gCAFU,aAAa,CAMpB;6BAhJ0B,sCAAsC;8BAJrC,kCAAkC"}

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

@@ -0,0 +1,156 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { DEPTH_BACKGROUND_VALUE } from "../../../depth/DEPTH_BACKGROUND_VALUE.js";
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { chunk_project_position_from_depth } from "../../../shader/chunk/camera/chunk_project_position_from_depth.js";
+import { chunk_screen_importance } from "../../../shader/chunk/screen_space/chunk_screen_importance.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { VSM_FEEDBACK_LAYOUT } from "../VSM_FEEDBACK_LAYOUT.js";
+import { chunk_vsm_find_page } from "./chunk_vsm_find_page.js";
+
+export const VSM_DEMAND_WORKGROUP_SIZE = 8;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_DEMAND_SETTINGS_STRUCT = WebGPUStruct.from({
+    /** the map's row of `shadow_virtual` */
+    record_row: u32,
+    /** requests the feedback buffer holds */
+    request_capacity: u32,
+}, "VSMDemandSettings");
+
+const RECORD_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual');
+const L = VSM_FEEDBACK_LAYOUT;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', VSM_DEMAND_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addTexture('depth', 'depth')
+    .addUniform('camera', CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer('light_database', WebGPUArray.from(u32), false)
+    // one counter per page-table cell: the importance of the pixels that asked for its page this frame
+    .addStorageBuffer('counts', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('feedback', WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const CELL_NONE: u32 = 0xFFFFFFFFu;
+
+@compute @workgroup_size(${VSM_DEMAND_WORKGROUP_SIZE}, ${VSM_DEMAND_WORKGROUP_SIZE}, 1)
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let size = textureDimensions(depth);
+
+    // a lane past the edge does not return: the whole subgroup has to reach the counting below
+    let inside = global_id.x < size.x && global_id.y < size.y;
+    let pixel = min(global_id.xy, size - 1u);
+
+    let z = textureLoad(depth, pixel, 0);
+
+    let record = ${RECORD_TABLE.marshalling_method_read}(&light_database, settings.record_row);
+
+    var cell = CELL_NONE;
+    var level = 0u;
+    var page = vec2i(0);
+    var light_depth = 0.0;
+
+    let uv = (vec2f(pixel) + 0.5) / vec2f(size);
+
+    // the view clears to the background depth: no surface there to shadow
+    if (inside && z != ${DEPTH_BACKGROUND_VALUE}) {
+        let position = project_position_from_depth(uv, z, camera.view_projection_matrix_inverse);
+
+        let wanted = vsm_request_page(&light_database, record, position);
+
+        if (wanted.level != VSM_LEVEL_NONE) {
+            level = wanted.level;
+            page = wanted.page;
+            cell = vsm_cell_index(record, page, level);
+            light_depth = vsm_light_space(record, position).z;
+        }
+    }
+
+    // a pixel counts by where it is on screen: the exposure's metering mask, the edges counting for
+    // less but never for nothing
+    let weight = select(0u, screen_importance_weight(uv, f32(size.y) / f32(size.x)), cell != CELL_NONE);
+
+    // neighbouring pixels mostly want the same page: a subgroup that agrees adds once — agreement
+    // being its lowest and highest cell the same, a lane asking for nothing included
+    let agreed = subgroupMin(cell) == subgroupMax(cell);
+    let asking = subgroupAdd(weight);
+    let elected = subgroupElect();
+
+    var add = 0u;
+
+    if (agreed) {
+        if (elected) {
+            add = asking;
+        }
+    } else {
+        add = weight;
+    }
+
+    if (add == 0u) {
+        return;
+    }
+
+    let before = atomicAdd(&counts[cell], add);
+
+    // the first to ask lists the page, with the depth of a receiver it shadows
+    if (before != 0u) {
+        return;
+    }
+
+    let index = atomicAdd(&feedback[${L.REQUEST_COUNT}u], 1u);
+
+    if (index >= settings.request_capacity) {
+        return;
+    }
+
+    let base = ${L.HEADER_WORDS}u + index * ${L.REQUEST_WORDS}u;
+
+    atomicStore(&feedback[base + ${L.REQUEST_LEVEL}u], level);
+    atomicStore(&feedback[base + ${L.REQUEST_X}u], u32(page.x));
+    atomicStore(&feedback[base + ${L.REQUEST_Y}u], u32(page.y));
+    atomicStore(&feedback[base + ${L.REQUEST_DEPTH}u], bitcast<u32>(light_depth));
+}
+`, [
+    CAMERA_UNIFORM_STRUCT.declaration_chunk,
+    RECORD_TABLE.chunk_read,
+    chunk_project_position_from_depth,
+    chunk_screen_importance,
+    chunk_vsm_find_page,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Ask for the pages the main view's pixels will sample: one thread per pixel of its depth, the
+ * point's world position back from the depth, and the page {@link chunk_vsm_find_page} requests for
+ * it — the same page every sampler starts its walk from.
+ *
+ * Each page-table cell has a counter of the importance of the pixels asking for it: a pixel adds
+ * its weight under the screen importance mask ({@link chunk_screen_importance}, the automatic
+ * exposure's metering mask), so a page wanted in the middle of the screen outweighs one wanted by as
+ * many pixels at its edge. The pixel whose add finds the counter at zero lists the page in the
+ * feedback buffer, so the list holds each page once without a compaction pass.
+ * {@link shader_vsm_gather_counts} writes the final sums into it afterwards.
+ *
+ * Dispatch over the depth texture at {@link VSM_DEMAND_WORKGROUP_SIZE}² with `counts` and the
+ * feedback buffer zeroed.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_demand = ComputeShader.from({
+    label: "VSM/Demand",
+    body,
+    resources,
+});

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

@@ -0,0 +1,13 @@
+export const VSM_GATHER_WORKGROUP_SIZE: 64;
+/**
+ * Write the pixels that asked for each listed page into its request, once {@link shader_vsm_demand}
+ * has run over every pixel: the counter of the page's cell, as it ended.
+ *
+ * One thread per request the feedback buffer can hold — a fixed dispatch of
+ * `ceil(request_capacity / 64)` workgroups, the listed ones doing the work.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_gather_counts: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vsm_gather_counts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vsm_gather_counts.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/shader_vsm_gather_counts.js"],"names":[],"mappings":"AAUA,2CAA4C;AAc5C;;;;;;;;GAQG;AACH,uCAFU,aAAa,CAiCpB;8BA9D2B,kCAAkC"}

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

@@ -0,0 +1,65 @@
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { VSM_FEEDBACK_LAYOUT } from "../VSM_FEEDBACK_LAYOUT.js";
+import { chunk_vsm_addressing } from "./chunk_vsm_addressing.js";
+import { VSM_DEMAND_SETTINGS_STRUCT } from "./shader_vsm_demand.js";
+
+export const VSM_GATHER_WORKGROUP_SIZE = 64;
+
+const RECORD_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual');
+const L = VSM_FEEDBACK_LAYOUT;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', VSM_DEMAND_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer('light_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('counts', WebGPUArray.from(u32), false)
+    .addStorageBuffer('feedback', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Write the pixels that asked for each listed page into its request, once {@link shader_vsm_demand}
+ * has run over every pixel: the counter of the page's cell, as it ended.
+ *
+ * One thread per request the feedback buffer can hold — a fixed dispatch of
+ * `ceil(request_capacity / 64)` workgroups, the listed ones doing the work.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_gather_counts = ComputeShader.from({
+    label: "VSM/GatherCounts",
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${VSM_GATHER_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let index = global_id.x;
+    let listed = min(atomicLoad(&feedback[${L.REQUEST_COUNT}u]), settings.request_capacity);
+
+    if (index >= listed) {
+        return;
+    }
+
+    let base = ${L.HEADER_WORDS}u + index * ${L.REQUEST_WORDS}u;
+
+    let level = atomicLoad(&feedback[base + ${L.REQUEST_LEVEL}u]);
+    let page = vec2i(
+        i32(atomicLoad(&feedback[base + ${L.REQUEST_X}u])),
+        i32(atomicLoad(&feedback[base + ${L.REQUEST_Y}u])),
+    );
+
+    let record = ${RECORD_TABLE.marshalling_method_read}(&light_database, settings.record_row);
+
+    atomicStore(&feedback[base + ${L.REQUEST_IMPORTANCE}u], counts[vsm_cell_index(record, page, level)]);
+}
+`, [
+            RECORD_TABLE.chunk_read,
+            chunk_vsm_addressing,
+        ]),
+    resources,
+});

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

@@ -0,0 +1,30 @@
+export const VSM_MOVERS_WORKGROUP_SIZE: number;
+/**
+ * What the mover pass runs with: how many rows the "last seen" buffer covers, how many movers the
+ * list holds, and the dispatch's shape — `group_count` workgroups folded into rows of `groups_x`,
+ * since a table's pages can take more than one dimension of a dispatch holds.
+ *
+ * @type {WebGPUStruct}
+ */
+export const VSM_MOVERS_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * List the casters that moved since the last frame, for every virtual shadow map's stale pass.
+ *
+ * One thread per slot of the `meshes` table, freed pages included, against a buffer of what each
+ * row was when the pass last saw it ({@link VSM_LAST_SEEN_WORDS}). A row moved when its world matrix
+ * differs from the one the hierarchy pass kept from last frame, or when its world box, geometry or
+ * material differs from the one the pass saw — which is also how a row that appeared or left shows.
+ * A change to a material's parameters, the same material, is not seen. Nothing about a row is
+ * declared; what changed is observed. A mover is listed with the union of its box now and then:
+ * every page either one covers may hold its old shadow, or lack its new one.
+ *
+ * Dispatch with as many workgroups as the "last seen" buffer's rows need at
+ * {@link VSM_MOVERS_WORKGROUP_SIZE} — the table's pages, times its groups per page — folded into rows
+ * of at most a dispatch dimension's limit, and once per frame, before the stale passes.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_movers: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vsm_movers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vsm_movers.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/shader_vsm_movers.js"],"names":[],"mappings":"AAmBA,+CAA2E;AAE3E;;;;;;GAMG;AACH,yCAFU,YAAY,CAOE;AAiIxB;;;;;;;;;;;;;;;;GAgBG;AACH,gCAFU,aAAa,CAMpB;6BA9K0B,sCAAsC;8BALrC,kCAAkC"}

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

@@ -0,0 +1,184 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { chunk_scene_database_access, MESHES_TABLE } from "../../../scene/chunk_scene_database_access.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { GPU_DATABASE_NULL } from "../../../buffer/table/GPU_DATABASE_NULL.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    VSM_EMPTY_BOUND,
+    VSM_LAST_SEEN_GEOMETRY,
+    VSM_LAST_SEEN_MATERIAL,
+    VSM_LAST_SEEN_WORDS,
+    VSM_MOVERS_STRUCT
+} from "../VSM_MOVER_LAYOUT.js";
+import { chunk_vsm_append_mover } from "./chunk_vsm_append_mover.js";
+
+export const VSM_MOVERS_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+/**
+ * What the mover pass runs with: how many rows the "last seen" buffer covers, how many movers the
+ * list holds, and the dispatch's shape — `group_count` workgroups folded into rows of `groups_x`,
+ * since a table's pages can take more than one dimension of a dispatch holds.
+ *
+ * @type {WebGPUStruct}
+ */
+export const VSM_MOVERS_SETTINGS_STRUCT = WebGPUStruct.from({
+    row_count: u32,
+    capacity: u32,
+    groups_x: u32,
+    group_count: u32,
+}, "VSMMoversSettings");
+
+const WG = VSM_MOVERS_WORKGROUP_SIZE;
+const PG = MESHES_TABLE.page_iterator_symbol_prefix(WG);
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', VSM_MOVERS_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+    // per mesh row, what the pass saw it as last frame: its world box by the bits of its floats,
+    // then its geometry and material — empty and NULL for a row that held nothing
+    .addStorageBuffer('last_seen', WebGPUArray.from(u32), true)
+    .addStorageBuffer('movers', VSM_MOVERS_STRUCT, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const EMPTY = ${VSM_EMPTY_BOUND};
+const NO_MESH = ${GPU_DATABASE_NULL}u;
+const WORDS = ${VSM_LAST_SEEN_WORDS}u;
+
+@compute @workgroup_size(${WG},1,1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) local_id: u32,
+) {
+    // the dispatch's workgroups, folded into rows; the last row's tail past the count has nothing to
+    // walk, and leaves whole
+    let group_index = wg_id.x + wg_id.y * settings.groups_x;
+
+    if (group_index >= settings.group_count) {
+        return;
+    }
+
+    // the page iterator's own arithmetic, done here too: a page that has been freed is still walked,
+    // since the rows it held may have been casters a moment ago
+    let page_index = group_index / ${PG}_GROUPS_PER_PAGE;
+    let page_group = group_index % ${PG}_GROUPS_PER_PAGE;
+    let slot = page_group * ${WG}u + local_id;
+    let row = page_index * ${PG}_ELEMENTS_PER_PAGE + slot;
+
+    let tracked = slot < ${PG}_ELEMENTS_PER_PAGE && row < settings.row_count;
+
+    // the page address is uniform across the workgroup, so this is too
+    let allocated = ${PG}_setup(&scene_database, group_index, local_id);
+
+    var occupied = false;
+
+    if (allocated && slot < ${PG}_ELEMENTS_PER_PAGE) {
+        occupied = ${PG}_is_occupied(slot);
+    }
+
+    var now_min = vec3f(EMPTY);
+    var now_max = vec3f(-EMPTY);
+    var now_geometry = NO_MESH;
+    var now_material = NO_MESH;
+    var turned = false;
+
+    if (occupied) {
+        let mesh = ${PG}_read(&scene_database, slot);
+
+        now_geometry = mesh.geometry;
+        now_material = mesh.material;
+
+        now_min = vec3f(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
+        now_max = vec3f(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
+
+        // the hierarchy pass keeps last frame's world matrix beside this frame's: any change of the
+        // transform, including a turn that leaves the box where it was
+        let node = scene_read_node(&scene_database, mesh.node);
+
+        turned = any(node.global[0] != node.prev_global[0])
+            || any(node.global[1] != node.prev_global[1])
+            || any(node.global[2] != node.prev_global[2])
+            || any(node.global[3] != node.prev_global[3]);
+    }
+
+    var is_mover = false;
+    var box_min = now_min;
+    var box_max = now_max;
+
+    if (tracked) {
+        let base = row * WORDS;
+
+        let then_min = vec3f(
+            bitcast<f32>(last_seen[base]),
+            bitcast<f32>(last_seen[base + 1u]),
+            bitcast<f32>(last_seen[base + 2u]),
+        );
+        let then_max = vec3f(
+            bitcast<f32>(last_seen[base + 3u]),
+            bitcast<f32>(last_seen[base + 4u]),
+            bitcast<f32>(last_seen[base + 5u]),
+        );
+
+        // a row that appeared, left or changed shape has a box it did not have before; one given
+        // another mesh may keep its box, but not its geometry or material
+        let changed = any(now_min != then_min) || any(now_max != then_max)
+            || now_geometry != last_seen[base + ${VSM_LAST_SEEN_GEOMETRY}u]
+            || now_material != last_seen[base + ${VSM_LAST_SEEN_MATERIAL}u];
+
+        // where it is and where it was; an empty box is the identity of both
+        box_min = min(now_min, then_min);
+        box_max = max(now_max, then_max);
+
+        is_mover = (changed || turned) && all(box_min <= box_max);
+
+        last_seen[base] = bitcast<u32>(now_min.x);
+        last_seen[base + 1u] = bitcast<u32>(now_min.y);
+        last_seen[base + 2u] = bitcast<u32>(now_min.z);
+        last_seen[base + 3u] = bitcast<u32>(now_max.x);
+        last_seen[base + 4u] = bitcast<u32>(now_max.y);
+        last_seen[base + 5u] = bitcast<u32>(now_max.z);
+        last_seen[base + ${VSM_LAST_SEEN_GEOMETRY}u] = now_geometry;
+        last_seen[base + ${VSM_LAST_SEEN_MATERIAL}u] = now_material;
+    }
+
+    vsm_append_mover(is_mover, box_min, box_max, settings.capacity);
+}
+`, [
+    MESHES_TABLE.chunk_iterate(WG),
+    chunk_scene_database_access,
+    chunk_vsm_append_mover,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * List the casters that moved since the last frame, for every virtual shadow map's stale pass.
+ *
+ * One thread per slot of the `meshes` table, freed pages included, against a buffer of what each
+ * row was when the pass last saw it ({@link VSM_LAST_SEEN_WORDS}). A row moved when its world matrix
+ * differs from the one the hierarchy pass kept from last frame, or when its world box, geometry or
+ * material differs from the one the pass saw — which is also how a row that appeared or left shows.
+ * A change to a material's parameters, the same material, is not seen. Nothing about a row is
+ * declared; what changed is observed. A mover is listed with the union of its box now and then:
+ * every page either one covers may hold its old shadow, or lack its new one.
+ *
+ * Dispatch with as many workgroups as the "last seen" buffer's rows need at
+ * {@link VSM_MOVERS_WORKGROUP_SIZE} — the table's pages, times its groups per page — folded into rows
+ * of at most a dispatch dimension's limit, and once per frame, before the stale passes.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_movers = ComputeShader.from({
+    label: "VSM/Movers",
+    body,
+    resources,
+});