@woosh/meep-engine 3.33.0 → 3.35.0

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../../core/assert.js";
 import { shadowmap_budget_carry_over } from "./shadowmap_budget_carry_over.js";
+import { SHADOWMAP_VGEO_TAU_SCALE } from "./SHADOWMAP_VGEO_TAU_SCALE.js";
 import AABB2 from "../../../../core/geom/2d/aabb/AABB2.js";
 import { MaxRectanglesPacker } from "../../../../core/geom/packing/max-rect/MaxRectanglesPacker.js";
 import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
@@ -32,6 +33,8 @@ import {
     shader_csm_caster_range_publish,
 } from "./csm/shader/shader_csm_caster_range.js";
 import { DEFAULT_SHADOWMAP_UPDATE_BUDGET } from "./DEFAULT_SHADOWMAP_UPDATE_BUDGET.js";
+import { VGEO_CUT_STAT } from "../../geometry/virtual/runtime/layout/VGEO_CUT_STAT.js";
+import { shadowmap_caster_detail_pending } from "./shadowmap_caster_detail_pending.js";
 import { DirectionalLightShadowmap } from "./DirectionalLightShadowmap.js";
 import { POINT_SHADOW_CUBE_COLS, POINT_SHADOW_CUBE_ROWS } from "./POINT_SHADOW_CUBE_LAYOUT.js";
 import {
@@ -388,6 +391,8 @@ export class GPUSceneShadowmapContext {
         this.#cameras = new CameraManager(graphics.device);
         this.shadow_view_manager = new ViewManager(graphics, this.#cameras, {
             obtain: () => scene_ctx,
+        }, {
+            virtual_geometry_tau_scale: SHADOWMAP_VGEO_TAU_SCALE,
         });
 
         this.#render_target = RenderTarget.from({
@@ -523,6 +528,58 @@ export class GPUSceneShadowmapContext {
         });
     }
 
+    /**
+     * Pages the scene's virtual geometry has installed so far, or 0 for a scene without any.
+     *
+     * @returns {number}
+     */
+    #installed_page_count() {
+        return this.#scene_ctx.virtual_geometry?.pool.installed_page_count ?? 0;
+    }
+
+    /**
+     * Flag every cached local map whose last cut of virtual geometry could now be drawn finer.
+     *
+     * Directional maps redraw every frame and need nothing of this. A local map's views are its own
+     * view contexts, each of which holds what the last reading of its cut said — so the question is
+     * answered from the map's own readings, and a map that cut nothing clamped is left alone however
+     * many pages arrive for other views (SHADOW_PLAN_2026_09_28 §2.5).
+     *
+     * @param {Shadowmap[]} shadowmaps
+     */
+    #mark_caster_detail_pending(shadowmaps) {
+        if (this.#scene_ctx.virtual_geometry === undefined) {
+            return;
+        }
+
+        const installs_now = this.#installed_page_count();
+        const views = this.shadow_view_manager;
+
+        for (let i = 0; i < shadowmaps.length; i++) {
+            const map = shadowmaps[i];
+
+            if (map.light.isDirectionalLight || map.is_invalid) {
+                continue;
+            }
+
+            let clamped = 0;
+
+            for (let j = 0; j < map.views.length; j++) {
+                const view = map.views[j];
+
+                if (views.exists(view)) {
+                    clamped += views.obtain(view).virtual_geometry_cut.stats[VGEO_CUT_STAT.CLAMPED];
+                }
+            }
+
+            map.caster_detail_pending = shadowmap_caster_detail_pending({
+                clamped,
+                installs_at_draw: map.installs_at_draw,
+                installs_now,
+            });
+        }
+    }
+
     /**
      *
      * @param {Light} light
@@ -602,6 +659,10 @@ export class GPUSceneShadowmapContext {
             m.projected_area_px = compute_light_projected_area_px(m.light, main_camera, view_resolution);
         }
 
+        // Step 2b: a cached map whose last cut of virtual geometry was clamped, and under which pages
+        // have installed since, would now draw finer — score it as if it had never been drawn.
+        this.#mark_caster_detail_pending(shadowmaps);
+
         // Step 3: policy reserves pending resize footprints alongside committed layouts. It
         // never mutates layout and never invalidates — sampling continues against the old
         // region until draw() commits the pending during a normal raster pass. Directionals and
@@ -799,6 +860,8 @@ export class GPUSceneShadowmapContext {
             map.should_draw = false;
             map.is_invalid = false;
             map.last_updated_frame_index = frame_index;
+            map.caster_detail_pending = false;
+            map.installs_at_draw = this.#installed_page_count();
             this.#debug_render_count++;
         }
 

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

@@ -0,0 +1,12 @@
+/**
+ * How much coarser than the camera a shadow view cuts virtual geometry: its τ is the runtime's
+ * times this — see `VGeoViewCut.tau_scale`.
+ *
+ * Measured on Zorah (SHADOW_PLAN_2026_09_28 §7.2): at 2 the cascades draw 39% of the clusters they
+ * draw at 1, and false light against cascades at a quarter of the τ rises from 0.006–0.154% of the
+ * screen to 0.028–0.400%.
+ *
+ * @type {number}
+ */
+export const SHADOWMAP_VGEO_TAU_SCALE: number;
+//# sourceMappingURL=SHADOWMAP_VGEO_TAU_SCALE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SHADOWMAP_VGEO_TAU_SCALE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/SHADOWMAP_VGEO_TAU_SCALE.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,uCAFU,MAAM,CAE0B"}

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

