@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/shader/resource/ShaderResourceGroupDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderResourceGroupDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceGroupDescriptor.js"],"names":[],"mappings":"AAeA;;;;;GAKG;AAEH;IAEI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAQV;;OAEG;IACH,4CAEC;IAED;;;;;OAKG;IACH,qCAHW,sBAAsB,GACpB,oBAAoB,CAoHhC;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAc/B;IAED;;;;OAIG;IACH,6CAFa,mBAAmB,CA6B/B;IAED;;;OAGG;IACH,mDAHW,iBAAe,MAAM,GACnB,yBAAyB,CAqBrC;IAED;;;OAGG;IACH,gBAFY,MAAM,CAWjB;IAED;;;;OAIG;IACH,WAHW,MAAM,YACN,wBAAwB,QAUlC;IAED;;;;OAIG;IACH,UAHW,MAAM,GACJ,wBAAwB,GAAC,SAAS,CAiB9C;IAqDD;;;;;;OAMG;IACH,iBALW,MAAM,SACN,UAAU,GAAC,MAAM,wBAEf,IAAI,CAqChB;IAED;;;;;;OAMG;IACH,uBALW,MAAM,QACN,UAAU,kBACV,OAAO,GACL,IAAI,CAmBhB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,mFAGN,OAAO,kBACP,YAAY,GACV,IAAI,CA8ChB;IAED;;;;;;;OAOG;IACH,wBANW,MAAM,qGAIL,6BAA6B,CAyBxC;IAED;;;;;;OAMG;IACH,iBALW,MAAM,gDAEN,iBAAiB,GACf,6BAA6B,CA4BzC;;CAEJ;gCA1gBY,OAAO,kDAAkD,EAAE,iBAAiB;qCAC5E,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,+BAA+B,EAAE,YAAY;yBACpD,OAAO,uBAAuB,EAAE,UAAU;yCANd,+BAA+B;0CAV9B,0DAA0D"}
+{"version":3,"file":"ShaderResourceGroupDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceGroupDescriptor.js"],"names":[],"mappings":"AAqCA;IAEI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAQV;;OAEG;IACH,4CAEC;IAED;;;;;OAKG;IACH,qCAHW,sBAAsB,GACpB,oBAAoB,CAkJhC;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAc/B;IAED;;;;OAIG;IACH,6CAFa,mBAAmB,CA6B/B;IAED;;;OAGG;IACH,mDAHW,iBAAe,MAAM,GACnB,yBAAyB,CAqBrC;IAED;;;OAGG;IACH,gBAFY,MAAM,CAWjB;IAED;;;;OAIG;IACH,WAHW,MAAM,YACN,wBAAwB,QAUlC;IAED;;;;OAIG;IACH,UAHW,MAAM,GACJ,wBAAwB,GAAC,SAAS,CAiB9C;IAqDD;;;;;;OAMG;IACH,iBALW,MAAM,SACN,UAAU,GAAC,MAAM,wBAEf,IAAI,CAqChB;IAED;;;;;;OAMG;IACH,uBALW,MAAM,QACN,UAAU,kBACV,OAAO,GACL,IAAI,CAmBhB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,mFAGN,OAAO,kBACP,YAAY,GACV,IAAI,CA8ChB;IAED;;;;;;;OAOG;IACH,wBANW,MAAM,qGAIL,6BAA6B,CAyBxC;IAED;;;;;;OAMG;IACH,iBALW,MAAM,gDAEN,iBAAiB,GACf,6BAA6B,CA4BzC;;CAEJ;gCAvjBY,OAAO,kDAAkD,EAAE,iBAAiB;qCAC5E,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,+BAA+B,EAAE,YAAY;yBACpD,OAAO,uBAAuB,EAAE,UAAU;yCANd,+BAA+B;0CAV9B,0DAA0D"}

package/src/shade/renderer/shader/resource/ShaderResourceGroupDescriptor.js

@@ -20,6 +20,21 @@ import { ShaderResourceDescriptor } from "./ShaderResourceDescriptor.js";
  * @typedef {import("../type/WebGPUType.js").WebGPUType} WebGPUType
  */
 
