@woosh/meep-engine 3.33.0 → 3.34.0

package/src/shade/renderer/scene/GPUSceneContext.js

@@ -273,12 +273,19 @@ export class GPUSceneContext {
 
     /**
      * The feedback loop that carries the cut's readings into the residency, once
-     * {@link enable_virtual_geometry} has run. A host calls its `read` once a frame after every
-     * rasterization path has cut.
+     * {@link enable_virtual_geometry} has run. The renderer reads it once a frame after every
+     * rasterization path has cut; a host does not.
      * @type {VGeoFeedbackLoop|undefined}
      */
     #virtual_geometry_feedback;
 
+    /**
+     * Where the residency's pages are fetched, and the workers that fetch them. This context made
+     * it and handed it in, so the residency does not release it and {@link destroy} does.
+     * @type {VGeoPageFetcher|undefined}
+     */
+    #virtual_geometry_fetcher;
+
     /**
      * @returns {GPUVirtualGeometryRuntime|undefined}
      */
@@ -310,9 +317,10 @@ export class GPUSceneContext {
      *
      * And the residency and the feedback loop with it, so that an engine host gets the whole
      * streaming loop by enabling virtual geometry rather than by wiring four objects itself
-     * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, call
-     * {@link virtual_geometry_feedback}'s `read` once a frame after the last rasterization path,
-     * and every page after the root arrives because the cut asked for it.
+     * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, and every
+     * page after the root arrives because a cut asked for it. The renderer opens and closes each
+     * frame and schedules each reading, and {@link destroy} releases all of it; a host touches none
+     * of it.
      *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
      *     {@link GPUVirtualGeometryRuntime}, except for `residency`
@@ -332,26 +340,46 @@ export class GPUSceneContext {
             ...rest,
         });
 
-        this.#virtual_geometry = new GPUVirtualGeometryRuntime({
-            pool,
-            ...rest,
-        });
+        /*
+         All four or none. Installed one at a time, a throw partway — options a residency refuses —
+         left a runtime on offer with no loop behind it, and destroy() then threw on the missing loop
+         before it reached the rest of the scene.
+        */
+        let runtime;
+        let fetcher;
+        let tiers;
+        let feedback;
+
+        try {
+            runtime = new GPUVirtualGeometryRuntime({
+                pool,
+                ...rest,
+            });
 
-        // pages are fetched, verified and decoded on workers, spawned on first use; a host with no
-        // Worker gets the same fetch in-process
-        const fetcher = new VGeoPageFetcher({
-            worker_count: residency.worker_count,
-            make_worker: typeof Worker === 'undefined' ? undefined : make_vgeo_page_worker,
-        });
+            // pages are fetched, verified and decoded on workers, spawned on first use; a host with
+            // no Worker gets the same fetch in-process
+            fetcher = new VGeoPageFetcher({
+                worker_count: residency.worker_count,
+                make_worker: typeof Worker === 'undefined' ? undefined : make_vgeo_page_worker,
+            });
 
-        this.#virtual_geometry_residency = new VGeoResidency({ pool, options: residency, fetcher });
+            tiers = new VGeoResidency({ pool, options: residency, fetcher });
 
-        this.#virtual_geometry_feedback = new VGeoFeedbackLoop({
-            runtime: this.#virtual_geometry,
-            residency: this.#virtual_geometry_residency,
-        });
+            feedback = new VGeoFeedbackLoop({ runtime, residency: tiers });
+        } catch (error) {
+            // the pool is the only one holding anything yet: the fetcher spawns its workers on its
+            // first fetch, and the runtime makes its buffer on its first frame
+            pool.destroy();
 
-        return this.#virtual_geometry;
+            throw error;
+        }
+
+        this.#virtual_geometry = runtime;
+        this.#virtual_geometry_fetcher = fetcher;
+        this.#virtual_geometry_residency = tiers;
+        this.#virtual_geometry_feedback = feedback;
+
+        return runtime;
     }
 
     /**
@@ -683,20 +711,64 @@ export class GPUSceneContext {
         });
     }
 
+    /**
+     * Release this context's virtual geometry — everything {@link enable_virtual_geometry} built,
+     * so that a host tears a scene down by destroying the renderer and nothing of the streaming loop
+     * is left for it to find — then its rows, its database, its TLAS, its lights, its probe volume,
+     * its volumetrics, its volumetric light map, its animation and its skinning: every buffer the
+     * context made. Safe to call twice, and on a context that never enabled virtual geometry.
+     */
     destroy() {
+        this.#destroy_virtual_geometry();
+
         if (this.#rows !== null) {
             this.#rows.destroy();
         }
 
         this.#scene_database.destroy();
+        this.#tlas.destroy();
         this.#lights.destroy();
         this.#light_probe_volume.destroy();
+        this.#volumetrics.destroy();
+        this.volumetric_light_map.destroy();
         this.#animation_manager.destroy();
         if (this.#skinning !== null) {
             this.#skinning.destroy();
         }
     }
 