@@ -0,0 +1,11 @@
+/**
+ * How much coarser than the camera a shadow view cuts virtual geometry: its τ is the runtime's
+ * times this — see `VGeoViewCut.tau_scale`.
+ *
+ * Measured on Zorah (SHADOW_PLAN_2026_09_28 §7.2): at 2 the cascades draw 39% of the clusters they
+ * draw at 1, and false light against cascades at a quarter of the τ rises from 0.006–0.154% of the
+ * screen to 0.028–0.400%.
+ *
+ * @type {number}
+ */
+export const SHADOWMAP_VGEO_TAU_SCALE = 2;

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

@@ -94,6 +94,21 @@ export class Shadowmap {
      * @type {boolean}
      */
     is_invalid: boolean;
+    /**
+     * True when this map's last draw cut virtual geometry that was clamped — coarser than its own
+     * threshold asked for, because pages were missing — and pages have installed since. Scored as if
+     * the map had never been drawn, so it wins its way back into the budget ahead of maps that are
+     * merely stale; set each frame by {@link GPUSceneShadowmapContext.select_for_draw} and cleared
+     * by a draw. See `shadowmap_caster_detail_pending`.
+     * @type {boolean}
+     */
+    caster_detail_pending: boolean;
+    /**
+     * The virtual-geometry pool's install count when this map was last drawn — what
+     * {@link caster_detail_pending} compares against.
+     * @type {number}
+     */
+    installs_at_draw: number;
     /**
      * Per-frame "draw this map now" signal set by
      * {@link GPUSceneShadowmapContext.select_for_draw} during selection and consumed by

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;;;;;;;;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;oBA3KY,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;;;;;;;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"}

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

@@ -104,6 +104,23 @@ export class Shadowmap {
      */
     is_invalid = true;
 
+    /**
+     * True when this map's last draw cut virtual geometry that was clamped — coarser than its own
+     * threshold asked for, because pages were missing — and pages have installed since. Scored as if
+     * the map had never been drawn, so it wins its way back into the budget ahead of maps that are
+     * merely stale; set each frame by {@link GPUSceneShadowmapContext.select_for_draw} and cleared
+     * by a draw. See `shadowmap_caster_detail_pending`.
+     * @type {boolean}
+     */
+    caster_detail_pending = false;
+
+    /**
+     * The virtual-geometry pool's install count when this map was last drawn — what
+     * {@link caster_detail_pending} compares against.
+     * @type {number}
+     */
+    installs_at_draw = 0;
+
     /**
      * Per-frame "draw this map now" signal set by
      * {@link GPUSceneShadowmapContext.select_for_draw} during selection and consumed by

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

@@ -0,0 +1,25 @@
+/**
+ * Whether a cached shadow map would draw finer virtual geometry if it were drawn again now.
+ *
+ * A spot or point map is kept until the scorer re-selects it, and its first draw is forced at
+ * creation — when little but the roots of the scene's virtual geometry is resident. A cut that was
+ * **clamped** drew coarser clusters over surface whose pages were missing and asked for them; once
+ * pages have **installed** since the map was drawn, a redraw is a different, finer map. Keyed on the
+ * map's own incomplete cut rather than on every install in the scene, so a map whose cut was
+ * complete is never redrawn for pages someone else wanted (SHADOW_PLAN_2026_09_28 §2.5).
+ *
+ * @param {Object} options
+ * @param {number} options.clamped clusters the map's views' last readings drew clamped, summed
+ * @param {number} options.installs_at_draw the pool's install count when the map was drawn
+ * @param {number} options.installs_now the pool's install count now
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function shadowmap_caster_detail_pending({ clamped, installs_at_draw, installs_now }: {
+    clamped: number;
+    installs_at_draw: number;
+    installs_now: number;
+}): boolean;
+//# sourceMappingURL=shadowmap_caster_detail_pending.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shadowmap_caster_detail_pending.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/shadowmap_caster_detail_pending.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAR2B,OAAO,EAAvB,MAAM;IACU,gBAAgB,EAAhC,MAAM;IACU,YAAY,EAA5B,MAAM;IACJ,OAAO,CAOnB"}

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

@@ -0,0 +1,22 @@
+/**
+ * Whether a cached shadow map would draw finer virtual geometry if it were drawn again now.
+ *
+ * A spot or point map is kept until the scorer re-selects it, and its first draw is forced at
+ * creation — when little but the roots of the scene's virtual geometry is resident. A cut that was
+ * **clamped** drew coarser clusters over surface whose pages were missing and asked for them; once
+ * pages have **installed** since the map was drawn, a redraw is a different, finer map. Keyed on the
+ * map's own incomplete cut rather than on every install in the scene, so a map whose cut was
+ * complete is never redrawn for pages someone else wanted (SHADOW_PLAN_2026_09_28 §2.5).
+ *
+ * @param {Object} options
+ * @param {number} options.clamped clusters the map's views' last readings drew clamped, summed
+ * @param {number} options.installs_at_draw the pool's install count when the map was drawn
+ * @param {number} options.installs_now the pool's install count now
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function shadowmap_caster_detail_pending({ clamped, installs_at_draw, installs_now }) {
+    return clamped > 0 && installs_now > installs_at_draw;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"shadowmap_update_score.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/shadowmap_update_score.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oFAHW,MAAM,GACJ,MAAM,CAWlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oGAHW,UAAU,MAAM,CAAC,GACf,MAAM,CAuClB"}
+{"version":3,"file":"shadowmap_update_score.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/shadowmap_update_score.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oFAHW,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oGAHW,UAAU,MAAM,CAAC,GACf,MAAM,CAuClB"}

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

@@ -32,8 +32,11 @@ export function compute_shadowmap_update_score(map, current_frame_index) {
         return Infinity;
     }
 
-    // staleness = frames since last refresh; -1 (never) maps to a large positive number
-    const staleness = current_frame_index - map.last_updated_frame_index;
+    // staleness = frames since last refresh; -1 (never) maps to a large positive number, and so does
+    // a map whose last cut of virtual geometry was clamped and could now be drawn finer
+    const staleness = map.caster_detail_pending
+        ? current_frame_index + 1
+        : current_frame_index - map.last_updated_frame_index;
 
     return map.projected_area_px * (1 + Math.max(0, staleness));
 }

package/src/shade/renderer/texture/TextureManager.d.ts

@@ -39,7 +39,8 @@ export class TextureManager {
      */
     release(shade: ShadeTexture): boolean;
     /**
-     * Release every texture the manager is holding. Called by {@link GraphicsContext#destroy}.
+     * Release every texture the manager is holding, and the mipmap generator's buffer. Called by
+     * {@link GraphicsContext#destroy}.
      *
      * @returns {void}
      */

package/src/shade/renderer/texture/TextureManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextureManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/TextureManager.js"],"names":[],"mappings":"AAsEA;IAuCI;;;OAGG;IACH,+BAIC;IA5BD;;;OAGG;IACH,qCAEC;IAwBD;;;;OAIG;IACH,cAHW,YAAY,GACV,iBAAiB,CAY7B;IAiCD,uDAqCC;IAeD;;;;OAIG;IACH,kCAHW,iBAAiB,GACf,iBAAiB,CAa7B;IAED;;;;;;;;;;;;;;OAcG;IACH,eAHW,YAAY,GACV,OAAO,CAoBnB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAShB;IAED,eAEC;IAED,+BAQC;;CACJ;2BAhSY,OAAO,mBAAmB,EAAE,YAAY;sCAPf,oCAAoC;kCADxC,wBAAwB;kCADxB,+CAA+C"}
+{"version":3,"file":"TextureManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/TextureManager.js"],"names":[],"mappings":"AAsEA;IAuCI;;;OAGG;IACH,+BAIC;IA5BD;;;OAGG;IACH,qCAEC;IAwBD;;;;OAIG;IACH,cAHW,YAAY,GACV,iBAAiB,CAY7B;IAiCD,uDAqCC;IAeD;;;;OAIG;IACH,kCAHW,iBAAiB,GACf,iBAAiB,CAa7B;IAED;;;;;;;;;;;;;;OAcG;IACH,eAHW,YAAY,GACV,OAAO,CAoBnB;IAED;;;;;OAKG;IACH,WAFa,IAAI,CAWhB;IAED,eAEC;IAED,+BAQC;;CACJ;2BAnSY,OAAO,mBAAmB,EAAE,YAAY;sCAPf,oCAAoC;kCADxC,wBAAwB;kCADxB,+CAA+C"}