+/**
+ * What a binding was given, for an error message: the class of an object, since its string form is
+ * `[object Object]`.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+function describe_binding_value(value) {
+    if (typeof value === "object") {
+        return `a ${value.constructor?.name ?? "prototype-less object"}`;
+    }
+
+    return `${typeof value} '${value}'`;
+}
+
 export class ShaderResourceGroupDescriptor {
 
     /**
@@ -152,7 +167,37 @@ export class ShaderResourceGroupDescriptor {
                 } else if (binding_value.isGPUTextureContext === true) {
                     binding_value = binding_value.obtainView();
                 } else {
-                    throw new Error(`Unexpected texture value '${binding_value}'`)
+                    throw new Error(`Texture '${resource.name}' was given ${describe_binding_value(binding_value)}, which is neither a GPUTextureView, a GPUTextureContext nor a ShadeTexture`);
+                }
+
+            } else if (resource.type === ResourceType.Sampler) {
+
+                // Resolved here as the frame graph does in `encoder_prepare_shader_binding`. Passed
+                // through, a descriptor reaches createBindGroup, which reads it as a GPUBufferBinding
+                // with no buffer and says only that — not which binding, nor that it was a sampler.
+                if (binding_value.isSamplerDescriptor === true) {
+                    // not an assert, for the same reason as the ShadeTexture branch above
+                    if (encoder === undefined || encoder === null) {
+                        throw new Error(
+                            `Binding '${resource.name}' is a SamplerDescriptor, which only the encoder can`
+                            + ` resolve to a sampler, and generateBindings was called without one`
+                        );
+                    }
+
+                    binding_value = encoder.graphics.samplers.obtain(binding_value);
+                } else if (!(binding_value instanceof GPUSampler)) {
+                    throw new Error(`Sampler '${resource.name}' was given ${describe_binding_value(binding_value)}, which is neither a GPUSampler nor a SamplerDescriptor`);
+                }
+
+            } else if (resource.type === ResourceType.StorageTexture) {
+
+                // as above: a texture context passed through fails in createBindGroup the same way
+                if (binding_value.isGPUTextureContext === true) {
+                    assert.notEqual(binding_value.descriptor.usage & GPUTextureUsage.STORAGE_BINDING, 0, `storage texture '${resource.name}' does not declare STORAGE_BINDING`);
+
+                    binding_value = binding_value.obtainView();
+                } else if (!(binding_value instanceof GPUTextureView)) {
+                    throw new Error(`Storage texture '${resource.name}' was given ${describe_binding_value(binding_value)}, which is neither a GPUTextureView nor a GPUTextureContext`);
                 }
 
             }

package/src/shade/renderer/shader/type/serde/read_gpu_typed_buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read_gpu_typed_buffer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/type/serde/read_gpu_typed_buffer.js"],"names":[],"mappings":"AAuGA;;;;GAIG;AACH,6CAHW,YAAY,yBAqDtB;AAwBD;;;;;;GAMG;AACH,8DALW,WAAW,eACX,MAAM,UACN,MAAM,GACJ,EAAE,CAsBd;6BAjN4B,4CAA4C"}
+{"version":3,"file":"read_gpu_typed_buffer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/type/serde/read_gpu_typed_buffer.js"],"names":[],"mappings":"AAwGA;;;;GAIG;AACH,6CAHW,YAAY,yBAqDtB;AAwBD;;;;;;GAMG;AACH,8DALW,WAAW,eACX,MAAM,UACN,MAAM,GACJ,EAAE,CAsBd;6BAlN4B,4CAA4C"}

package/src/shade/renderer/shader/type/serde/read_gpu_typed_buffer.js

@@ -79,11 +79,12 @@ function read_multiple_f32(buffer, count) {
  *
  * @param {BinaryBuffer} buffer
  * @param {number} count
- * @returns {Uint32Array}
+ * @returns {Int32Array}
  */
 function read_multiple_i32(buffer, count) {
 
-    const r = new Uint32Array(count);
+    // signed storage, or every negative component reads back as its u32 bit pattern
+    const r = new Int32Array(count);
     buffer.readInt32Array(r, 0, count);
     return r;
 }

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

