@woosh/meep-engine 3.64.0 → 3.65.0

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

@@ -0,0 +1,31 @@
+/**
+ * A one-step sphere parallax for a probe's radiance tap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.3, "Parallax
+ * correction"): the direction along which a probe sees what a ray from another point reaches.
+ *
+ * ```wgsl
+ * fn probe_clipmap_parallax(slot: u32, probe: vec3<f32>, spacing: f32, position: vec3<f32>, direction: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * - `probe` is where the slot's probe stands, `spacing` its cascade's; `direction` is unit.
+ * - The ray from `position` along `direction` is met with a sphere about the probe whose radius is the probe's
+ *   mean depth along `direction`, one bilinear tap of its depth tile. The far root is taken, so a point inside
+ *   the sphere always meets it. The result is the unit direction from the probe to where they meet.
+ * - Where the ray misses the sphere, or meets it only behind the point, the result is `direction`.
+ *
+ * **Misses.** The depth is the visibility's (§8.2): a ray that missed, and a hit further than
+ * `PROBE_DEPTH_LIMIT` spacings, are both stored as the limit. The sphere therefore never stands further than
+ * the limit, and whatever lies past it, the sky included, is taken to be that near. A point a distance d from
+ * the probe has its direction toward such a thing turned by up to asin(d / (limit · spacing)), where the right
+ * turn for the sky is none. The probes of a cage each turn by their own angle, so their taps of one distant
+ * thing land on different texels. The depth cannot tell a miss from a hit at the limit, and its two moments say
+ * what share of a texel's rays went past the limit but not how far: a parallax that is right past the limit
+ * needs a distance the probe does not store.
+ *
+ * `probe_clipmap_sample_radiance` does not take this parallax, for that reason: it taps along the lobe. The
+ * chunk is kept for a reader whose probes see nothing past the limit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_parallax: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_probe_clipmap_parallax.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_probe_clipmap_parallax.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_parallax.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,2CAFU,SAAS,CAwBZ;0BArDmB,uCAAuC"}

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

@@ -0,0 +1,54 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_probe_clipmap_pick } from "./chunk_probe_clipmap_pick.js";
+
+/**
+ * A one-step sphere parallax for a probe's radiance tap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.3, "Parallax
+ * correction"): the direction along which a probe sees what a ray from another point reaches.
+ *
+ * ```wgsl
+ * fn probe_clipmap_parallax(slot: u32, probe: vec3<f32>, spacing: f32, position: vec3<f32>, direction: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * - `probe` is where the slot's probe stands, `spacing` its cascade's; `direction` is unit.
+ * - The ray from `position` along `direction` is met with a sphere about the probe whose radius is the probe's
+ *   mean depth along `direction`, one bilinear tap of its depth tile. The far root is taken, so a point inside
+ *   the sphere always meets it. The result is the unit direction from the probe to where they meet.
+ * - Where the ray misses the sphere, or meets it only behind the point, the result is `direction`.
+ *
+ * **Misses.** The depth is the visibility's (§8.2): a ray that missed, and a hit further than
+ * `PROBE_DEPTH_LIMIT` spacings, are both stored as the limit. The sphere therefore never stands further than
+ * the limit, and whatever lies past it, the sky included, is taken to be that near. A point a distance d from
+ * the probe has its direction toward such a thing turned by up to asin(d / (limit · spacing)), where the right
+ * turn for the sky is none. The probes of a cage each turn by their own angle, so their taps of one distant
+ * thing land on different texels. The depth cannot tell a miss from a hit at the limit, and its two moments say
+ * what share of a texel's rays went past the limit but not how far: a parallax that is right past the limit
+ * needs a distance the probe does not store.
+ *
+ * `probe_clipmap_sample_radiance` does not take this parallax, for that reason: it taps along the lobe. The
+ * chunk is kept for a reader whose probes see nothing past the limit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_parallax = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_parallax(slot: u32, probe: vec3<f32>, spacing: f32, position: vec3<f32>, direction: vec3<f32>) -> vec3<f32> {
+    // a miss reads the limit here, as a hit at the limit does: see the chunk's notes on misses
+    let radius = probe_clipmap_depth_moments(slot, direction).x * spacing;
+    let origin = position - probe;
+    let b = dot(direction, origin);
+    let discriminant = b * b - (dot(origin, origin) - radius * radius);
+
+    if (discriminant >= 0.0) {
+        let t = sqrt(discriminant) - b;
+
+        if (t > 0.0) {
+            return normalize(origin + t * direction);
+        }
+    }
+
+    return direction;
+}
+`, [
+        chunk_probe_clipmap_pick,
+    ]);

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

@@ -13,10 +13,14 @@
  *   picked by, at the visibility it was picked at. The trilinear part cancels.
  * - **The sample vector** is Lagarde's dominant direction, `normalize(mix(r, n, α))` with r the
  *   reflection of the view and α the roughness squared.
- * - **A radiance tap** a probe, along the sample vector after a one-step sphere parallax: the reflected ray
- *   is met with a sphere about the probe whose radius is its mean depth along the vector. The depth is held
- *   at the cage's diagonal (§8.2), past which no parallax is taken. One bilinear tap of the tile, through
- *   its skirt and the depth's sampler.
+ * - **A radiance tap** a probe, along the sample vector: one bilinear tap of the tile, through its skirt and
+ *   the depth's sampler. Every picked probe is tapped along the same direction, as if what it sees there were
+ *   infinitely far.
+ * - **No parallax** is taken toward what a probe sees along the vector. The only distance a probe stores is its
+ *   visibility depth, where a miss and a hit past `PROBE_DEPTH_LIMIT` both read the limit, so a sphere of
+ *   that depth turns the taps of the sky and of everything distant, each probe's by its own angle
+ *   (`chunk_probe_clipmap_parallax`, kept beside this chunk and not linked by it; §9.3, "Parallax
+ *   correction"). A reflection of something nearer than the limit is therefore placed as if it were far.
  * - **The rough end** is the probes' SH, mixed by the same shares and resolved for the GGX lobe
  *   (`sh3_color_get_radiance_with_GGX`, as Brick4 resolves its probes). The two are blended by
  *   `roughness_to_mip_ratio`: SH alone from roughness 0.7.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_probe_clipmap_sample_radiance.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_sample_radiance.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,kDAFU,SAAS,CAmIZ;0BA1KmB,uCAAuC"}
+{"version":3,"file":"chunk_probe_clipmap_sample_radiance.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_sample_radiance.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,kDAFU,SAAS,CAoHZ;0BA/JmB,uCAAuC"}

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

@@ -41,10 +41,14 @@ import { PROBE_RECEIVER_BIAS_VIEW } from "./PROBE_CLIPMAP.js";
  *   picked by, at the visibility it was picked at. The trilinear part cancels.
  * - **The sample vector** is Lagarde's dominant direction, `normalize(mix(r, n, α))` with r the
  *   reflection of the view and α the roughness squared.
- * - **A radiance tap** a probe, along the sample vector after a one-step sphere parallax: the reflected ray
- *   is met with a sphere about the probe whose radius is its mean depth along the vector. The depth is held
- *   at the cage's diagonal (§8.2), past which no parallax is taken. One bilinear tap of the tile, through
- *   its skirt and the depth's sampler.
+ * - **A radiance tap** a probe, along the sample vector: one bilinear tap of the tile, through its skirt and
+ *   the depth's sampler. Every picked probe is tapped along the same direction, as if what it sees there were
+ *   infinitely far.
+ * - **No parallax** is taken toward what a probe sees along the vector. The only distance a probe stores is its
+ *   visibility depth, where a miss and a hit past `PROBE_DEPTH_LIMIT` both read the limit, so a sphere of
+ *   that depth turns the taps of the sky and of everything distant, each probe's by its own angle
+ *   (`chunk_probe_clipmap_parallax`, kept beside this chunk and not linked by it; §9.3, "Parallax
+ *   correction"). A reflection of something nearer than the limit is therefore placed as if it were far.
  * - **The rough end** is the probes' SH, mixed by the same shares and resolved for the GGX lobe
  *   (`sh3_color_get_radiance_with_GGX`, as Brick4 resolves its probes). The two are blended by
  *   `roughness_to_mip_ratio`: SH alone from roughness 0.7.
@@ -97,23 +101,8 @@ fn probe_clipmap_lobe(slot: u32, share: f32, position: vec3<f32>, normal: vec3<f
     out.weight = share * probe_visibility_weight(toward, lobe, visibility) / probe_visibility_weight(toward, normal, visibility);
     out.sh = probe_record_sh_decode(record.sh);
 
-    // the reflected ray met with a sphere about the probe, its radius the probe's mean depth along the lobe
-    let radius = probe_clipmap_depth_moments(slot, lobe).x * spacing;
-    let origin = position - probe;
-    let b = dot(lobe, origin);
-    let discriminant = b * b - (dot(origin, origin) - radius * radius);
-
-    var direction = lobe;
-
-    if (discriminant >= 0.0) {
-        let t = sqrt(discriminant) - b;
-
-        if (t > 0.0) {
-            direction = normalize(origin + t * lobe);
-        }
-    }
-
-    out.radiance = probe_clipmap_radiance(slot, direction).rgb;
+    // along the lobe itself: no parallax toward what the probe sees there (chunk_probe_clipmap_parallax, on misses)
+    out.radiance = probe_clipmap_radiance(slot, lobe).rgb;
 
     return out;
 }

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

@@ -4,8 +4,13 @@
  *
  * ```wgsl
  * fn probe_clipmap_want(wants: bool, position: vec3<f32>, bias_direction: vec3<f32>, cascade_count: u32, resolution: u32, anchor: vec3<f32>, select_half: f32, wanted_capacity: u32)
+ * fn probe_clipmap_want_cage(wants: bool, cascade: u32, cage: vec3<i32>, resolution: u32, wanted_capacity: u32)
  * ```
  *
+ * `probe_clipmap_want_cage` wants one cage by name, the cage whose least point is `cage` in `cascade`, for a
+ * caller that knows its cages without a point to read them from; the cascade's cage window must hold it
+ * (`clipmap_contains`). `probe_clipmap_want` is the two it reads from a point.
+ *
  * The cages are the pick's: the cascade `probe_clipmap_select_in` answers for the point, by the windows'
  * `anchor` and `select_half` as the pick reads them, the cage of the point biased along `bias_direction` by
  * that cascade's spacing, and in the cascade's blend skirt the next cascade's cage too, biased by its own. A cage a bias moved out of its window is not wanted. Each cage
@@ -16,8 +21,8 @@
  * workgroup's table and sets its bits; the rest want it through that lane. Measured on the AMD iGPU at
  * 1280×720 on Sponza before the claims, the bits' atomics were 140 of want's 345 µs and the appends 90.
  *
- * Every lane of the workgroup calls it once, wanting or not, from uniform control flow: the appends are
- * the subgroup's.
+ * Every lane of the workgroup calls `probe_clipmap_want` once, or `probe_clipmap_want_cage` at most twice, which
+ * the claim table is sized for, wanting or not, from uniform control flow: the appends are the subgroup's.
  *
  * @type {CodeChunk}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_probe_clipmap_want.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_want.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uCAFU,SAAS,CAgFZ;0BA9HmB,uCAAuC"}
+{"version":3,"file":"chunk_probe_clipmap_want.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_want.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,uCAFU,SAAS,CA+EZ;0BAlImB,uCAAuC"}

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

@@ -13,7 +13,7 @@ import { PROBE_THREAD_WORKGROUP_SIZE } 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. Sized for {@link PROBE_THREAD_WORKGROUP_SIZE}
- * lanes: want's 8×8 tiles, and the hits' wants' 64.
+ * lanes: want's 8×8 tiles, and the hits' wants' 64; the meshlets' wants' lanes are twice as many, a cage each.
  * @type {number}
  */
 const WANT_CLAIM_SLOTS = 2 * 2 * PROBE_THREAD_WORKGROUP_SIZE;