package/src/shade/renderer/texture/TextureManager.js

@@ -271,7 +271,8 @@ export class TextureManager {
     }
 
     /**
-     * Release every texture the manager is holding. Called by {@link GraphicsContext#destroy}.
+     * Release every texture the manager is holding, and the mipmap generator's buffer. Called by
+     * {@link GraphicsContext#destroy}.
      *
      * @returns {void}
      */
@@ -282,6 +283,8 @@ export class TextureManager {
 
         this.#cache.clear();
         this.#bound = new WeakMap();
+
+        this.#mipmaps.destroy();
     }
 
     update() {

package/src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.js

@@ -241,7 +241,7 @@ export class WebGPUMipmapGenerator {
     #parameters_buffer_stride = 256;
 
     destroy() {
-        this.#parameters_buffer.destroy();
+        this.#parameters_buffer?.destroy();
         this.#parameters_buffer = undefined;
     }
 

package/src/shade/renderer/util/Uint32BufferSamplingStats.d.ts

@@ -41,11 +41,19 @@ export class Uint32BufferSamplingStats {
      */
     setGlobalMax(column_id: number, value: number): void;
     /**
+     * Read the records back through a copy into a buffer taken from `buffers`, once `encoder` is
+     * submitted.
+     *
+     * A reading can be lost, and then nothing of it is applied: when this is destroyed while it is in
+     * flight, or when its buffer is destroyed under the mapping — which is what tearing `buffers` down
+     * does. A renderer torn down with a frame's reading still on the GPU does both, so a lost reading
+     * is an answer here, not an error.
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUBufferAllocator} buffers
+     * @returns {Promise<boolean>} whether the reading was applied
      */
-    readback_explicit(encoder: ShadeGPUCommandContext, buffers: GPUBufferAllocator): Promise<void>;
+    readback_explicit(encoder: ShadeGPUCommandContext, buffers: GPUBufferAllocator): Promise<boolean>;
     readback(): Promise<any>;
     upload(): void;
     /**

package/src/shade/renderer/util/Uint32BufferSamplingStats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Uint32BufferSamplingStats.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/util/Uint32BufferSamplingStats.js"],"names":[],"mappings":"AAWA;IAgMI;;;;;OAKG;IACH,wCAHW,MAAM,cACN,MAAM,EAwBhB;IArND;;;OAGG;IACH,sBAEC;IA4BD;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,wBAHW,MAAM,SACN,MAAM,QAOhB;IAoBD;;;;OAIG;IACH,2BAHW,sBAAsB,WACtB,kBAAkB,iBA0B5B;IAED,yBASC;IAED,eAEC;IAED;;;;;;OAMG;IACH,8CAJW,MAAM,qCAEN,MAAM,QAmBhB;IAgCD;;;OAGG;IACH,gBAFW,MAAM,QAchB;IAED,gBAEC;;CACJ;qCAzPY,OAAO,wCAAwC,EAAE,sBAAsB;iCACvE,OAAO,iCAAiC,EAAE,kBAAkB"}
+{"version":3,"file":"Uint32BufferSamplingStats.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/util/Uint32BufferSamplingStats.js"],"names":[],"mappings":"AAYA;IA+OI;;;;;OAKG;IACH,wCAHW,MAAM,cACN,MAAM,EAwBhB;IApQD;;;OAGG;IACH,sBAEC;IAkCD;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,wBAHW,MAAM,SACN,MAAM,QAOhB;IAoBD;;;;;;;;;;;;OAYG;IACH,2BAJW,sBAAsB,WACtB,kBAAkB,GAChB,QAAQ,OAAO,CAAC,CAqB5B;IAwCD,yBASC;IAED,eAEC;IAED;;;;;;OAMG;IACH,8CAJW,MAAM,qCAEN,MAAM,QAmBhB;IAgCD;;;OAGG;IACH,gBAFW,MAAM,QAchB;IAED,gBAIC;;CACJ;qCA1SY,OAAO,wCAAwC,EAAE,sBAAsB;iCACvE,OAAO,iCAAiC,EAAE,kBAAkB"}

package/src/shade/renderer/util/Uint32BufferSamplingStats.js

@@ -1,5 +1,6 @@
 import { assert } from "../../../core/assert.js";
 import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
+import { warn_limited } from "../../util/warn_limited.js";
 import { inspect_via_copy } from "../buffer/inspect_gpu_buffer.js";
 
 /**
@@ -50,6 +51,12 @@ export class Uint32BufferSamplingStats {
      */
     #device;
 
+    /**
+     * Set by {@link destroy}. A reading still in flight then applies nothing.
+     * @type {boolean}
+     */
+    #destroyed = false;
+
     /**
      *
      * @returns {GPUBuffer}
@@ -130,9 +137,17 @@ export class Uint32BufferSamplingStats {
     }
 
     /**
+     * Read the records back through a copy into a buffer taken from `buffers`, once `encoder` is
+     * submitted.
+     *
+     * A reading can be lost, and then nothing of it is applied: when this is destroyed while it is in
+     * flight, or when its buffer is destroyed under the mapping — which is what tearing `buffers` down
+     * does. A renderer torn down with a frame's reading still on the GPU does both, so a lost reading
+     * is an answer here, not an error.
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUBufferAllocator} buffers
+     * @returns {Promise<boolean>} whether the reading was applied
      */
     async readback_explicit(encoder, buffers) {
         const tmp_desc = new BufferResourceDescriptor();
@@ -146,18 +161,51 @@ export class Uint32BufferSamplingStats {
 
         encoder.copyBufferToBuffer(stat_buffer, 0, tmp_buffer, 0);
 
+        const applied = await this.#read(encoder, tmp_buffer, size);
+
+        // back unmapped, whatever became of the reading. A pool torn down while it was in flight has
+        // already destroyed the buffer and no longer holds it, so it declines it
+        buffers.release(tmp_buffer);
+
+        return applied;
+    }
+
+    /**
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {GPUBuffer} tmp_buffer
+     * @param {number} size
+     * @returns {Promise<boolean>} whether the reading was applied; `tmp_buffer` is unmapped either way
+     */
+    async #read(encoder, tmp_buffer, size) {
         await encoder.done;
 
-        await tmp_buffer.mapAsync(GPUMapMode.READ, 0, size);
+        if (this.#destroyed) {
+            // and the buffer may be too — mapping it would be a validation error, not an abort
+            return false;
+        }
+
+        try {
+            await tmp_buffer.mapAsync(GPUMapMode.READ, 0, size);
+        } catch (e) {
+            // An AbortError when the buffer was destroyed under the mapping. Torn down alongside this,
+            // that is the expected end of a reading in flight; on its own it is not
+            if (!this.#destroyed) {
+                warn_limited(`Uint32BufferSamplingStats: a reading was lost, its mapping failed (${e.name})`);
+            }
+
+            return false;
+        }
 
-        const buffer = tmp_buffer.getMappedRange(0, size);
+        // destroyed while the mapping was in flight: the records it would land in are gone
+        const applied = !this.#destroyed;
 
-        const uint32 = new Uint32Array(buffer);
-        this.#write_data(uint32);
+        if (applied) {
+            this.#write_data(new Uint32Array(tmp_buffer.getMappedRange(0, size)));
+        }
 
         tmp_buffer.unmap();
 
-        buffers.release(tmp_buffer);
+        return applied;
     }
 
     async readback() {
@@ -250,6 +298,8 @@ export class Uint32BufferSamplingStats {
     }
 
     destroy() {
+        this.#destroyed = true;
+
         this.#stat_buffer.destroy();
     }
 }

package/src/shade/renderer/view/ViewManager.d.ts

@@ -10,8 +10,14 @@ export class ViewManager {
      * @param {GraphicsContext} graphics
      * @param {CameraManager} cameras
      * @param {SceneManager} scenes
+     * @param {Object} [options]
+     * @param {number} [options.virtual_geometry_tau_scale] how much coarser than the runtime's
+     *     threshold the views this hands out cut virtual geometry — the owner of the views decides,
+     *     since nothing in the runtime knows what kind of view it is cutting for
      */
-    constructor(graphics: GraphicsContext, cameras: CameraManager, scenes: SceneManager);
+    constructor(graphics: GraphicsContext, cameras: CameraManager, scenes: SceneManager, { virtual_geometry_tau_scale }?: {
+        virtual_geometry_tau_scale?: number;
+    });
     /**
      *
      * @return {SceneManager}

package/src/shade/renderer/view/ViewManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ViewManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/ViewManager.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;IAmCI;;;;;OAKG;IACH,sBAJW,eAAe,WACf,aAAa,UACb,YAAY,EAQtB;IA9BD;;;OAGG;IACH,8DAEC;IA2CD;;;;OAIG;IACH,aAHW,IAAI,GACF,OAAO,CAInB;IAED;;;;OAIG;IACH,aAHW,IAAI,GACF,cAAc,CAI1B;IAED;;;;;;;;;;;;;OAaG;IACH,cAFW,IAAI,QASd;IAED;;;;;;OAMG;IACH,WAFa,IAAI,CAQhB;;CACJ;8BA/HY,OAAO,uBAAuB,EAAE,eAAe;4BAC/C,OAAO,4BAA4B,EAAE,aAAa;2BAClD,OAAO,0BAA0B,EAAE,YAAY;mBAC/C,OAAO,WAAW,EAAE,IAAI;+BANN,qBAAqB"}
+{"version":3,"file":"ViewManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/ViewManager.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH;IAyCI;;;;;;;;;OASG;IACH,sBARW,eAAe,WACf,aAAa,UACb,YAAY;QAEK,0BAA0B,GAA3C,MAAM;OAchB;IA5CD;;;OAGG;IACH,8DAEC;IA0DD;;;;OAIG;IACH,aAHW,IAAI,GACF,OAAO,CAInB;IAED;;;;OAIG;IACH,aAHW,IAAI,GACF,cAAc,CAI1B;IAED;;;;;;;;;;;;;OAaG;IACH,cAFW,IAAI,QASd;IAED;;;;;;OAMG;IACH,WAFa,IAAI,CAQhB;;CACJ;8BA9IY,OAAO,uBAAuB,EAAE,eAAe;4BAC/C,OAAO,4BAA4B,EAAE,aAAa;2BAClD,OAAO,0BAA0B,EAAE,YAAY;mBAC/C,OAAO,WAAW,EAAE,IAAI;+BANN,qBAAqB"}

package/src/shade/renderer/view/ViewManager.js

@@ -1,3 +1,4 @@
+import { assert } from "../../../core/assert.js";
 import { HashMap } from "../../../core/collection/map/HashMap.js";
 import { GPUViewContext } from "./GPUViewContext.js";
 
@@ -43,14 +44,28 @@ export class ViewManager {
      */
     #graphics;
 
+    /**
+     * What every view this hands out starts its `VGeoViewCut.tau_scale` at.
+     * @type {number}
+     */
+    #virtual_geometry_tau_scale;
+
     /**
      *
      * @param {GraphicsContext} graphics
      * @param {CameraManager} cameras
      * @param {SceneManager} scenes
+     * @param {Object} [options]
+     * @param {number} [options.virtual_geometry_tau_scale] how much coarser than the runtime's
+     *     threshold the views this hands out cut virtual geometry — the owner of the views decides,
+     *     since nothing in the runtime knows what kind of view it is cutting for
      */
-    constructor(graphics, cameras, scenes) {
+    constructor(graphics, cameras, scenes, { virtual_geometry_tau_scale = 1 } = {}) {
+        assert.isNumber(virtual_geometry_tau_scale, 'virtual_geometry_tau_scale');
+        assert.greaterThan(virtual_geometry_tau_scale, 0, 'virtual_geometry_tau_scale');
+
         this.#graphics = graphics;
+        this.#virtual_geometry_tau_scale = virtual_geometry_tau_scale;
 
         this.#device = graphics.device;
         this.#cameras = cameras;
@@ -70,6 +85,7 @@ export class ViewManager {
         const gpu_ctx = new GPUViewContext(this.#graphics, scene, camera);
 
         gpu_ctx.label = view.label;
+        gpu_ctx.virtual_geometry_cut.tau_scale = this.#virtual_geometry_tau_scale;
 
         return gpu_ctx;
     }

package/src/shade/renderer/volumetrics/GPUSceneVolumetrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUSceneVolumetrics.js"],"names":[],"mappings":"AAOA;;;GAGG;AAEH;;;GAGG;AACH;IAkCI;;;;OAIG;IACH,4CAFW,gBAAgB,EAkB1B;IArDD;;OAEG;IACH,QAFU,gBAAgB,CAEpB;IAWN,gCAEC;IAOD,sCAEC;IA8BD,gBAEC;IAED;;;;OAIG;IACH,YAHW,eAAe,gBACf,MAAM,QA+ChB;;CAEJ;8BAzHY,OAAO,uBAAuB,EAAE,eAAe;+BAC/C,OAAO,uBAAuB,EAAE,gBAAgB;mCAN1B,8CAA8C;+BADlD,6BAA6B"}
+{"version":3,"file":"GPUSceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUSceneVolumetrics.js"],"names":[],"mappings":"AAOA;;;GAGG;AAEH;;;GAGG;AACH;IAkCI;;;;OAIG;IACH,4CAFW,gBAAgB,EAkB1B;IArDD;;OAEG;IACH,QAFU,gBAAgB,CAEpB;IAWN,gCAEC;IAOD,sCAEC;IA8BD,gBAGC;IAED;;;;OAIG;IACH,YAHW,eAAe,gBACf,MAAM,QA+ChB;;CAEJ;8BA1HY,OAAO,uBAAuB,EAAE,eAAe;+BAC/C,OAAO,uBAAuB,EAAE,gBAAgB;mCAN1B,8CAA8C;+BADlD,6BAA6B"}

package/src/shade/renderer/volumetrics/GPUSceneVolumetrics.js

@@ -73,6 +73,7 @@ export class GPUSceneVolumetrics {
 
     destroy() {
         this.#table.destroy();
+        this.#metadata_buffer.destroy();
     }
 
     /**

package/src/shade/renderer/volumetrics/GPUViewVolumetrics.d.ts

@@ -30,16 +30,26 @@ export class GPUViewVolumetrics {
      * @param {number} options.light_cluster_lookup
      * @param {number} options.light_cluster_parameters
      * @param {number} options.shadowmap_atlas
+     * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode the renderer's; picks the froxel GI
+     *   module that starts the froxel irradiance volume
+     * @returns {{resolved: number, metadata: number, irradiance: {Y: number, CoCg: number}}} the
+     *   integrated aerial LUT, the metadata buffer, and the froxel irradiance volume
+     *   (chunk_volumetrics_irradiance_sh) for the transparent surfaces the lighting pass cannot see
      */
-    graph_update({ graph, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, }: {
+    graph_update({ graph, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, indirect_lighting_mode, }: {
         graph: FrameGraph;
         light_cluster_data: number;
         light_cluster_lookup: number;
         light_cluster_parameters: number;
         shadowmap_atlas: number;
+        indirect_lighting_mode: import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode;
     }): {
-        resolved: any;
-        metadata: any;
+        resolved: number;
+        metadata: number;
+        irradiance: {
+            Y: number;
+            CoCg: number;
+        };
     };
     #private;
 }

package/src/shade/renderer/volumetrics/GPUViewVolumetrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUViewVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUViewVolumetrics.js"],"names":[],"mappings":"AAiCA;IAkII;;;;OAIG;IACH,kBAHW,cAAc,qBAwBxB;IAxHD;;OAEG;IACH,4BAOC;IAjBD;;OAEG;IACH,2BAEC;IAsCD;;OAEG;IACH,0BAEC;IAZD;;OAEG;IACH,yBAEC;IAwFD,gBAWC;IA6ND;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACM,kBAAkB,EAAlC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACU,wBAAwB,EAAxC,MAAM;QACU,eAAe,EAA/B,MAAM;;;;MAoFhB;;CAEJ;yBA5eY,OAAO,2DAA2D,EAAE,UAAU;6BAC9E,OAAO,2BAA2B,EAAE,cAAc"}
+{"version":3,"file":"GPUViewVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUViewVolumetrics.js"],"names":[],"mappings":"AAiCA;IAkII;;;;OAIG;IACH,kBAHW,cAAc,qBAwBxB;IAxHD;;OAEG;IACH,4BAOC;IAjBD;;OAEG;IACH,2BAEC;IAsCD;;OAEG;IACH,0BAEC;IAZD;;OAEG;IACH,yBAEC;IAwFD,gBAWC;IA6ND;;;;;;;;;;;;;OAaG;IACH;QAX+B,KAAK,EAAzB,UAAU;QACM,kBAAkB,EAAlC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACU,wBAAwB,EAAxC,MAAM;QACU,eAAe,EAA/B,MAAM;QACuE,sBAAsB,EAAnG,OAAO,iCAAiC,EAAE,yBAAyB;QAEjE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAyFvF;;CAEJ;yBApfY,OAAO,2DAA2D,EAAE,UAAU;6BAC9E,OAAO,2BAA2B,EAAE,cAAc"}

package/src/shade/renderer/volumetrics/GPUViewVolumetrics.js

@@ -429,6 +429,11 @@ export class GPUViewVolumetrics {
      * @param {number} options.light_cluster_lookup
      * @param {number} options.light_cluster_parameters
      * @param {number} options.shadowmap_atlas
+     * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode the renderer's; picks the froxel GI
+     *   module that starts the froxel irradiance volume
+     * @returns {{resolved: number, metadata: number, irradiance: {Y: number, CoCg: number}}} the
+     *   integrated aerial LUT, the metadata buffer, and the froxel irradiance volume
+     *   (chunk_volumetrics_irradiance_sh) for the transparent surfaces the lighting pass cannot see
      */
     graph_update({
                      graph,
@@ -436,6 +441,7 @@ export class GPUViewVolumetrics {
                      light_cluster_lookup,
                      light_cluster_parameters,
                      shadowmap_atlas,
+                     indirect_lighting_mode,
                  }) {
 
         const view = this.#view;
@@ -487,7 +493,7 @@ export class GPUViewVolumetrics {
             taa_output = graph_import_texture(graph, this.#volumetrics_textures[parity], "volumetrics taa output");
         }
 
-        const { lut_aerial } = graph_build_volumetrics({
+        const { lut_aerial, irradiance } = graph_build_volumetrics({
             graph,
             camera,
             lights,
@@ -496,6 +502,7 @@ export class GPUViewVolumetrics {
             light_cluster_lookup,
             light_cluster_parameters,
             shadowmap_atlas,
+            indirect_lighting_mode,
 
             volumetrics_metadata: gr_metadata,
             volumetric_resolution: resolution,
@@ -511,6 +518,7 @@ export class GPUViewVolumetrics {
         return {
             resolved: lut_aerial,
             metadata: gr_metadata,
+            irradiance,
         };
     }
 

package/src/shade/renderer/volumetrics/chunk_volumetrics_irradiance_sh.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The froxel irradiance volume: the light a transparent surface standing in a froxel receives, for
+ * surfaces the lighting pass cannot see — the particles. The froxel GI stage (`gi/`) starts it with
+ * whatever the renderer's indirect lighting mode says a point there receives — the environment,
+ * Brick4, the light probe volume — and `shader_volumetrics_build_lighting` adds, in the same loop
+ * that lights the fog, every directional, point and spot light, their shadows, and the fog's own
+ * attenuation toward each light. idTech 8 builds the same thing in the same pass ("Froxels
+ * Irradiance Volume", Sousa, SIGGRAPH 2025, p.29).
+ *
+ * Stored in the Metro Exodus L1 encoding (`l1i/`): luma as SH2 — four coefficients — and chroma as
+ * its constant band only. Two lights of different colours from opposite sides therefore light both
+ * sides in their luminance-weighted mix, not one colour each; that is the price of 6 coefficients
+ * instead of 12.
+ *
+ * Every light is added as a delta — all of its irradiance from one direction — and scaled by
+ * `1/(2 pi)`, which is the scale under which `resolve_irradiance_sh_to_diffuse(Y, CoCg, n)` returns
+ * `E(n) / pi`: the Lambertian radiance of a unit-albedo surface facing `n`. With SH2 that is
+ * `E * max(0, 1/4 + cos(theta)/2)` per light, over `pi` — the band-limited clamped cosine, a quarter
+ * dim at the peak and a quarter lit a right angle past the terminator.
+ *
+ * - `volumetrics_irradiance_sh_add(sh, irradiance, direction_to_light)` — one light's contribution,
+ *   `irradiance` being what reaches the point at normal incidence and `direction_to_light` a unit
+ *   vector pointing toward the light.
+ * - `volumetrics_irradiance_sh_add_radiance(sh, radiance)` — a whole radiance field arriving at the
+ *   point, as RGB SH2: coefficients of radiance, not cosine-convolved, ordered `[DC, y, z, x]` in
+ *   the project's all-positive basis (`sh2_basis_at`). The form every GI source hands over — the
+ *   probes of Brick4 and of the light probe volume, and `GPULightCollection.environment_sh`. A light
+ *   is the delta field `E sh2_basis_at(l)`, and adding it this way adds exactly what
+ *   `volumetrics_irradiance_sh_add` does.
+ * - `volumetrics_irradiance_sh_storable(sh)` — what an `rgba16float` volume can hold. A clustered
+ *   light close to a froxel exceeds half precision on its own and stores as +Inf, and an infinite
+ *   luma times a zero band-1 basis is a NaN; either would reach every particle sampling that froxel.
+ *   Non-finite coefficients become 0 and the rest are clamped to the half range.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_irradiance_sh: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_irradiance_sh.d.ts.map