@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -0,0 +1,93 @@
+import { MESH_SDF_BAND_VOXELS, MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
+import { chunk_mod_v3i } from "../../../shader/chunk/geometry/vec3/chunk_mod_v3i.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_brick_clipmap } from "./chunk_brick_clipmap.js";
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+fn brick_provider_resolves(bounds: array<f32, 6>, voxel: f32) -> bool {
+    let diagonal = length(vec3<f32>(bounds[3] - bounds[0], bounds[4] - bounds[1], bounds[5] - bounds[2]));
+
+    return !(diagonal < 0.5 * voxel);
+}
+`);
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+struct BrickProviderCell {
+    cascade: u32,
+    cell: vec3<i32>,
+    voxel: f32,
+    band: f32,
+    corner: vec3<f32>,
+    far: vec3<f32>,
+}
+
+fn brick_provider_cell(key: u32, resolution: u32) -> BrickProviderCell {
+    let cascade = brick_clipmap_key_cascade(key, resolution);
+    let level = brick_levels[cascade];
+
+    var out: BrickProviderCell;
+
+    out.cascade = cascade;
+    // the world cell the storage cell holds: the window's one congruent to it
+    out.cell = level.corner + mod_v3i(vec3<i32>(brick_clipmap_key_storage(key, resolution)) - level.corner, vec3<i32>(i32(resolution)));
+    out.voxel = level.cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+    out.band = ${MESH_SDF_BAND_VOXELS}.0 * out.voxel;
+    // texel 0, at voxel 7·cell of the cascade (§7.2)
+    out.corner = vec3<f32>(out.cell) * level.cell_size;
+    out.far = out.corner + vec3<f32>(level.cell_size);
+
+    return out;
+}
+`, [chunk_brick_clipmap, chunk_mod_v3i]);
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+fn brick_provider_key(build: u32, ring_capacity: u32) -> u32 {
+    return brick_ring[(brick_take[BRICK_TAKE_FIRST] + build) & (ring_capacity - 1u)];
+}
+`, [chunk_brick_clipmap, chunk_brick_provider_cell, chunk_brick_provider_resolves]);

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Entries a record holds, and instances a batch samples at once: a lane each.
+ * @type {number}
+ */
+export const MESH_BRICK_BATCH: number;
+/**
+ * Nodes a walk keeps on a level of its frontier; the rest are handed on to the next round. Eight
+ * nodes a lane a level at most.
+ *
+ * Measured on Zorah's TLAS (12,608 leaves, 27 levels deep), the widest level of a cell's walk is
+ * 758 nodes at cascade 2 and 2,410 at cascade 5; at this frontier and tasks of
+ * {@link MESH_BRICK_BATCH} nodes every walk ends in its third round. The frontier is 4 KiB of the
+ * walk's 5.1 KiB of workgroup memory, and the iGPU's walk is bound by how many workgroups that memory
+ * lets in: against 1,024 nodes, which ended every walk in its second round, the walks of a full
+ * rebuild of Zorah's windows went from 71.1 to 43.0 ms there, and stayed even on the 4090.
+ * @type {number}
+ */
+export const MESH_BRICK_FRONTIER: number;
+/**
+ * Words of a record's header: its build slot, then how many entries it holds.
+ * @type {number}
+ */
+export const MESH_BRICK_RECORD_HEADER_WORDS: number;
+/**
+ * Words of a task or batch record.
+ * @type {number}
+ */
+export const MESH_BRICK_RECORD_WORDS: number;
+/**
+ * Rounds of walks the provider starts with: the walk from the root, and one for what it hands on.
+ * @type {number}
+ */
+export const MESH_BRICK_ROUNDS: number;
+/**
+ * Rounds a walk of a TLAS over at most 2^20 leaves can need. A task starts from at most
+ * {@link MESH_BRICK_BATCH} nodes and hands on only past {@link MESH_BRICK_FRONTIER}, eight times as
+ * many, so a chain of k rounds needs a level 64·8^(k-1) nodes wide; 2^20 leaves allow k = 6.
+ * @type {number}
+ */
+export const MESH_BRICK_ROUND_LIMIT: number;
+/**
+ * The first of a build slot's object words.
+ * @type {number}
+ */
+export const MESH_BRICK_ACCUMULATOR_OBJECTS: number;
+/**
+ * The word of the cell's flags for the frame, {@link MESH_BRICK_FLAG_TOUCHED} and
+ * {@link MESH_BRICK_FLAG_UNFINISHED}. The walk that sets the first of them lists the cell for the
+ * resolve: most taken cells set none, and the resolve never reads them.
+ * @type {number}
+ */
+export const MESH_BRICK_ACCUMULATOR_FLAGS: number;
+/**
+ * Words of a build slot's accumulators.
+ * @type {number}
+ */
+export const MESH_BRICK_ACCUMULATOR_WORDS: number;
+/**
+ * A batch of the cell was made: the resolve merges its texel and object words.
+ * @type {number}
+ */
+export const MESH_BRICK_FLAG_TOUCHED: number;
+/**
+ * A walk of the cell did not finish: a record it could not take, a level past the walk's budget, or
+ * nodes past the frontier in the last round. The resolve asks for the cell again
+ * (`BRICK_STAGING_RETRY_WORD`).
+ * @type {number}
+ */
+export const MESH_BRICK_FLAG_UNFINISHED: number;
+/**
+ * Batch records the walks asked for, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_BATCHES: number;
+/**
+ * Batch records asked for past the capacity, ever: their rows were not sampled, and their cells asked for again.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_BATCHES_DROPPED: number;
+/**
+ * Task records the walks asked for, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_TASKS: number;
+/**
+ * Task records asked for past the capacity, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_TASKS_DROPPED: number;
+/**
+ * Times a walk of the last round had nodes past its frontier, ever: the host adds a round.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_ROUNDS_SHORT: number;
+/**
+ * Times a walk reached its level budget with nodes left, ever: a tree deeper than an LBVH builds.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_LEVELS_SHORT: number;
+/**
+ * Cells asked for again because a walk of theirs did not finish, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_CELLS_RETRIED: number;
+/**
+ * The most batch records a frame asked for.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_BATCHES_PEAK: number;
+/**
+ * The most task records a round asked for.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_TASKS_PEAK: number;
+/**
+ * The most cells a frame listed for the resolve.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_RESOLVES_PEAK: number;
+/**
+ * Words of the statistics.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_WORDS: number;
+/**
+ * The frame's batch records asked for so far: the next one's index.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_BATCHES: number;
+/**
+ * Two words, the frame's task records asked for so far in each half of the task buffer. Round r reads
+ * half `(r - 1) & 1` and writes half `r & 1`; the walk from the root writes half 0.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_TASKS: number;
+/**
+ * Workgroups of the round being dispatched: its tasks, as many as the capacity holds.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_ROUND_GROUPS: number;
+/**
+ * Workgroups of the batch pass: the frame's batches, as many as the capacity holds.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_BATCH_GROUPS: number;
+/**
+ * The frame's cells listed for the resolve so far: the next one's place on `mesh_brick_resolves`.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_RESOLVES: number;
+/**
+ * Workgroups of the resolve: the frame's listed cells.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_RESOLVE_GROUPS: number;
+/**
+ * Words of the counters: the statistics, then the frame's counters.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_WORDS: number;
+//# sourceMappingURL=MESH_BRICK.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MESH_BRICK.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK.js"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,+BAFU,MAAM,CAE0C;AAE1D;;;;;;;;;;;GAWG;AACH,kCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,sCAFU,MAAM,CAEyE;AAEzF;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;;GAKG;AACH,qCAFU,MAAM,CAEiI;AAUjJ;;;GAGG;AACH,6CAFU,MAAM,CAEyD;AAEzE;;;;;GAKG;AACH,2CAFU,MAAM,CAEgF;AAEhG;;;GAGG;AACH,2CAFU,MAAM,CAE6D;AAE7E;;;GAGG;AACH,sCAFU,MAAM,CAEyB;AAEzC;;;;;GAKG;AACH,yCAFU,MAAM,CAE4B;AAO5C;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;GAGG;AACH,mDAFU,MAAM,CAEsC;AAEtD;;;GAGG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,iDAFU,MAAM,CAEoC;AAEpD;;;GAGG;AACH,gDAFU,MAAM,CAEmC;AAEnD;;;GAGG;AACH,gDAFU,MAAM,CAEmC;AAEnD;;;GAGG;AACH,iDAFU,MAAM,CAEoC;AAEpD;;;GAGG;AACH,gDAFU,MAAM,CAEmC;AAEnD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,iDAFU,MAAM,CAEoC;AAEpD;;;GAGG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,yCAFU,MAAM,CAEqD;AAErE;;;;GAIG;AACH,uCAFU,MAAM,CAEuD;AAEvE;;;GAGG;AACH,8CAFU,MAAM,CAE4D;AAE5E;;;GAGG;AACH,8CAFU,MAAM,CAEmE;AAEnF;;;GAGG;AACH,0CAFU,MAAM,CAE+D;AAE/E;;;GAGG;AACH,gDAFU,MAAM,CAEiE;AAEjF;;;GAGG;AACH,uCAFU,MAAM,CAE8D"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK.js

@@ -0,0 +1,219 @@
+import { MESH_SDF_BRICK_TEXEL_COUNT } from "../../../../geometry/sdf/MESH_SDF.js";
+import { BRICK_CELL_WORKGROUP_SIZE, BRICK_OBJECT_CELLS } from "../BRICK_CLIPMAP.js";
+
+/*
+ The mesh provider's device state (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9 built it).
+
+ A taken cell's instances are gathered whole by a walk of the TLAS (`shader_mesh_brick_gather`), a
+ workgroup a walk, and leave it in batch records of up to MESH_BRICK_BATCH rows. A walk keeps
+ MESH_BRICK_FRONTIER nodes a level and hands the nodes past them on in task records of up to
+ MESH_BRICK_BATCH nodes, each a walk of its own in the next round. Every batch is sampled by a
+ workgroup of its own (`shader_mesh_brick_batch`) and merged into its cell's accumulators by atomic
+ maxima; the accumulators are merged into the staging once a cell, for the cells a walk listed
+ (`shader_mesh_brick_resolve`).
+
+ A record, task or batch, is MESH_BRICK_RECORD_WORDS words: its build slot, how many entries it
+ holds, then the entries, TLAS nodes for a task and `meshes` rows for a batch.
+*/
+
+/**
+ * Entries a record holds, and instances a batch samples at once: a lane each.
+ * @type {number}
+ */
+export const MESH_BRICK_BATCH = BRICK_CELL_WORKGROUP_SIZE;
+
+/**
+ * Nodes a walk keeps on a level of its frontier; the rest are handed on to the next round. Eight
+ * nodes a lane a level at most.
+ *
+ * Measured on Zorah's TLAS (12,608 leaves, 27 levels deep), the widest level of a cell's walk is
+ * 758 nodes at cascade 2 and 2,410 at cascade 5; at this frontier and tasks of
+ * {@link MESH_BRICK_BATCH} nodes every walk ends in its third round. The frontier is 4 KiB of the
+ * walk's 5.1 KiB of workgroup memory, and the iGPU's walk is bound by how many workgroups that memory
+ * lets in: against 1,024 nodes, which ended every walk in its second round, the walks of a full
+ * rebuild of Zorah's windows went from 71.1 to 43.0 ms there, and stayed even on the 4090.
+ * @type {number}
+ */
+export const MESH_BRICK_FRONTIER = 512;
+
+/**
+ * Words of a record's header: its build slot, then how many entries it holds.
+ * @type {number}
+ */
+export const MESH_BRICK_RECORD_HEADER_WORDS = 2;
+
+/**
+ * Words of a task or batch record.
+ * @type {number}
+ */
+export const MESH_BRICK_RECORD_WORDS = MESH_BRICK_RECORD_HEADER_WORDS + MESH_BRICK_BATCH;
+
+/**
+ * Rounds of walks the provider starts with: the walk from the root, and one for what it hands on.
+ * @type {number}
+ */
+export const MESH_BRICK_ROUNDS = 2;
+
+/**
+ * Rounds a walk of a TLAS over at most 2^20 leaves can need. A task starts from at most
+ * {@link MESH_BRICK_BATCH} nodes and hands on only past {@link MESH_BRICK_FRONTIER}, eight times as
+ * many, so a chain of k rounds needs a level 64·8^(k-1) nodes wide; 2^20 leaves allow k = 6.
+ * @type {number}
+ */
+export const MESH_BRICK_ROUND_LIMIT = 1 + Math.ceil(Math.log2((1 << 20) / MESH_BRICK_BATCH) / Math.log2(MESH_BRICK_FRONTIER / MESH_BRICK_BATCH));
+
+/*
+ A build slot's accumulators, MESH_BRICK_ACCUMULATOR_WORDS words: a word a texel holding 255 less the
+ least byte the batches staged there, a word an object cell holding the largest object key the
+ batches bid (`brick_object_key`), and the cell's flags for the frame. A texel or object word is 0
+ when nothing reached it, so a buffer the device has zeroed starts empty, and the resolve leaves each
+ one it merges at 0 for the next frame; the cell's walk from the root clears the flags.
+*/
+
+/**
+ * The first of a build slot's object words.
+ * @type {number}
+ */
+export const MESH_BRICK_ACCUMULATOR_OBJECTS = MESH_SDF_BRICK_TEXEL_COUNT;
+
+/**
+ * The word of the cell's flags for the frame, {@link MESH_BRICK_FLAG_TOUCHED} and
+ * {@link MESH_BRICK_FLAG_UNFINISHED}. The walk that sets the first of them lists the cell for the
+ * resolve: most taken cells set none, and the resolve never reads them.
+ * @type {number}
+ */
+export const MESH_BRICK_ACCUMULATOR_FLAGS = MESH_BRICK_ACCUMULATOR_OBJECTS + BRICK_OBJECT_CELLS;
+
+/**
+ * Words of a build slot's accumulators.
+ * @type {number}
+ */
+export const MESH_BRICK_ACCUMULATOR_WORDS = MESH_BRICK_ACCUMULATOR_FLAGS + 1;
+
+/**
+ * A batch of the cell was made: the resolve merges its texel and object words.
+ * @type {number}
+ */
+export const MESH_BRICK_FLAG_TOUCHED = 1;
+
+/**
+ * A walk of the cell did not finish: a record it could not take, a level past the walk's budget, or
+ * nodes past the frontier in the last round. The resolve asks for the cell again
+ * (`BRICK_STAGING_RETRY_WORD`).
+ * @type {number}
+ */
+export const MESH_BRICK_FLAG_UNFINISHED = 2;
+
+/*
+ The counters, `mesh_brick_counters`, every word an atomic. The statistics come first and accumulate
+ for the provider's life; the frame's counters after them are cleared at the start of every frame.
+*/
+
+/**
+ * Batch records the walks asked for, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_BATCHES = 0;
+
+/**
+ * Batch records asked for past the capacity, ever: their rows were not sampled, and their cells asked for again.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_BATCHES_DROPPED = 1;
+
+/**
+ * Task records the walks asked for, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_TASKS = 2;
+
+/**
+ * Task records asked for past the capacity, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_TASKS_DROPPED = 3;
+
+/**
+ * Times a walk of the last round had nodes past its frontier, ever: the host adds a round.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_ROUNDS_SHORT = 4;
+
+/**
+ * Times a walk reached its level budget with nodes left, ever: a tree deeper than an LBVH builds.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_LEVELS_SHORT = 5;
+
+/**
+ * Cells asked for again because a walk of theirs did not finish, ever.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_CELLS_RETRIED = 6;
+
+/**
+ * The most batch records a frame asked for.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_BATCHES_PEAK = 7;
+
+/**
+ * The most task records a round asked for.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_TASKS_PEAK = 8;
+
+/**
+ * The most cells a frame listed for the resolve.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_RESOLVES_PEAK = 9;
+
+/**
+ * Words of the statistics.
+ * @type {number}
+ */
+export const MESH_BRICK_STATISTIC_WORDS = 10;
+
+/**
+ * The frame's batch records asked for so far: the next one's index.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_BATCHES = MESH_BRICK_STATISTIC_WORDS;
+
+/**
+ * Two words, the frame's task records asked for so far in each half of the task buffer. Round r reads
+ * half `(r - 1) & 1` and writes half `r & 1`; the walk from the root writes half 0.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_TASKS = MESH_BRICK_COUNTER_BATCHES + 1;
+
+/**
+ * Workgroups of the round being dispatched: its tasks, as many as the capacity holds.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_ROUND_GROUPS = MESH_BRICK_COUNTER_TASKS + 2;
+
+/**
+ * Workgroups of the batch pass: the frame's batches, as many as the capacity holds.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_BATCH_GROUPS = MESH_BRICK_COUNTER_ROUND_GROUPS + 1;
+
+/**
+ * The frame's cells listed for the resolve so far: the next one's place on `mesh_brick_resolves`.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_RESOLVES = MESH_BRICK_COUNTER_BATCH_GROUPS + 1;
+
+/**
+ * Workgroups of the resolve: the frame's listed cells.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_RESOLVE_GROUPS = MESH_BRICK_COUNTER_RESOLVES + 1;
+
+/**
+ * Words of the counters: the statistics, then the frame's counters.
+ * @type {number}
+ */
+export const MESH_BRICK_COUNTER_WORDS = MESH_BRICK_COUNTER_RESOLVE_GROUPS + 1;

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK_INSTANCE_STRUCT.d.ts

@@ -1,19 +1,5 @@
 /**
- * Instances a cell's mesh provider samples at most (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7): the
- * rest are dropped and counted, and a dropped instance can leave a hole. Coarse cascades are where
- * it binds.
- * @type {number}
- */
-export const MESH_BRICK_INSTANCE_LIMIT: 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. A row past it writes no object, as
- * a provider that cannot name a row does (§7.6, contract 5).
- * @type {number}
- */
-export const MESH_BRICK_ROW_LIMIT: number;
-/**
- * An instance as the mesh provider samples it, made once a cell (§7.7):
+ * An instance as the mesh provider samples it, made once a batch (§7.7):
  * - `to_local_0..2`: the rows of the inverse of the instance's `node.global`, from the world into the
  *   geometry's space;
  * - `box_min`, `box_max`: the row's world box, for the box test;

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

@@ -1 +1 @@
-{"version":3,"file":"MESH_BRICK_INSTANCE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK_INSTANCE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,mCAFU,MAAM,CAE4B;AAE5C;;;;;;;;;;;;GAYG;AACH,yCAFU,YAAY,CAYE;6BAzCK,yCAAyC"}
+{"version":3,"file":"MESH_BRICK_INSTANCE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK_INSTANCE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,yCAFU,YAAY,CAYE;6BAzBK,yCAAyC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK_INSTANCE_STRUCT.js

@@ -2,23 +2,7 @@ import { f32, u32, vec3f, vec4f } from "../../../../shader/type/WEBGPU_WGSL_PRIM
 import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
 
 /**
- * Instances a cell's mesh provider samples at most (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7): the
- * rest are dropped and counted, and a dropped instance can leave a hole. Coarse cascades are where
- * it binds.
- * @type {number}
- */
-export const MESH_BRICK_INSTANCE_LIMIT = 64;
-
-/**
- * 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. A row past it writes no object, as
- * a provider that cannot name a row does (§7.6, contract 5).
- * @type {number}
- */
-export const MESH_BRICK_ROW_LIMIT = 1 << 24;
-
-/**
- * An instance as the mesh provider samples it, made once a cell (§7.7):
+ * An instance as the mesh provider samples it, made once a batch (§7.7):
  * - `to_local_0..2`: the rows of the inverse of the instance's `node.global`, from the world into the
  *   geometry's space;
  * - `box_min`, `box_max`: the row's world box, for the box test;

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MeshSDFBrickProvider.d.ts

@@ -1,17 +1,26 @@
 /**
- * @typedef {import("../GPUBrickClipmap.js").BrickProviderContext} BrickProviderContext
- * @typedef {import("../../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
- */
-/**
- * The world's bricks from the meshes' cached fields (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7): a
- * {@link BrickProvider} like any plugin, registered first. Per taken cell, the instances in the SDF
- * world whose boxes reach it, each sampled at the level of its field that suits the cascade, merged
- * into the staging by the minimum of the bytes, with the nearest instance's row as each 2³ cell's
- * object.
+ * The world's bricks from the meshes' cached fields (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9
+ * built it): a {@link BrickProvider} like any plugin, registered first. Every instance in the SDF world
+ * whose box comes within the band of a taken cell is sampled there, at the level of its field that
+ * suits the cascade, however many reach the cell.
+ *
+ * A frame is one pass of dispatches, every one sized by a count on the device:
+ * - **walks** (`shader_mesh_brick_gather`), {@link rounds} of them: the taken cells' TLAS walks from the
+ *   root, a workgroup a cell, then the walks of what each round handed on;
+ * - **batches** (`shader_mesh_brick_batch`): a workgroup a batch of up to 64 rows the walks found,
+ *   merged into the cell's accumulators by atomic maxima;
+ * - **resolve** (`shader_mesh_brick_resolve`): a workgroup a cell the walks listed, one a batch reached
+ *   or a walk of which did not finish, merging its accumulators into the staging by the provider
+ *   contract (§7.6), and asking again for a cell whose walk did not finish. Most taken cells have no
+ *   instance near them, and are not listed;
+ * - **commands** (`shader_mesh_brick_command`), a thread before each dispatch but the walks from the
+ *   root: what the passes before it asked for, as its dispatch.
  *
- * It reads the view's scene through the context: the TLAS over the mesh rows, the scene database and
- * the geometry caches. A cell's instances past {@link MESH_BRICK_INSTANCE_LIMIT} are dropped; they and
- * whatever the gather itself dropped are counted in {@link statistics}.
+ * What the device asked for past a capacity, and walks the last round could not finish, are counted in
+ * {@link statistics}. The counts are read back each frame, and a later frame grows what held work back:
+ * a buffer to the power of two at or past the most asked for, the rounds by one up to
+ * {@link MESH_BRICK_ROUND_LIMIT}. The cells that lost work are asked for again meanwhile, so nothing is
+ * lost for longer than the growth takes.
  */
 export class MeshSDFBrickProvider {
     /**
@@ -19,9 +28,28 @@ export class MeshSDFBrickProvider {
      */
     constructor(device: GPUDevice);
     /**
+     * Counts that accumulate for the provider's life, {@link MESH_BRICK_STATISTIC_WORDS} words at the start
+     * of the buffer (`MESH_BRICK.js`): the records asked for and the ones past a capacity, walks left
+     * unfinished, cells asked for again, the most records a frame and a round asked for, and the most
+     * cells a frame listed for the resolve.
      * @returns {GPUBuffer}
      */
     get statistics(): GPUBuffer;
+    /**
+     * Rounds of walks a frame runs: two at first, one more each time the last round could not finish a walk.
+     * @returns {number}
+     */
+    get rounds(): number;
+    /**
+     * Task records a half of the task buffer holds.
+     * @returns {number}
+     */
+    get task_capacity(): number;
+    /**
+     * Batch records a frame can sample.
+     * @returns {number}
+     */
+    get batch_capacity(): number;
     /**
      * @param {FrameGraph} graph
      * @param {BrickProviderContext} context

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

@@ -1 +1 @@
-{"version":3,"file":"MeshSDFBrickProvider.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MeshSDFBrickProvider.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH;IAuBI;;OAEG;IACH,+BAUC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,0BAHW,UAAU,WACV,oBAAoB,QAgB9B;IA+BD,gBAOC;;CACJ;mCArHY,OAAO,uBAAuB,EAAE,oBAAoB;yBACpD,OAAO,oEAAoE,EAAE,UAAU"}
+{"version":3,"file":"MeshSDFBrickProvider.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MeshSDFBrickProvider.js"],"names":[],"mappings":"AA0DA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAyDI;;OAEG;IACH,+BAmBC;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;OAGG;IACH,qBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,0BAHW,UAAU,WACV,oBAAoB,QAsC9B;IAsND,gBAYC;;CACJ;mCA/aY,OAAO,uBAAuB,EAAE,oBAAoB;yBACpD,OAAO,oEAAoE,EAAE,UAAU"}