@@ -1,14 +1,14 @@
 /**
  * Default per-frame shadow refresh budget, measured in **views** (one cube face counts as one
  * view, one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
- * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
- * keeps the cost of the refresh step roughly proportional to how much work we're asking the
- * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
- * equivalent work to 6 spot lights.
+ * directional one per cascade ({@link GPUSceneShadowmapContext.cascade_count}). A bigger light
+ * consumes more of the budget, which keeps the cost of the refresh step roughly proportional to
+ * how much work we're asking the GPU to do — a single point light running the meshlet
+ * rasterization pipeline 6 times is equivalent work to 6 spot lights.
  *
- * Directional lights are always refreshed unconditionally (they drive the whole scene) and
- * their view cost is charged against the budget, so they effectively reduce the pool available
- * for local lights that frame.
+ * Directional lights are always refreshed unconditionally (they drive the whole scene), and their
+ * views are not charged against the budget: they cannot be refused, so charging them could only
+ * shrink the pool the local lights compete for — see {@link ShadowmapDrawSelector}.
  *
  * Unused budget is carried over between frames when demand exceeds supply. This lets a light
  * that's too expensive to fit in a single frame (e.g. a point needing 6 views when only 2 are

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

@@ -1,14 +1,14 @@
 /**
  * Default per-frame shadow refresh budget, measured in **views** (one cube face counts as one
  * view, one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
- * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
- * keeps the cost of the refresh step roughly proportional to how much work we're asking the
- * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
- * equivalent work to 6 spot lights.
+ * directional one per cascade ({@link GPUSceneShadowmapContext.cascade_count}). A bigger light
+ * consumes more of the budget, which keeps the cost of the refresh step roughly proportional to
+ * how much work we're asking the GPU to do — a single point light running the meshlet
+ * rasterization pipeline 6 times is equivalent work to 6 spot lights.
  *
- * Directional lights are always refreshed unconditionally (they drive the whole scene) and
- * their view cost is charged against the budget, so they effectively reduce the pool available
- * for local lights that frame.
+ * Directional lights are always refreshed unconditionally (they drive the whole scene), and their
+ * views are not charged against the budget: they cannot be refused, so charging them could only
+ * shrink the pool the local lights compete for — see {@link ShadowmapDrawSelector}.
  *
  * Unused budget is carried over between frames when demand exceeds supply. This lets a light
  * that's too expensive to fit in a single frame (e.g. a point needing 6 views when only 2 are

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

@@ -0,0 +1,19 @@
+/**
+ * A directional light's shadow map: a row of the light database's `shadow_directional` table,
+ * which the light's `shadow_id` names. It says where the map is, which is one of two things:
+ *
+ * - **cascades** — a range over the `shadow_cascade` table, one row per cascade, nearest first, with
+ *   `virtual_map` naming nothing;
+ * - **a virtual shadow map** — `virtual_map` names its row of the `shadow_virtual` table, and the
+ *   cascade range is empty.
+ *
+ * Neither the range nor the link owns its rows: the shadow context claims a map's rows when it
+ * builds the map and gives them back when it evicts it, while the record itself sits in a slot that
+ * is reassigned densely as maps come and go. A record written without `virtual_map` leaves it
+ * naming nothing, which is how a cascaded map's record is written.
+ *
+ * @type {WebGPUStruct}
+ */
+export const DIRECTIONAL_SHADOWMAP_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=DIRECTIONAL_SHADOWMAP_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DIRECTIONAL_SHADOWMAP_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/DIRECTIONAL_SHADOWMAP_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,YAAY,CASY;6BAzBL,mCAAmC"}

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

@@ -0,0 +1,27 @@
+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. It says where the map is, which is one of two things:
+ *
+ * - **cascades** — a range over the `shadow_cascade` table, one row per cascade, nearest first, with
+ *   `virtual_map` naming nothing;
+ * - **a virtual shadow map** — `virtual_map` names its row of the `shadow_virtual` table, and the
+ *   cascade range is empty.
+ *
+ * Neither the range nor the link owns its rows: the shadow context claims a map's rows when it
+ * builds the map and gives them back when it evicts it, while the record itself sits in a slot that
+ * is reassigned densely as maps come and go. A record written without `virtual_map` leaves it
+ * naming nothing, which is how a cascaded map's record is written.
+ *
+ * @type {WebGPUStruct}
+ */
+export const DIRECTIONAL_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,
+    /** the map's row in `shadow_virtual`, or NULL for a cascaded map */
+    virtual_map: u32,
+}, "DirectionalShadowmap").pack();

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

