@woosh/meep-engine 3.59.0 → 3.60.0

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

@@ -8,17 +8,43 @@ export const PROBE_ACCUMULATE_SETTINGS: WebGPUStruct;
  * gathers its own rays and writes the texel, blended with its history, to the probe's maps in
  * `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.
+ * 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**: the mean of the texel's resolved rays, a back face's being zero, blended by
- *   α = max(1/(a+1), 1 − e^(−Δt·p/τ)). a is the texel's own count of the updates that reached it, held
- *   in its alpha; p the updates between a texel's rays, n_r²/R below one ray a texel. Counting a texel
- *   rather than the probe keeps α right where an update covers a subset: a texel's first ray is taken
- *   whole whenever it comes. A texel no ray reached keeps its history.
- * - **Depth**: the moments (d, d²) of the rays landing in the texel, in spacings: a miss √3, a back
- *   face 0.2·t (DDGI 2021's shortening), a hit t, every sample held to √3 (D9). Blended by the probe's
- *   α = max(1/(n+1), 1 − e^(−Δt/τ)), n its updates. At most 64 rays a texel, which the settings hold
- *   R to (R ≤ 64·n_d²).
+ * - **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
+ *   `PROBE_TEXEL_RAYS` of them. A guided texel's rays are spread evenly over it however many it takes,
+ *   so their mean needs no weight for the guide's choice.
+ * - **Radiance**: the mean of the texel's resolved rays, a back face's being zero, is a sample of the
+ *   texel's multi-scale mean (`chunk_multiscale_mean`), its estimator in `probe_estimators` and its mean
+ *   in the atlas.
+ *   - Δt and τ are frames: Δt since the probe's last update, τ `response_frames`.
+ *   - The short mean blends by β = max(1/(a+1), 1 − e^(−Δt·p/τ)), its variance by the same with 2τ. a is
+ *     the texel's own count of the updates that reached it, held in its alpha; p the updates between a
+ *     texel's rays: one over the share of updates that reach it, averaged over the uniform period
+ *     (`probe_clipmap_guide_rate`), n_r²/R below one ray a texel when every update is uniform. A texel
+ *     the guide passes over thus blends what it takes as fully as its rarity asks. Counting a texel
+ *     rather than the probe keeps β right where an update covers a subset.
+ *   - 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.
+ *   - 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.
+ * - **Depth**: the moments (d, d²) of the rays landing in the texel, in spacings: a miss the limit, a
+ *   back face 0.2·t (DDGI 2021's shortening), a hit t, every sample held to the limit, the farthest a
+ *   cage tests a relocated probe, (1 + 0.45)·√3 (`PROBE_DEPTH_LIMIT`, D9). On a uniform update the
+ *   sample is the plain mean, blended by the probe's α = max(1/(n+1), 1 − e^(−Δt/τ)), n its updates. At
+ *   most 64 rays a texel, which the settings hold R to (R ≤ 64·n_d²).
+ *   - On a guided update the sample is a mean of means: each radiance texel inside the depth texel gives
+ *     its own mean, since the guide gives the brighter ones more rays, at most 64/f² of its rays,
+ *     evenly strided. It is taken only when every one of them took rays. The guide gives a dark one,
+ *     a back face's or a shadowed wall's, none, and the lit ones' depths are not the whole texel's: its
+ *     depth comes from the uniform updates.
+ *   - The time term's period is one over the share of updates that reach the depth texel, a uniform
+ *     update counting as reaching every one, a guided one as often as its least reached radiance texel.
  * - **A new probe's history is another probe's**, its slot's last owner: on its first update a texel
  *   no ray reached is cleared, radiance to nothing seen, depth to the moments of a miss.
  * - **Stored rounded stochastically** onto halves (`f16_round_stochastic`), with noise fresh for each

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+BA;;GAEG;AACH,wCAFU,YAAY,CAmBQ;AAgB9B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8CAFU,aAAa,CAgMpB;6BAlR0B,sCAAsC;8BAHrC,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":"AA0CA;;GAEG;AACH,wCAFU,YAAY,CAqBQ;AAmB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,8CAFU,aAAa,CAmVpB;6BA3c0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -1,6 +1,10 @@
+import { chunk_multiscale_mean } from "../../../shader/chunk/filter/chunk_multiscale_mean.js";
+import { MULTISCALE_MEAN_STRUCT } from "../../../shader/chunk/filter/MULTISCALE_MEAN_STRUCT.js";
 import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
 import { chunk_index_to_grid2d } from "../../../shader/chunk/grid/chunk_index_to_grid2d.js";
 import { chunk_f16_round_stochastic } from "../../../shader/chunk/math/chunk_f16_round_stochastic.js";
+import { chunk_rgbe9995_decode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_decode.js";
+import { F16_MAX_DEFINITION } from "../../../shader/chunk/math/F16_MAX_DEFINITION.js";
 import { chunk_hash_to_float01 } from "../../../shader/chunk/random/chunk_hash_to_float01.js";
 import { chunk_pcg3d } from "../../../shader/chunk/random/pcg/chunk_pcg3d.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
@@ -11,12 +15,17 @@ import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import { BRICK_TRACE_MISS, BRICK_TRACE_UNRESOLVED } from "../brick/BRICK_CLIPMAP.js";
 import {
     chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    chunk_probe_clipmap_ray_layout,
     chunk_probe_clipmap_ray_texel,
     PROBE_DEPTH_HISTORY_RESOURCE,
+    PROBE_ESTIMATORS_RESOURCE,
+    PROBE_GUIDE_READ_RESOURCE,
     PROBE_MAPS_WRITE_RESOURCE,
     PROBE_ORIGINS_READ_RESOURCE,
     PROBE_RADIANCE_HISTORY_RESOURCE,
     PROBE_RAY_STRUCT,
+    PROBE_RAY_SUMS_READ_RESOURCE,
     PROBE_RAYS_READ_RESOURCE,
     PROBE_RECORDS_READ_RESOURCE,
     PROBE_STATES_READ_RESOURCE,
@@ -24,7 +33,9 @@ import {
 } from "./chunk_probe_clipmap.js";
 import {
     PROBE_BACK_FACE_DEPTH,
+    PROBE_CHANGE_SIGNIFICANCE,
     PROBE_DEPTH_LIMIT,
+    PROBE_DEPTH_TEXEL_RAYS,
     PROBE_RADIANCE_SAMPLES_LIMIT,
     PROBE_THREAD_WORKGROUP_SIZE
 } from "./PROBE_CLIPMAP.js";
@@ -35,7 +46,7 @@ import {
 export const PROBE_ACCUMULATE_SETTINGS = WebGPUStruct.from({
     /** probes a frame updates at most: the trace list's bound */
     trace_capacity: u32,
-    /** rays an update casts, R */
+    /** rays a uniform update casts, R; a guided update casts its probe's own (`probe_ray_sums`) */
     rays_per_probe: u32,
     /** octahedral radiance texels a side, n_r */
     radiance_resolution: u32,
@@ -45,10 +56,12 @@ export const PROBE_ACCUMULATE_SETTINGS = WebGPUStruct.from({
     radiance_tiles_per_row: u32,
     /** tiles a row of the depth atlas */
     depth_tiles_per_row: u32,
-    /** the frame's time on the records' clock, seconds */
-    time: f32,
-    /** the blend's response time, τ, seconds */
-    response_time: f32,
+    /** the frame, of the frames the clipmap has recorded */
+    frame: u32,
+    /** the short mean's response, τ, in frames; the depth's blend's */
+    response_frames: f32,
+    /** updates between a probe's uniform ones, `PROBE_UNIFORM_PERIOD` */
+    uniform_period: u32,
 }, "ProbeAccumulateSettings");
 
 const resources = new ShaderResourceSetDescriptor();
@@ -59,11 +72,14 @@ resources.createGroup()
     .add(PROBE_TRACE_READ_RESOURCE)
     .add(PROBE_ORIGINS_READ_RESOURCE)
     .add(PROBE_RAYS_READ_RESOURCE)
+    .add(PROBE_RAY_SUMS_READ_RESOURCE)
     .add(PROBE_STATES_READ_RESOURCE)
     .add(PROBE_RECORDS_READ_RESOURCE)
+    .add(PROBE_GUIDE_READ_RESOURCE)
     .add(PROBE_MAPS_WRITE_RESOURCE)
     .add(PROBE_RADIANCE_HISTORY_RESOURCE)
-    .add(PROBE_DEPTH_HISTORY_RESOURCE);
+    .add(PROBE_DEPTH_HISTORY_RESOURCE)
+    .add(PROBE_ESTIMATORS_RESOURCE);
 
 /**
  * Accumulate (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8): a thread a texel of each listed probe's maps,
@@ -71,17 +87,43 @@ resources.createGroup()
  * gathers its own rays and writes the texel, blended with its history, to the probe's maps in
  * `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.