+    /**
+     * Everything {@link enable_virtual_geometry} built, in the order it depends on itself: the work
+     * still outstanding first — the loop's and the residency's fetches, and the workers they run on
+     * — because each of those lands on the pool's rows when it finishes, and then the device memory,
+     * the runtime's feedback buffer before the pool's tables that its frames write into.
+     *
+     * Afterwards the scene has no virtual geometry, which is what every rasterization path already
+     * takes to mean "skip the cut".
+     */
+    #destroy_virtual_geometry() {
+        const runtime = this.#virtual_geometry;
+
+        if (runtime === undefined) {
+            return;
+        }
+
+        this.#virtual_geometry_feedback.destroy();
+
+        // gives back every container's rows and slots, and cancels what they had on the wire
+        this.#virtual_geometry_residency.destroy();
+
+        this.#virtual_geometry_fetcher.destroy();
+
+        runtime.destroy();
+        runtime.pool.destroy();
+
+        this.#virtual_geometry = undefined;
+        this.#virtual_geometry_residency = undefined;
+        this.#virtual_geometry_feedback = undefined;
+        this.#virtual_geometry_fetcher = undefined;
+    }
+
 }
 
 /**

package/src/shade/renderer/scene/rows/GPUSceneRows.d.ts

@@ -220,7 +220,10 @@ export class GPUSceneRows {
      */
     for_each_descendant(entity: number, visitor: (arg0: number) => void): void;
     /**
-     * Forget everything, freeing every row. For the context's own teardown.
+     * Forget everything. For the context's own teardown, which destroys the tables and the tree
+     * next — so no row is given back to them one at a time, which cost about 2 µs a row and took a
+     * scene of millions seconds to leave. What outlives the context is not the rows' to give back:
+     * the skinned clones go back to the shared geometry manager with the skinning context.
      */
     destroy(): void;
     #private;

