@woosh/meep-engine 3.61.1 → 3.61.3

package/src/generation/foliage/skeleton/ShootWoodHash.js

@@ -39,7 +39,7 @@ const SCRATCH_ST = new Float64Array(2);
  * of an axis that has died are passed over, and leave the hash at the next {@link refresh}.
  */
 export class ShootWoodHash {
-    /** @type {Map<number, number[]>} */
+    /** @type {Map<number, number[] & {max?: number}>} */
     cells = new Map();
 
     /**
@@ -75,6 +75,47 @@ export class ShootWoodHash {
 
     query = 0;
 
+    /** @type {number[]} */
+    #min_x = [];
+    /** @type {number[]} */
+    #max_x = [];
+    /** @type {number[]} */
+    #min_y = [];
+    /** @type {number[]} */
+    #max_y = [];
+    /** @type {number[]} */
+    #min_z = [];
+    /** @type {number[]} */
+    #max_z = [];
+    /** @type {number[]} */
+    #bx0 = [];
+    /** @type {number[]} */
+    #bx1 = [];
+    /** @type {number[]} */
+    #by0 = [];
+    /** @type {number[]} */
+    #by1 = [];
+    /** @type {number[]} */
+    #bz0 = [];
+    /** @type {number[]} */
+    #bz1 = [];
+    /** @type {number[]} */
+    #thickest = [];
+    #refreshed_max = -1;
+    /** @type {number[]} */
+    #last_candidates = [];
+    #last_b0 = NaN;
+    #last_b1 = NaN;
+    #last_b2 = NaN;
+    #last_radius = NaN;
+    #last_min_radius = NaN;
+    #last_ax0 = NaN;
+    #last_ax1 = NaN;
+    #last_ay0 = NaN;
+    #last_ay1 = NaN;
+    #last_az0 = NaN;
+    #last_az1 = NaN;
+
     /**
      * @param {Array<{alive: boolean, points: number[], radii: number[], units: number[]}>} axes
      */
@@ -94,24 +135,43 @@ export class ShootWoodHash {
         this.seen.push(0);
         const p = this.axes[m].points;
         const a = k * 3, b = a + 3;
-        const x0 = Math.floor(Math.min(p[a], p[b]) / WOOD_CELL), x1 = Math.floor(Math.max(p[a], p[b]) / WOOD_CELL);
-        const y0 = Math.floor(Math.min(p[a + 1], p[b + 1]) / WOOD_CELL), y1 = Math.floor(Math.max(p[a + 1], p[b + 1]) / WOOD_CELL);
-        const z0 = Math.floor(Math.min(p[a + 2], p[b + 2]) / WOOD_CELL), z1 = Math.floor(Math.max(p[a + 2], p[b + 2]) / WOOD_CELL);
+        const min_x = Math.min(p[a], p[b]), max_x = Math.max(p[a], p[b]);
+        const min_y = Math.min(p[a + 1], p[b + 1]), max_y = Math.max(p[a + 1], p[b + 1]);
+        const min_z = Math.min(p[a + 2], p[b + 2]), max_z = Math.max(p[a + 2], p[b + 2]);
+        const x0 = Math.floor(min_x / WOOD_CELL), x1 = Math.floor(max_x / WOOD_CELL);
+        const y0 = Math.floor(min_y / WOOD_CELL), y1 = Math.floor(max_y / WOOD_CELL);
+        const z0 = Math.floor(min_z / WOOD_CELL), z1 = Math.floor(max_z / WOOD_CELL);
+        this.#min_x.push(min_x);
+        this.#max_x.push(max_x);
+        this.#min_y.push(min_y);
+        this.#max_y.push(max_y);
+        this.#min_z.push(min_z);
+        this.#max_z.push(max_z);
+        this.#bx0.push(min_x);
+        this.#bx1.push(max_x);
+        this.#by0.push(min_y);
+        this.#by1.push(max_y);
+        this.#bz0.push(min_z);
+        this.#bz1.push(max_z);
+        this.#thickest.push(-1);
         for (let x = x0; x <= x1; x++) for (let y = y0; y <= y1; y++) for (let z = z0; z <= z1; z++) {
             if (!aabb3_intersects_segment3(
                 x * WOOD_CELL - CROSSING_TOLERANCE, y * WOOD_CELL - CROSSING_TOLERANCE, z * WOOD_CELL - CROSSING_TOLERANCE,
                 (x + 1) * WOOD_CELL + CROSSING_TOLERANCE, (y + 1) * WOOD_CELL + CROSSING_TOLERANCE, (z + 1) * WOOD_CELL + CROSSING_TOLERANCE,
                 p[a], p[a + 1], p[a + 2], p[b], p[b + 1], p[b + 2]
             )) continue;
-            const key = ((x + KEY_SPAN / 2) * KEY_SPAN + (y + KEY_SPAN / 2)) * KEY_SPAN + (z + KEY_SPAN / 2);
+            const key = (x * KEY_SPAN + y) * KEY_SPAN + z;
             let list = this.cells.get(key);
             if (list === undefined) {
                 list = [];
                 this.cells.set(key, list);
             }
+            list.max = Infinity;
             list.push(id);
             this.cell_max.set(key, Infinity);
         }
+        this.#refreshed_max = -1;
+        this.#last_b0 = NaN;
     }
 
     /**
@@ -121,6 +181,22 @@ export class ShootWoodHash {
      */
     refresh() {
         const axes = this.axes;
+        const n = this.unit_axis.length;
+        for (let id = 0; id < n; id++) {
+            const axis = axes[this.unit_axis[id]];
+            if (!axis.alive) continue;
+            const k = this.unit_index[id];
+            const r = axis.radii.length > k + 1 ? Math.max(axis.radii[k], axis.radii[k + 1]) : shoot_radius(axis.units[k], 0);
+            if (r === this.#thickest[id]) continue;
+            this.#thickest[id] = r;
+            const pad = r + CLEARANCE;
+            this.#bx0[id] = this.#min_x[id] - pad;
+            this.#bx1[id] = this.#max_x[id] + pad;
+            this.#by0[id] = this.#min_y[id] - pad;
+            this.#by1[id] = this.#max_y[id] + pad;
+            this.#bz0[id] = this.#min_z[id] - pad;
+            this.#bz1[id] = this.#max_z[id] + pad;
+        }
         let most = 0;
         for (const [key, list] of this.cells) {
             let max = 0;
@@ -130,8 +206,7 @@ export class ShootWoodHash {
                 const axis = axes[this.unit_axis[id]];
                 if (!axis.alive) continue;
                 list[kept++] = id;
-                const k = this.unit_index[id];
-                const thickest = axis.radii.length > k + 1 ? Math.max(axis.radii[k], axis.radii[k + 1]) : shoot_radius(axis.units[k], 0);
+                const thickest = this.#thickest[id];
                 if (thickest > max) max = thickest;
             }
             if (kept === 0) {
@@ -140,10 +215,13 @@ export class ShootWoodHash {
                 continue;
             }
             list.length = kept;
+            list.max = max;
             this.cell_max.set(key, max);
             if (max > most) most = max;
         }
         this.max_radius = most;
+        this.#refreshed_max = most;
+        this.#last_b0 = NaN;
     }
 
     /**
@@ -172,44 +250,132 @@ export class ShootWoodHash {
      * @returns {number}
      */
     hits(a, b, radius, min_radius, skip) {
-        const pad = radius + this.max_radius + CLEARANCE;
-        const x0 = Math.floor((Math.min(a[0], b[0]) - pad) / WOOD_CELL), x1 = Math.floor((Math.max(a[0], b[0]) + pad) / WOOD_CELL);
-        const y0 = Math.floor((Math.min(a[1], b[1]) - pad) / WOOD_CELL), y1 = Math.floor((Math.max(a[1], b[1]) + pad) / WOOD_CELL);
-        const z0 = Math.floor((Math.min(a[2], b[2]) - pad) / WOOD_CELL), z1 = Math.floor((Math.max(a[2], b[2]) + pad) / WOOD_CELL);
-        const query = ++this.query;
-        const axes = this.axes;
+        if (this.cells.size === 0) return -1;
+        const fresh = this.max_radius === this.#refreshed_max;
         const ax0 = Math.min(a[0], b[0]) - radius, ax1 = Math.max(a[0], b[0]) + radius;
         const ay0 = Math.min(a[1], b[1]) - radius, ay1 = Math.max(a[1], b[1]) + radius;
         const az0 = Math.min(a[2], b[2]) - radius, az1 = Math.max(a[2], b[2]) + radius;
+        const axes = this.axes;
+        const bx0 = this.#bx0, bx1 = this.#bx1, by0 = this.#by0, by1 = this.#by1, bz0 = this.#bz0, bz1 = this.#bz1;
+        const thickest_arr = this.#thickest;
+        const skip_geom_free = skip.length <= 2;
+
+        if (fresh && b[0] === this.#last_b0 && b[1] === this.#last_b1 && b[2] === this.#last_b2
+            && radius === this.#last_radius && min_radius === this.#last_min_radius
+            && ax0 >= this.#last_ax0 && ax1 <= this.#last_ax1
+            && ay0 >= this.#last_ay0 && ay1 <= this.#last_ay1
+            && az0 >= this.#last_az0 && az1 <= this.#last_az1) {
+            const cands = this.#last_candidates;
+            for (let i = 0; i < cands.length; i++) {
+                const id = cands[i];
+                if (bx0[id] > ax1 || bx1[id] < ax0 || by0[id] > ay1 || by1[id] < ay0 || bz0[id] > az1 || bz1[id] < az0) continue;
+                const m = this.unit_axis[id];
+                const k = this.unit_index[id];
+                if (skip_geom_free && skip(m, k, 0, 0)) continue;
+                const p = axes[m].points;
+                const q = k * 3;
+                line3_compute_segment_segment_closest_points(SCRATCH_ST, a[0], a[1], a[2], b[0], b[1], b[2], p[q], p[q + 1], p[q + 2], p[q + 3], p[q + 4], p[q + 5]);
+                const s = SCRATCH_ST[0], t = SCRATCH_ST[1];
+                const r = ShootWoodHash.radius_at(axes[m], k, t);
+                const dx = a[0] + (b[0] - a[0]) * s - (p[q] + (p[q + 3] - p[q]) * t);
+                const dy = a[1] + (b[1] - a[1]) * s - (p[q + 1] + (p[q + 4] - p[q + 1]) * t);
+                const dz = a[2] + (b[2] - a[2]) * s - (p[q + 2] + (p[q + 5] - p[q + 2]) * t);
+                const limit = r + radius + CLEARANCE;
+                if (dx * dx + dy * dy + dz * dz >= limit * limit) continue;
+                if (!skip_geom_free && skip(m, k, r, s)) continue;
+                return m;
+            }
+            return -1;
+        }
+
+        const reach = this.max_radius + CLEARANCE;
+        const x0 = Math.floor((ax0 - reach) / WOOD_CELL), x1 = Math.floor((ax1 + reach) / WOOD_CELL);
+        const y0 = Math.floor((ay0 - reach) / WOOD_CELL), y1 = Math.floor((ay1 + reach) / WOOD_CELL);
+        const z0 = Math.floor((az0 - reach) / WOOD_CELL), z1 = Math.floor((az1 + reach) / WOOD_CELL);
+        const single = x0 === x1 && y0 === y1 && z0 === z1;
+        const query = single ? 0 : ++this.query;
+        const seen = this.seen;
+        const cands = this.#last_candidates;
+        if (fresh) {
+            cands.length = 0;
+            this.#last_b0 = b[0];
+            this.#last_b1 = b[1];
+            this.#last_b2 = b[2];
+            this.#last_radius = radius;
+            this.#last_min_radius = min_radius;
+            this.#last_ax0 = ax0;
+            this.#last_ax1 = ax1;
+            this.#last_ay0 = ay0;
+            this.#last_ay1 = ay1;
+            this.#last_az0 = az0;
+            this.#last_az1 = az1;
+        }
         for (let x = x0; x <= x1; x++) for (let y = y0; y <= y1; y++) for (let z = z0; z <= z1; z++) {
-            const key = ((x + KEY_SPAN / 2) * KEY_SPAN + (y + KEY_SPAN / 2)) * KEY_SPAN + (z + KEY_SPAN / 2);
+            const key = (x * KEY_SPAN + y) * KEY_SPAN + z;
             const list = this.cells.get(key);
-            if (list === undefined || this.cell_max.get(key) < min_radius) continue;
+            if (list === undefined || list.max < min_radius) continue;
+            if (fresh) {
+                const pad_c = list.max + CLEARANCE;
+                if (x * WOOD_CELL > ax1 + pad_c || (x + 1) * WOOD_CELL < ax0 - pad_c
+                    || y * WOOD_CELL > ay1 + pad_c || (y + 1) * WOOD_CELL < ay0 - pad_c
+                    || z * WOOD_CELL > az1 + pad_c || (z + 1) * WOOD_CELL < az0 - pad_c) continue;
+            }
             for (let i = 0; i < list.length; i++) {
                 const id = list[i];
-                if (this.seen[id] === query) continue;
-                this.seen[id] = query;
+                if (fresh) {
+                    if (bx0[id] > ax1 || bx1[id] < ax0 || by0[id] > ay1 || by1[id] < ay0 || bz0[id] > az1 || bz1[id] < az0) continue;
+                    const thickest = thickest_arr[id];
+                    if (thickest < min_radius) continue;
+                    if (!single) {
+                        if (seen[id] === query) continue;
+                        seen[id] = query;
+                    }
+                    const m = this.unit_axis[id];
+                    const axis = axes[m];
+                    if (!axis.alive) continue;
+                    cands.push(id);
+                    const k = this.unit_index[id];
+                    if (skip_geom_free && skip(m, k, 0, 0)) continue;
+                    const p = axis.points;
+                    const q = k * 3;
+                    line3_compute_segment_segment_closest_points(SCRATCH_ST, a[0], a[1], a[2], b[0], b[1], b[2], p[q], p[q + 1], p[q + 2], p[q + 3], p[q + 4], p[q + 5]);
+                    const s = SCRATCH_ST[0], t = SCRATCH_ST[1];
+                    const r = ShootWoodHash.radius_at(axis, k, t);
+                    const dx = a[0] + (b[0] - a[0]) * s - (p[q] + (p[q + 3] - p[q]) * t);
+                    const dy = a[1] + (b[1] - a[1]) * s - (p[q + 1] + (p[q + 4] - p[q + 1]) * t);
+                    const dz = a[2] + (b[2] - a[2]) * s - (p[q + 2] + (p[q + 5] - p[q + 2]) * t);
+                    const limit = r + radius + CLEARANCE;
+                    if (dx * dx + dy * dy + dz * dz >= limit * limit) continue;
+                    if (!skip_geom_free && skip(m, k, r, s)) continue;
+                    this.#last_b0 = NaN;
+                    return m;
+                }
+                if (!single) {
+                    if (seen[id] === query) continue;
+                    seen[id] = query;
+                }
                 const m = this.unit_axis[id];
                 const axis = axes[m];
                 if (!axis.alive) continue;
                 const k = this.unit_index[id];
-                const p = axis.points;
-                const q = k * 3;
-                // the thickest the unit is, and whether its box padded by that meets the capsule's
                 const thickest = axis.radii.length > k + 1 ? Math.max(axis.radii[k], axis.radii[k + 1]) : shoot_radius(axis.units[k], 0);
                 if (thickest < min_radius) continue;
                 const pad_k = thickest + CLEARANCE;
-                if (Math.min(p[q], p[q + 3]) - pad_k > ax1 || Math.max(p[q], p[q + 3]) + pad_k < ax0
-                    || Math.min(p[q + 1], p[q + 4]) - pad_k > ay1 || Math.max(p[q + 1], p[q + 4]) + pad_k < ay0
-                    || Math.min(p[q + 2], p[q + 5]) - pad_k > az1 || Math.max(p[q + 2], p[q + 5]) + pad_k < az0) continue;
+                if (this.#min_x[id] - pad_k > ax1 || this.#max_x[id] + pad_k < ax0
+                    || this.#min_y[id] - pad_k > ay1 || this.#max_y[id] + pad_k < ay0
+                    || this.#min_z[id] - pad_k > az1 || this.#max_z[id] + pad_k < az0) continue;
+                if (skip_geom_free && skip(m, k, 0, 0)) continue;
+                const p = axis.points;
+                const q = k * 3;
                 line3_compute_segment_segment_closest_points(SCRATCH_ST, a[0], a[1], a[2], b[0], b[1], b[2], p[q], p[q + 1], p[q + 2], p[q + 3], p[q + 4], p[q + 5]);
                 const s = SCRATCH_ST[0], t = SCRATCH_ST[1];
                 const r = ShootWoodHash.radius_at(axis, k, t);
                 const dx = a[0] + (b[0] - a[0]) * s - (p[q] + (p[q + 3] - p[q]) * t);
                 const dy = a[1] + (b[1] - a[1]) * s - (p[q + 1] + (p[q + 4] - p[q + 1]) * t);
                 const dz = a[2] + (b[2] - a[2]) * s - (p[q + 2] + (p[q + 5] - p[q + 2]) * t);
-                if (Math.hypot(dx, dy, dz) >= r + radius + CLEARANCE) continue;
-                if (skip(m, k, r, s)) continue;
+                const limit = r + radius + CLEARANCE;
+                if (dx * dx + dy * dy + dz * dz >= limit * limit) continue;
+                if (!skip_geom_free && skip(m, k, r, s)) continue;
                 return m;
             }
         }

package/src/shade/playground/probe_clipmap/README.md

@@ -21,7 +21,7 @@ has the two lines that put it there. Another scene loads with `?scene=/some/othe
 | control | what it does |
 |---|---|
 | Indirect light | the probe clipmap, or IBL to compare against |
-| Debug view | the brick clipmap as the probes' rays see it; the geometry caches' mesh SDF; the hits' albedo from the cards |
+| Debug view | the brick clipmap as the probes' rays see it; the geometry caches' mesh SDF; the hits' albedo from the meshes' surface caches; the brick material the probes' hits read; the light the probes' indirect diffuse (irradiance / π) or indirect specular (radiance) is made of, before the surface's albedo, metalness, reflectance and occlusion, through the frame's TAA and exposure |
 | Path tracer (P) | the accumulating path tracer's image in place of the rasterized one, as ground truth; TAA is off while it is on and comes back after |
 | History re-sampling (R) | each probe update pools its rays with what four of its neighbours have already seen, where their depth confirms it (`ProbeClipmapSettings.history_resampling`); off by default, and measured quieter but no faster to converge on Sponza (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8) |
 | Ray re-sampling (T) | each probe update also takes every ray one neighbour traced the same frame, the neighbour drawn by its radiance and the probe's sight of it, each ray where the probe's depth confirms its hit or sky (`ProbeClipmapSettings.ray_resampling`); off by default (PROBE_RAY_REPROJECTION_SCOPE_2026_11_01.md) |
@@ -39,6 +39,5 @@ the camera, the sun or the point lights restarts it. It stops at three bounces.
 
 ## What to expect
 
-Specular light still comes from the environment, unoccluded, until the probes' specular lands (the
-proposal's S6). Indoors, where the probes' diffuse is rightly darker than IBL's, that sky reflection shows
-as a bluish sheen over cloth and stone.
+Both lobes come from the probes (the proposal's §9). A pixel no probe weighs anything for takes the
+environment's light for both, as IBL gives it.

package/src/shade/playground/probe_clipmap/index.html

@@ -99,7 +99,11 @@
             <option value="None" selected>None</option>
             <option value="BrickClipmap">Brick clipmap — what the rays see</option>
             <option value="MeshSDF">Mesh SDF — the geometry caches</option>
-            <option value="MeshCards">Mesh cards — the hits' albedo</option>
+            <option value="MeshSurfaces">Mesh surfaces — each mesh's surface cache</option>
+            <option value="IndirectDiffuse">Indirect diffuse — the probes' irradiance / π, before the material</option>
+            <option value="IndirectSpecular">Indirect specular — the probes' radiance, before the material</option>
+            <option value="BrickMaterial">Brick material — the probes' hits' albedo</option>
+            <option value="BrickMetalRough">Brick material — the probes' hits' metal (R) and rough (G)</option>
         </select>
     </label>
 
@@ -153,18 +157,6 @@
         frame-time knob; this page starts higher so Sponza is whole in seconds, not minutes.
     </p>
 
-    <label>
-        <span>Card capture</span>
-        <select id="card_capture_mode">
-            <option value="Raster" selected>Raster — the material's own pass</option>
-            <option value="Trace">Trace — a ray a texel</option>
-        </select>
-    </label>
-    <p class="note">
-        How the cards take their albedo. A change captures every card set again; the Mesh cards view
-        shows what they hold.
-    </p>
-
     <hr>
 
     <div id="status"></div>

package/src/shade/playground/probe_clipmap/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/probe_clipmap/main.js"],"names":[],"mappings":"AA0FA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAsSzB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/probe_clipmap/main.js"],"names":[],"mappings":"AAyFA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAsSzB"}

package/src/shade/playground/probe_clipmap/main.js

@@ -11,7 +11,6 @@ import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.j
 import { OrbitalCameraController } from "../../renderer/camera/orbital/OrbitalCameraController.js";
 import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
 import { create_frame_loop } from "../../renderer/create_frame_loop.js";
-import { MeshCardCaptureMode } from "../../renderer/geometry/sdf/cards/MeshCardCaptureMode.js";
 import { ProbeClipmapDebugView } from "../../renderer/global_illumination/probe_clipmap/debug/ProbeClipmapDebugView.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
 import { PointLight } from "../../renderer/light/model/PointLight.js";
@@ -214,6 +213,10 @@ export async function start() {
 
         sun.transform.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
         sun.transform.updateMatrix();
+
+        // a light changed in place reaches the GPU only through the collection's version; without it the
+        // shadow cascades, which read the transform themselves, turn and the light does not
+        scene.lights.needsUpdate = true;
     }
 
     aim_sun();
@@ -238,10 +241,6 @@ export async function start() {
         renderer.probe_clipmap.debug_view = ProbeClipmapDebugView[event.target.value];
     });
 
-    element('card_capture_mode').addEventListener('change', event => {
-        renderer.probe_clipmap.card_capture_mode = MeshCardCaptureMode[event.target.value];
-    });
-
     const taa_toggle = element('taa');
     const path_tracing_toggle = element('path_tracing');
 

package/src/shade/playground/probe_clipmap_box/README.md

@@ -0,0 +1,55 @@
+# Probe clipmap GI — a box with a hole
+
+A closed box under `ShadeIndirectLightingMode.ProbeClipmap`
+(`src/shade/renderer/global_illumination/probe_clipmap/PROBE_CLIPMAP_PROPOSAL_2026_10_27.md`), built to watch how
+the probes follow a change: the sun moved from one wall to another, or the only opening closed. Nothing but the
+sun lights the inside, so what the probes should hold after a change is known without a reference renderer, and
+with the hole closed it is nothing at all.
+
+## Running it
+
+```bash
+npm install
+npm run dev
+```
+
+then open <http://localhost:5173/src/shade/playground/probe_clipmap_box/index.html>. The page needs no asset.
+
+## The box
+
+`scene.js` builds it, and a harness can build the same one through `build_hole_box`.
+
+- The inside is 5 m a side: five spacings of the finest probe cascade at the GI's default spacing.
+- Every slab is 0.25 m thick, two voxels of the finest brick, so a wall has an inside the distance field can
+  tell from its outside. Each slab is a geometry of its own size at unit scale, since a mesh's distance field
+  is cached per geometry and a scaled unit cube would not be one.
+- The walls have the classic Cornell reflectances: white 0.73, red (0.63, 0.065, 0.05) at −x and green
+  (0.14, 0.45, 0.091) at +x.
+- The hole is 1.25 m square in the middle of the ceiling. A flat sky of (0.2, 0.25, 0.35) is seen through it.
+
+## The controls
+
+| control | what it does |
+|---|---|
+| Sun (1, 2, 3) | through the hole onto the red wall or the green wall, from 45°, or straight down onto the floor |
+| Hole open (H) | closed, a lid of the hole's size sits flush in the ceiling; it is placed into the scene and taken out again, so the bricks the rays march are rebuilt as a level's would be |
+| Indirect light | the probe clipmap, or IBL to compare against |
+| Debug view | the brick clipmap as the rays see it; the geometry caches' mesh SDF; the hits' albedo from the meshes' surface caches |
+| Restart GI (K) | gives the clipmaps back and builds them again from nothing, the geometry caches kept: a cold start without a reload |
+| Path tracer (P) | the accumulating path tracer, three bounces, for context; TAA is off while it is on |
+| TAA | the resolve the probe pick's noise is meant for |
+| Exposure | fixed f-stops; eye adaptation is off, so a change on screen is the light's. The probes' estimators state their thresholds in it too: a change below what the display shows is taken for noise and followed slowly |
+
+The stats line counts the frames since the sun or the hole last changed.
+
+## What to look for
+
+- **Hole closed**: the inside should go black. Whatever light stays is what the probes still hold.
+- **Sun moved between the walls**: the colour bleeding onto the back wall and the floor should swap from red
+  to green.
+- **Restart**: until the brick clipmap has built (about 48 frames at the default build budget), the rays see
+  no walls and every probe sees the sky; the light then has to drain out of the probes.
+
+Aiming the sun sets `scene.lights.needsUpdate`: a light changed in place reaches the GPU only when the light
+collection's version moves, while the shadow cascades read the transform themselves, so without it the
+shadow turns and the light does not.

package/src/shade/playground/probe_clipmap_box/index.html

@@ -0,0 +1,185 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — probe clipmap GI, a box with a hole</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --panel: rgba(20, 22, 26, 0.88);
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; overflow: hidden; background: #0d0f12; }
+
+        /* body carries tabindex so the camera controller's keyboard device has something focusable
+           to listen on; the focus ring around the whole viewport is not wanted */
+        body:focus { outline: none; }
+
+        #view { display: block; width: 100vw; height: 100vh; }
+
+        #panel {
+            position: fixed;
+            top: 12px;
+            left: 12px;
+            width: 320px;
+            padding: 12px 14px;
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            backdrop-filter: blur(6px);
+            color: var(--text);
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        #panel h1 { font-size: 13px; font-weight: 600; margin: 0 0 8px; }
+
+        label { display: flex; align-items: center; gap: 8px; padding: 3px 0; cursor: pointer; }
+        label input[type="checkbox"] { margin: 0; }
+        label .hint { color: var(--muted); font-size: 11.5px; }
+        label > span:first-child { flex: 0 0 96px; }
+
+        select {
+            flex: 1 1 auto;
+            min-width: 0;
+            font: 12px system-ui, -apple-system, Segoe UI, sans-serif;
+            padding: 3px 6px;
+            border-radius: 5px;
+            border: 1px solid var(--line);
+            background: #14161a;
+            color: var(--text);
+        }
+
+        button {
+            font: 12px system-ui, -apple-system, Segoe UI, sans-serif;
+            padding: 3px 10px;
+            border-radius: 5px;
+            border: 1px solid var(--line);
+            background: #1d2026;
+            color: var(--text);
+            cursor: pointer;
+        }
+
+        input[type="range"] { flex: 1 1 auto; min-width: 0; }
+
+        output { flex: 0 0 34px; text-align: right; color: var(--muted); font: 12px ui-monospace, SFMono-Regular, Consolas, monospace; }
+
+        hr { border: 0; border-top: 1px solid var(--line); margin: 10px 0; }
+
+        #status { font-size: 12px; color: var(--muted); word-break: break-word; }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        #stats {
+            margin-top: 6px;
+            font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--text);
+            white-space: pre;
+        }
+
+        p.note { margin: 8px 0 0; font-size: 11.5px; color: var(--muted); }
+    </style>
+</head>
+<body tabindex="0">
+
+<canvas id="view"></canvas>
+
+<div id="panel">
+    <h1>Probe clipmap GI — a box with a hole</h1>
+
+    <label>
+        <span>Sun</span>
+        <select id="sun_aim">
+            <option value="RedWall" selected>Onto the red wall</option>
+            <option value="GreenWall">Onto the green wall</option>
+            <option value="Down">Straight down</option>
+        </select>
+    </label>
+
+    <label>
+        <input type="checkbox" id="hole_open" checked>
+        <span>Hole open <span class="hint">— closed, nothing lights the inside; H flips it</span></span>
+    </label>
+
+    <p class="note">1, 2 and 3 aim the sun.</p>
+
+    <hr>
+
+    <label>
+        <span>Indirect light</span>
+        <select id="indirect">
+            <option value="ProbeClipmap" selected>Probe clipmap</option>
+            <option value="IBL">IBL</option>
+        </select>
+    </label>
+
+    <label>
+        <span>Debug view</span>
+        <select id="debug_view">
+            <option value="None" selected>None</option>
+            <option value="BrickClipmap">Brick clipmap — what the rays see</option>
+            <option value="MeshSDF">Mesh SDF — the geometry caches</option>
+            <option value="MeshSurfaces">Mesh surfaces — each mesh's surface cache</option>
+        </select>
+    </label>
+
+    <label>
+        <span>Restart GI</span>
+        <button id="restart">Restart</button>
+        <span class="hint">K</span>
+    </label>
+    <p class="note">
+        Gives the probes and bricks back and builds them again from nothing, the geometry caches kept: the
+        convergence from a cold start, without reloading.
+    </p>
+
+    <label>
+        <input type="checkbox" id="path_tracing">
+        <span>Path tracer <span class="hint">— three bounces, for context; P flips it</span></span>
+    </label>
+
+    <label>
+        <input type="checkbox" id="taa" checked>
+        <span>TAA <span class="hint">— resolves the probe pick's noise</span></span>
+    </label>
+
+    <label>
+        <span>Exposure</span>
+        <input type="range" id="exposure" min="-4" max="8" step="0.5">
+        <output id="exposure_value"></output>
+    </label>
+
+    <hr>
+
+    <div id="status"></div>
+    <div id="stats"></div>
+
+    <p class="note">
+        Drag to orbit, wheel to zoom, WASD to move. The exposure is fixed, so a change you see is the light's,
+        not the eye's adapting.
+    </p>
+</div>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+
+        console.error(error);
+    });
+</script>
+
+</body>
+</html>

package/src/shade/playground/probe_clipmap_box/main.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stand the page up. Called by the page rather than run on import, so that nothing here touches the DOM
+ * until there is one.
+ *
+ * @returns {Promise<void>}
+ */
+export function start(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/probe_clipmap_box/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/probe_clipmap_box/main.js"],"names":[],"mappings":"AAsEA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAwPzB"}