@@ -1,4 +1,8 @@
 export class DirectionalLightShadowmap extends Shadowmap {
+    /**
+     * @param {number} cascade_count how many cascades to split the view range into
+     */
+    constructor(cascade_count: number);
     /**
      * The closest depth that is covered by the shadow cascades
      * @type {number}
@@ -9,14 +13,27 @@ export class DirectionalLightShadowmap extends Shadowmap {
      * @type {number}
      */
     distance_max: number;
+    /**
+     * How many cascades the map was built with. Fixed for its life: a different count is a
+     * different map, which the shadow context builds in its place.
+     *
+     * @type {number}
+     */
+    cascade_count: number;
+    /**
+     * Per cascade, how far its slice reaches into the view range, as a fraction of it.
+     *
+     * @type {Float32Array}
+     */
     splits: Float32Array;
     /**
-     * The row of the light database's `shadow_csm_caster_range` table this map's caster range is
-     * published into, claimed by the shadow context with the map; -1 until then.
+     * The row of the map's nearest cascade in the light database's `shadow_cascade` table — its
+     * cascades are {@link cascade_count} rows from here — claimed by the shadow context with the
+     * map; -1 until then and after it is given back.
      *
      * @type {number}
      */
-    caster_row: number;
+    first_cascade: number;
     /**
      * Per cascade, the nearest caster along the light's axis that the GPU measured — from the
      * world origin, the previous frame's cascade frusta — as the readback delivered it. NaN until
@@ -34,22 +51,38 @@ export class DirectionalLightShadowmap extends Shadowmap {
     caster_range_valid: boolean;
     /**
      * What the accumulate pass measures this frame's casters against: the light's axis and each
-     * cascade's four side planes, as {@link update} fitted them. `base` is the shadow context's.
-     *
-     * `planes` is what is marshalled — a vec4 per plane — and `planes_words` the one buffer those
-     * are views over, which {@link update} writes.
+     * cascade's four side planes, as {@link update} fitted them, inward, a vec4 per plane and four
+     * planes per cascade. `base` is the shadow context's.
      *
-     * @type {{z_axis: Float32Array, planes: Float32Array[], planes_words: Float32Array, base: number, cascade_count: number}}
+     * @type {{z_axis: Float32Array, planes_words: Float32Array, base: number, cascade_count: number}}
      */
     caster_settings: {
         z_axis: Float32Array;
-        planes: Float32Array[];
         planes_words: Float32Array;
         base: number;
         cascade_count: number;
     };
     update(main_camera: any, scene_ctx: any): void;
-    make_record(): any[];
+    make_record(): {
+        first_cascade: number;
+        cascade_count: number;
+        virtual_map: number;
+    };
+    /**
+     * The CPU's half of cascade `index`'s `shadow_cascade` row: where it is in the atlas, and the
+     * view-projection it was drawn with. The other half, `caster_near`, is the GPU's.
+     *
+     * @param {number} index
+     * @param {{atlas: number[], projection: ArrayLike<number>}} result written into and returned
+     * @returns {{atlas: number[], projection: ArrayLike<number>}}
+     */
+    make_cascade_record(index: number, result: {
+        atlas: number[];
+        projection: ArrayLike<number>;
+    }): {
+        atlas: number[];
+        projection: ArrayLike<number>;
+    };
     #private;
 }
 import { Shadowmap } from "./Shadowmap.js";

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

