@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js

@@ -1,6 +1,7 @@
 import { assert } from "../../../../core/assert.js";
 import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
 import { MESH_CARD_CAPTURE_BUDGET_MAX } from "../../geometry/sdf/cards/GPUMeshCardSets.js";
+import { MeshCardCaptureMode } from "../../geometry/sdf/cards/MeshCardCaptureMode.js";
 import { MESH_SDF_BAKE_BUDGET_MAX } from "../../geometry/sdf/GPUGeometrySDFManager.js";
 import { ProbeClipmapDebugView } from "./debug/ProbeClipmapDebugView.js";
 
@@ -239,8 +240,17 @@ export class ProbeClipmapSettings {
      * GPU with another load of 40–73%, which is in the medians: the least loaded frames cost 0.11 ms at
      * 16,384. At the default Sponza's cards are captured in 10 frames.
      *
-     * On the AMD iGPU (RDNA2) a page costs 0.78 µs: 16,384 pages cost 33.5 ms at the median, and
-     * about 1,290 fit 1 ms (1,024 cost 0.80 ms).
+     * Re-derived once the material reads became trilinear at a texel's footprint (2026-10-30), which
+     * costs 1.30× at the median, timed on the same pages in the same frame: 16,384 pages cost 0.54 and
+     * 0.55 ms at the median in two runs (the old capture 0.54 ms beside them), 32,768 cost 1.48 and
+     * 1.52 ms, and the least loaded frames 0.15 ms at 16,384.
+     *
+     * On the AMD iGPU (RDNA2), measured before that, a page costs 0.78 µs: 16,384 pages cost 33.5 ms at
+     * the median, and about 1,290 fit 1 ms (1,024 cost 0.80 ms).
+     *
+     * Derived for {@link MeshCardCaptureMode.Trace}. A rastered card set is taken whole, the frame's
+     * last past the budget, and a frame also stops at what its scratch holds: at the largest budget
+     * Sponza's recapture took 13 frames on the iGPU, 2.5 ms of capture a frame on average.
      * @returns {number}
      */
     get card_capture_budget() {
@@ -258,6 +268,38 @@ export class ProbeClipmapSettings {
         this.#card_capture_budget = v;
     }
 
+    #card_capture_mode = MeshCardCaptureMode.Raster;
+
+    /**
+     * How card pages are captured: each card drawn through its material's own template and textures,
+     * or a ray a texel against the geometry's BLAS with the path tracer's material sampling. A change
+     * captures every card set again.
+     *
+     * Raster is the default. The trace took one level-0 tap of the material's 64² resident copy a
+     * texel and kept it, which aliased: on Sponza's outer wall the brick texture's dark band, every
+     * 12.8 card texels, landed on a row of texels once and between rows at its other repeats, a seam
+     * across the wall. The raster samples the texture's mips at the card texel's footprint, as UE's
+     * card capture does, and since 2026-10-30 the trace reads the resident copy's mips there too,
+     * trilinearly, at 1.30× its cost (see {@link card_capture_budget}). Against the one-tap trace, the
+     * cards' colours agreed with the raster's to 3 codes on average over Sponza's wall, floor, ceiling
+     * and banners, and recapturing all of Sponza (154,138 pages) at the largest budget, the two
+     * interleaved in one process, cost the trace 9.1–12.7 ms and the raster 0.6 ms on the RTX 4090,
+     * and 335 ms against 33 ms on the AMD iGPU (RDNA2).
+     * @returns {MeshCardCaptureMode}
+     */
+    get card_capture_mode() {
+        return this.#card_capture_mode;
+    }
+
+    /**
+     * @param {MeshCardCaptureMode} v
+     */
+    set card_capture_mode(v) {
+        assert.enum(v, MeshCardCaptureMode, 'card_capture_mode');
+
+        this.#card_capture_mode = v;
+    }
+
     #probe_cascade_count = 5;
 
     /**
@@ -411,46 +453,28 @@ export class ProbeClipmapSettings {
         this.#ray_budget = v;
     }
 
-    #response_time = 0.5;
-
-    /**
-     * Seconds of the exponential blend a probe's radiance follows a change by: an update blends by
-     * `1 − e^(−Δt / response_time)`. DDGI's hysteresis of 0.97 a frame at 60 fps is 0.55 s.
-     * @returns {number}
-     */
-    get response_time() {
-        return this.#response_time;
-    }
-
-    /**
-     * @param {number} v seconds, positive and finite
-     */
-    set response_time(v) {
-        assert.isFinite(v, 'response_time');
-        assert.greaterThan(v, 0, 'response_time');
-
-        this.#response_time = v;
-    }
-
-    #retention_time = 1;
+    #response_frames = 30;
 
     /**
-     * Seconds a probe no pixel wants keeps its slot before it is freed, so a probe that leaves the screen
-     * and comes back within it keeps its history.
+     * Frames of the short mean a probe's radiance follows a change by, in its multi-scale mean: an update
+     * blends the short mean by `1 − e^(−Δt / response_frames)`, Δt the frames since the probe's last update,
+     * and the mean catches up with it once the two disagree past the texel's noise. The depth's moments
+     * blend by the same. Frames, not seconds: an update happens in a frame, and the records count them.
+     * 30 is half a second at 60 fps; DDGI's hysteresis of 0.97 a frame is 33.
      * @returns {number}
      */
-    get retention_time() {
-        return this.#retention_time;
+    get response_frames() {
+        return this.#response_frames;
     }
 
     /**
-     * @param {number} v seconds, positive and finite
+     * @param {number} v frames, positive and finite
      */
-    set retention_time(v) {
-        assert.isFinite(v, 'retention_time');
-        assert.greaterThan(v, 0, 'retention_time');
+    set response_frames(v) {
+        assert.isFinite(v, 'response_frames');
+        assert.greaterThan(v, 0, 'response_frames');
 
-        this.#retention_time = v;
+        this.#response_frames = v;
     }
 
     #debug_view = ProbeClipmapDebugView.None;

package/src/shade/renderer/global_illumination/probe_clipmap/brick/BRICK_CLIPMAP.d.ts

@@ -37,6 +37,13 @@ export const BRICK_OBJECT_CELLS_PER_AXIS: number;
  * @type {number}
  */
 export const BRICK_OBJECT_CELLS: number;
+/**
+ * The `meshes` rows an object cell can name: one more than the largest row that fits in the 24 bits
+ * the object decision packs a row into beside its distance byte (`chunk_brick_object`). A row past it
+ * writes no object, as a provider that cannot name a row does (§7.6, contract 5).
+ * @type {number}
+ */
+export const BRICK_OBJECT_ROW_LIMIT: number;
 /**
  * Words of a build slot's staged distances: 512 bytes, four texels a word, texel `t` in byte `t % 4`
  * of word `t / 4`.
@@ -44,13 +51,21 @@ export const BRICK_OBJECT_CELLS: number;
  */
 export const BRICK_STAGING_DISTANCE_WORDS: number;
 /**
- * Words of a build slot in the staging: its distances, then its objects.
+ * The word of a build slot that asks for its cell again (§7.6, contract 7), after its distances and
+ * its objects: clear makes it 0, and a provider that could not finish the cell this frame writes 1.
+ * Free then puts the key back on the ring rather than out of the pending set, and the cell is built
+ * again from what the frame stored.
+ * @type {number}
+ */
+export const BRICK_STAGING_RETRY_WORD: number;
+/**
+ * Words of a build slot in the staging: its distances, its objects, then its retry word.
  * @type {number}
  */
 export const BRICK_STAGING_WORDS: number;
 /**
- * Lanes of the passes that run a workgroup a taken cell: free, store and the mesh provider. Eight
- * texels a lane.
+ * Lanes of the passes that run a workgroup a taken cell: free, store and the mesh provider's walk,
+ * batches and resolve. Eight texels a lane.
  * @type {number}
  */
 export const BRICK_CELL_WORKGROUP_SIZE: number;

package/src/shade/renderer/global_illumination/probe_clipmap/brick/BRICK_CLIPMAP.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BRICK_CLIPMAP.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/BRICK_CLIPMAP.js"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;GAIG;AACH,kCAFU,MAAM,CAE8B;AAE9C;;;;GAIG;AACH,yCAFU,MAAM,CAEkD;AAElE;;;;GAIG;AACH,0CAFU,MAAM,CAEmD;AAEnE;;;GAGG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,iCAFU,MAAM,CAEmD;AAEnE;;;;GAIG;AACH,2CAFU,MAAM,CAE2D;AAE3E;;;GAGG;AACH,kCAFU,MAAM,CAEqE;AAErF;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,0CAFU,MAAM,CAE8B;AAM9C;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;GAKG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAQnC;;;;GAIG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;;GAIG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAOlC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,qCAFU,MAAM,CAEwB"}
+{"version":3,"file":"BRICK_CLIPMAP.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/BRICK_CLIPMAP.js"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;GAIG;AACH,kCAFU,MAAM,CAE8B;AAE9C;;;;GAIG;AACH,yCAFU,MAAM,CAEkD;AAElE;;;;GAIG;AACH,0CAFU,MAAM,CAEmD;AAEnE;;;GAGG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,iCAFU,MAAM,CAEmD;AAEnE;;;;;GAKG;AACH,qCAFU,MAAM,CAE8B;AAE9C;;;;GAIG;AACH,2CAFU,MAAM,CAE2D;AAE3E;;;;;;GAMG;AACH,uCAFU,MAAM,CAE0E;AAE1F;;;GAGG;AACH,kCAFU,MAAM,CAEgD;AAEhE;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,0CAFU,MAAM,CAE8B;AAM9C;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;GAKG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAQnC;;;;GAIG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;;GAIG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAOlC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;GAGG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,qCAFU,MAAM,CAEwB"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/BRICK_CLIPMAP.js

@@ -57,6 +57,14 @@ export const BRICK_OBJECT_CELLS_PER_AXIS = 4;
  */
 export const BRICK_OBJECT_CELLS = BRICK_OBJECT_CELLS_PER_AXIS ** 3;
 
+/**
+ * The `meshes` rows an object cell can name: one more than the largest row that fits in the 24 bits
+ * the object decision packs a row into beside its distance byte (`chunk_brick_object`). A row past it
+ * writes no object, as a provider that cannot name a row does (§7.6, contract 5).
+ * @type {number}
+ */
+export const BRICK_OBJECT_ROW_LIMIT = 1 << 24;
+
 /**
  * Words of a build slot's staged distances: 512 bytes, four texels a word, texel `t` in byte `t % 4`
  * of word `t / 4`.
@@ -65,14 +73,23 @@ export const BRICK_OBJECT_CELLS = BRICK_OBJECT_CELLS_PER_AXIS ** 3;
 export const BRICK_STAGING_DISTANCE_WORDS = MESH_SDF_BRICK_TEXEL_COUNT / 4;
 
 /**
- * Words of a build slot in the staging: its distances, then its objects.
+ * The word of a build slot that asks for its cell again (§7.6, contract 7), after its distances and
+ * its objects: clear makes it 0, and a provider that could not finish the cell this frame writes 1.
+ * Free then puts the key back on the ring rather than out of the pending set, and the cell is built
+ * again from what the frame stored.
+ * @type {number}
+ */
+export const BRICK_STAGING_RETRY_WORD = BRICK_STAGING_DISTANCE_WORDS + BRICK_OBJECT_CELLS;
+
+/**
+ * Words of a build slot in the staging: its distances, its objects, then its retry word.
  * @type {number}
  */
-export const BRICK_STAGING_WORDS = BRICK_STAGING_DISTANCE_WORDS + BRICK_OBJECT_CELLS;
+export const BRICK_STAGING_WORDS = BRICK_STAGING_RETRY_WORD + 1;
 
 /**
- * Lanes of the passes that run a workgroup a taken cell: free, store and the mesh provider. Eight
- * texels a lane.
+ * Lanes of the passes that run a workgroup a taken cell: free, store and the mesh provider's walk,
+ * batches and resolve. Eight texels a lane.
  * @type {number}
  */
 export const BRICK_CELL_WORKGROUP_SIZE = 64;

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.d.ts

@@ -9,7 +9,9 @@
  * @property {number} take `brick_take`'s handle: the taken keys' first and count, and the cell dispatch
  *   at {@link BRICK_TAKE_CELL_DISPATCH}, a workgroup a taken cell. Bind it read-only and dispatch
  *   through it.
- * @property {number} staging `brick_staging`'s handle, `BRICK_STAGING_WORDS` words a build slot
+ * @property {number} staging `brick_staging`'s handle, `BRICK_STAGING_WORDS` words a build slot. A provider
+ *   that could not finish a cell sets its `BRICK_STAGING_RETRY_WORD`, and the cell is built again (§7.6, contract 7)
+ * @property {number} staging_capacity build slots the staging holds: at least the frame's taken cells
  * @property {GPUBuffer} ring the keys; taken key `b` sits at `(taken_first + b) & (ring_capacity - 1)`
  * @property {number} ring_capacity
  * @property {number} resolution cells a cascade's window has a side
@@ -192,9 +194,14 @@ export type BrickProviderContext = {
      */
     take: number;
     /**
-     * `brick_staging`'s handle, `BRICK_STAGING_WORDS` words a build slot
+     * `brick_staging`'s handle, `BRICK_STAGING_WORDS` words a build slot. A provider
+     * that could not finish a cell sets its `BRICK_STAGING_RETRY_WORD`, and the cell is built again (§7.6, contract 7)
      */
     staging: number;
+    /**
+     * build slots the staging holds: at least the frame's taken cells
+     */
+    staging_capacity: number;
     /**
      * the keys; taken key `b` sits at `(taken_first + b) & (ring_capacity - 1)`
      */

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUBrickClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js"],"names":[],"mappings":"AAiFA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA0JI;;;;;;OAMG;IACH;QAJ2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,UAAU,EAA1B,MAAM;OA8FhB;IA5PD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IA4OX;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;;;;;OAQG;IACH,mCASC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,sBAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAMnB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAZ+B,KAAK,EAAzB,UAAU;QACM,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,MAAM,EAAtB,MAAM;QAC4B,SAAS,EAA3C,UAAU,aAAa,CAAC;QACM,KAAK,EAAnC,eAAe,GAAC,IAAI;QACH,MAAM,GAAvB,MAAM;QAEJ,MAAM,CAgGlB;IAgWD,gBAcC;;CACJ;mCA36BY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU;8BACpF,OAAO,mCAAmC,EAAE,eAAe;;;;;;;WAyC1D,UAAU;;;;WACV,MAAM;;;;;;UACN,MAAM;;;;aAGN,MAAM;;;;;mBAEN,MAAM;;;;gBACN,MAAM;mBACN,MAAM;;;;;;;;;;WAGN,eAAe;;;+BAMN,UAAU,QAAE,oBAAoB,KAAG,IAAI;;+BAxF/B,0CAA0C"}
+{"version":3,"file":"GPUBrickClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js"],"names":[],"mappings":"AAiFA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA2JI;;;;;;OAMG;IACH;QAJ2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,UAAU,EAA1B,MAAM;OA8FhB;IA7PD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IA6OX;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;;;;;OAQG;IACH,mCASC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,sBAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAMnB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAZ+B,KAAK,EAAzB,UAAU;QACM,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,MAAM,EAAtB,MAAM;QAC4B,SAAS,EAA3C,UAAU,aAAa,CAAC;QACM,KAAK,EAAnC,eAAe,GAAC,IAAI;QACH,MAAM,GAAvB,MAAM;QAEJ,MAAM,CAoGlB;IAgWD,gBAcC;;CACJ;mCAl7BY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU;8BACpF,OAAO,mCAAmC,EAAE,eAAe;;;;;;;WAyC1D,UAAU;;;;WACV,MAAM;;;;;;UACN,MAAM;;;;;aAGN,MAAM;;;;sBAEN,MAAM;;;;;mBAEN,MAAM;;;;gBACN,MAAM;mBACN,MAAM;;;;;;;;;;WAGN,eAAe;;;+BAMN,UAAU,QAAE,oBAAoB,KAAG,IAAI;;+BA1F/B,0CAA0C"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js

@@ -90,7 +90,9 @@ const SCROLL_BOXES_PER_CASCADE = 3;
  * @property {number} take `brick_take`'s handle: the taken keys' first and count, and the cell dispatch
  *   at {@link BRICK_TAKE_CELL_DISPATCH}, a workgroup a taken cell. Bind it read-only and dispatch
  *   through it.
- * @property {number} staging `brick_staging`'s handle, `BRICK_STAGING_WORDS` words a build slot
+ * @property {number} staging `brick_staging`'s handle, `BRICK_STAGING_WORDS` words a build slot. A provider
+ *   that could not finish a cell sets its `BRICK_STAGING_RETRY_WORD`, and the cell is built again (§7.6, contract 7)
+ * @property {number} staging_capacity build slots the staging holds: at least the frame's taken cells
  * @property {GPUBuffer} ring the keys; taken key `b` sits at `(taken_first + b) & (ring_capacity - 1)`
  * @property {number} ring_capacity
  * @property {number} resolution cells a cascade's window has a side
@@ -278,6 +280,7 @@ export class GPUBrickClipmap {
         state: -1,
         take: -1,
         staging: -1,
+        staging_capacity: 0,
         ring: null,
         ring_capacity: 0,
         resolution: 0,
@@ -576,6 +579,7 @@ export class GPUBrickClipmap {
         context.state = take_data.state;
         context.take = take_data.take;
         context.staging = take_data.staging;
+        context.staging_capacity = this.#staging_cells;
         context.ring = this.#ring;
         context.ring_capacity = this.#ring_capacity;
         context.resolution = this.resolution;
@@ -609,6 +613,9 @@ export class GPUBrickClipmap {
                 } finally {
                     reference.release();
                 }
+            })
+            .catch(() => {
+                // a reading lost to a timeout or a lost device: the count runs on, and a later reading carries it
             });
 
         this.#fresh = false;

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap.d.ts

@@ -64,6 +64,18 @@ export const chunk_brick_clipmap: CodeChunk;
  * @type {CodeChunk}
  */
 export const chunk_brick_clipmap_enqueue: CodeChunk;
+/**
+ * Put a key that is still pending back on the ring: one taken this frame whose cell a provider asked
+ * for again (§7.6, contract 7). Its pending bit stays set, so no enqueue can add it a second time, and
+ * the ring still holds every key at most once.
+ *
+ * ```wgsl
+ * fn brick_clipmap_requeue_pending(key: u32, ring_capacity: u32)
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_requeue_pending: CodeChunk;
 import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_brick_clipmap.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_brick_clipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap.js"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,mCAFU,wBAAwB,CAE4F;AAE9H;;;;;GAKG;AACH,kCAFU,wBAAwB,CAEuE;AAEzG;;;;GAIG;AACH,kCAFU,wBAAwB,CAE6E;AAE/G;;;;GAIG;AACH,qCAFU,wBAAwB,CAEgG;AAElI;;;;GAIG;AACH,kCAFU,wBAAwB,CAE6E;AAE/G;;;;GAIG;AACH,qCAFU,wBAAwB,CAEmF;AAErH;;;;;;;;;;;;;;;;GAgBG;AACH,kCAFU,SAAS,CAmDhB;AAEH;;;;;;;;;;GAUG;AACH,0CAFU,SAAS,CAmBhB;yCAnKsC,sDAAsD;0BADrE,uCAAuC"}
+{"version":3,"file":"chunk_brick_clipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap.js"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,mCAFU,wBAAwB,CAE4F;AAE9H;;;;;GAKG;AACH,kCAFU,wBAAwB,CAEuE;AAEzG;;;;GAIG;AACH,kCAFU,wBAAwB,CAE6E;AAE/G;;;;GAIG;AACH,qCAFU,wBAAwB,CAEgG;AAElI;;;;GAIG;AACH,kCAFU,wBAAwB,CAE6E;AAE/G;;;;GAIG;AACH,qCAFU,wBAAwB,CAEmF;AAErH;;;;;;;;;;;;;;;;GAgBG;AACH,kCAFU,SAAS,CAoDhB;AAEH;;;;;;;;;;GAUG;AACH,0CAFU,SAAS,CAmBhB;AAMH;;;;;;;;;;GAUG;AACH,kDAFU,SAAS,CAYhB;yCAhMsC,sDAAsD;0BADrE,uCAAuC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap.js

@@ -12,6 +12,7 @@ import {
     BRICK_OBJECT_CELLS,
     BRICK_OBJECT_CELLS_PER_AXIS,
     BRICK_STAGING_DISTANCE_WORDS,
+    BRICK_STAGING_RETRY_WORD,
     BRICK_STAGING_WORDS,
     BRICK_STATE_FREE,
     BRICK_STATE_HEAD,
@@ -95,6 +96,7 @@ const BRICK_CLIPMAP_BAND_VOXELS = ${MESH_SDF_BAND_VOXELS}.0;
 const BRICK_OBJECT_CELLS = ${BRICK_OBJECT_CELLS}u;
 const BRICK_OBJECT_CELLS_PER_AXIS = ${BRICK_OBJECT_CELLS_PER_AXIS}u;
 const BRICK_STAGING_DISTANCE_WORDS = ${BRICK_STAGING_DISTANCE_WORDS}u;
+const BRICK_STAGING_RETRY_WORD = ${BRICK_STAGING_RETRY_WORD}u;
 const BRICK_STAGING_WORDS = ${BRICK_STAGING_WORDS}u;
 const BRICK_CELL_WORKGROUP_SIZE = ${BRICK_CELL_WORKGROUP_SIZE}u;
 const BRICK_THREAD_WORKGROUP_SIZE = ${BRICK_THREAD_WORKGROUP_SIZE}u;
@@ -167,3 +169,29 @@ fn brick_clipmap_enqueue(key: u32, ring_capacity: u32) {
 chunk_brick_clipmap_enqueue.requireResource(BRICK_STATE_RESOURCE);
 chunk_brick_clipmap_enqueue.requireResource(BRICK_RING_RESOURCE);
 chunk_brick_clipmap_enqueue.requireResource(BRICK_PENDING_RESOURCE);
+
+/**
+ * Put a key that is still pending back on the ring: one taken this frame whose cell a provider asked
+ * for again (§7.6, contract 7). Its pending bit stays set, so no enqueue can add it a second time, and
+ * the ring still holds every key at most once.
+ *
+ * ```wgsl
+ * fn brick_clipmap_requeue_pending(key: u32, ring_capacity: u32)
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_requeue_pending = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_clipmap_requeue_pending(key: u32, ring_capacity: u32) {
+    let at = atomicAdd(&brick_state[BRICK_STATE_TAIL], 1u);
+
+    brick_ring[at & (ring_capacity - 1u)] = key;
+}
+`, [
+    chunk_brick_clipmap,
+]);
+
+chunk_brick_clipmap_requeue_pending.requireResource(BRICK_STATE_RESOURCE);
+chunk_brick_clipmap_requeue_pending.requireResource(BRICK_RING_RESOURCE);

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.d.ts

@@ -71,7 +71,7 @@ export const chunk_brick_clipmap_sample: CodeChunk;
 export const chunk_brick_clipmap_window: CodeChunk;
 /**
  * A step of a march through the brick clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.9): what the
- * tracer and the soft shadow both walk.
+ * tracer walks.
  *
  * ```wgsl
  * fn brick_clipmap_march(origin: vec3<f32>, direction: vec3<f32>, cascade_count: u32, march: ptr<function, BrickClipmapMarch>) -> u32
@@ -112,34 +112,6 @@ export const chunk_brick_clipmap_march: CodeChunk;
  * @type {CodeChunk}
  */
 export const chunk_brick_clipmap_trace: CodeChunk;
-/**
- * How much of a light's disk a point sees along a ray through the brick clipmap (§7.9), from 0 to 1.
- *
- * ```wgsl
- * fn brick_clipmap_soft_shadow(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, sin_angle: f32, cascade_count: u32) -> f32
- * ```
- *
- * `direction` is toward the light, unit length, and `sin_angle` the sine of the light's angular
- * radius (its `disk_radius`). The march is the tracer's (`brick_clipmap_march`), from `t_min`, at
- * most {@link BRICK_TRACE_STEPS} steps.
- *
- * The estimate is Quílez's two-sided penumbra. The light's edge is a cone about the ray, of radius
- * `t·sin θ`; in each brick the march reads the clearance, the field less the tracer's half-voxel
- * expand, so that a wall thinner than a voxel shadows as it is hit. The least of the clearance over the
- * cone's radius goes below zero inside the occluder:
- * - the march goes on into the occluder, half a voxel a step, until the least reaches -1, which is
- *   the light hidden whole;
- * - clamped to [-1, 1], it maps through `¼(1 + x)²(2 - x)` to the visible part, which is half at the
- *   shadow's geometric edge, as the analytic disk is. The classic, one-sided estimate reads 0 there.
- *
- * EMPTY inside hides the light whole. An EMPTY cell, or a block passed whole, is clear by at least a
- * voxel, wider than a sun's cone within its cascade's range, and the march reads nothing in it. A march
- * out of every window, or past `t_max`, sees what it has not found hidden; so does one that spends
- * its steps.
- *
- * @type {CodeChunk}
- */
-export const chunk_brick_clipmap_soft_shadow: CodeChunk;
 /**
  * The finest cascade's signed distance at a point (§7.9), for probe relocation.
  *

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_brick_clipmap_trace.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,gCAFU,MAAM,CAEwB;AAExC;;;GAGG;AACH,yCAFU,wBAAwB,CAEoE;AAEtG;;;GAGG;AACH,+CAFU,wBAAwB,CAEgF;AAElH;;;GAGG;AACH,2CAFU,wBAAwB,CAEyE;AAE3G;;;GAGG;AACH,qCAFU,wBAAwB,CAEqF;AAEvH;;;GAGG;AACH,oCAFU,wBAAwB,CAEyE;AAE3G;;;GAGG;AACH,qCAFU,wBAAwB,CAE6E;AAE/G;;;;;;;;;;;;;GAaG;AACH,yCAFU,SAAS,CAoCZ;AAKP;;;;;;;;;;;;GAYG;AACH,yCAFU,SAAS,CAyBZ;AAIP;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wCAFU,SAAS,CAgFZ;AAKP;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCAFU,SAAS,CAoGZ;AAEP;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8CAFU,SAAS,CA8CZ;AAEP;;;;;;;;;;;;GAYG;AACH,2CAFU,SAAS,CAsCZ;AAIP;;;;;;;;;;;;;;GAcG;AACH,2CAFU,SAAS,CA0BZ;AAEP;;;;;;;;;;;;;;GAcG;AACH,yCAFU,SAAS,CAqBZ;yCArkBkC,sDAAsD;0BADrE,uCAAuC"}
+{"version":3,"file":"chunk_brick_clipmap_trace.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,gCAFU,MAAM,CAEwB;AAExC;;;GAGG;AACH,yCAFU,wBAAwB,CAEoE;AAEtG;;;GAGG;AACH,+CAFU,wBAAwB,CAEgF;AAElH;;;GAGG;AACH,2CAFU,wBAAwB,CAEyE;AAE3G;;;GAGG;AACH,qCAFU,wBAAwB,CAEqF;AAEvH;;;GAGG;AACH,oCAFU,wBAAwB,CAEyE;AAE3G;;;GAGG;AACH,qCAFU,wBAAwB,CAE6E;AAE/G;;;;;;;;;;;;;GAaG;AACH,yCAFU,SAAS,CAoCZ;AAKP;;;;;;;;;;;;GAYG;AACH,yCAFU,SAAS,CAyBZ;AAIP;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wCAFU,SAAS,CAgFZ;AAKP;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCAFU,SAAS,CAoGZ;AAEP;;;;;;;;;;;;GAYG;AACH,2CAFU,SAAS,CAsCZ;AAIP;;;;;;;;;;;;;;GAcG;AACH,2CAFU,SAAS,CA0BZ;AAEP;;;;;;;;;;;;;;GAcG;AACH,yCAFU,SAAS,CAqBZ;yCA5fkC,sDAAsD;0BADrE,uCAAuC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.js

@@ -161,7 +161,7 @@ chunk_brick_clipmap_window.requireResource(BRICK_LEVELS_RESOURCE);
 
 /**
  * A step of a march through the brick clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.9): what the
- * tracer and the soft shadow both walk.
+ * tracer walks.
  *
  * ```wgsl
  * fn brick_clipmap_march(origin: vec3<f32>, direction: vec3<f32>, cascade_count: u32, march: ptr<function, BrickClipmapMarch>) -> u32
@@ -383,79 +383,6 @@ fn brick_clipmap_trace(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_ma
         chunk_brick_clipmap_march,
     ]);
 
-/**
- * How much of a light's disk a point sees along a ray through the brick clipmap (§7.9), from 0 to 1.
- *
- * ```wgsl
- * fn brick_clipmap_soft_shadow(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, sin_angle: f32, cascade_count: u32) -> f32
- * ```
- *
- * `direction` is toward the light, unit length, and `sin_angle` the sine of the light's angular
- * radius (its `disk_radius`). The march is the tracer's (`brick_clipmap_march`), from `t_min`, at
- * most {@link BRICK_TRACE_STEPS} steps.
- *
- * The estimate is Quílez's two-sided penumbra. The light's edge is a cone about the ray, of radius
- * `t·sin θ`; in each brick the march reads the clearance, the field less the tracer's half-voxel
- * expand, so that a wall thinner than a voxel shadows as it is hit. The least of the clearance over the
- * cone's radius goes below zero inside the occluder:
- * - the march goes on into the occluder, half a voxel a step, until the least reaches -1, which is
- *   the light hidden whole;
- * - clamped to [-1, 1], it maps through `¼(1 + x)²(2 - x)` to the visible part, which is half at the
- *   shadow's geometric edge, as the analytic disk is. The classic, one-sided estimate reads 0 there.
- *
- * EMPTY inside hides the light whole. An EMPTY cell, or a block passed whole, is clear by at least a
- * voxel, wider than a sun's cone within its cascade's range, and the march reads nothing in it. A march
- * out of every window, or past `t_max`, sees what it has not found hidden; so does one that spends
- * its steps.
- *
- * @type {CodeChunk}
- */
-export const chunk_brick_clipmap_soft_shadow = CodeChunk.from(
-    //language=WGSL
-    `
-fn brick_clipmap_soft_shadow(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, sin_angle: f32, cascade_count: u32) -> f32 {
-    var march: BrickClipmapMarch;
-
-    march.t = t_min;
-    march.cascade = brick_clipmap_start(origin + t_min * direction, cascade_count);
-
-    // the least clearance over the cone's radius, the light's edge
-    var least = 1.0;
-
-    for (var step = 0u; step < ${BRICK_TRACE_STEPS}u && march.cascade < cascade_count && march.t <= t_max; step++) {
-        let stood = brick_clipmap_march(origin, direction, cascade_count, &march);
-
-        if (stood != BRICK_MARCH_CELL) {
-            continue;
-        }
-
-        if (march.entry == BRICK_CLIPMAP_EMPTY_INSIDE) {
-            return 0.0;
-        }
-
-        let distance = brick_clipmap_sample(march.entry, (march.position - march.cell_min) / march.voxel, march.voxel);
-
-        least = min(least, (distance - 0.5 * march.voxel) / (march.t * sin_angle));
-
-        if (least <= -1.0) {
-            return 0.0;
-        }
-
-        // inside the occluder the field gives no step: half a voxel, the tracer's least
-        march.t += max(distance, 0.5 * march.voxel);
-    }
-
-    let x = clamp(least, -1.0, 1.0);
-
-    return 0.25 * (1.0 + x) * (1.0 + x) * (2.0 - x);
-}
-`, [
-        chunk_brick_clipmap,
-        chunk_brick_clipmap_sample,
-        chunk_brick_clipmap_window,
-        chunk_brick_clipmap_march,
-    ]);
-
 /**
  * The finest cascade's signed distance at a point (§7.9), for probe relocation.
  *

package/src/shade/renderer/global_illumination/probe_clipmap/brick/{mesh/chunk_mesh_brick_object.d.ts → chunk_brick_object.d.ts}

@@ -1,12 +1,12 @@
 /**
- * A world texel's byte and a texel's bid to be its object cell's object
+ * A world texel's byte and a texel's bid to be its object cell's object, the same for every provider
  * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.2, §7.6):
  *
  * ```wgsl
- * fn mesh_brick_encode(distance: f32, band: f32) -> u32     // saturate(d / 2R + 0.5), in a byte
- * fn mesh_brick_object_key(byte: u32, row: u32) -> u32      // larger for a nearer texel
- * fn mesh_brick_object_key_byte(key: u32) -> u32
- * fn mesh_brick_object_key_row(key: u32) -> u32
+ * fn brick_encode(distance: f32, band: f32) -> u32     // saturate(d / 2R + 0.5), in a byte
+ * fn brick_object_key(byte: u32, row: u32) -> u32      // larger for a nearer texel
+ * fn brick_object_key_byte(key: u32) -> u32
+ * fn brick_object_key_row(key: u32) -> u32
  * ```
  *
  * A key is the complement of the byte in its high eight bits and the row in its low 24, so the
@@ -16,6 +16,6 @@
  *
  * @type {CodeChunk}
  */
-export const chunk_mesh_brick_object: CodeChunk;
-import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
-//# sourceMappingURL=chunk_mesh_brick_object.d.ts.map
+export const chunk_brick_object: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_brick_object.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_brick_object.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_object.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,iCAFU,SAAS,CAsBhB;0BAzCuB,uCAAuC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_object.js

@@ -0,0 +1,42 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { BRICK_OBJECT_ROW_LIMIT } from "./BRICK_CLIPMAP.js";
+
+/**
+ * A world texel's byte and a texel's bid to be its object cell's object, the same for every provider
+ * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.2, §7.6):
+ *
+ * ```wgsl
+ * fn brick_encode(distance: f32, band: f32) -> u32     // saturate(d / 2R + 0.5), in a byte
+ * fn brick_object_key(byte: u32, row: u32) -> u32      // larger for a nearer texel
+ * fn brick_object_key_byte(key: u32) -> u32
+ * fn brick_object_key_row(key: u32) -> u32
+ * ```
+ *
+ * A key is the complement of the byte in its high eight bits and the row in its low 24, so the
+ * largest of a cell's keys, which workgroup atomics can take, is its nearest texel, and among equally
+ * near ones the lowest row: the same object whatever order the lanes ran in. A row past the 24 bits
+ * cannot be named and bids as row 0, no object.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_object = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_encode(distance: f32, band: f32) -> u32 {
+    return u32(round(saturate(distance / (2.0 * band) + 0.5) * 255.0));
+}
+
+fn brick_object_key(byte: u32, row: u32) -> u32 {
+    let named = select(0u, row, row < ${BRICK_OBJECT_ROW_LIMIT}u);
+
+    return ~((byte << 24u) | named);
+}
+
+fn brick_object_key_byte(key: u32) -> u32 {
+    return (~key) >> 24u;
+}
+
+fn brick_object_key_row(key: u32) -> u32 {
+    return (~key) & ${BRICK_OBJECT_ROW_LIMIT - 1}u;
+}
+`);

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_provider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A brick provider's resolution cull (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7), which reads nothing:
+ *
+ * ```wgsl
+ * fn brick_provider_resolves(bounds: array<f32, 6>, voxel: f32) -> bool
+ * ```
+ *
+ * An instance whose world box is under half a voxel across is out of the cascade, emissive or not. The ½-voxel
+ * hit would make it a lamp a voxel wide, 4 m at cascade 5.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_provider_resolves: CodeChunk;
+/**
+ * A taken cell's key's cell in the world (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.6), the same for every provider:
+ *
+ * ```wgsl
+ * fn brick_provider_cell(key: u32, resolution: u32) -> BrickProviderCell
+ * ```
+ *
+ * Its cascade, its lattice cell (the window's one congruent to the storage cell), the cascade's voxel and the band
+ * of the field's encoding in world units, and the cell's box, texel 0 at its corner (§7.2).
+ *
+ * Requires the importing shader to declare `brick_levels`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_provider_cell: CodeChunk;
+/**
+ * What a brick provider (§7.6) reads of a taken cell, the same for every provider:
+ *
+ * ```wgsl
+ * fn brick_provider_key(build: u32, ring_capacity: u32) -> u32
+ * ```
+ *
+ * Taken cell `build`'s key, whose cell {@link chunk_brick_provider_cell} places. The resolution cull comes with it
+ * ({@link chunk_brick_provider_resolves}).
+ *
+ * Requires the importing shader to declare `brick_take`, `brick_ring` and `brick_levels`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_provider: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_brick_provider.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_brick_provider.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_provider.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,4CAFU,SAAS,CAUhB;AAEH;;;;;;;;;;;;;GAaG;AACH,wCAFU,SAAS,CA+BsB;AAEzC;;;;;;;;;;;;;GAaG;AACH,mCAFU,SAAS,CAQiE;0BA1F1D,uCAAuC"}