package/src/shade/renderer/scene/rows/GPUSceneRows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneRows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUSceneRows.js"],"names":[],"mappings":"AAcA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAoID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA2II;;;;;;;;;OASG;IACH;QAR2C,OAAO,EAAvC,sBAAsB;QACC,UAAU;QACV,MAAM;QACD,UAAU,EAAtC,kBAAkB;QACU,SAAS,EAArC,kBAAkB;QACyB,IAAI,EAA/C,iCAAiC;QACW,QAAQ,QAAxC,sBAAsB;OAmB5C;IAED;;OAEG;IACH,iGAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,oBAA8B;IAE9B;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,8BAHoB,MAAM,QAAE,eAAe,QAAE,aAAa,QAAE,OAAO,KAAG,IAAI,QASzE;IAED;;;;;;;;;OASG;IACH,6BAHW,KAAK,GACH,OAAO,CAyBnB;IAED;;;;;;;;;;OAUG;IACH,gBAFW,MAAM,QAuChB;IAED;;;;;;;;OAQG;IACH,gBAFW,MAAM,QA0BhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,2EAOC;IAED;;;;OAIG;IACH,gCAEC;IAqCD;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,YACN,eAAe,YACf,aAAa,YACb,OAAO,QAgDjB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAUhB;IAwCD;;;;OAIG;IACH,SAFa,MAAM,CAsDlB;IAyMD;;;;OAIG;IACH;;;;;;;;OAQG;IACH,4BAHW,MAAM,kBACG,MAAM,KAAG,IAAI,QAiBhC;IAyGD;;OAEG;IACH,gBA+BC;;CACJ;qCA5oCY,OAAO,kDAAkD,EAAE,sBAAsB;;iCAEjF,OAAO,sCAAsC,EAAE,kBAAkB;iCACjE,OAAO,sCAAsC,EAAE,kBAAkB;gDACjE,OAAO,yCAAyC,EAAE,iCAAiC;qCACnF,OAAO,oDAAoD,EAAE,sBAAsB;8BACnF,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;oBACvD,OAAO,wCAAwC,EAAE,KAAK"}
+{"version":3,"file":"GPUSceneRows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUSceneRows.js"],"names":[],"mappings":"AAcA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAoID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA2II;;;;;;;;;OASG;IACH;QAR2C,OAAO,EAAvC,sBAAsB;QACC,UAAU;QACV,MAAM;QACD,UAAU,EAAtC,kBAAkB;QACU,SAAS,EAArC,kBAAkB;QACyB,IAAI,EAA/C,iCAAiC;QACW,QAAQ,QAAxC,sBAAsB;OAmB5C;IAED;;OAEG;IACH,iGAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,oBAA8B;IAE9B;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,8BAHoB,MAAM,QAAE,eAAe,QAAE,aAAa,QAAE,OAAO,KAAG,IAAI,QASzE;IAED;;;;;;;;;OASG;IACH,6BAHW,KAAK,GACH,OAAO,CAyBnB;IAED;;;;;;;;;;OAUG;IACH,gBAFW,MAAM,QAuChB;IAED;;;;;;;;OAQG;IACH,gBAFW,MAAM,QA0BhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,2EAOC;IAED;;;;OAIG;IACH,gCAEC;IAqCD;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,YACN,eAAe,YACf,aAAa,YACb,OAAO,QAgDjB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAUhB;IAwCD;;;;OAIG;IACH,SAFa,MAAM,CAsDlB;IAyMD;;;;OAIG;IACH;;;;;;;;OAQG;IACH,4BAHW,MAAM,kBACG,MAAM,KAAG,IAAI,QAiBhC;IAyGD;;;;;OAKG;IACH,gBAUC;;CACJ;qCA1nCY,OAAO,kDAAkD,EAAE,sBAAsB;;iCAEjF,OAAO,sCAAsC,EAAE,kBAAkB;iCACjE,OAAO,sCAAsC,EAAE,kBAAkB;gDACjE,OAAO,yCAAyC,EAAE,iCAAiC;qCACnF,OAAO,oDAAoD,EAAE,sBAAsB;8BACnF,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;oBACvD,OAAO,wCAAwC,EAAE,KAAK"}

package/src/shade/renderer/scene/rows/GPUSceneRows.js

@@ -1143,33 +1143,15 @@ export class GPUSceneRows {
     }
 
     /**
-     * Forget everything, freeing every row. For the context's own teardown.
+     * Forget everything. For the context's own teardown, which destroys the tables and the tree
+     * next — so no row is given back to them one at a time, which cost about 2 µs a row and took a
+     * scene of millions seconds to leave. What outlives the context is not the rows' to give back:
+     * the skinned clones go back to the shared geometry manager with the skinning context.
      */
     destroy() {
-        for (const [entity, entry] of this.#mesh_entries) {
-            if (entry.written) {
-                const row = row_of_entity(entity);
-
-                this.#meshes.remove(row);
-                this.#tlas.instance_remove(row);
-
-                if (entry.skinned) {
-                    this.#skinning().release_clone(entity);
-                }
-            }
-        }
-
         this.#mesh_entries.clear();
 
-        const acquired = this.#acquired;
-
-        for (let entity = acquired.nextSetBit(0); entity !== -1; entity = acquired.nextSetBit(entity + 1)) {
-            if (this.#written.get(entity)) {
-                this.#transforms.remove(row_of_entity(entity));
-            }
-        }
-
-        acquired.reset();
+        this.#acquired.reset();
         this.#written.reset();
         this.#reason.fill(0);
         this.#holds.fill(0);

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":"AAuFA;;GAEG;AACH;IAgPI;;;;;;;;OAQG;IACH,sBAPW,eAAe,aACf,eAAe,SAGf,kBAAkB,EA+D5B;IApTD,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;IAkGD;;;;;OAKG;IACH,iCAMC;IAgHD;;;;OAIG;IACH,eAHW,KAAK,GACH,SAAS,GAAC,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,6BAPW,MAAM,SAEN,eAAe,eACf,MAAM,mBACN,UAAU,MAAM,CAAC,QAgE3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAFW,sBAAsB,QAsFhC;IAsbD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAwOnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAiBC;;CACJ;qCAn9CY,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;oCA9DX,+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":"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"}

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"}