@@ -1 +1 @@
-{"version":3,"file":"DirectionalLightShadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/DirectionalLightShadowmap.js"],"names":[],"mappings":"AAiGA;IACI;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB,qBAAuD;IAEvD;;;;;OAKG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;;;;OAOG;IACH,cAFU,YAAY,CAEiD;IASvE;;;;OAIG;IACH,oBAFU,OAAO,CAEU;IAE3B;;;;;;;;OAQG;IACH,iBAFU;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,YAAY,EAAE,CAAC;QAAC,YAAY,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAC,CAYpH;IAEL,+CAiQC;IAED,qBAYC;;CAEJ;0BA5ZyB,gBAAgB"}
+{"version":3,"file":"DirectionalLightShadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/DirectionalLightShadowmap.js"],"names":[],"mappings":"AAyGA;IAsEI;;OAEG;IACH,2BAFW,MAAM,EAiBhB;IAvFD;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAFU,MAAM,CAEF;IAEd;;;;OAIG;IACH,QAFU,YAAY,CAEf;IAEP;;;;;;OAMG;IACH,eAFU,MAAM,CAEG;IAEnB;;;;;;;OAOG;IACH,cAFU,YAAY,CAET;IASb;;;;OAIG;IACH,oBAFU,OAAO,CAEU;IAE3B;;;;;;OAMG;IACH,iBAFU;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,YAAY,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAC,CAEjF;IAsBhB,+CA0QC;IAED;;;;MAQC;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,UACN;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,UAAU,MAAM,CAAC,CAAA;KAAC,GAC9C;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,UAAU,MAAM,CAAC,CAAA;KAAC,CAiB5D;;CAEJ;0BAxdyB,gBAAgB"}

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

@@ -20,14 +20,19 @@ import { inverseLerp } from "../../../../core/math/inverseLerp.js";
 import {
     quaternion_invert_orientation
 } from "../../../../engine/graphics/ecs/camera/quaternion_invert_orientation.js";
-import { CSM_CASTER_RANGE_UNKNOWN } from "./csm/CSM_CASTER_RANGE_STRUCT.js";
+import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import { CSM_CASCADE_STRUCT, CSM_CASTER_RANGE_UNKNOWN } from "./csm/CSM_CASCADE_STRUCT.js";
 import { SHADOWMAP_CSM_CASCADE_BLEND_FRACTION } from "./csm/SHADOWMAP_CSM_CASCADE_BLEND_FRACTION.js";
-import { SHADOWMAP_CSM_CASCADE_COUNT } from "./csm/SHADOWMAP_CSM_CASCADE_COUNT.js";
 import { SHADOWMAP_CSM_CASTER_RANGE_MARGIN_FRACTION } from "./csm/SHADOWMAP_CSM_CASTER_RANGE_MARGIN_FRACTION.js";
 import { Shadowmap } from "./Shadowmap.js";
 import { SHADOWMAP_FILTER_SIZE } from "./SHADOWMAP_FILTER_SIZE.js";
 import { update_frustum_far_plane } from "./update_frustum_far_plane.js";
 
