@woosh/meep-engine 3.38.0 → 3.39.0

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

@@ -20,14 +20,18 @@ 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 { 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 +39,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 +59,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 +73,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 +115,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 +147,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 +165,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 +238,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 +430,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 +461,35 @@ 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,
+        };
+    }
+
+    /**
+     * 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;
     }
 
 }

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

@@ -50,6 +50,20 @@ export class GPUSceneShadowmapContext {
      * @type {boolean}
      */
     use_tetrahedron_point_shadows: boolean;
+    /**
+     * 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: number);
+    /**
+     * @returns {number} cascades per directional shadow map
+     */
+    get cascade_count(): number;
     /**
      * @param {number} v views per frame, at least one. A higher budget keeps more lights current
      *        and rasterizes more per frame; a lower one refreshes fewer of them per frame and
@@ -80,12 +94,12 @@ export class GPUSceneShadowmapContext {
      */
     get debug_drop_size_scale(): number;
     /**
-     * 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(): number;
+    get cascade_table(): number;
     /**
      *
      * @param {Light} light
@@ -110,7 +124,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
@@ -208,6 +223,7 @@ export type GPULightCollection = import("../../light/GPULightCollection.js").GPU
 export type Light = import("../../light/model/Light.js").Light;
 export type GPUSceneContext = import("../../scene/GPUSceneContext.js").GPUSceneContext;
 export type Shadowmap = import("./Shadowmap.js").Shadowmap;
+export type GPURecordWriter = import("../../buffer/table/serde/generate_record_writer.js").GPURecordWriter;
 import { MaxRectanglesPacker } from "../../../../core/geom/packing/max-rect/MaxRectanglesPacker.js";
 import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 import { ViewManager } from "../../view/ViewManager.js";

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

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AA0FA;;GAEG;AACH;IAgPI;;;;;;;;OAQG;IACH,sBAPW,eAAe,aACf,eAAe,SAGf,kBAAkB,EAiE5B;IAtTD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsCpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IA2BtC;;;;OAIG;IACH,6BAIC;IAhBD;;OAEG;IACH,4BAEC;IA8ED;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAoGD;;;;;OAKG;IACH,iCAMC;IAoKD;;;;OAIG;IACH,eAHW,KAAK,GACH,SAAS,GAAC,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,6BAPW,MAAM,SAEN,eAAe,eACf,MAAM,mBACN,UAAU,MAAM,CAAC,QAoE3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAFW,sBAAsB,QAwFhC;IAsbD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAwOnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAiBC;;CACJ;qCA/gDY,OAAO,2CAA2C,EAAE,sBAAsB;8BAC1E,OAAO,0BAA0B,EAAE,eAAe;qBAClD,OAAO,wBAAwB,EAAE,MAAM;iCACvC,OAAO,mCAAmC,EAAE,kBAAkB;oBAC9D,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;wBACxD,OAAO,gBAAgB,EAAE,SAAS;oCAhEX,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}
+{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AAsGA;;GAEG;AACH;IAsQI;;;;;;;;OAQG;IACH,sBAPW,eAAe,aACf,eAAe,SAGf,kBAAkB,EAiE5B;IA5UD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsCpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IAetC;;;;;;;;OAQG;IACH,6BAIC;IApBD;;OAEG;IACH,4BAEC;IA0CD;;;;OAIG;IACH,6BAIC;IAhBD;;OAEG;IACH,4BAEC;IAwED;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAoGD;;;;;OAKG;IACH,4BAMC;IA2LD;;;;OAIG;IACH,eAHW,KAAK,GACH,SAAS,GAAC,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,6BAPW,MAAM,SAEN,eAAe,eACf,MAAM,mBACN,UAAU,MAAM,CAAC,QAoE3B;IAsGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAFW,sBAAsB,QAwFhC;IAsbD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAiQnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAiBC;;CACJ;qCA1nDY,OAAO,2CAA2C,EAAE,sBAAsB;8BAC1E,OAAO,0BAA0B,EAAE,eAAe;qBAClD,OAAO,wBAAwB,EAAE,MAAM;iCACvC,OAAO,mCAAmC,EAAE,kBAAkB;oBAC9D,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;wBACxD,OAAO,gBAAgB,EAAE,SAAS;8BAClC,OAAO,oDAAoD,EAAE,eAAe;oCAtErD,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}