+ * 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**: the mean of the texel's resolved rays, a back face's being zero, blended by
- *   α = max(1/(a+1), 1 − e^(−Δt·p/τ)). a is the texel's own count of the updates that reached it, held
- *   in its alpha; p the updates between a texel's rays, n_r²/R below one ray a texel. Counting a texel
- *   rather than the probe keeps α right where an update covers a subset: a texel's first ray is taken
- *   whole whenever it comes. A texel no ray reached keeps its history.
- * - **Depth**: the moments (d, d²) of the rays landing in the texel, in spacings: a miss √3, a back
- *   face 0.2·t (DDGI 2021's shortening), a hit t, every sample held to √3 (D9). Blended by the probe's
- *   α = max(1/(n+1), 1 − e^(−Δt/τ)), n its updates. At most 64 rays a texel, which the settings hold
- *   R to (R ≤ 64·n_d²).
+ * - **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
+ *   `PROBE_TEXEL_RAYS` of them. A guided texel's rays are spread evenly over it however many it takes,
+ *   so their mean needs no weight for the guide's choice.
+ * - **Radiance**: the mean of the texel's resolved rays, a back face's being zero, is a sample of the
+ *   texel's multi-scale mean (`chunk_multiscale_mean`), its estimator in `probe_estimators` and its mean
+ *   in the atlas.
+ *   - Δt and τ are frames: Δt since the probe's last update, τ `response_frames`.
+ *   - The short mean blends by β = max(1/(a+1), 1 − e^(−Δt·p/τ)), its variance by the same with 2τ. a is
+ *     the texel's own count of the updates that reached it, held in its alpha; p the updates between a
+ *     texel's rays: one over the share of updates that reach it, averaged over the uniform period
+ *     (`probe_clipmap_guide_rate`), n_r²/R below one ray a texel when every update is uniform. A texel
+ *     the guide passes over thus blends what it takes as fully as its rarity asks. Counting a texel
+ *     rather than the probe keeps β right where an update covers a subset.
+ *   - 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.
+ *   - 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.
+ * - **Depth**: the moments (d, d²) of the rays landing in the texel, in spacings: a miss the limit, a
+ *   back face 0.2·t (DDGI 2021's shortening), a hit t, every sample held to the limit, the farthest a
+ *   cage tests a relocated probe, (1 + 0.45)·√3 (`PROBE_DEPTH_LIMIT`, D9). On a uniform update the
+ *   sample is the plain mean, blended by the probe's α = max(1/(n+1), 1 − e^(−Δt/τ)), n its updates. At
+ *   most 64 rays a texel, which the settings hold R to (R ≤ 64·n_d²).
+ *   - On a guided update the sample is a mean of means: each radiance texel inside the depth texel gives
+ *     its own mean, since the guide gives the brighter ones more rays, at most 64/f² of its rays,
+ *     evenly strided. It is taken only when every one of them took rays. The guide gives a dark one,
+ *     a back face's or a shadowed wall's, none, and the lit ones' depths are not the whole texel's: its
+ *     depth comes from the uniform updates.
+ *   - The time term's period is one over the share of updates that reach the depth texel, a uniform
+ *     update counting as reaching every one, a guided one as often as its least reached radiance texel.
  * - **A new probe's history is another probe's**, its slot's last owner: on its first update a texel
  *   no ray reached is cleared, radiance to nothing seen, depth to the moments of a miss.
  * - **Stored rounded stochastically** onto halves (`f16_round_stochastic`), with noise fresh for each
@@ -98,7 +140,7 @@ export const shader_probe_clipmap_accumulate = ComputeShader.from({
         //language=WGSL
         `
 fn probe_accumulate_light(ray: ${PROBE_RAY_STRUCT.wgsl_ref}) -> vec3<f32> {
-    return vec3<f32>(unpack2x16float(ray.light_rg), unpack2x16float(ray.light_b).x);
+    return rgbe9995_decode(ray.light);
 }
 
 // uniform noise in [0, 1) for a texel's store, fresh each update
@@ -108,6 +150,36 @@ fn probe_accumulate_store_noise(slot: u32, texel: u32, updates: u32) -> vec3<f32
     return vec3<f32>(hash_to_float01(hash.x), hash_to_float01(hash.y), hash_to_float01(hash.z));
 }
 
+// a texel's estimator from its words, its mean the atlas's
+fn probe_accumulate_estimator(mean: vec3<f32>, words: vec4<u32>) -> ${MULTISCALE_MEAN_STRUCT.wgsl_ref} {
+    let rg = unpack2x16float(words.x);
+    let b_r = unpack2x16float(words.y);
+    let deviation = vec3<f32>(b_r.y, unpack2x16float(words.z));
+    let tail = unpack2x16float(words.w);
+
+    return ${MULTISCALE_MEAN_STRUCT.make({
+        mean: 'mean',
+        short_mean: 'vec3<f32>(rg, b_r.x)',
+        variance: 'deviation * deviation',
+        reduction: 'tail.x',
+        inconsistency: 'tail.y',
+    })};
+}
+
+// a texel's estimator as its words: the means and the deviation rounded stochastically, as the maps are, by
+// noise of their own after the texel's; the inconsistency held to a half
+fn probe_accumulate_estimator_words(e: ${MULTISCALE_MEAN_STRUCT.wgsl_ref}, slot: u32, key: u32, updates: u32) -> vec4<u32> {
+    let short_mean = f16_round_stochastic(vec4<f32>(e.short_mean, 0.0), vec4<f32>(probe_accumulate_store_noise(slot, key, updates), 0.0));
+    let deviation = f16_round_stochastic(vec4<f32>(sqrt(e.variance), 0.0), vec4<f32>(probe_accumulate_store_noise(slot, key + 1u, updates), 0.0));
+
+    return vec4<u32>(
+        pack2x16float(short_mean.rg),
+        pack2x16float(vec2<f32>(short_mean.b, deviation.r)),
+        pack2x16float(deviation.gb),
+        pack2x16float(vec2<f32>(e.reduction, min(e.inconsistency, F16_MAX))),
+    );
+}
+
 // a ray's depth sample, in spacings: past a miss's, as far as a sample goes
 fn probe_accumulate_depth(ray: ${PROBE_RAY_STRUCT.wgsl_ref}, spacing: f32) -> f32 {
     if ((ray.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_MISS}u) {
@@ -119,6 +191,27 @@ fn probe_accumulate_depth(ray: ${PROBE_RAY_STRUCT.wgsl_ref}, spacing: f32) -> f3
     return min(select(t, ${PROBE_BACK_FACE_DEPTH} * t, (ray.flags & PROBE_RAY_BACK_FACE) != 0u), ${PROBE_DEPTH_LIMIT});
 }
 
+// a guided update's rays of a radiance texel, for the probe whose guide starts at word base: the first
+// one, and how many, at most PROBE_TEXEL_RAYS
+fn probe_accumulate_guided_rays(base: u32, texel: u32, updates: u32, rays: u32, n: u32) -> vec2<u32> {
+    let texels = n * n;
+    let position = probe_clipmap_guide_texel(texel, updates, n);
+    let first = probe_guide[base + position];
+    let end = select(rays, probe_guide[base + position + 1u], position + 1u < texels);
+
+    return vec2<u32>(first, min(select(0u, end - first, end > first), PROBE_TEXEL_RAYS));
+}
+
+// the rays a guided update gives a radiance texel, R·(w + e)/W
+fn probe_accumulate_expected_rays(base: u32, texel: u32, rays: u32, n: u32) -> f32 {
+    let texels = n * n;
+    let total = probe_guide[base + 2u * texels + 2u * n];
+    let share = probe_guide[base + 2u * texels + 2u * n + 1u];
+
+    // the guide passes always leave a total; a guide they never wrote gives nothing
+    return select(0.0, f32(rays) * f32(probe_guide[base + texels + texel] + share) / f32(total), total > 0u);
+}
+
 @compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
 fn main(
     @builtin(workgroup_id) workgroup_id: vec3<u32>,
@@ -139,21 +232,28 @@ fn main(
     let i = thread % per_probe;
     let slot = probe_trace.elements[k];
 
-    let rays = settings.rays_per_probe;
-    let first_ray = k * rays;
+    // the update's rays: the probe's first among the frame's, and how many
+    let span = probe_clipmap_probe_rays(k);
+    let rays = span.y;
+    let first_ray = span.x;
     let updates = probe_state_updates(probe_states[slot].x);
-    let elapsed = max(settings.time - probe_records[slot].traced_time, 0.0);
+    let elapsed = f32(settings.frame - probe_records[slot].traced_frame);
     let rounds = max(rays / texels, 1u);
 
     let maps = k * probe_clipmap_maps_words(n, m);
+    let guided = probe_clipmap_guided(probe_states[slot].x, settings.uniform_period, settings.rays_per_probe, texels);
+    let base = k * probe_clipmap_guide_words(n);
 
     if (i < texels) {
         var sum = vec3<f32>(0.0);
         var count = 0u;
         var back_faces = 0u;
 
-        for (var round = 0u; round < rounds; round++) {
-            let ray = probe_clipmap_texel_ray(i, round, updates, rays, texels);
+        let run = probe_accumulate_guided_rays(base, i, updates, rays, n);
+        let gathered = select(rounds, run.y, guided);
+
+        for (var round = 0u; round < gathered; round++) {
+            let ray = select(probe_clipmap_texel_ray(i, round, updates, rays, texels), run.x + round, guided);
 
             if (ray == PROBE_CLIPMAP_NONE) {
                 continue;
@@ -174,12 +274,42 @@ fn main(
         let history = select(textureLoad(probe_radiance, tile + vec2<u32>(i % n, i / n), 0), vec4<f32>(0.0), updates == 0u);
 
         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);
 
         if (count > 0u) {
-            let period = max(1.0, f32(texels) / f32(rays));
-            let alpha = max(1.0 / (history.a + 1.0), 1.0 - exp(-elapsed * period / settings.response_time));
+            let sample = sum / f32(count);
+            let estimator = slot * texels + i;
+            let rate = probe_clipmap_guide_rate(probe_accumulate_expected_rays(base, i, rays, n), settings.rays_per_probe, texels, settings.uniform_period);
+
+            var e = multiscale_mean_seed(sample);
+
+            if (history.a > 0.0) {
+                // the gap in response times, a texel's own: its period is one over its share of updates
+                let gap = elapsed / (rate * settings.response_frames);
+                let ramp = 1.0 / (history.a + 1.0);
+                let variance_time = 1.0 - exp(-0.5 * gap);
+                let before = probe_accumulate_estimator(history.rgb, probe_estimators[estimator]);
+                // the estimator's own floor on the variance
+                let deviation = rgb_to_luminance(sqrt(max(vec3<f32>(1e-5), 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, 1.0 - exp(-gap)),
+                    max(ramp, variance_time),
+                    select(0.0, ramp, history.a < ${PROBE_RADIANCE_SAMPLES_LIMIT}.0),
+                    ramp <= variance_time,
+                );
+            }
+
+            texel = vec4<f32>(e.mean, min(history.a + 1.0, ${PROBE_RADIANCE_SAMPLES_LIMIT}.0));
 
-            texel = vec4<f32>(mix(history.rgb, sum / f32(count), alpha), min(history.a + 1.0, ${PROBE_RADIANCE_SAMPLES_LIMIT}.0));
+            probe_estimators[estimator] = probe_accumulate_estimator_words(e, slot, per_probe + 2u * i, updates);
         }
 
         // the count is whole, which any noise keeps
@@ -188,6 +318,7 @@ fn main(
         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);
 
         return;
     }
@@ -198,8 +329,50 @@ fn main(
 
     var sum = vec2<f32>(0.0);
     var count = 0u;
+    // the share of guided updates that reach this texel: its least reached radiance texel's
+    var reach = 1.0;
+
+    if (n >= m && guided) {
+        // the radiance texels inside this one, each a mean of its own
+        let f = n / m;
+        let budget = max(${PROBE_DEPTH_TEXEL_RAYS}u / (f * f), 1u);
+
+        for (var v = 0u; v < f; v++) {
+            for (var u = 0u; u < f; u++) {
+                let texel = (at.y * f + v) * n + at.x * f + u;
+                let run = probe_accumulate_guided_rays(base, texel, updates, rays, n);
+                let stride = max((run.y + budget - 1u) / budget, 1u);
+
+                reach = min(reach, min(probe_accumulate_expected_rays(base, texel, rays, n), 1.0));
+
+                var texel_sum = vec2<f32>(0.0);
+                var texel_count = 0u;
+
+                for (var q = 0u; q < run.y; q += stride) {
+                    let record = probe_rays[first_ray + run.x + q];
+
+                    if ((record.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_UNRESOLVED}u) {
+                        continue;
+                    }
+
+                    let d = probe_accumulate_depth(record, spacing);
 
-    if (n >= m) {
+                    texel_sum += vec2<f32>(d, d * d);
+                    texel_count++;
+                }
+
+                if (texel_count > 0u) {
+                    sum += texel_sum / f32(texel_count);
+                    count++;
+                }
+            }
+        }
+
+        // a radiance texel the guide gave no ray, a dark one: the lit ones' depths are not the whole texel's
+        if (count < f * f) {
+            count = 0u;
+        }
+    } else if (n >= m) {
         // the radiance texels inside this one: their rays land in it
         let f = n / m;
 
@@ -207,6 +380,8 @@ fn main(
             for (var u = 0u; u < f; u++) {
                 let texel = (at.y * f + v) * n + at.x * f + u;
 
+                reach = min(reach, min(probe_accumulate_expected_rays(base, texel, rays, n), 1.0));
+
                 for (var round = 0u; round < rounds; round++) {
                     let ray = probe_clipmap_texel_ray(texel, round, updates, rays, texels);
 
@@ -231,9 +406,14 @@ fn main(
         // the radiance texel this one is inside: those of its rays whose direction lands here
         let f = m / n;
         let texel = (at.y / f) * n + at.x / f;
+        let run = probe_accumulate_guided_rays(base, texel, updates, rays, n);
+        let gathered = select(rounds, run.y, guided);
+
+        // of the radiance texel's rays, the share whose direction lands here
+        reach = min(probe_accumulate_expected_rays(base, texel, rays, n) / f32(f * f), 1.0);
 
-        for (var round = 0u; round < rounds; round++) {
-            let ray = probe_clipmap_texel_ray(texel, round, updates, rays, texels);
+        for (var round = 0u; round < gathered; round++) {
+            let ray = select(probe_clipmap_texel_ray(texel, round, updates, rays, texels), run.x + round, guided);
 
             if (ray == PROBE_CLIPMAP_NONE) {
                 continue;
@@ -259,7 +439,10 @@ fn main(
     var moments = textureLoad(probe_depth, tile + at, 0).rg;
 
     if (count > 0u) {
-        let alpha = max(1.0 / f32(updates + 1u), 1.0 - exp(-elapsed / settings.response_time));
+        // a uniform update reaches every depth texel, a guided one those its rays land in
+        let period = f32(settings.uniform_period);
+        let rate = (1.0 + (period - 1.0) * reach) / period;
+        let alpha = max(1.0 / f32(updates + 1u), 1.0 - exp(-elapsed / (rate * settings.response_frames)));
 
         moments = mix(moments, sum / f32(count), alpha);
     } else if (updates == 0u) {
@@ -273,12 +456,18 @@ fn main(
 }
 `, [
             chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_layout,
             chunk_probe_clipmap_ray_texel,
+            chunk_probe_clipmap_guide,
             chunk_folded_workgroup_index,
             chunk_index_to_grid2d,
             chunk_f16_round_stochastic,
             chunk_pcg3d,
             chunk_hash_to_float01,
+            chunk_multiscale_mean,
+            F16_MAX_DEFINITION,
+            chunk_rgbe9995_decode,
             PROBE_RAY_STRUCT.declaration_chunk,
+            MULTISCALE_MEAN_STRUCT.declaration_chunk,
         ]),
 });

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

@@ -17,7 +17,7 @@ export const PROBE_ADMIT_SETTINGS: WebGPUStruct;
  * Admit (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a point wanted this frame, dispatched
  * through `PROBE_DISPATCH_ADMIT`.
  *
- * A point that has a probe has its wanted time brought to the frame's. One that has none pops a slot:
+ * A point that has a probe has its wanted frame brought to this one. One that has none pops a slot:
  * the slot becomes a NEW probe at the point the cascade's window holds in that storage cell, with
  * nothing traced, its indirection entry names it, and it goes on the frame's active list. A pop the
  * free list cannot serve is counted, and the host grows the capacity on it (§7.10's pattern); the
@@ -26,6 +26,10 @@ export const PROBE_ADMIT_SETTINGS: WebGPUStruct;
  * Either way the probe is marked the screen's when its entry carries `PROBE_WANTED_SCREEN`, and the
  * hits' when it does not, which decides whether its hits want in turn.
  *
+ * A probe this frame's want leaves waiting for an update, that was not before, is counted into
+ * `PROBE_COUNTER_WAITING` beside retire's: one an update served since it was last wanted, and a NEW one.
+ * A probe that already waited, NEW or wanted since its last update, retire counted.
+ *
  * Retire ran first, so an entry that names a slot names the probe of this very point: the window holds
  * one point a storage cell, and a probe whose point left was freed.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_admit.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_admit.js"],"names":[],"mappings":"AAuBA;;GAEG;AACH,2CAFU,YAAY,CAKU;AAUhC;;;;;GAKG;AACH,iDAFU,aAAa,CAqBpB;AAEH;;GAEG;AACH,mCAFU,YAAY,CAWG;AAgBzB;;;;;;;;;;;;;;;;;GAiBG;AACH,yCAFU,aAAa,CAiEpB;6BAvK0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_admit.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_admit.js"],"names":[],"mappings":"AAwBA;;GAEG;AACH,2CAFU,YAAY,CAKU;AAUhC;;;;;GAKG;AACH,iDAFU,aAAa,CAqBpB;AAEH;;GAEG;AACH,mCAFU,YAAY,CAWG;AAgBzB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yCAFU,aAAa,CAsEpB;6BAhL0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -2,10 +2,11 @@ import { chunk_collection_u32_append } from "../../../gpu_primitive/chunk_collec
 import { chunk_folded_dispatch } from "../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
 import { chunk_slot_stack } from "../../../gpu_primitive/slot_stack/chunk_slot_stack.js";
 import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_subgroup_atomic_add } from "../../../shader/chunk/subgroup/chunk_subgroup_atomic_add.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 { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import {
     chunk_probe_clipmap,
@@ -74,8 +75,8 @@ export const PROBE_ADMIT_SETTINGS = WebGPUStruct.from({
     resolution: u32,
     /** keys over every cascade: what the wanted list holds at most */
     key_count: u32,
-    /** the frame's time, seconds since the clipmap was made */
-    time: f32,
+    /** the frame, of the frames the clipmap has recorded */
+    frame: u32,
 }, "ProbeAdmitSettings");
 
 const resources = new ShaderResourceSetDescriptor();
@@ -96,7 +97,7 @@ resources.createGroup()
  * Admit (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a point wanted this frame, dispatched
  * through `PROBE_DISPATCH_ADMIT`.
  *
- * A point that has a probe has its wanted time brought to the frame's. One that has none pops a slot:
+ * A point that has a probe has its wanted frame brought to this one. One that has none pops a slot:
  * the slot becomes a NEW probe at the point the cascade's window holds in that storage cell, with
  * nothing traced, its indirection entry names it, and it goes on the frame's active list. A pop the
  * free list cannot serve is counted, and the host grows the capacity on it (§7.10's pattern); the
@@ -105,6 +106,10 @@ resources.createGroup()
  * Either way the probe is marked the screen's when its entry carries `PROBE_WANTED_SCREEN`, and the
  * hits' when it does not, which decides whether its hits want in turn.
  *
+ * A probe this frame's want leaves waiting for an update, that was not before, is counted into
+ * `PROBE_COUNTER_WAITING` beside retire's: one an update served since it was last wanted, and a NEW one.
+ * A probe that already waited, NEW or wanted since its last update, retire counted.
+ *
  * Retire ran first, so an entry that names a slot names the probe of this very point: the window holds
  * one point a storage cell, and a probe whose point left was freed.
  *
@@ -125,20 +130,25 @@ fn main(
 
     var slot = 0u;
     var admitted = false;
+    var waits = false;
 
     if (index < min(probe_wanted.count, settings.key_count)) {
         let resolution = settings.resolution;
         let wanted = probe_wanted.elements[index];
         let key = wanted & ~PROBE_WANTED_SCREEN;
-        let screen = select(0u, 1u, (wanted & PROBE_WANTED_SCREEN) != 0u);
+        let screen = (wanted & PROBE_WANTED_SCREEN) != 0u;
         let cascade = probe_clipmap_key_cascade(key, resolution);
         let storage = probe_clipmap_key_storage(key, resolution);
         let texel = probe_clipmap_indirection_texel(cascade, storage, resolution);
         let entry = textureLoad(probe_indirection, texel).x;
 
         if (entry != PROBE_CLIPMAP_NONE) {
-            probe_records[entry].wanted_time = settings.time;
-            probe_records[entry].screen = screen;
+            let waited = probe_state_kind(probe_states[entry].x) == PROBE_STATE_NEW || probe_records[entry].wanted_frame > probe_records[entry].traced_frame;
+
+            probe_records[entry].wanted_frame = settings.frame;
+            probe_records[entry].flags = (probe_records[entry].flags & ~PROBE_RECORD_SCREEN) | select(0u, PROBE_RECORD_SCREEN, screen);
+
+            waits = !waited;
         } else {
             slot = slot_stack_pop(&probe_counters[PROBE_COUNTER_FREE], &probe_free, settings.capacity);
 
@@ -147,13 +157,10 @@ fn main(
             } else {
                 // field by field: nothing of the slot's last probe stays
                 probe_records[slot].cell = probe_clipmap_window_point(storage, probe_levels[cascade].corner, resolution);
-                probe_records[slot].cascade = cascade;
-                probe_records[slot].wanted_time = settings.time;
-                probe_records[slot].traced_time = settings.time;
-                probe_records[slot].back_face = 0.0;
-                probe_records[slot].screen = screen;
-                probe_records[slot].sh.CoCg = vec2<f32>(0.0);
-                probe_records[slot].sh.Y = vec4<f32>(0.0);
+                probe_records[slot].flags = probe_record_flags(0.0, screen, cascade);
+                probe_records[slot].wanted_frame = settings.frame;
+                probe_records[slot].traced_frame = settings.frame;
+                probe_records[slot].sh = vec3<u32>(0u);
 
                 // at its lattice point until its first update relocates it
                 probe_states[slot] = vec2<u32>(probe_state(PROBE_STATE_NEW, 0u), 0u);
@@ -161,10 +168,12 @@ fn main(
                 textureStore(probe_indirection, texel, vec4<u32>(slot, 0u, 0u, 0u));
 
                 admitted = true;
+                waits = true;
             }
         }
     }
 
+    subgroup_atomic_add_u32(&probe_counters[PROBE_COUNTER_WAITING], select(0u, 1u, waits));
     collection_u32_append(&probe_active_write, admitted, slot, settings.capacity);
 }
 `, [
@@ -172,5 +181,6 @@ fn main(
             chunk_folded_workgroup_index,
             chunk_slot_stack,
             chunk_collection_u32_append,
+            chunk_subgroup_atomic_add,
         ]),
 });

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

@@ -5,14 +5,23 @@ export const PROBE_DUE_SETTINGS: WebGPUStruct;
 /**
  * Due (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): a thread an entry of the frame's active list,
  * dispatched twice through `PROBE_DISPATCH_ACTIVE` after schedule has set the period T. A probe is due
- * when a pixel or a hit wanted it this frame, its point's bit set, and:
- * - it is NEW, in the first pass, which lists them first;
- * - in the second pass, it is ALIVE and `(frame + h(slot)) mod T` is 0, or DEAD and
- *   `(frame + h(slot)) mod 8T` is 0, so that a probe inside a solid notices when the scene changes.
+ * when a want waits on it:
+ * - it is NEW, in the first pass, which lists them first: it has had no update;
+ * - in the second pass, it is ALIVE or DEAD, a pixel or a hit wanted it since its last update, its
+ *   wanted time past its traced time, and `(frame + h(slot)) mod T` is 0. A DEAD probe's update casts
+ *   the fewest rays (`PROBE_RAYS_PER_TEXEL_MIN`), every period rather than every eighth at R, so that a
+ *   probe inside a solid notices when the scene changes sooner, for fewer rays (Enshrouded's dead probes
+ *   trace 16 a frame).
+ *
+ * Wanted since its last update, not this frame: a hit wants a probe the frame after its own probe's
+ * update, so a probe that only hits keep is wanted on few of its turns. Measured on Sponza with the
+ * point's bit as the test, the hits' probes were updated 0.8 times a second at p10 against the screen's
+ * 6.6 at the least, and 6 s had passed since the last update at p99 (§8.3). A want an update served
+ * waits on nothing: the update comes after admit in its frame, so its traced time is the want's or later.
  *
  * The due go on the trace list, which holds the frame's updates, at most U: past it the count still
- * rises and nothing is written, and a probe not listed waits its next turn. With T = ⌈P_w / U⌉ the
- * expected count a frame is under U, so only NEW probes past U, a camera cut, wait.
+ * rises and nothing is written, and a probe not listed waits its next turn. With T = ⌈P_w / U⌉ over the
+ * probes waiting, the expected count a frame is under U, so only NEW probes past U, a camera cut, wait.
  *
  * @type {ComputeShader}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_due.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_due.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH,iCAFU,YAAY,CAaC;AAcvB;;;;;;;;;;;;;GAaG;AACH,uCAFU,aAAa,CAkDpB;6BAtG0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_due.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_due.js"],"names":[],"mappings":"AAkBA;;GAEG;AACH,iCAFU,YAAY,CAWC;AAavB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uCAFU,aAAa,CA4CpB;6BArG0B,sCAAsC;8BAHrC,kCAAkC"}