@@ -30,8 +30,13 @@ const WANT_CLAIM_PROBES = 16;
  *
  * ```wgsl
  * fn probe_clipmap_want(wants: bool, position: vec3<f32>, bias_direction: vec3<f32>, cascade_count: u32, resolution: u32, anchor: vec3<f32>, select_half: f32, wanted_capacity: u32)
+ * fn probe_clipmap_want_cage(wants: bool, cascade: u32, cage: vec3<i32>, resolution: u32, wanted_capacity: u32)
  * ```
  *
+ * `probe_clipmap_want_cage` wants one cage by name, the cage whose least point is `cage` in `cascade`, for a
+ * caller that knows its cages without a point to read them from; the cascade's cage window must hold it
+ * (`clipmap_contains`). `probe_clipmap_want` is the two it reads from a point.
+ *
  * The cages are the pick's: the cascade `probe_clipmap_select_in` answers for the point, by the windows'
  * `anchor` and `select_half` as the pick reads them, the cage of the point biased along `bias_direction` by
  * that cascade's spacing, and in the cascade's blend skirt the next cascade's cage too, biased by its own. A cage a bias moved out of its window is not wanted. Each cage
@@ -42,8 +47,8 @@ const WANT_CLAIM_PROBES = 16;
  * workgroup's table and sets its bits; the rest want it through that lane. Measured on the AMD iGPU at
  * 1280×720 on Sponza before the claims, the bits' atomics were 140 of want's 345 µs and the appends 90.
  *
