@woosh/meep-engine 3.60.5 → 3.60.7

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

@@ -1,16 +1,17 @@
+import { chunk_rgbe9995_decode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_decode.js";
 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_divide_round_up_u32 } from "../../../shader/chunk/math/chunk_divide_round_up_u32.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";
 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 { BRICK_TRACE_MISS, BRICK_TRACE_UNRESOLVED } from "../brick/BRICK_CLIPMAP.js";
 import {
@@ -27,7 +28,6 @@ import {
     PROBE_RAY_STRUCT,
     PROBE_RAY_SUMS_READ_RESOURCE,
     PROBE_RAYS_READ_RESOURCE,
-    PROBE_RECORDS_READ_RESOURCE,
     PROBE_RESAMPLES_READ_RESOURCE,
     PROBE_STATES_READ_RESOURCE,
     PROBE_TRACE_READ_RESOURCE
@@ -39,7 +39,9 @@ import {
     PROBE_DEPTH_LIMIT,
     PROBE_DEPTH_TEXEL_RAYS,
     PROBE_RADIANCE_SAMPLES_LIMIT,
-    PROBE_THREAD_WORKGROUP_SIZE
+    PROBE_SHORT_BLEND,
+    PROBE_THREAD_WORKGROUP_SIZE,
+    PROBE_VARIANCE_BLEND
 } from "./PROBE_CLIPMAP.js";
 
 /**
@@ -56,12 +58,10 @@ export const PROBE_ACCUMULATE_SETTINGS = WebGPUStruct.from({
     depth_resolution: u32,
     /** tiles a row of the radiance atlas */
     radiance_tiles_per_row: u32,
+    /** texels of skirt around a radiance tile's map on each side: 1, or 0 for a clipmap whose radiance is never sampled */
+    radiance_skirt: u32,
     /** tiles a row of the depth atlas */
     depth_tiles_per_row: u32,
-    /** 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");
@@ -76,7 +76,6 @@ resources.createGroup()
     .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)
@@ -103,13 +102,12 @@ resources.createGroup()
  * - **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 short mean blends by β = max(1/(a+1), `PROBE_SHORT_BLEND`), its variance by max(1/(a+1),
+ *     `PROBE_VARIANCE_BLEND`), a the texel's own count of the updates that reached it, held in its alpha.
+ *     A sample's blend is a sample's however long since the last one: a probe nobody wanted, or a texel the
+ *     guide passes over, takes no more of its next sample for the wait. A change in the light is the
+ *     estimator's to find. 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.
@@ -118,20 +116,17 @@ resources.createGroup()
  *   - A texel's first sample seeds both means. A texel no ray reached keeps its history.
  *   - Where the frame re-samples (`PROBE_CLIPMAP_RESAMPLING`), the sample pools the rays with the texel's
  *     re-samples of the probe's neighbours (`shader_probe_clipmap_resample`), each a ray's worth at a
- *     visibility of one (`chunk_probe_clipmap_resampled`). Only a texel some ray reached takes them: its
- *     time terms are a sampled texel's.
+ *     visibility of one (`chunk_probe_clipmap_resampled`). Only a texel some ray reached takes them.
  * - **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
+ *   sample is the plain mean, blended by the probe's α = max(1/(n+1), `PROBE_SHORT_BLEND`), 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
@@ -210,16 +205,6 @@ fn probe_accumulate_guided_rays(base: u32, texel: u32, updates: u32, rays: u32,
     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>,
@@ -245,7 +230,6 @@ fn main(
     let rays = span.y;
     let first_ray = span.x;
     let updates = probe_state_updates(probe_states[slot].x);
-    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);
@@ -278,7 +262,7 @@ fn main(
             back_faces += select(0u, 1u, (record.flags & PROBE_RAY_BACK_FACE) != 0u);
         }
 
-        let tile = index_to_grid2d(slot, settings.radiance_tiles_per_row) * (n + 2u) + 1u;
+        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);
 
         var texel = history;
@@ -292,15 +276,11 @@ fn main(
             let pooled = probe_clipmap_resampled(k * texels + i, sum, count);
             let sample = pooled.rgb / pooled.w;
             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)));
@@ -310,10 +290,10 @@ fn main(
                 e = multiscale_mean_add(
                     before,
                     sample,
-                    max(ramp, 1.0 - exp(-gap)),
-                    max(ramp, variance_time),
+                    max(ramp, ${PROBE_SHORT_BLEND}),
+                    max(ramp, ${PROBE_VARIANCE_BLEND}),
                     select(0.0, ramp, history.a < ${PROBE_RADIANCE_SAMPLES_LIMIT}.0),
-                    ramp <= variance_time,
+                    ramp <= ${PROBE_VARIANCE_BLEND},
                 );
             }
 
@@ -339,8 +319,6 @@ 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
@@ -351,9 +329,7 @@ fn main(
             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));
+                let stride = max(divide_round_up_u32(run.y, budget), 1u);
 
                 var texel_sum = vec2<f32>(0.0);
                 var texel_count = 0u;
@@ -390,8 +366,6 @@ 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);
 
@@ -419,9 +393,6 @@ fn main(
         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 < gathered; round++) {
             let ray = select(probe_clipmap_texel_ray(texel, round, updates, rays, texels), run.x + round, guided);
 
@@ -449,12 +420,7 @@ fn main(
     var moments = textureLoad(probe_depth, tile + at, 0).rg;
 
     if (count > 0u) {
-        // 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);
+        moments = mix(moments, sum / f32(count), max(1.0 / f32(updates + 1u), ${PROBE_SHORT_BLEND}));
     } else if (updates == 0u) {
         moments = vec2<f32>(${PROBE_DEPTH_LIMIT}, ${PROBE_DEPTH_LIMIT} * ${PROBE_DEPTH_LIMIT});
     }
@@ -472,6 +438,7 @@ fn main(
             chunk_probe_clipmap_resampled,
             chunk_folded_workgroup_index,
             chunk_index_to_grid2d,
+            chunk_divide_round_up_u32,
             chunk_f16_round_stochastic,
             chunk_pcg3d,
             chunk_hash_to_float01,

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

@@ -23,9 +23,6 @@ export const PROBE_ADMIT_SETTINGS: WebGPUStruct;
  * free list cannot serve is counted, and the host grows the capacity on it (§7.10's pattern); the
  * point is wanted again the next frame.
  *
- * 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.

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":"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"}
+{"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":"AAyBA;;GAEG;AACH,2CAFU,YAAY,CAKU;AAUhC;;;;;GAKG;AACH,iDAFU,aAAa,CAsBpB;AAEH;;GAEG;AACH,mCAFU,YAAY,CAWG;AAgBzB;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCAFU,aAAa,CAmEpB;6BA3K0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -1,5 +1,6 @@
 import { chunk_collection_u32_append } from "../../../gpu_primitive/chunk_collection_u32_append.js";
 import { chunk_folded_dispatch } from "../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { chunk_divide_round_up_u32 } from "../../../shader/chunk/math/chunk_divide_round_up_u32.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";
@@ -26,8 +27,8 @@ import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
  * @type {WebGPUStruct}
  */
 export const PROBE_ADMIT_COMMAND_SETTINGS = WebGPUStruct.from({
-    /** keys over every cascade: what the wanted list holds at most */
-    key_count: u32,
+    /** what the wanted list holds at most: every key, or fewer where the wants cannot want more */
+    wanted_capacity: u32,
 }, "ProbeAdmitCommandSettings");
 
 const command_resources = new ShaderResourceSetDescriptor();
@@ -52,8 +53,8 @@ export const shader_probe_clipmap_admit_command = ComputeShader.from({
         `
 @compute @workgroup_size(1)
 fn main() {
-    let wanted = min(probe_wanted.count, settings.key_count);
-    let folded = folded_dispatch((wanted + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+    let wanted = min(probe_wanted.count, settings.wanted_capacity);
+    let folded = folded_dispatch(divide_round_up_u32(wanted, PROBE_THREAD_WORKGROUP_SIZE));
 
     probe_dispatch[PROBE_DISPATCH_ADMIT] = folded.x;
     probe_dispatch[PROBE_DISPATCH_ADMIT + 1u] = folded.y;
@@ -61,6 +62,7 @@ fn main() {
 }
 `, [
             chunk_probe_clipmap,
+            chunk_divide_round_up_u32,
             chunk_folded_dispatch,
         ]),
 });
@@ -73,8 +75,8 @@ export const PROBE_ADMIT_SETTINGS = WebGPUStruct.from({
     capacity: u32,
     /** lattice points a cascade's window has a side */
     resolution: u32,
-    /** keys over every cascade: what the wanted list holds at most */
-    key_count: u32,
+    /** what the wanted list holds at most: every key, or fewer where the wants cannot want more */
+    wanted_capacity: u32,
     /** the frame, of the frames the clipmap has recorded */
     frame: u32,
 }, "ProbeAdmitSettings");
@@ -103,9 +105,6 @@ resources.createGroup()
  * free list cannot serve is counted, and the host grows the capacity on it (§7.10's pattern); the
  * point is wanted again the next frame.
  *
- * 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.
@@ -132,11 +131,9 @@ fn main(
     var admitted = false;
     var waits = false;
 
-    if (index < min(probe_wanted.count, settings.key_count)) {
+    if (index < min(probe_wanted.count, settings.wanted_capacity)) {
         let resolution = settings.resolution;
-        let wanted = probe_wanted.elements[index];
-        let key = wanted & ~PROBE_WANTED_SCREEN;
-        let screen = (wanted & PROBE_WANTED_SCREEN) != 0u;
+        let key = probe_wanted.elements[index];
         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);
@@ -146,7 +143,6 @@ fn main(
             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 {
@@ -157,7 +153,7 @@ 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].flags = probe_record_flags(0.0, screen, cascade);
+                probe_records[slot].flags = probe_record_flags(0.0, cascade);
                 probe_records[slot].wanted_frame = settings.frame;
                 probe_records[slot].traced_frame = settings.frame;
                 probe_records[slot].sh = vec3<u32>(0u);

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

@@ -0,0 +1,26 @@
+/**
+ * The next bounce a front-face hit takes, E_ind (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7;
+ * WORLD_PROBE_CACHE_SCOPE_2026_11_01.md §1.4): a thread a ray, after the light pass through the same launch,
+ * `PROBE_DISPATCH_RAYS`. It adds ρ_d·E_ind/π to the ray's light, ρ_d the albedo shade left in its `row`.
+ *
+ * - **The first clipmap**: the frustum's probes, picked at the hit along its normal, the view back along
+ *   the ray, with the ray's own jitter as the noise (`probe_clipmap_pick_in`).
+ * - **Where it has probes**, their SH is the bounce, and the ray's `row` is cleared: a hit the first clipmap
+ *   serves wants nothing of the fallback (`shader_probe_clipmap_want_hits`).
+ * - **Where it has none**, the fallback's, the world cache's: the same pick there, at its own spacing.
+ * - **Where neither has**, the bounce is **zero**, not the environment: a hit behind the camera in a cave
+ *   must not bring daylight in. The next frame's hits' wants ask the fallback for the probes it read, so the
+ *   bounce has them a frame or two later.
+ *
+ * "Has probes" is the pick's own answer, some corner weighing anything: NEW, DEAD and occluded probes count as
+ * none. The records hold the SH their projection last wrote, at most a frame old, so each frame takes one more
+ * bounce. LPV's 0.97 a bounce is dropped: an albedo under one bounds the series already.
+ *
+ * Every probe ray takes it, of either clipmap; only the frustum's rays' rows are read after, by the world
+ * cache's wants.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_bounce: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_bounce.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_bounce.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_bounce.js"],"names":[],"mappings":"AAuEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0CAFU,aAAa,CAgFpB;8BAjK2B,kCAAkC"}

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

@@ -0,0 +1,173 @@
+import { chunk_rgbe9995_decode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_decode.js";
+import { chunk_rgbe9995_encode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_encode.js";
+import { CLIPMAP_LEVEL_ARRAY } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import {
+    chunk_uv_octahedral_unit_decode
+} from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import {
+    chunk_resolve_irradiance_sh_to_diffuse
+} from "../../../shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_diffuse.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { vec2u } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import { BRICK_TRACE_HIT } from "../brick/BRICK_CLIPMAP.js";
+import {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_ray_jitter,
+    chunk_probe_clipmap_ray_layout,
+    chunk_probe_clipmap_ray_origin,
+    chunk_probe_clipmap_ray_texel,
+    PROBE_ORIGINS_READ_RESOURCE,
+    PROBE_RAY_SUMS_READ_RESOURCE,
+    PROBE_RAYS_WRITE_RESOURCE,
+    PROBE_RECORD_STRUCT,
+    PROBE_STATES_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import {
+    chunk_probe_clipmap_pick_in,
+    PROBE_DEPTH_SAMPLER_RESOURCE,
+    PROBE_SAMPLING_STRUCT
+} from "./chunk_probe_clipmap_pick.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+import { PROBE_TRACE_SETTINGS } from "./shader_probe_clipmap_trace.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_TRACE_SETTINGS);
+
+// the rays and their probes, of the clipmap whose update this is
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_ORIGINS_READ_RESOURCE)
+    .add(PROBE_RAYS_WRITE_RESOURCE)
+    .add(PROBE_RAY_SUMS_READ_RESOURCE)
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(STBN_VEC2_RESOURCE)
+    .add(PROBE_DEPTH_SAMPLER_RESOURCE);
+
+// the clipmap a hit takes its bounce from first: the frustum's probes
+resources.createGroup()
+    .add(ShaderResourceDescriptor.uniform("bounce_first_levels", CLIPMAP_LEVEL_ARRAY))
+    .add(ShaderResourceDescriptor.uniform("bounce_first_sampling", PROBE_SAMPLING_STRUCT))
+    .add(ShaderResourceDescriptor.texture("bounce_first_indirection", "uint", "3d"))
+    .add(ShaderResourceDescriptor.storageBuffer("bounce_first_states", WebGPUArray.from(vec2u)))
+    .add(ShaderResourceDescriptor.storageBuffer("bounce_first_records", WebGPUArray.from(PROBE_RECORD_STRUCT)))
+    .add(ShaderResourceDescriptor.texture("bounce_first_depth", "float", "2d"));
+
+// the clipmap it falls back to where the first has no probe: the world cache
+resources.createGroup()
+    .add(ShaderResourceDescriptor.uniform("bounce_fallback_levels", CLIPMAP_LEVEL_ARRAY))
+    .add(ShaderResourceDescriptor.uniform("bounce_fallback_sampling", PROBE_SAMPLING_STRUCT))
+    .add(ShaderResourceDescriptor.texture("bounce_fallback_indirection", "uint", "3d"))
+    .add(ShaderResourceDescriptor.storageBuffer("bounce_fallback_states", WebGPUArray.from(vec2u)))
+    .add(ShaderResourceDescriptor.storageBuffer("bounce_fallback_records", WebGPUArray.from(PROBE_RECORD_STRUCT)))
+    .add(ShaderResourceDescriptor.texture("bounce_fallback_depth", "float", "2d"));
+
+/**
+ * The next bounce a front-face hit takes, E_ind (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7;
+ * WORLD_PROBE_CACHE_SCOPE_2026_11_01.md §1.4): a thread a ray, after the light pass through the same launch,
+ * `PROBE_DISPATCH_RAYS`. It adds ρ_d·E_ind/π to the ray's light, ρ_d the albedo shade left in its `row`.
+ *
+ * - **The first clipmap**: the frustum's probes, picked at the hit along its normal, the view back along
+ *   the ray, with the ray's own jitter as the noise (`probe_clipmap_pick_in`).
+ * - **Where it has probes**, their SH is the bounce, and the ray's `row` is cleared: a hit the first clipmap
+ *   serves wants nothing of the fallback (`shader_probe_clipmap_want_hits`).
+ * - **Where it has none**, the fallback's, the world cache's: the same pick there, at its own spacing.
+ * - **Where neither has**, the bounce is **zero**, not the environment: a hit behind the camera in a cave
+ *   must not bring daylight in. The next frame's hits' wants ask the fallback for the probes it read, so the
+ *   bounce has them a frame or two later.
+ *
+ * "Has probes" is the pick's own answer, some corner weighing anything: NEW, DEAD and occluded probes count as
+ * none. The records hold the SH their projection last wrote, at most a frame old, so each frame takes one more
+ * bounce. LPV's 0.97 a bounce is dropped: an albedo under one bounds the series already.
+ *
+ * Every probe ray takes it, of either clipmap; only the frustum's rays' rows are read after, by the world
+ * cache's wants.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_bounce = ComputeShader.from({
+    label: "Probe Clipmap Bounce",
+    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 record = probe_rays[ray];
+    let albedo = unpack4x8unorm(record.row).rgb;
+    let front_hit = (record.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_HIT}u && (record.flags & PROBE_RAY_BACK_FACE) == 0u;
+
+    // only a front-face hit that bounces anything takes more light
+    if (!front_hit || all(albedo == vec3<f32>(0.0))) {
+        return;
+    }
+
+    // the probe's update's rays, and this one's place among them
+    let k = record.flags >> PROBE_RAY_PROBE_SHIFT;
+    let span = probe_clipmap_probe_rays(k);
+    let rays = span.y;
+    let i = ray - span.x;
+
+    let slot = probe_trace.elements[k];
+    let n = settings.radiance_resolution;
+    let updates = probe_state_updates(probe_states[slot].x);
+    let texel = probe_clipmap_ray_texel(i, updates, rays, n * n);
+
+    let direction = uv_octahedral_unit_decode(unpack2x16unorm(record.direction));
+    let position = probe_clipmap_ray_origin(probe_origins[k], slot, record.direction) + record.t * direction;
+    let normal = uv_octahedral_unit_decode(unpack2x16unorm(record.normal));
+    let noise = probe_clipmap_ray_jitter(slot, texel, i, updates, rays, n);
+
+    var probes = probe_clipmap_sh_in(
+        &bounce_first_records,
+        probe_clipmap_pick_in(&bounce_first_levels, &bounce_first_sampling, bounce_first_indirection, &bounce_first_states, bounce_first_depth, position, normal, -direction, noise),
+    );
+
+    if (probes.found) {
+        // served: nothing of the fallback is wanted here
+        probe_rays[ray].row = 0u;
+    } else {
+        probes = probe_clipmap_sh_in(
+            &bounce_fallback_records,
+            probe_clipmap_pick_in(&bounce_fallback_levels, &bounce_fallback_sampling, bounce_fallback_indirection, &bounce_fallback_states, bounce_fallback_depth, position, normal, -direction, noise),
+        );
+    }
+
+    if (!probes.found) {
+        return;
+    }
+
+    // E/π, as the resolve gives it
+    let e = resolve_irradiance_sh_to_diffuse(probes.sh.Y, probes.sh.CoCg, normal);
+
+    if (all(e == vec3<f32>(0.0))) {
+        return;
+    }
+
+    probe_rays[ray].light = rgbe9995_encode(rgbe9995_decode(record.light) + albedo * e);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_layout,
+            chunk_probe_clipmap_ray_texel,
+            chunk_probe_clipmap_ray_jitter,
+            chunk_probe_clipmap_ray_origin,
+            chunk_folded_workgroup_index,
+            chunk_uv_octahedral_unit_decode,
+            chunk_probe_clipmap_pick_in,
+            chunk_resolve_irradiance_sh_to_diffuse,
+            chunk_rgbe9995_decode,
+            chunk_rgbe9995_encode,
+        ]),
+});

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

@@ -0,0 +1,32 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_CANDIDATE_SETTINGS: WebGPUStruct;
+/**
+ * The candidate (Enshrouded's "pick neighbor candidates"): a thread a listed probe B, dispatched through
+ * `PROBE_DISPATCH_TRACED` after relocation, draws the one neighbour whose rays of this frame it re-samples
+ * (`shader_probe_clipmap_resample_rays`), and writes it to `probe_candidates`: its place in the list, or
+ * `PROBE_CLIPMAP_NONE`, and the weight its rays take.
+ *
+ * - **The neighbours**: the 26 around B's lattice point in its cascade. One is a candidate if it is ALIVE, its
+ *   record holds that point (the storage wraps), and it is listed this frame (`probe_clipmap_listed`), so that its
+ *   rays are in `probe_rays`. A NEW one is not. M counts them.
+ * - **The importance**: the neighbour's radiance, its irradiance's L0 luma, times B's visibility of it: Chebyshev
+ *   over B's depth moments toward it (`probe_visibility_chebyshev`), its distance in B's spacings held to the depth
+ *   limit, as the moments are. A dark neighbour, or one behind a wall, weighs about nothing.
+ * - **The draw**: one by its importance, a reservoir of one through the 26 with a hash of the slot, the update count
+ *   and the neighbour.
+ * - **The weight**: the draw's density divided out, `(1 / M) / p`, p the drawn one's importance over the sum: the
+ *   rays B takes are then, in expectation, every candidate's alike.
+ * - A probe whose first update this is, or a DEAD one, draws nothing: its depth is not yet its own, or it is
+ *   inside a solid.
+ *
+ * Reads the depth atlas as the last publish left it, and the frame's origins, records and states, which no pass
+ * after relocation writes before accumulate.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_candidate: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_candidate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_candidate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_candidate.js"],"names":[],"mappings":"AA6BA;;GAEG;AACH,uCAFU,YAAY,CAKO;AAqB7B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6CAFU,aAAa,CAuFpB;6BA9J0B,sCAAsC;8BAHrC,kCAAkC"}