@woosh/meep-engine 3.56.0 → 3.58.0

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace.js

@@ -0,0 +1,203 @@
+import { MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
+import { LIGHT_DATA_RESOURCE } from "../../../light/LIGHT_DATA_RESOURCE.js";
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { LIGHT_FLAGS } from "../../../light/model/io/LIGHT_FLAGS.js";
+import { chunk_uv_octahedral_unit_decode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
+import { chunk_uv_octahedral_unit_encode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_encode.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_directional_lights_iteration_mask } from "../../../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
+import { chunk_stbn_sample_vec2 } from "../../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import { chunk_hash_lowbias32 } from "../../../shader/chunk/random/chunk_hash_lowbias32.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import {
+    BRICK_ATLAS_TEXTURE_RESOURCE,
+    BRICK_LEVELS_RESOURCE,
+    BRICK_MAP_TEXTURE_RESOURCE,
+    BRICK_OBJECTS_RESOURCE,
+    BRICK_OCCUPANCY_TEXTURE_RESOURCE,
+    BRICK_SAMPLER_RESOURCE,
+    chunk_brick_clipmap_object,
+    chunk_brick_clipmap_soft_shadow,
+    chunk_brick_clipmap_trace
+} from "../brick/chunk_brick_clipmap_trace.js";
+import {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_ray_texel,
+    PROBE_ORIGINS_READ_RESOURCE,
+    PROBE_RAYS_WRITE_RESOURCE,
+    PROBE_STATES_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_SHADOWED_SUNS, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+const DIRECTIONAL = LIGHT_DATABASE_SPEC.get('light_directional');
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_TRACE_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** rays an update casts, R, a power of two */
+    rays_per_probe: u32,
+    /** octahedral radiance texels a side, n_r, a power of two */
+    radiance_resolution: u32,
+    /** the brick clipmap's cascades */
+    brick_cascade_count: u32,
+    /** how far a ray goes before it is a miss, metres: across the coarsest window */
+    t_max: f32,
+}, "ProbeTraceSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_TRACE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_ORIGINS_READ_RESOURCE)
+    .add(PROBE_RAYS_WRITE_RESOURCE)
+    .add(STBN_VEC2_RESOURCE)
+    .add(LIGHT_DATA_RESOURCE);
+
+resources.createGroup()
+    .add(BRICK_LEVELS_RESOURCE)
+    .add(BRICK_MAP_TEXTURE_RESOURCE)
+    .add(BRICK_OCCUPANCY_TEXTURE_RESOURCE)
+    .add(BRICK_ATLAS_TEXTURE_RESOURCE)
+    .add(BRICK_SAMPLER_RESOURCE)
+    .add(BRICK_OBJECTS_RESOURCE);
+
+/**
+ * Trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a ray of the frame's updates, R a listed
+ * probe, dispatched through `PROBE_DISPATCH_RAYS`.
+ *
+ * - **Texel**: `probe_clipmap_ray_texel`, all of them an update, or a spread subset below R = n_r².
+ * - **Direction**: the texel's octahedral square, jittered by STBN at the texel, moved by the slot's
+ *   hash so that neighbouring probes do not jitter alike, and at the update count: one stratified,
+ *   jittered ray a texel, LPV's own pattern.
+ * - **Origin**: the probe where relocation left it, `probe_origins`; t_min one voxel of the brick
+ *   cascade there.
+ * - **Direct light**: a hit off a front face takes E_dir = Σ colour·max(0, n·l)·visibility over the
+ *   directional lights (§8.7). The visibility is the brick clipmap's soft shadow toward each of the
+ *   first {@link PROBE_SHADOWED_SUNS} lights that cast shadows, in the table's order, from a voxel off
+ *   the hit along its normal, outside the half-voxel expand; lights past them are unshadowed at hits. A
+ *   surface turned from a light marches no shadow toward it, since the light gives it nothing.
+ *   - Measured on Sponza at 1280×720 with 131,072 rays, the shadows are about half of the pass on the
+ *     AMD iGPU (7.9 ms against 4.2 without them) and most of it on the RTX 4090 (355 µs against 62). Most
+ *     hits are on walls nearly parallel to a high sun, whose shadow rays graze them.
+ * - **Back face**: a hit whose field's gradient is along the ray, so it came from inside a solid.
+ *
+ * Writes the ray's `PROBE_RAY_STRUCT`, with the `meshes` row of the hit's surface and E_dir as its
+ * light, which shade turns into the ray's radiance.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_trace = ComputeShader.from({
+    label: "Probe Clipmap Trace",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let ray = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+    let rays = settings.rays_per_probe;
+
+    if (ray >= min(probe_trace.count, settings.trace_capacity) * rays) {
+        return;
+    }
+
+    let slot = probe_trace.elements[ray / rays];
+    let i = ray % rays;
+
+    let n = settings.radiance_resolution;
+    let texels = n * n;
+    let state = probe_states[slot];
+    let updates = probe_state_updates(state.x);
+
+    let texel = probe_clipmap_ray_texel(i, updates, rays, texels);
+    let round = select(0u, i / texels, rays >= texels);
+    let per_texel = max(rays / texels, 1u);
+
+    let scramble = hash_lowbias32(slot);
+    let noise_xy = vec2<u32>(texel % n, texel / n) + vec2<u32>(scramble & 127u, (scramble >> 7u) & 127u);
+    let jitter = stbn_sample_vec2(vec3<u32>(noise_xy, updates * per_texel + round));
+
+    let direction = uv_octahedral_unit_decode((vec2<f32>(f32(texel % n), f32(texel / n)) + jitter) / f32(n));
+
+    let origin = probe_origins[ray / rays].xyz;
+
+    let cascade_count = settings.brick_cascade_count;
+    let start = brick_clipmap_start(origin, cascade_count);
+    let t_min = brick_levels[min(start, cascade_count - 1u)].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+
+    let hit = brick_clipmap_trace(origin, direction, t_min, settings.t_max, cascade_count);
+
+    let is_hit = hit.kind == BRICK_TRACE_HIT;
+    let back_face = is_hit && dot(hit.normal, direction) > 0.0;
+
+    var direct = vec3<f32>(0.0);
+
+    if (is_hit && !back_face) {
+        let voxel = brick_levels[hit.cascade].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+        let lifted = hit.position + voxel * hit.normal;
+
+        var bits = directional_lights_iteration_mask(&light_data);
+        var shadowed = 0u;
+
+        while (bits != 0u) {
+            let index = countTrailingZeros(bits);
+
+            bits &= ~(1u << index);
+
+            let light = ${DIRECTIONAL.marshalling_method_read}(&light_data, index);
+            let n_dot_l = dot(hit.normal, -light.direction);
+
+            var visible = 1.0;
+
+            if ((light.flags & ${LIGHT_FLAGS.CASTS_SHADOW_BIT}u) != 0u && shadowed < ${PROBE_SHADOWED_SUNS}u) {
+                // a surface turned from the light takes none of it whatever the shadow, so it marches none;
+                // the light keeps its place among the shadowed all the same
+                if (n_dot_l > 0.0) {
+                    visible = brick_clipmap_soft_shadow(lifted, -light.direction, 0.0, settings.t_max, sin(light.disk_radius), cascade_count);
+                }
+
+                shadowed++;
+            }
+
+            direct += light.color * max(n_dot_l, 0.0) * visible;
+        }
+    }
+
+    probe_rays[ray].t = hit.t;
+    probe_rays[ray].direction = pack2x16unorm(uv_octahedral_unit_encode(direction));
+    probe_rays[ray].normal = select(0u, pack2x16unorm(uv_octahedral_unit_encode(hit.normal)), is_hit);
+    probe_rays[ray].row = brick_clipmap_object(hit);
+    probe_rays[ray].flags = hit.kind | select(0u, PROBE_RAY_BACK_FACE, back_face) | (select(0u, hit.cascade, is_hit) << PROBE_RAY_CASCADE_SHIFT);
+    probe_rays[ray].light_rg = pack2x16float(direct.rg);
+    probe_rays[ray].light_b = pack2x16float(vec2<f32>(direct.b, 0.0));
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_texel,
+            chunk_folded_workgroup_index,
+            chunk_hash_lowbias32,
+            chunk_stbn_sample_vec2,
+            chunk_uv_octahedral_unit_decode,
+            chunk_uv_octahedral_unit_encode,
+            chunk_brick_clipmap_trace,
+            chunk_brick_clipmap_object,
+            chunk_brick_clipmap_soft_shadow,
+            chunk_directional_lights_iteration_mask,
+            DIRECTIONAL.chunk_read,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_TRACE_COMMAND_SETTINGS: WebGPUStruct;
+/**
+ * The update's commands (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, once the due passes
+ * have listed the frame's updates, the list's count clamped to U:
+ * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation and the probes' projection;
+ * - a thread a ray of theirs, R a probe, at `PROBE_DISPATCH_RAYS`: trace and shade;
+ * - a thread a texel of their maps, n_r² + n_d² a probe, at `PROBE_DISPATCH_TEXELS`: accumulate;
+ * - a thread a row of their radiance maps, n_r a probe, at `PROBE_DISPATCH_ROWS`: the projection's rows;
+ * - a thread a texel of their tiles, (n_r + 2)² + (n_d + 2)² a probe, at `PROBE_DISPATCH_PUBLISH`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_trace_command: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_trace_command.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_trace_command.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.js"],"names":[],"mappings":"AAQA;;GAEG;AACH,2CAFU,YAAY,CAWU;AAUhC;;;;;;;;;;GAUG;AACH,iDAFU,aAAa,CAgDpB;6BAlF0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.js

@@ -0,0 +1,88 @@
+import { chunk_folded_dispatch } from "../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { chunk_probe_clipmap, PROBE_DISPATCH_RESOURCE, PROBE_TRACE_READ_RESOURCE } from "./chunk_probe_clipmap.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_TRACE_COMMAND_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** rays an update casts, R */
+    rays_per_probe: u32,
+    /** octahedral radiance texels a side, n_r */
+    radiance_resolution: u32,
+    /** octahedral depth texels a side, n_d */
+    depth_resolution: u32,
+}, "ProbeTraceCommandSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_TRACE_COMMAND_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_DISPATCH_RESOURCE);
+
+/**
+ * The update's commands (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, once the due passes
+ * have listed the frame's updates, the list's count clamped to U:
+ * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation and the probes' projection;
+ * - a thread a ray of theirs, R a probe, at `PROBE_DISPATCH_RAYS`: trace and shade;
+ * - a thread a texel of their maps, n_r² + n_d² a probe, at `PROBE_DISPATCH_TEXELS`: accumulate;
+ * - a thread a row of their radiance maps, n_r a probe, at `PROBE_DISPATCH_ROWS`: the projection's rows;
+ * - a thread a texel of their tiles, (n_r + 2)² + (n_d + 2)² a probe, at `PROBE_DISPATCH_PUBLISH`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_trace_command = ComputeShader.from({
+    label: "Probe Clipmap Trace Command",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let traced = min(probe_trace.count, settings.trace_capacity);
+    let probes = folded_dispatch((traced + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_TRACED] = probes.x;
+    probe_dispatch[PROBE_DISPATCH_TRACED + 1u] = probes.y;
+    probe_dispatch[PROBE_DISPATCH_TRACED + 2u] = probes.z;
+
+    let rays = folded_dispatch((traced * settings.rays_per_probe + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_RAYS] = rays.x;
+    probe_dispatch[PROBE_DISPATCH_RAYS + 1u] = rays.y;
+    probe_dispatch[PROBE_DISPATCH_RAYS + 2u] = rays.z;
+
+    let n = settings.radiance_resolution;
+    let m = settings.depth_resolution;
+
+    let texels = folded_dispatch((traced * (n * n + m * m) + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_TEXELS] = texels.x;
+    probe_dispatch[PROBE_DISPATCH_TEXELS + 1u] = texels.y;
+    probe_dispatch[PROBE_DISPATCH_TEXELS + 2u] = texels.z;
+
+    let rows = folded_dispatch((traced * n + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_ROWS] = rows.x;
+    probe_dispatch[PROBE_DISPATCH_ROWS + 1u] = rows.y;
+    probe_dispatch[PROBE_DISPATCH_ROWS + 2u] = rows.z;
+
+    let tiles = folded_dispatch((traced * ((n + 2u) * (n + 2u) + (m + 2u) * (m + 2u)) + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_PUBLISH] = tiles.x;
+    probe_dispatch[PROBE_DISPATCH_PUBLISH + 1u] = tiles.y;
+    probe_dispatch[PROBE_DISPATCH_PUBLISH + 2u] = tiles.z;
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_dispatch,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_WANT_SETTINGS: WebGPUStruct;
+/**
+ * Want (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a tile of {@link PROBE_WANT_TILE}² pixels,
+ * the launch the screen's tiles.
+ *
+ * Each frame a tile wants the probes of one of its pixels, picked by STBN at (tile, frame), the cages
+ * that pixel's pick reads (§9.1): the finest cascade whose cage window holds the point, the cage of
+ * the point biased `0.1` of that cascade's spacing along `mix(n, v, 0.2)`, and in the cascade's blend
+ * skirt the next cascade's cage too, biased by its own spacing. A sky pixel wants nothing; neither does
+ * a cage a bias moved out of its window. Each cage point's bit is set, and a point whose bit was clear
+ * goes on the wanted list, so the list holds every point wanted this frame once.
+ *
+ * At a cascade's outer edge a lattice cell is 58 pixels on a 1080p screen at a 60° field of view, and
+ * 19 at 120°, so a tile of 8 samples every cell several times a frame, and a workgroup's 64 tiles want
+ * a few cages between them. So the first lane of a workgroup to want a cage claims it in the
+ * workgroup's table and sets its bits; the rest want it through that lane. Measured on the AMD iGPU at
+ * 1280×720 on Sponza, the bits' atomics were 140 of want's 345 µs and the appends 90.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_want.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_want.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.js"],"names":[],"mappings":"AAoCA;;GAEG;AACH,kCAFU,YAAY,CAUE;AAexB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCAFU,aAAa,CAuHpB;6BAxL0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.js

@@ -0,0 +1,199 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_collection_u32_append } from "../../../gpu_primitive/chunk_collection_u32_append.js";
+import { chunk_project_position_from_depth } from "../../../shader/chunk/camera/chunk_project_position_from_depth.js";
+import { chunk_clipmap_contains } from "../../../shader/chunk/clipmap/chunk_clipmap_contains.js";
+import { chunk_clipmap_select_finest } from "../../../shader/chunk/clipmap/chunk_clipmap_select_finest.js";
+import { chunk_is_background } from "../../../shader/chunk/depth/chunk_is_background.js";
+import { chunk_mat4_extract_position } from "../../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
+import { chunk_decode_g_buffer_normal } from "../../../shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { chunk_stbn_sample_vec2 } from "../../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_WANTED_BITS_RESOURCE,
+    PROBE_WANTED_WRITE_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_RECEIVER_BIAS, PROBE_RECEIVER_BIAS_VIEW, PROBE_WANT_TILE, PROBE_WANT_WORKGROUP_TILES } from "./PROBE_CLIPMAP.js";
+
+/**
+ * Slots of a workgroup's claim table: twice the claims its lanes make at most, a cage in each of two
+ * cascades a lane, so a probe finds a slot within a few.
+ * @type {number}
+ */
+const WANT_CLAIM_SLOTS = 2 * 2 * PROBE_WANT_WORKGROUP_TILES ** 2;
+
+/**
+ * Slots a claim tries before it wants its cage anyway: a bound, which a half-full table does not reach.
+ * @type {number}
+ */
+const WANT_CLAIM_PROBES = 16;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_WANT_SETTINGS = WebGPUStruct.from({
+    cascade_count: u32,
+    /** lattice points a cascade's window has a side */
+    resolution: u32,
+    /** the frame's index, what the tile's pixel is picked by */
+    frame: u32,
+    /** keys over every cascade: what the wanted list holds at most */
+    key_count: u32,
+}, "ProbeWantSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_WANT_SETTINGS);
+
+resources.createGroup()
+    .addTexture("gBufferDepth")
+    .addTexture("gBufferNormals", "uint")
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .add(STBN_VEC2_RESOURCE)
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_WANTED_BITS_RESOURCE)
+    .add(PROBE_WANTED_WRITE_RESOURCE);
+
+/**
+ * Want (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a tile of {@link PROBE_WANT_TILE}² pixels,
+ * the launch the screen's tiles.
+ *
+ * Each frame a tile wants the probes of one of its pixels, picked by STBN at (tile, frame), the cages
+ * that pixel's pick reads (§9.1): the finest cascade whose cage window holds the point, the cage of
+ * the point biased `0.1` of that cascade's spacing along `mix(n, v, 0.2)`, and in the cascade's blend
+ * skirt the next cascade's cage too, biased by its own spacing. A sky pixel wants nothing; neither does
+ * a cage a bias moved out of its window. Each cage point's bit is set, and a point whose bit was clear
+ * goes on the wanted list, so the list holds every point wanted this frame once.
+ *
+ * At a cascade's outer edge a lattice cell is 58 pixels on a 1080p screen at a 60° field of view, and
+ * 19 at 120°, so a tile of 8 samples every cell several times a frame, and a workgroup's 64 tiles want
+ * a few cages between them. So the first lane of a workgroup to want a cage claims it in the
+ * workgroup's table and sets its bits; the rest want it through that lane. Measured on the AMD iGPU at
+ * 1280×720 on Sponza, the bits' atomics were 140 of want's 345 µs and the appends 90.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want = ComputeShader.from({
+    label: "Probe Clipmap Want",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+// the cages the workgroup's lanes have claimed, by their key plus one; zero at the workgroup's start
+var<workgroup> probe_want_claims: array<atomic<u32>, ${WANT_CLAIM_SLOTS}>;
+
+// the cell whose corners are the cascade's cage around a point biased by its spacing, and whether the
+// cascade's cage window holds it
+fn probe_want_cage(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>, cage: ptr<function, vec3<i32>>) -> bool {
+    let level = probe_levels[cascade];
+    let biased = position + bias_direction * (${PROBE_RECEIVER_BIAS} * level.cell_size);
+
+    *cage = vec3<i32>(floor(biased / level.cell_size));
+
+    return clipmap_contains(*cage, level.corner, level.size);
+}
+
+// whether this lane is the first of its workgroup to want the cage whose least point has \`key\`; a lane
+// that finds no room in its probes wants it as well, which the bits make harmless
+fn probe_want_claim(key: u32) -> bool {
+    let tag = key + 1u;
+
+    var at = (tag * 2654435761u) >> ${32 - Math.log2(WANT_CLAIM_SLOTS)}u;
+
+    for (var probe = 0u; probe < ${WANT_CLAIM_PROBES}u; probe++) {
+        let seen = atomicCompareExchangeWeak(&probe_want_claims[at], 0u, tag);
+
+        if (seen.exchanged) {
+            return true;
+        }
+
+        if (seen.old_value == tag) {
+            return false;
+        }
+
+        // another cage's slot: the next one; an empty slot that failed spuriously is tried again
+        if (seen.old_value != 0u) {
+            at = (at + 1u) & ${WANT_CLAIM_SLOTS - 1}u;
+        }
+    }
+
+    return true;
+}
+
+@compute @workgroup_size(${PROBE_WANT_WORKGROUP_TILES}, ${PROBE_WANT_WORKGROUP_TILES})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let size = textureDimensions(gBufferDepth);
+    let tiles = (size + ${PROBE_WANT_TILE - 1}u) / ${PROBE_WANT_TILE}u;
+    let tile = id.xy;
+
+    let jitter = stbn_sample_vec2(vec3<u32>(tile, settings.frame));
+    let pixel = min(tile * ${PROBE_WANT_TILE}u + vec2<u32>(jitter * ${PROBE_WANT_TILE}.0), size - 1u);
+
+    let on_screen = all(tile < tiles);
+    let depth = textureLoad(gBufferDepth, pixel, 0).r;
+
+    let uv = (vec2<f32>(pixel) + 0.5) / vec2<f32>(size);
+    let position = project_position_from_depth(uv, depth, camera.view_projection_matrix_inverse);
+    let normal = decode_g_buffer_normal(textureLoad(gBufferNormals, pixel, 0).xy);
+    let view_direction = normalize(mat4_extract_position(camera.transform) - position);
+    let bias_direction = mix(normal, view_direction, ${PROBE_RECEIVER_BIAS_VIEW});
+
+    let selection = clipmap_select_finest(&probe_levels, settings.cascade_count, position, PROBE_BLEND_SKIRT);
+
+    let surface = on_screen && !is_background(depth) && selection.level != CLIPMAP_LEVEL_NONE;
+    let finest = select(0u, selection.level, surface);
+    let next = min(finest + 1u, settings.cascade_count - 1u);
+
+    var cage_finest: vec3<i32>;
+    var cage_next: vec3<i32>;
+
+    let resolution = settings.resolution;
+
+    // storage wraps by the window's side, a power of two: the low bits of a point, negative ones too
+    let wrap = vec3<u32>(resolution - 1u);
+
+    let wants_finest = surface && probe_want_cage(finest, position, bias_direction, &cage_finest)
+        && probe_want_claim(probe_clipmap_key(finest, vec3<u32>(cage_finest) & wrap, resolution));
+    let wants_next = surface && selection.edge_weight > 0.0 && finest + 1u < settings.cascade_count
+        && probe_want_cage(next, position, bias_direction, &cage_next)
+        && probe_want_claim(probe_clipmap_key(next, vec3<u32>(cage_next) & wrap, resolution));
+
+    // every lane through all sixteen corners, so that the appends stay in uniform control flow
+    for (var k = 0u; k < 16u; k++) {
+        let coarse = k >= 8u;
+        let cascade = select(finest, next, coarse);
+        let wants = select(wants_finest, wants_next, coarse);
+        let corner = vec3<i32>(vec3<u32>(k & 1u, (k >> 1u) & 1u, (k >> 2u) & 1u));
+        let point = select(cage_finest, cage_next, coarse) + corner;
+
+        let storage = vec3<u32>(point) & wrap;
+        let key = probe_clipmap_key(cascade, storage, resolution);
+        let bit = 1u << (key & 31u);
+
+        var first = false;
+
+        if (wants) {
+            first = (atomicOr(&probe_wanted_bits[key >> 5u], bit) & bit) == 0u;
+        }
+
+        collection_u32_append(&probe_wanted, first, key, settings.key_count);
+    }
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_stbn_sample_vec2,
+            chunk_project_position_from_depth,
+            chunk_decode_g_buffer_normal,
+            chunk_mat4_extract_position,
+            chunk_is_background,
+            chunk_clipmap_select_finest,
+            chunk_clipmap_contains,
+            chunk_collection_u32_append,
+        ]),
+});

package/src/shade/renderer/gpu_primitive/indirect/chunk_folded_dispatch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The workgroup counts of an indirect dispatch of `groups` workgroups, folded as
+ * `IndirectComputeCommandBuildPass` folds them: x to
+ * {@link WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}, what is left of it in rows of x, and
+ * what is left of those in slices of x·y. A shader dispatched through it finds its workgroup with
+ * `folded_workgroup_index` and never reads `num_workgroups`.
+ *
+ * ```wgsl
+ * fn folded_dispatch(groups: u32) -> vec3<u32>
+ * ```
+ *
+ * No workgroups is `(0, 1, 1)`, which dispatches nothing. For the passes that write their own
+ * commands on the device, a word each: `command[at + i] = folded[i]`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_folded_dispatch: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_folded_dispatch.d.ts.map

package/src/shade/renderer/gpu_primitive/indirect/chunk_folded_dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_folded_dispatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/indirect/chunk_folded_dispatch.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CAahB;0BA9BuB,oCAAoC"}

package/src/shade/renderer/gpu_primitive/indirect/chunk_folded_dispatch.js

@@ -0,0 +1,31 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "./WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+
+/**
+ * The workgroup counts of an indirect dispatch of `groups` workgroups, folded as
+ * `IndirectComputeCommandBuildPass` folds them: x to
+ * {@link WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}, what is left of it in rows of x, and
+ * what is left of those in slices of x·y. A shader dispatched through it finds its workgroup with
+ * `folded_workgroup_index` and never reads `num_workgroups`.
+ *
+ * ```wgsl
+ * fn folded_dispatch(groups: u32) -> vec3<u32>
+ * ```
+ *
+ * No workgroups is `(0, 1, 1)`, which dispatches nothing. For the passes that write their own
+ * commands on the device, a word each: `command[at + i] = folded[i]`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_folded_dispatch = CodeChunk.from(
+    //language=WGSL
+    `
+fn folded_dispatch(groups: u32) -> vec3<u32> {
+    const LIMIT = ${WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}u;
+
+    let rows = (groups + LIMIT - 1u) / LIMIT;
+    let slices = (rows + LIMIT - 1u) / LIMIT;
+
+    return vec3<u32>(min(groups, LIMIT), min(max(rows, 1u), LIMIT), max(slices, 1u));
+}
+`);

package/src/shade/renderer/gpu_primitive/slot_stack/chunk_slot_stack.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What {@link chunk_slot_stack}'s pop hands back when the stack is empty: the engine's one "no index"
+ * word, which no capacity reaches.
+ *
+ * @type {number}
+ */
+export const SLOT_STACK_NONE: number;
+/**
+ * A stack of free slot indices on the device: a count, and the array the slots sit in below it. A
+ * pool hands its slots out by popping and takes them back by pushing; the order inside is
+ * arbitrary, and what matters is that every free slot appears once (`shader_slot_stack_fill` makes a
+ * fresh one).
+ *
+ * ```wgsl
+ * fn slot_stack_pop(count: ptr<storage, atomic<u32>, read_write>, slots: ptr<storage, array<u32>, read_write>, capacity: u32) -> u32
+ * fn slot_stack_push(count: ptr<storage, atomic<u32>, read_write>, slots: ptr<storage, array<u32>, read_write>, slot: u32)
+ * ```
+ *
+ * **The pop's guard catches wrapped counts, not just zero.** When many threads race an empty stack,
+ * the first over-pop wraps the count to `0xFFFFFFFF` before its undo lands, and a concurrent thread
+ * then reads a huge old value. Testing only `== 0` would let it index `slots[old - 1]` with garbage and
+ * hand out a slot that is not free. The count never legitimately exceeds `capacity`, so `> capacity`
+ * names every wrapped state; each thread that subtracted adds back exactly once, so the count
+ * converges to 0.
+ *
+ * **Pushes and pops go in separate dispatches.** A pop can read a slot a concurrent push has counted
+ * but not yet written.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_slot_stack: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_slot_stack.d.ts.map

package/src/shade/renderer/gpu_primitive/slot_stack/chunk_slot_stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_slot_stack.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/slot_stack/chunk_slot_stack.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,8BAFU,MAAM,CAE0B;AAE1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+BAFU,SAAS,CAyBhB;0BAxDuB,oCAAoC"}