- * Every lane of the workgroup calls it once, wanting or not, from uniform control flow: the appends are
- * the subgroup's.
+ * Every lane of the workgroup calls `probe_clipmap_want` once, or `probe_clipmap_want_cage` at most twice, which
+ * the claim table is sized for, wanting or not, from uniform control flow: the appends are the subgroup's.
  *
  * @type {CodeChunk}
  */
@@ -80,46 +85,45 @@ fn probe_want_claim(key: u32) -> bool {
     return true;
 }
 
-fn probe_clipmap_want(wants: bool, position: vec3<f32>, bias_direction: vec3<f32>, cascade_count: u32, resolution: u32, anchor: vec3<f32>, select_half: f32, wanted_capacity: u32) {
-    let selection = probe_clipmap_select_in(&probe_levels, cascade_count, anchor, select_half, position);
-
-    let held = wants && selection.level != CLIPMAP_LEVEL_NONE;
-    let finest = select(0u, selection.level, held);
-    let next = min(finest + 1u, cascade_count - 1u);
-
-    var cage_finest: vec3<i32>;
-    var cage_next: vec3<i32>;
-
+fn probe_clipmap_want_cage(wants: bool, cascade: u32, cage: vec3<i32>, resolution: u32, wanted_capacity: u32) {
     // 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 = held && probe_clipmap_cage(finest, position, bias_direction, &cage_finest)
-        && probe_want_claim(probe_clipmap_key(finest, vec3<u32>(cage_finest) & wrap, resolution));
-    let wants_next = held && selection.edge_weight > 0.0 && finest + 1u < cascade_count
-        && probe_clipmap_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 wanted = 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 claimed = wants && probe_want_claim(probe_clipmap_key(cascade, vec3<u32>(cage) & wrap, resolution));
 
-        let storage = vec3<u32>(point) & wrap;
-        let key = probe_clipmap_key(cascade, storage, resolution);
+    // every lane through all eight corners, so that the appends stay in uniform control flow
+    for (var k = 0u; k < 8u; k++) {
+        let corner = vec3<i32>(vec3<u32>(k & 1u, (k >> 1u) & 1u, (k >> 2u) & 1u));
+        let key = probe_clipmap_key(cascade, vec3<u32>(cage + corner) & wrap, resolution);
         let bit = 1u << (key & 31u);
 
         var first = false;
 
-        if (wanted) {
+        if (claimed) {
             first = (atomicOr(&probe_wanted_bits[key >> 5u], bit) & bit) == 0u;
         }
 
         collection_u32_append(&probe_wanted, first, key, wanted_capacity);
     }
 }
+
+fn probe_clipmap_want(wants: bool, position: vec3<f32>, bias_direction: vec3<f32>, cascade_count: u32, resolution: u32, anchor: vec3<f32>, select_half: f32, wanted_capacity: u32) {
+    let selection = probe_clipmap_select_in(&probe_levels, cascade_count, anchor, select_half, position);
+
+    let held = wants && selection.level != CLIPMAP_LEVEL_NONE;
+    let finest = select(0u, selection.level, held);
+    let next = min(finest + 1u, cascade_count - 1u);
+
+    var cage_finest: vec3<i32>;
+    var cage_next: vec3<i32>;
+
+    let wants_finest = held && probe_clipmap_cage(finest, position, bias_direction, &cage_finest);
+    let wants_next = held && selection.edge_weight > 0.0 && finest + 1u < cascade_count
+        && probe_clipmap_cage(next, position, bias_direction, &cage_next);
+
+    probe_clipmap_want_cage(wants_finest, finest, cage_finest, resolution, wanted_capacity);
+    probe_clipmap_want_cage(wants_next, next, cage_next, resolution, wanted_capacity);
+}
 `, [
         chunk_probe_clipmap,
         chunk_probe_clipmap_select_in,

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

@@ -0,0 +1,28 @@
+/**
+ * Record the wants of a list of meshlets whose fragments pick probes (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3):
+ * the meshlets a forward pass draws, which no pixel of the G-buffer stands for. Each wants the cages a reader
+ * anywhere inside its world box can read, a thread a cage: its cages are counted
+ * (`shader_probe_clipmap_want_meshlet_count`), the counts summed (`graph_prefix_scan_csdldf`), and the sums
+ * launch the wants (`shader_probe_clipmap_want_meshlets`), as the meshes' expansion to meshlets is launched.
+ *
+ * The wants go into the clipmap's late set (`GPUProbeClipmap.write_want_bindings`), so the pass belongs after the
+ * clipmap's lifetime in the frame, and its probes are admitted by the next frame's.
+ *
+ * @param {Object} options
+ * @param {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {import("./GPUProbeClipmap.js").GPUProbeClipmap} options.clipmap the clipmap the fragments pick from
+ * @param {import("../../../scene/GPUSceneContext.js").GPUSceneContext} options.scene the meshlets' scene
+ * @param {number} options.camera graph handle of the view's camera uniform
+ * @param {number} options.meshlet_collection graph handle of the list, `MESHLET_COLLECTION_STRUCT`
+ * @param {number} options.meshlet_iterator_command graph handle of the indirect dispatch that walks the list, a
+ *   workgroup of `COMPUTE_SHADER_DEFAULT_GROUP_SIZE` meshlets, folded
+ */
+export function graph_probe_clipmap_want_meshlets({ graph, clipmap, scene, camera, meshlet_collection, meshlet_iterator_command }: {
+    graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    clipmap: import("./GPUProbeClipmap.js").GPUProbeClipmap;
+    scene: import("../../../scene/GPUSceneContext.js").GPUSceneContext;
+    camera: number;
+    meshlet_collection: number;
+    meshlet_iterator_command: number;
+}): void;
+//# sourceMappingURL=graph_probe_clipmap_want_meshlets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_probe_clipmap_want_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/graph_probe_clipmap_want_meshlets.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IARyG,KAAK,EAAnG,OAAO,iEAAiE,EAAE,UAAU;IAC5B,OAAO,EAA/D,OAAO,sBAAsB,EAAE,eAAe;IACuB,KAAK,EAA1E,OAAO,mCAAmC,EAAE,eAAe;IAC3C,MAAM,EAAtB,MAAM;IACU,kBAAkB,EAAlC,MAAM;IACU,wBAAwB,EAAxC,MAAM;SAoGhB"}

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

@@ -0,0 +1,138 @@
+import { assert } from "../../../../../core/assert.js";
+import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
+import { MESHLET_DEFINITION_STRUCT } from "../../../geometry/meshlet/encoding/MESHLET_DEFINITION_STRUCT.js";
+import { INDIRECT_COMPUTE_COMMAND_DESCRIPTOR } from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { shader_prefix_sum_to_command } from "../../../rasterize/expand/mesh/shader_prefix_sum_to_command.js";
+import { graph_create_buffer } from "../../../shader/graph/graph_create_buffer.js";
+import {
+    shader_probe_clipmap_want_meshlet_count,
+    shader_probe_clipmap_want_meshlets
+} from "./shader_probe_clipmap_want_meshlets.js";
+
+/**
+ * Bytes a meshlet list's count takes ahead of its elements, which sit on a 16-byte boundary.
+ * @type {number}
+ */
+const MESHLET_LIST_HEADER_BYTES = 16;
+
+/**
+ * Record the wants of a list of meshlets whose fragments pick probes (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3):
+ * the meshlets a forward pass draws, which no pixel of the G-buffer stands for. Each wants the cages a reader
+ * anywhere inside its world box can read, a thread a cage: its cages are counted
+ * (`shader_probe_clipmap_want_meshlet_count`), the counts summed (`graph_prefix_scan_csdldf`), and the sums
+ * launch the wants (`shader_probe_clipmap_want_meshlets`), as the meshes' expansion to meshlets is launched.
+ *
+ * The wants go into the clipmap's late set (`GPUProbeClipmap.write_want_bindings`), so the pass belongs after the
+ * clipmap's lifetime in the frame, and its probes are admitted by the next frame's.
+ *
+ * @param {Object} options
+ * @param {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {import("./GPUProbeClipmap.js").GPUProbeClipmap} options.clipmap the clipmap the fragments pick from
+ * @param {import("../../../scene/GPUSceneContext.js").GPUSceneContext} options.scene the meshlets' scene
+ * @param {number} options.camera graph handle of the view's camera uniform
+ * @param {number} options.meshlet_collection graph handle of the list, `MESHLET_COLLECTION_STRUCT`
+ * @param {number} options.meshlet_iterator_command graph handle of the indirect dispatch that walks the list, a
+ *   workgroup of `COMPUTE_SHADER_DEFAULT_GROUP_SIZE` meshlets, folded
+ */
+export function graph_probe_clipmap_want_meshlets({ graph, clipmap, scene, camera, meshlet_collection, meshlet_iterator_command }) {
+    assert.defined(graph, 'graph');
+    assert.defined(clipmap, 'clipmap');
+    assert.defined(scene, 'scene');
+    assert.isNonNegativeInteger(camera, 'camera');
+    assert.isNonNegativeInteger(meshlet_collection, 'meshlet_collection');
+    assert.isNonNegativeInteger(meshlet_iterator_command, 'meshlet_iterator_command');
+
+    graph.push_scope("probe clipmap want meshlets");
+
+    // a count for every meshlet the list has room for
+    const capacity = Math.floor((graph.getDescriptor(meshlet_collection).size - MESHLET_LIST_HEADER_BYTES) / MESHLET_DEFINITION_STRUCT.size);
+
+    // what the clipmap binds for a late want: its levels and settings for both passes, its late list and bits for the wants'
+    const want = {};
+
+    const count_data = {};
+
+    const count_pass = graph.add("count cages", count_data, (data, resources, context) => {
+        clipmap.write_want_bindings(want);
+
+        shader_probe_clipmap_want_meshlet_count.dispatchIndirect({
+            encoder: context.encoder,
+            command: resources.get(data.command),
+            bindings: {
+                scene_database: scene.scene_database_buffer,
+                meshlet_metadata: scene.geometries.meshlets.buffer_metadata,
+                input: resources.get(data.input),
+                output: resources.get(data.output),
+                probe_levels: want.probe_levels,
+                settings: want.settings,
+            },
+        });
+    });
+
+    count_data.command = count_pass.read(meshlet_iterator_command);
+    count_data.input = count_pass.read(meshlet_collection);
+    count_data.output = count_pass.create("cage counts", BufferResourceDescriptor.from(
+        MESHLET_LIST_HEADER_BYTES + Math.max(1, Math.ceil(capacity / 4)) * 16,
+        GPUBufferUsage.STORAGE,
+        // the count, which no thread writes for a list of no meshlet
+        0, MESHLET_LIST_HEADER_BYTES,
+    ));
+
+    const sums = graph_prefix_scan_csdldf({
+        graph,
+        input: count_data.output,
+        output: graph_create_buffer(graph, "cage offsets", prefix_scan_csdldf_output_descriptor(capacity)),
+        element_max_count: capacity,
+    });
+
+    const command_data = {};
+
+    const command_pass = graph.add("make want command", command_data, (data, resources, context) => {
+        shader_prefix_sum_to_command.dispatch({
+            encoder: context.encoder,
+            bindings: {
+                prefix_sums: resources.get(data.prefix_sums),
+                command: resources.get(data.command),
+            },
+        });
+    });
+
+    command_data.prefix_sums = command_pass.read(sums);
+    command_data.command = command_pass.create("command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+
+    const want_data = {};
+
+    const want_pass = graph.add("want cages", want_data, (data, resources, context) => {
+        clipmap.write_want_bindings(want);
+
+        shader_probe_clipmap_want_meshlets.dispatchIndirect({
+            encoder: context.encoder,
+            command: resources.get(data.command),
+            bindings: {
+                camera: resources.get(data.camera),
+                scene_database: scene.scene_database_buffer,
+                meshlet_metadata: scene.geometries.meshlets.buffer_metadata,
+                input: resources.get(data.input),
+                prefix_sums: resources.get(data.prefix_sums),
+                probe_levels: want.probe_levels,
+                probe_wanted: want.probe_wanted,
+                probe_wanted_bits: want.probe_wanted_bits,
+                settings: want.settings,
+            },
+        });
+    });
+
+    want_data.command = want_pass.read(command_data.command);
+    want_data.camera = want_pass.read(camera);
+    want_data.input = want_pass.read(meshlet_collection);
+    want_data.prefix_sums = want_pass.read(sums);
+
+    // it writes the clipmap's own late set, which the graph does not hold
+    want_pass.make_side_effect();
+
+    graph.pop_scope();
+}

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

@@ -9,9 +9,9 @@ export const PROBE_ACCUMULATE_SETTINGS: WebGPUStruct;
  * `probe_maps` (`probe_clipmap_maps_words`): two words a radiance texel, rgba as half floats; then a
  * word a radiance texel, its rays this update, resolved in the low half and back faces in the high,
  * which classification sums; then a word a depth texel, its moments as half floats; then a word a
- * radiance texel, how far its sample fell from its mean in its own deviation, luminance, held to
- * `PROBE_CHANGE_SIGNIFICANCE`, and one for its blending one, as half floats, which the probe's ray request
- * sums (zero where no sample was blended).
+ * radiance texel, its estimator after the update as the probe's L0 estimator sums it
+ * (`shader_probe_clipmap_project`): its short mean less its mean and its deviation (the estimator's own,
+ * floored at the display's exposure), luminance, as half floats; nothing for a texel no ray has reached.
  *
  * - **A texel's rays**: on a uniform update (`PROBE_UNIFORM_PERIOD`), `probe_clipmap_texel_ray`'s. On a
  *   guided one, the run that begins at its walk position in the probe's guide, at most
@@ -29,6 +29,10 @@ export const PROBE_ACCUMULATE_SETTINGS: WebGPUStruct;
  *   - The mean blends by at least 1/(a+1) until the count reaches its limit: a young texel is its running
  *     mean, which the estimator's blend reduction, nothing at its seed, would otherwise hold back. Past it
  *     the estimator alone, down to 1/8192 an update on a noisy texel.
+ *   - And by at least the probe's L0 blend (`PROBE_REQUEST_STRUCT`'s `blend`), its L0 estimator's catch-up
+ *     after its last update: a change in the probe's whole light, which the texels' own tests, a one-ray
+ *     sample's noise apiece, do not see. The texel's own catch-up stays, for light that moves without
+ *     changing L0.
  *   - Samples are clipped once the variance's window has passed, when 1/(a+1) is no longer its blend:
  *     before that it holds no spread to clip to.
  *   - A texel's first sample seeds both means. A texel no ray reached keeps its history.

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

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_accumulate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_accumulate.js"],"names":[],"mappings":"AA+CA;;GAEG;AACH,wCAFU,YAAY,CAmBQ;AAsB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,8CAFU,aAAa,CA2TpB;6BAvb0B,sCAAsC;8BAJrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_accumulate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_accumulate.js"],"names":[],"mappings":"AA+CA;;GAEG;AACH,wCAFU,YAAY,CAmBQ;AAwB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,8CAFU,aAAa,CAgUpB;6BAlc0B,sCAAsC;8BAJrC,kCAAkC"}

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

@@ -29,6 +29,7 @@ import {
     PROBE_RAY_STRUCT,
     PROBE_RAY_SUMS_READ_RESOURCE,
     PROBE_RAYS_READ_RESOURCE,
+    PROBE_REQUESTS_READ_RESOURCE,
     PROBE_RESAMPLES_READ_RESOURCE,
     PROBE_STATES_READ_RESOURCE,
     PROBE_TRACE_READ_RESOURCE
@@ -36,7 +37,6 @@ import {
 import { chunk_probe_clipmap_resampled } from "./chunk_probe_clipmap_resampled.js";
 import {
     PROBE_BACK_FACE_DEPTH,
-    PROBE_CHANGE_SIGNIFICANCE,
     PROBE_DEPTH_LIMIT,
     PROBE_DEPTH_TEXEL_RAYS,
     PROBE_RADIANCE_SAMPLES_LIMIT,
@@ -82,6 +82,8 @@ resources.createGroup()
     .add(PROBE_RADIANCE_HISTORY_RESOURCE)
     .add(PROBE_DEPTH_HISTORY_RESOURCE)
     .add(PROBE_ESTIMATORS_RESOURCE)
+    // the probes' L0 blends, as their last projection left them
+    .add(PROBE_REQUESTS_READ_RESOURCE)
     // read only where the frame re-samples (chunk_probe_clipmap_resampled)
     .add(PROBE_RESAMPLES_READ_RESOURCE)
     // the factor the display multiplies radiance by ahead of its tone curve, as the last frame was shown
@@ -94,9 +96,9 @@ resources.createGroup()
  * `probe_maps` (`probe_clipmap_maps_words`): two words a radiance texel, rgba as half floats; then a
  * word a radiance texel, its rays this update, resolved in the low half and back faces in the high,
  * which classification sums; then a word a depth texel, its moments as half floats; then a word a
- * radiance texel, how far its sample fell from its mean in its own deviation, luminance, held to
- * `PROBE_CHANGE_SIGNIFICANCE`, and one for its blending one, as half floats, which the probe's ray request
- * sums (zero where no sample was blended).
+ * radiance texel, its estimator after the update as the probe's L0 estimator sums it
+ * (`shader_probe_clipmap_project`): its short mean less its mean and its deviation (the estimator's own,
+ * floored at the display's exposure), luminance, as half floats; nothing for a texel no ray has reached.
  *
  * - **A texel's rays**: on a uniform update (`PROBE_UNIFORM_PERIOD`), `probe_clipmap_texel_ray`'s. On a
  *   guided one, the run that begins at its walk position in the probe's guide, at most
@@ -114,6 +116,10 @@ resources.createGroup()
  *   - The mean blends by at least 1/(a+1) until the count reaches its limit: a young texel is its running
  *     mean, which the estimator's blend reduction, nothing at its seed, would otherwise hold back. Past it
  *     the estimator alone, down to 1/8192 an update on a noisy texel.
+ *   - And by at least the probe's L0 blend (`PROBE_REQUEST_STRUCT`'s `blend`), its L0 estimator's catch-up
+ *     after its last update: a change in the probe's whole light, which the texels' own tests, a one-ray
+ *     sample's noise apiece, do not see. The texel's own catch-up stays, for light that moves without
+ *     changing L0.
  *   - Samples are clipped once the variance's window has passed, when 1/(a+1) is no longer its blend:
  *     before that it holds no spread to clip to.
  *   - A texel's first sample seeds both means. A texel no ray reached keeps its history.
@@ -268,34 +274,29 @@ fn main(
         let tile = index_to_grid2d(slot, settings.radiance_tiles_per_row) * (n + 2u * settings.radiance_skirt) + settings.radiance_skirt;
         let history = select(textureLoad(probe_radiance, tile + vec2<u32>(i % n, i / n), 0), vec4<f32>(0.0), updates == 0u);
 
+        let estimator = slot * texels + i;
+
         var texel = history;
-        // how far the sample fell from the texel's mean in its own deviation, luminance, and that it blended
-        // one: the probe's ray request reads their sums. A texel's part is held to PROBE_CHANGE_SIGNIFICANCE,
-        // so that one bright sample is one texel's at most
-        var change = vec2<f32>(0.0);
+        // the texel's estimator, its history's until a sample is blended
+        var e = probe_accumulate_estimator(history.rgb, probe_estimators[estimator]);
 
         if (count > 0u) {
             // the rays, and the neighbours' re-samples where the frame took them
             let pooled = probe_clipmap_resampled(k * texels + i, sum, count);
             let sample = pooled.rgb / pooled.w;
-            let estimator = slot * texels + i;
+            let before = e;
 
-            var e = multiscale_mean_seed(sample);
+            e = multiscale_mean_seed(sample);
 
             if (history.a > 0.0) {
                 let ramp = 1.0 / (history.a + 1.0);
-                let before = probe_accumulate_estimator(history.rgb, probe_estimators[estimator]);
-                // the estimator's own floor on the deviation, at the display's exposure
-                let deviation = rgb_to_luminance(max(multiscale_mean_deviation_floor(before.short_mean, probe_exposure.value), sqrt(max(vec3<f32>(0.0), before.variance))));
-
-                change = vec2<f32>(clamp(rgb_to_luminance(sample - history.rgb) / deviation, -${PROBE_CHANGE_SIGNIFICANCE}.0, ${PROBE_CHANGE_SIGNIFICANCE}.0), 1.0);
 
                 e = multiscale_mean_add(
                     before,
                     sample,
                     max(ramp, ${PROBE_SHORT_BLEND}),
                     max(ramp, ${PROBE_VARIANCE_BLEND}),
-                    select(0.0, ramp, history.a < ${PROBE_RADIANCE_SAMPLES_LIMIT}.0),
+                    max(select(0.0, ramp, history.a < ${PROBE_RADIANCE_SAMPLES_LIMIT}.0), probe_requests[slot].blend),
                     ramp <= ${PROBE_VARIANCE_BLEND},
                     probe_exposure.value,
                 );
@@ -306,13 +307,23 @@ fn main(
             probe_estimators[estimator] = probe_accumulate_estimator_words(e, slot, per_probe + 2u * i, updates);
         }
 
+        // the estimator as the probe's L0 estimator sums it, its deviation floored at the display's exposure as
+        // the estimator's own; nothing for a texel no ray has reached
+        var state = vec2<f32>(0.0);
+
+        if (texel.a > 0.0) {
+            let deviation = max(multiscale_mean_deviation_floor(e.short_mean, probe_exposure.value), sqrt(max(vec3<f32>(0.0), e.variance)));
+
+            state = vec2<f32>(rgb_to_luminance(e.short_mean - e.mean), rgb_to_luminance(deviation));
+        }
+
         // the count is whole, which any noise keeps
         let stored = f16_round_stochastic(texel, vec4<f32>(probe_accumulate_store_noise(slot, i, updates), 0.0));
 
         probe_maps[maps + 2u * i] = pack2x16float(stored.rg);
         probe_maps[maps + 2u * i + 1u] = pack2x16float(stored.ba);
         probe_maps[maps + 2u * texels + i] = count | (back_faces << 16u);
-        probe_maps[maps + 3u * texels + m * m + i] = pack2x16float(change);
+        probe_maps[maps + 3u * texels + m * m + i] = pack2x16float(state);
 
         return;
     }