@woosh/meep-engine 3.38.0 → 3.39.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,
@@ -67,6 +72,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 +94,12 @@ const DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION = [
  */
 const DEFAULT_SHADOWMAP_LOCAL_RESOLUTION = 128;
 
+/**
+ * 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']);
+
 /**
  * Shadows for a single scene
  */
@@ -177,6 +189,34 @@ export class GPUSceneShadowmapContext {
      */
     use_tetrahedron_point_shadows = false;
 
+    /**
+     * 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 +287,30 @@ 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[]}
-     */
-    #caster_rows_free = [];
-
-    /**
-     * Rows ever claimed; the next new row.
-     * @type {number}
-     */
-    #caster_row_count = 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.
+     * 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_scratch = null;
 
     /**
-     * Rows {@link #caster_scratch} has words for.
+     * Cascade rows {@link #caster_scratch} has words for.
      * @type {number}
      */
     #caster_scratch_rows = 0;
 
     /**
-     * The readback service's handle for the caster range table, taken on first use.
+     * The readback service's handle for the `shadow_cascade` table, taken on first use.
      * @type {number}
      */
-    #caster_range_table = -1;
+    #cascade_table = -1;
+
+    /**
+     * Scratch for {@link #write_shadow_records}: the CPU's half of one cascade row.
+     * @type {{atlas: number[], projection: ArrayLike<number>}}
+     */
+    #cascade_record = { atlas: [0, 0, 0, 0], projection: null };
 
     /**
      * @returns {number} number of shadowmaps rasterized in the most recent draw pass
@@ -405,45 +439,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 +506,31 @@ 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');
+
+        for (let i = 0; i < map.cascade_count; i++) {
+            table.remove(first + i);
+        }
 
-        map.caster_row = -1;
+        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.
+     * 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 +541,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 +566,7 @@ export class GPUSceneShadowmapContext {
             bindings: {
                 scene_database: scene_ctx.scene_database_buffer,
                 settings,
+                planes,
                 ranges,
             },
         });
@@ -520,9 +578,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 +664,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
@@ -724,6 +782,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;
@@ -751,24 +812,50 @@ export class GPUSceneShadowmapContext {
 
             if (map.metadata_changed) {
                 table.set(slot, map.make_record());
+
+                if (light.isDirectionalLight) {
+                    // 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;
     }
 
     /**
@@ -899,7 +986,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);
         }
@@ -1321,7 +1408,7 @@ export class GPUSceneShadowmapContext {
         this.#release_map_gpu_contexts(map);
 
         if (map.light.isDirectionalLight === true) {
-            this.#release_caster_row(map);
+            this.#release_cascades(map);
         }
 
         map.light._gpu_shadowmap_id = -1;
@@ -1362,6 +1449,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 +1463,31 @@ export class GPUSceneShadowmapContext {
         let changed = false;
 
         const use_tetra = this.use_tetrahedron_point_shadows;
+        const cascade_count = this.#cascade_count;
         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.
+         *
+         * @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) {
+                return map.cascade_count !== cascade_count;
+            }
+
+            return false;
+        };
+
         registry.begin_reconcile();
         newcomers.length = 0;
 
@@ -1395,10 +1511,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 +1524,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 +1534,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 +1564,7 @@ export class GPUSceneShadowmapContext {
                 throw e;
             }
 
-            this.#claim_caster_row(map);
+            this.#claim_cascades(map);
             registry.add(map);
         };
 

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

@@ -159,7 +159,8 @@ 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 → array<SHADOWMAP_VIEW_METADATA_STRUCT, SHADOWMAP_CSM_CASCADE_COUNT>
+     *   - directional → CSM_SHADOWMAP_STRUCT (where its cascades are: a range over the
+     *     `shadow_cascade` table, whose rows the shadow context writes separately)
      * @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;;;;;;;OAOG;IACH,mBAEC;IAED,gBAEC;CACJ;oBA5LY,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;;;;;;;;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"}

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

@@ -177,7 +177,8 @@ 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 → array<SHADOWMAP_VIEW_METADATA_STRUCT, SHADOWMAP_CSM_CASCADE_COUNT>
+     *   - directional → CSM_SHADOWMAP_STRUCT (where its cascades are: a range over the
+     *     `shadow_cascade` table, whose rows the shadow context writes separately)
      * @returns {*}
      */
     make_record() {

package/src/shade/renderer/shadow/map/csm/CSM_CASCADE_STRUCT.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One cascade of a directional shadow map: a row of the light database's `shadow_cascade` table.
+ * A map's cascades are a run of consecutive rows, claimed and released together by the shadow
+ * context, which its `shadow_directional` record names as a range — so a map holds as many cascades
+ * as it was built with, and nothing about the record fixes how many that is.
+ *
+ * Two owners share the row. The CPU writes `atlas` and `projection` every frame it fits the
+ * cascade, and only those — through a writer that leaves the rest alone. The GPU writes
+ * `caster_near`, which is read back to fit the next frame's near plane; a whole-record write from
+ * the CPU would put its stale copy back over what the GPU published, ahead of the readback.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CSM_CASCADE_STRUCT: WebGPUStruct;
+/**
+ * The largest finite f32: what a cascade's caster range holds before anything is merged into it,
+ * and after the publish reset it. Not +inf, because WGSL will not const-fold
+ * `bitcast<f32>(0x7F800000u)`; no world coordinate comes within orders of magnitude of it.
+ *
+ * @type {number}
+ */
+export const CSM_CASTER_RANGE_UNKNOWN: number;
+/**
+ * {@link CSM_CASTER_RANGE_UNKNOWN} as the u32 bit pattern a scratch word is seeded with.
+ *
+ * @type {number}
+ */
+export const CSM_CASTER_RANGE_UNKNOWN_BITS: number;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=CSM_CASCADE_STRUCT.d.ts.map

package/src/shade/renderer/shadow/map/csm/CSM_CASCADE_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CSM_CASCADE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/csm/CSM_CASCADE_STRUCT.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,iCAFU,YAAY,CAoBE;AAExB;;;;;;GAMG;AACH,uCAFU,MAAM,CAEoC;AAEpD;;;;GAIG;AACH,4CAFU,MAAM,CAEwC;6BAjD3B,sCAAsC"}

package/src/shade/renderer/shadow/map/csm/CSM_CASCADE_STRUCT.js

@@ -0,0 +1,52 @@
+import { FLOAT32_MAX } from "../../../../../core/binary/FLOAT32_MAX.js";
+import { f32, mat4x4f, vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+
+/**
+ * One cascade of a directional shadow map: a row of the light database's `shadow_cascade` table.
+ * A map's cascades are a run of consecutive rows, claimed and released together by the shadow
+ * context, which its `shadow_directional` record names as a range — so a map holds as many cascades
+ * as it was built with, and nothing about the record fixes how many that is.
+ *
+ * Two owners share the row. The CPU writes `atlas` and `projection` every frame it fits the
+ * cascade, and only those — through a writer that leaves the rest alone. The GPU writes
+ * `caster_near`, which is read back to fit the next frame's near plane; a whole-record write from
+ * the CPU would put its stale copy back over what the GPU published, ahead of the readback.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CSM_CASCADE_STRUCT = WebGPUStruct.from({
+    /**
+     * Where in the shadow atlas the cascade is: x0, y0, width, height, in texels.
+     */
+    atlas: vec4f,
+    /**
+     * World to the cascade's clip space: the light camera's view-projection.
+     */
+    projection: mat4x4f,
+    /**
+     * `min(dot(light_z_axis, corner))` over the corners of every mesh row's world bounds that
+     * intersect the cascade's four side planes — measured from the world origin, so that a cascade
+     * whose centre moved between the frame it was measured for and the frame it is applied to can
+     * add its own translation. Written on the GPU by `shader_csm_caster_range_publish`;
+     * {@link CSM_CASTER_RANGE_UNKNOWN} when nothing was measured, which a reader treats as "no
+     * caster".
+     */
+    caster_near: f32,
+}, "CSMCascade").pack();
+
+/**
+ * The largest finite f32: what a cascade's caster range holds before anything is merged into it,
+ * and after the publish reset it. Not +inf, because WGSL will not const-fold
+ * `bitcast<f32>(0x7F800000u)`; no world coordinate comes within orders of magnitude of it.
+ *
+ * @type {number}
+ */
+export const CSM_CASTER_RANGE_UNKNOWN = FLOAT32_MAX;
+
+/**
+ * {@link CSM_CASTER_RANGE_UNKNOWN} as the u32 bit pattern a scratch word is seeded with.
+ *
+ * @type {number}
+ */
+export const CSM_CASTER_RANGE_UNKNOWN_BITS = 0x7F7FFFFF;

package/src/shade/renderer/shadow/map/csm/CSM_SHADOWMAP_STRUCT.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A directional light's shadow map: a row of the light database's `shadow_directional` table,
+ * which the light's `shadow_id` names. Nothing but where its cascades are — a range over the
+ * `shadow_cascade` table, one row per cascade, nearest first.
+ *
+ * The range does not own its rows: the shadow context claims a map's run when it builds the map and
+ * gives it back when it evicts it, while the record itself sits in a slot that is reassigned
+ * densely as maps come and go.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CSM_SHADOWMAP_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=CSM_SHADOWMAP_STRUCT.d.ts.map

package/src/shade/renderer/shadow/map/csm/CSM_SHADOWMAP_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CSM_SHADOWMAP_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/csm/CSM_SHADOWMAP_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,mCAFU,YAAY,CAOI;6BAlBG,sCAAsC"}

package/src/shade/renderer/shadow/map/csm/CSM_SHADOWMAP_STRUCT.js

@@ -0,0 +1,20 @@
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+
+/**
+ * A directional light's shadow map: a row of the light database's `shadow_directional` table,
+ * which the light's `shadow_id` names. Nothing but where its cascades are — a range over the
+ * `shadow_cascade` table, one row per cascade, nearest first.
+ *
+ * The range does not own its rows: the shadow context claims a map's run when it builds the map and
+ * gives it back when it evicts it, while the record itself sits in a slot that is reassigned
+ * densely as maps come and go.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CSM_SHADOWMAP_STRUCT = WebGPUStruct.from({
+    /** row of the map's nearest cascade in `shadow_cascade` */
+    first_cascade: u32,
+    /** how many cascades follow it, the nearest included */
+    cascade_count: u32,
+}, "CSMShadowmap").pack();

package/src/shade/renderer/shadow/map/csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How many cascades a directional shadow map (Cascaded Shadow Maps) has until told otherwise —
+ * {@link Renderer.shadow_cascade_count} sets it at runtime.
+ * NOTE: Capcom seems to use 3 cascades base on https://www.youtube.com/watch?v=nWgPtCDXlPc
+ * @type {number}
+ */
+export const SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT: number;
+//# sourceMappingURL=SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.d.ts.map

package/src/shade/renderer/shadow/map/csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,kDAFU,MAAM,CAEqC"}

package/src/shade/renderer/shadow/map/csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.js

@@ -0,0 +1,7 @@
+/**
+ * How many cascades a directional shadow map (Cascaded Shadow Maps) has until told otherwise —
+ * {@link Renderer.shadow_cascade_count} sets it at runtime.
+ * NOTE: Capcom seems to use 3 cascades base on https://www.youtube.com/watch?v=nWgPtCDXlPc
+ * @type {number}
+ */
+export const SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT = 3;