+/**
+ * Where a cascade's `caster_near` sits in its `shadow_cascade` record — what the readback asks for.
+ * @type {number}
+ */
+const CASTER_NEAR_BYTE_OFFSET = CSM_CASCADE_STRUCT.get('caster_near').offset;
 
 /**
  *
@@ -35,13 +40,15 @@ import { update_frustum_far_plane } from "./update_frustum_far_plane.js";
  * @param {number} result_offset
  * @param {number} near_plane
  * @param {number} far_plane
+ * @param {number} cascade_count
  * @returns {number[]}
  * see {@link build_light_cluster_parameters}
  */
 function build_split_parameters(result,
                                 result_offset,
                                 near_plane,
-                                far_plane) {
+                                far_plane,
+                                cascade_count) {
 
     // reference: https://github.com/InsaneZeroGame/Re3D/blob/eddeef8335f30a888c6fa3458d119904acd53517/renderer/render_utils.cpp#L72
 
@@ -53,7 +60,7 @@ function build_split_parameters(result,
 
     const offset = near_plane + near_offset;
 
-    const O = (far_plane - offset * exp2((SHADOWMAP_CSM_CASCADE_COUNT) / scale)) / (far_plane - offset);
+    const O = (far_plane - offset * exp2(cascade_count / scale)) / (far_plane - offset);
     const B = (1.0 - O) / offset;
 
     result[result_offset] = B;
@@ -67,17 +74,18 @@ function build_split_parameters(result,
  *
  * @param {number} cascade_index
  * @param {number[]} cascade_parameters
+ * @param {number} cascade_count
  * @return {number}
  * see {@link chunk_cluster_depth_from_z_slice}
  */
-function cascade_distance(cascade_index, cascade_parameters) {
+function cascade_distance(cascade_index, cascade_parameters, cascade_count) {
     let depth = (exp2(cascade_index / cascade_parameters[2]) - cascade_parameters[1]) / cascade_parameters[0];
 
     if (cascade_index <= 0) {
         depth = 0.0;
     }
 
-    if (cascade_index >= (SHADOWMAP_CSM_CASCADE_COUNT + 1)) {
+    if (cascade_index >= (cascade_count + 1)) {
         depth = Infinity;
     }
 
@@ -108,15 +116,29 @@ export class DirectionalLightShadowmap extends Shadowmap {
      */
     distance_max = 1;
 
-    splits = new Float32Array(SHADOWMAP_CSM_CASCADE_COUNT);
+    /**
+     * How many cascades the map was built with. Fixed for its life: a different count is a
+     * different map, which the shadow context builds in its place.
+     *
+     * @type {number}
+     */
+    cascade_count;
 
     /**
-     * The row of the light database's `shadow_csm_caster_range` table this map's caster range is
-     * published into, claimed by the shadow context with the map; -1 until then.
+     * Per cascade, how far its slice reaches into the view range, as a fraction of it.
+     *
+     * @type {Float32Array}
+     */
+    splits;
+
+    /**
+     * The row of the map's nearest cascade in the light database's `shadow_cascade` table — its
+     * cascades are {@link cascade_count} rows from here — claimed by the shadow context with the
+     * map; -1 until then and after it is given back.
      *
      * @type {number}
      */
-    caster_row = -1;
+    first_cascade = -1;
 
     /**
      * Per cascade, the nearest caster along the light's axis that the GPU measured — from the
@@ -126,14 +148,14 @@ export class DirectionalLightShadowmap extends Shadowmap {
      *
      * @type {Float32Array}
      */
-    caster_range = new Float32Array(SHADOWMAP_CSM_CASCADE_COUNT).fill(NaN);
+    caster_range;
 
     /**
      * {@link caster_range} as the bytes the readback writes into.
      *
      * @type {Uint8Array}
      */
-    #caster_range_bytes = new Uint8Array(this.caster_range.buffer);
+    #caster_range_bytes;
 
     /**
      * Whether {@link caster_range} has ever been delivered.
@@ -144,24 +166,32 @@ export class DirectionalLightShadowmap extends Shadowmap {
 
     /**
      * What the accumulate pass measures this frame's casters against: the light's axis and each
-     * cascade's four side planes, as {@link update} fitted them. `base` is the shadow context's.
+     * cascade's four side planes, as {@link update} fitted them, inward, a vec4 per plane and four
+     * planes per cascade. `base` is the shadow context's.
      *
-     * `planes` is what is marshalled — a vec4 per plane — and `planes_words` the one buffer those
-     * are views over, which {@link update} writes.
-     *
-     * @type {{z_axis: Float32Array, planes: Float32Array[], planes_words: Float32Array, base: number, cascade_count: number}}
+     * @type {{z_axis: Float32Array, planes_words: Float32Array, base: number, cascade_count: number}}
      */
-    caster_settings = (() => {
-        const planes_words = new Float32Array(SHADOWMAP_CSM_CASCADE_COUNT * 16);
+    caster_settings;
 
-        return {
+    /**
+     * @param {number} cascade_count how many cascades to split the view range into
+     */
+    constructor(cascade_count) {
+        super();
+
+        assert.isPositiveInteger(cascade_count, 'cascade_count');
+
+        this.cascade_count = cascade_count;
+        this.splits = new Float32Array(cascade_count);
+        this.caster_range = new Float32Array(cascade_count).fill(NaN);
+        this.#caster_range_bytes = new Uint8Array(this.caster_range.buffer);
+        this.caster_settings = {
             z_axis: new Float32Array(4),
-            planes: Array.from({ length: SHADOWMAP_CSM_CASCADE_COUNT * 4 }, (_, i) => planes_words.subarray(i * 4, i * 4 + 4)),
-            planes_words,
+            planes_words: new Float32Array(cascade_count * 16),
             base: 0,
-            cascade_count: SHADOWMAP_CSM_CASCADE_COUNT,
+            cascade_count,
         };
-    })();
+    }
 
     update(main_camera, scene_ctx) {
 
@@ -209,15 +239,17 @@ export class DirectionalLightShadowmap extends Shadowmap {
         const far_clip = SHADOW_MAX_DISTANCE;
         const near_clip = main_camera.near;
 
-        build_split_parameters(split_params, 0, near_clip, far_clip);
+        const cascade_count = this.cascade_count;
+
+        assert.equal(views.length, cascade_count, 'a view per cascade');
 
-        const cascade_count = views.length;
+        build_split_parameters(split_params, 0, near_clip, far_clip, cascade_count);
 
         const splits = this.splits;
 
         for (let i = 0; i < cascade_count; i++) {
 
-            const d = cascade_distance(i + 1, split_params);
+            const d = cascade_distance(i + 1, split_params, cascade_count);
 
             splits[i] = inverseLerp(near_clip, far_clip, d);
 
@@ -399,19 +431,26 @@ export class DirectionalLightShadowmap extends Shadowmap {
 
         }
 
-        // record carries one projection per cascade — recomputed above, so the
-        // shadow_directional row needs to be re-published.
+        // each cascade's row carries its projection — recomputed above, so the rows need to be
+        // written again; the shadow context writes them with the record when this is set
         this.metadata_changed = true;
 
-        // and ask for what the pass measures this frame, for the next frame's fit
-        if (this.caster_row !== -1) {
-            readback.request(
-                scene_ctx.lights.shadow_context.caster_range_table,
-                this.caster_row,
-                0,
-                this.#caster_range_bytes.length,
-                this.#caster_range_bytes
-            );
+        // and ask for what the pass measures this frame, for the next frame's fit: a cascade's
+        // range is one field of its row, and consecutive requests into consecutive bytes of the
+        // same target are delivered as one
+        if (this.first_cascade !== -1) {
+            const table = scene_ctx.lights.shadow_context.cascade_table;
+
+            for (let i = 0; i < cascade_count; i++) {
+                readback.request(
+                    table,
+                    this.first_cascade + i,
+                    CASTER_NEAR_BYTE_OFFSET,
+                    4,
+                    this.#caster_range_bytes,
+                    i * 4
+                );
+            }
         }
 
         // csm_debug_draw_preview({
@@ -423,17 +462,38 @@ export class DirectionalLightShadowmap extends Shadowmap {
     }
 
     make_record() {
-        const cascades = new Array(SHADOWMAP_CSM_CASCADE_COUNT);
-
-        for (let i = 0; i < SHADOWMAP_CSM_CASCADE_COUNT; i++) {
-            const aabb = this.layout[i];
-            cascades[i] = {
-                atlas: [aabb.x0, aabb.y0, aabb.width, aabb.height],
-                projection: this.views[i].camera.view_projection_matrix,
-            };
-        }
+        return {
+            first_cascade: this.first_cascade,
+            cascade_count: this.cascade_count,
+            // said outright: the slot may have held a virtual map's record a moment ago, and a write
+            // that leaves a field out keeps what the row had
+            virtual_map: GPU_DATABASE_NULL,
+        };
+    }
+
+    /**
+     * The CPU's half of cascade `index`'s `shadow_cascade` row: where it is in the atlas, and the
+     * view-projection it was drawn with. The other half, `caster_near`, is the GPU's.
+     *
+     * @param {number} index
+     * @param {{atlas: number[], projection: ArrayLike<number>}} result written into and returned
+     * @returns {{atlas: number[], projection: ArrayLike<number>}}
+     */
+    make_cascade_record(index, result) {
+        assert.isNonNegativeInteger(index, 'index');
+        assert.lessThan(index, this.cascade_count, 'index');
+
+        const aabb = this.layout[index];
+        const atlas = result.atlas;
+
+        atlas[0] = aabb.x0;
+        atlas[1] = aabb.y0;
+        atlas[2] = aabb.width;
+        atlas[3] = aabb.height;
+
+        result.projection = this.views[index].camera.view_projection_matrix;
 
-        return cascades;
+        return result;
     }
 
 }