@woosh/meep-engine 3.59.0 → 3.60.1

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

@@ -9,6 +9,7 @@ import {
     PROBE_ACTIVE_WRITTEN_RESOURCE,
     PROBE_COUNTERS_RESOURCE,
     PROBE_DISPATCH_RESOURCE,
+    PROBE_EVICTION_WRITE_RESOURCE,
     PROBE_WANTED_READ_RESOURCE
 } from "./chunk_probe_clipmap.js";
 
@@ -22,6 +23,8 @@ export const PROBE_SCHEDULE_SETTINGS = WebGPUStruct.from({
     key_count: u32,
     /** probes a frame updates at most, U = ⌊ray_budget / rays_per_probe⌋ */
     trace_capacity: u32,
+    /** slots kept free beyond the frame's wanted points, ⌈capacity · PROBE_FREE_SLACK⌉ */
+    slack: u32,
 }, "ProbeScheduleSettings");
 
 const resources = new ShaderResourceSetDescriptor();
@@ -32,17 +35,33 @@ resources.createGroup()
     .add(PROBE_ACTIVE_WRITTEN_RESOURCE)
     .add(PROBE_WANTED_READ_RESOURCE)
     .add(PROBE_COUNTERS_RESOURCE)
+    .add(PROBE_EVICTION_WRITE_RESOURCE)
     .add(PROBE_DISPATCH_RESOURCE);
 
 /**
- * Schedule (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, after admit, when the frame's active
- * list is whole.
- * - The period: with P_w the points wanted this frame, `T = max(1, ⌈P_w / U⌉)` frames, so that every
- *   wanted probe is updated once a period and the period follows the live count. It goes to
+ * Schedule (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3, §8.5): one thread, after admit, when the frame's
+ * active list is whole.
+ * - The period: with P_w the probes waiting for an update, the NEW and those wanted since their last
+ *   update, `T = max(1, ⌈P_w / U⌉)` frames, so that every probe a want waits on is updated within a period
+ *   and the period follows the live count. Retire and admit counted them in
+ *   `probe_counters[PROBE_COUNTER_WAITING]`, which it empties for the next frame's; the period goes to
  *   `probe_counters[PROBE_COUNTER_PERIOD]` for the due passes.
+ * - The next frame's eviction, `probe_eviction`: as many slots as the free ones fall short of the frame's
+ *   wanted points and the slack, the probes wanted longest ago first. Walking retire's age buckets from the
+ *   oldest, it asks for each bucket whole while the shortfall takes it, then for what is left of the
+ *   shortfall from the next; past the youngest bucket it counted anything in, it asks for nothing, so a
+ *   shortfall the evictable probes cannot cover frees them all and no more. It empties the buckets and
+ *   the count of a bucket's probes retire evicted.
  * - A thread an entry of the frame's active list, at `PROBE_DISPATCH_ACTIVE`: the due passes' launch, and
  *   the next frame's retire's, which reads this list.
  *
+ * A hit wants a probe the frame after its probe's update, so a probe hits keep may be wanted on few of
+ * its turns. The waiting count is what due lists over a period, where this frame's wanted points would
+ * count the probes a pixel wants every frame and miss most of those hits want between their turns.
+ *
+ * The frame's wanted points are the most a frame can admit, so the next frame's admissions find slots
+ * for as many points as this one wanted, and the slack more, before an admission starves.
+ *
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_schedule = ComputeShader.from({
@@ -53,10 +72,45 @@ export const shader_probe_clipmap_schedule = ComputeShader.from({
         `
 @compute @workgroup_size(1)
 fn main() {
-    let wanted = min(probe_wanted.count, settings.key_count);
+    let waiting = atomicLoad(&probe_counters[PROBE_COUNTER_WAITING]);
     let traced = max(settings.trace_capacity, 1u);
 
-    atomicStore(&probe_counters[PROBE_COUNTER_PERIOD], max((wanted + traced - 1u) / traced, 1u));
+    atomicStore(&probe_counters[PROBE_COUNTER_WAITING], 0u);
+    atomicStore(&probe_counters[PROBE_COUNTER_PERIOD], max((waiting + traced - 1u) / traced, 1u));
+
+    // the slots short of the frame's wanted points and the slack
+    let wanted = min(probe_wanted.count, settings.key_count);
+    let room = wanted + settings.slack;
+    let free = atomicLoad(&probe_counters[PROBE_COUNTER_FREE]);
+
+    var lacking = select(0u, room - free, room > free);
+    var buckets = 0u;
+    var remaining = 0u;
+
+    for (var k = 0u; k < PROBE_AGE_BUCKETS; k++) {
+        let at = PROBE_COUNTER_AGES + PROBE_AGE_BUCKETS - 1u - k;
+        let aged = atomicLoad(&probe_counters[at]);
+
+        atomicStore(&probe_counters[at], 0u);
+
+        // a bucket nothing was counted in is taken only for an older one: what ages into a bucket below every
+        // probe counted is not asked for
+        if (lacking > 0u && aged > 0u) {
+            if (aged <= lacking) {
+                lacking -= aged;
+                buckets = k + 1u;
+            } else {
+                buckets = k;
+                remaining = lacking;
+                lacking = 0u;
+            }
+        }
+    }
+
+    probe_eviction.buckets = buckets;
+    probe_eviction.remaining = remaining;
+
+    atomicStore(&probe_counters[PROBE_COUNTER_EVICTED], 0u);
 
     let live = min(probe_active_write.count, settings.capacity);
     let folded = folded_dispatch((live + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);

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

@@ -1,13 +1,15 @@
 /**
- * @type {WebGPUStruct}
- */
-export const PROBE_SHADE_SETTINGS: WebGPUStruct;
-/**
- * Shade (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a thread a ray of the frame's updates, R a listed
- * probe, dispatched through `PROBE_DISPATCH_RAYS` after trace. The radiance the ray brings back goes
- * over its light, three half floats:
+ * Shade (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a thread a ray of the frame's updates, dispatched
+ * through `PROBE_DISPATCH_RAYS` after trace, its probe the one trace wrote into its flags; a record of no
+ * ray (`PROBE_RAY_NONE`) is past the frame's last. The radiance the ray brings back goes over its light,
+ * three half floats:
  *
- * - a **miss** sees the environment along its direction, `sample_environment_color`;
+ * - a **miss** sees the prefiltered environment along its direction, `sample_environment_map`, at the
+ *   roughness whose lobe covers the solid angle of a radiance texel, 4π/n_r². The prefilter's lobe is the
+ *   spherical Gaussian exp(2(N·H − 1)/m²), m the roughness squared, whose integral over the sphere is
+ *   4πm²·(1 − (1 − e^(−k))/k), k = 2/m²: m = 1/n_r to 0.2% at n_r = 16, so the roughness is 1/√n_r. A sun
+ *   a few texels wide at level 0 is then a lobe a texel wide, which a texel's jittered rays all see,
+ *   rather than a point that only some probes' jitter ever lands on;
  * - a **front-face hit** is `emissive + ρ_d·E_dir/π` (D7), its surface from `probe_clipmap_hit_surface`
  *   at the hit's position, the probe's origin plus t along the ray, with the hit's normal, at its
  *   cascade's voxel; E_dir is what trace left in the light;
@@ -20,6 +22,5 @@ export const PROBE_SHADE_SETTINGS: WebGPUStruct;
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_shade: ComputeShader;
-import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_probe_clipmap_shade.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_shade.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_shade.js"],"names":[],"mappings":"AAyCA;;GAEG;AACH,mCAFU,YAAY,CAOG;AAyBzB;;;;;;;;;;;;;;;;GAgBG;AACH,yCAFU,aAAa,CAuDpB;6BA9H0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_shade.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_shade.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yCAFU,aAAa,CAyDpB;8BAxH2B,kCAAkC"}

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

@@ -1,4 +1,3 @@
-import { chunk_sample_environment_color } from "../../../atmosphere/chunk_sample_environment_color.js";
 import {
     MESH_CARD_ALBEDO_RESOURCE,
     MESH_CARD_EMISSIVE_RESOURCE,
@@ -9,14 +8,15 @@ import { MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
 import { MESH_SDF_HEADERS_RESOURCE, MESH_SDF_INDIRECTION_RESOURCE } from "../../../geometry/sdf/MESH_SDF_RESOURCES.js";
 import { ENVIRONMENT_MAP_SAMPLER_RESOURCE } from "../../../light/environment/ENVIRONMENT_MAP_SAMPLER_RESOURCE.js";
 import { SCENE_DATABASE_RESOURCE } from "../../../scene/SCENE_DATABASE_RESOURCE.js";
+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 { chunk_sample_environment_map } from "../../../shader/chunk/texture/sample/chunk_sample_environment_map.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 { RECIPROCAL_PI_DECLARATION } from "../../../shader/chunk/math/RECIPROCAL_PI_DECLARATION.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
-import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import { BRICK_TRACE_HIT, BRICK_TRACE_MISS } from "../brick/BRICK_CLIPMAP.js";
 import { BRICK_LEVELS_RESOURCE } from "../brick/chunk_brick_clipmap_trace.js";
 import {
@@ -26,32 +26,17 @@ import {
 } from "./chunk_probe_clipmap_hit_surface.js";
 import {
     chunk_probe_clipmap,
+    chunk_probe_clipmap_ray_origin,
     PROBE_ORIGINS_READ_RESOURCE,
     PROBE_RAYS_WRITE_RESOURCE,
     PROBE_TRACE_READ_RESOURCE
 } from "./chunk_probe_clipmap.js";
 import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
-
-/**
- * The largest finite half float: radiance past it would be infinite in the ray's record and in the
- * atlas after it, and an infinity times a zero weight is a NaN in every sum it reaches.
- * @type {number}
- */
-const HALF_MAX = 65504;
-
-/**
- * @type {WebGPUStruct}
- */
-export const PROBE_SHADE_SETTINGS = WebGPUStruct.from({
-    /** probes a frame updates at most: the trace list's bound */
-    trace_capacity: u32,
-    /** rays an update casts, R */
-    rays_per_probe: u32,
-}, "ProbeShadeSettings");
+import { PROBE_TRACE_SETTINGS } from "./shader_probe_clipmap_trace.js";
 
 const resources = new ShaderResourceSetDescriptor();
 
-resources.setImmediate("settings", PROBE_SHADE_SETTINGS);
+resources.setImmediate("settings", PROBE_TRACE_SETTINGS);
 
 resources.createGroup()
     .add(PROBE_TRACE_READ_RESOURCE)
@@ -73,11 +58,17 @@ resources.createGroup()
     .add(MESH_CARD_EMISSIVE_RESOURCE);
 
 /**
- * Shade (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a thread a ray of the frame's updates, R a listed
- * probe, dispatched through `PROBE_DISPATCH_RAYS` after trace. The radiance the ray brings back goes
- * over its light, three half floats:
+ * Shade (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a thread a ray of the frame's updates, dispatched
+ * through `PROBE_DISPATCH_RAYS` after trace, its probe the one trace wrote into its flags; a record of no
+ * ray (`PROBE_RAY_NONE`) is past the frame's last. The radiance the ray brings back goes over its light,
+ * three half floats:
  *
- * - a **miss** sees the environment along its direction, `sample_environment_color`;
+ * - a **miss** sees the prefiltered environment along its direction, `sample_environment_map`, at the
+ *   roughness whose lobe covers the solid angle of a radiance texel, 4π/n_r². The prefilter's lobe is the
+ *   spherical Gaussian exp(2(N·H − 1)/m²), m the roughness squared, whose integral over the sphere is
+ *   4πm²·(1 − (1 − e^(−k))/k), k = 2/m²: m = 1/n_r to 0.2% at n_r = 16, so the roughness is 1/√n_r. A sun
+ *   a few texels wide at level 0 is then a lobe a texel wide, which a texel's jittered rays all see,
+ *   rather than a point that only some probes' jitter ever lands on;
  * - a **front-face hit** is `emissive + ρ_d·E_dir/π` (D7), its surface from `probe_clipmap_hit_surface`
  *   at the hit's position, the probe's origin plus t along the ray, with the hit's normal, at its
  *   cascade's voxel; E_dir is what trace left in the light;
@@ -101,45 +92,47 @@ fn main(
     @builtin(local_invocation_index) lane: u32,
 ) {
     let ray = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
-    let rays = settings.rays_per_probe;
+    let record = probe_rays[ray];
+    let kind = record.flags & PROBE_RAY_KIND_MASK;
 
-    if (ray >= min(probe_trace.count, settings.trace_capacity) * rays) {
+    if (kind == PROBE_RAY_NONE) {
         return;
     }
-
-    let record = probe_rays[ray];
-    let kind = record.flags & PROBE_RAY_KIND_MASK;
     let direction = uv_octahedral_unit_decode(unpack2x16unorm(record.direction));
 
     var radiance = vec3<f32>(0.0);
     var albedo = vec3<f32>(0.0);
 
     if (kind == ${BRICK_TRACE_MISS}u) {
-        radiance = sample_environment_color(tEnvironment, sEnvironment, direction);
+        radiance = sample_environment_map(tEnvironment, sEnvironment, direction, inverseSqrt(f32(settings.radiance_resolution)));
     } else if (kind == ${BRICK_TRACE_HIT}u && (record.flags & PROBE_RAY_BACK_FACE) == 0u) {
-        let position = probe_origins[ray / rays].xyz + record.t * direction;
+        let k = record.flags >> PROBE_RAY_PROBE_SHIFT;
+        let origin = probe_clipmap_ray_origin(probe_origins[k], probe_trace.elements[k], record.direction);
+        let position = origin + record.t * direction;
         let normal = uv_octahedral_unit_decode(unpack2x16unorm(record.normal));
-        let voxel = brick_levels[record.flags >> PROBE_RAY_CASCADE_SHIFT].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+        let voxel = brick_levels[(record.flags >> PROBE_RAY_CASCADE_SHIFT) & PROBE_RAY_CASCADE_MASK].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
 
         let surface = probe_clipmap_hit_surface(record.row, position, normal, voxel);
-        let direct = vec3<f32>(unpack2x16float(record.light_rg), unpack2x16float(record.light_b).x);
+        let direct = rgbe9995_decode(record.light);
 
         radiance = surface.emissive + surface.albedo * direct * RECIPROCAL_PI;
         albedo = surface.albedo;
     }
 
-    let held = min(radiance, vec3<f32>(${HALF_MAX}.0));
-
-    probe_rays[ray].light_rg = pack2x16float(held.rg);
-    probe_rays[ray].light_b = pack2x16float(vec2<f32>(held.b, 0.0));
+    // held to RGB9E5's largest value, which the half-float atlas also holds: an infinity there times a
+    // zero weight would be a NaN in every sum it reaches
+    probe_rays[ray].light = rgbe9995_encode(radiance);
     probe_rays[ray].row = pack4x8unorm(vec4<f32>(albedo, 0.0));
 }
 `, [
             chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_origin,
             chunk_folded_workgroup_index,
             chunk_uv_octahedral_unit_decode,
-            chunk_sample_environment_color,
+            chunk_sample_environment_map,
             chunk_probe_clipmap_hit_surface,
+            chunk_rgbe9995_decode,
+            chunk_rgbe9995_encode,
             RECIPROCAL_PI_DECLARATION,
         ]),
 });

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

@@ -3,27 +3,34 @@
  */
 export const PROBE_TRACE_SETTINGS: WebGPUStruct;
 /**
- * Trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a ray of the frame's updates, R a listed
- * probe, dispatched through `PROBE_DISPATCH_RAYS`.
+ * Trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a ray of the frame's updates, dispatched
+ * through `PROBE_DISPATCH_RAYS`. The rays are laid out by listed probe (`probe_ray_sums`): a ray finds
+ * its probe by bisecting the sums, and its place among the probe's rays from the probe's first. A thread
+ * past the frame's last ray writes a record of no ray (`PROBE_RAY_NONE`), where the passes after stop.
  *
- * - **Texel**: `probe_clipmap_ray_texel`, all of them an update, or a spread subset below R = n_r².
+ * - **Texel**: on a uniform update (`PROBE_UNIFORM_PERIOD`), `probe_clipmap_ray_texel`: all of them,
+ *   or a spread subset below R = n_r². On a guided one, the walk position whose rays the ray is among
+ *   in the probe's guide (`chunk_probe_clipmap_guide`), found by bisecting the first rays. A texel's rays
+ *   then follow one another, in the walk's order.
  * - **Direction**: the texel's octahedral square, jittered by STBN at the texel, moved by the slot's
  *   hash so that neighbouring probes do not jitter alike, and at the update count: one stratified,
- *   jittered ray a texel, LPV's own pattern.
- * - **Origin**: the probe where relocation left it, `probe_origins`; t_min one voxel of the brick
- *   cascade there.
+ *   jittered ray a texel, LPV's own pattern. A guided texel's later rays rotate that jitter by R2
+ *   (`probe_clipmap_guided_ray_jitter`).
+ * - **Origin**: a point of a small ball around the probe where relocation left it, `probe_origins`, one a
+ *   ray (`probe_clipmap_ray_origin`); t_min one voxel of the brick cascade there.
  * - **Direct light**: a hit off a front face takes E_dir = Σ colour·max(0, n·l)·visibility over the
- *   directional lights (§8.7). The visibility is the brick clipmap's soft shadow toward each of the
- *   first {@link PROBE_SHADOWED_SUNS} lights that cast shadows, in the table's order, from a voxel off
- *   the hit along its normal, outside the half-voxel expand; lights past them are unshadowed at hits. A
- *   surface turned from a light marches no shadow toward it, since the light gives it nothing.
- *   - Measured on Sponza at 1280×720 with 131,072 rays, the shadows are about half of the pass on the
- *     AMD iGPU (7.9 ms against 4.2 without them) and most of it on the RTX 4090 (355 µs against 62). Most
- *     hits are on walls nearly parallel to a high sun, whose shadow rays graze them.
+ *   directional lights (§8.7). The visibility is a shadow ray, traced through the brick clipmap as the
+ *   ray itself was, toward each of the first {@link PROBE_SHADOWED_SUNS} lights that cast shadows, in the
+ *   table's order; lights past them are unshadowed at hits. It starts a voxel off the hit along its
+ *   normal, outside the half-voxel expand, and heads for a point of the light's disk drawn as the path
+ *   tracer draws it (`cone_sample_direction`), from the ray's slot and direction, so that the probe's
+ *   blend of its rays integrates the penumbra. The light is seen whole if the ray misses, and not at all
+ *   if it hits or spends its steps: what the march could not answer is no light, not all of it. A
+ *   surface turned from a light traces no ray toward it, since the light gives it nothing.
  * - **Back face**: a hit whose field's gradient is along the ray, so it came from inside a solid.
  *
  * Writes the ray's `PROBE_RAY_STRUCT`, with the `meshes` row of the hit's surface and E_dir as its
- * light, which shade turns into the ray's radiance.
+ * light, which shade turns into the ray's radiance, and its probe's place in the list in its flags.
  *
  * @type {ComputeShader}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_trace.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace.js"],"names":[],"mappings":"AAsCA;;GAEG;AACH,mCAFU,YAAY,CAaG;AAsBzB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,yCAFU,aAAa,CAkGpB;6BAvL0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_trace.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace.js"],"names":[],"mappings":"AA+CA;;GAEG;AACH,mCAFU,YAAY,CAeG;AAwBzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,yCAFU,aAAa,CAoJpB;6BAzP0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -2,10 +2,14 @@ import { MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
 import { LIGHT_DATA_RESOURCE } from "../../../light/LIGHT_DATA_RESOURCE.js";
 import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
 import { LIGHT_FLAGS } from "../../../light/model/io/LIGHT_FLAGS.js";
+import { chunk_cone_sample_direction } from "../../../shader/chunk/geometry/cone/chunk_cone_sample_direction.js";
 import { chunk_uv_octahedral_unit_decode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
 import { chunk_uv_octahedral_unit_encode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_encode.js";
+import { chunk_rgbe9995_encode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_encode.js";
 import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
 import { chunk_directional_lights_iteration_mask } from "../../../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
+import { chunk_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";
@@ -20,14 +24,19 @@ import {
     BRICK_OCCUPANCY_TEXTURE_RESOURCE,
     BRICK_SAMPLER_RESOURCE,
     chunk_brick_clipmap_object,
-    chunk_brick_clipmap_soft_shadow,
     chunk_brick_clipmap_trace
 } from "../brick/chunk_brick_clipmap_trace.js";
 import {
     chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    chunk_probe_clipmap_guided_ray_jitter,
     chunk_probe_clipmap_ray_jitter,
+    chunk_probe_clipmap_ray_layout,
+    chunk_probe_clipmap_ray_origin,
     chunk_probe_clipmap_ray_texel,
+    PROBE_GUIDE_READ_RESOURCE,
     PROBE_ORIGINS_READ_RESOURCE,
+    PROBE_RAY_SUMS_READ_RESOURCE,
     PROBE_RAYS_WRITE_RESOURCE,
     PROBE_STATES_READ_RESOURCE,
     PROBE_TRACE_READ_RESOURCE
@@ -42,7 +51,7 @@ const DIRECTIONAL = LIGHT_DATABASE_SPEC.get('light_directional');
 export const PROBE_TRACE_SETTINGS = WebGPUStruct.from({
     /** probes a frame updates at most: the trace list's bound */
     trace_capacity: u32,
-    /** rays an update casts, R, a power of two */
+    /** rays a uniform update casts, R, a power of two; a guided update casts its probe's own (`probe_ray_sums`) */
     rays_per_probe: u32,
     /** octahedral radiance texels a side, n_r, a power of two */
     radiance_resolution: u32,
@@ -50,6 +59,8 @@ export const PROBE_TRACE_SETTINGS = WebGPUStruct.from({
     brick_cascade_count: u32,
     /** how far a ray goes before it is a miss, metres: across the coarsest window */
     t_max: f32,
+    /** updates between a probe's uniform ones, `PROBE_UNIFORM_PERIOD` */
+    uniform_period: u32,
 }, "ProbeTraceSettings");
 
 const resources = new ShaderResourceSetDescriptor();
@@ -61,6 +72,8 @@ 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_GUIDE_READ_RESOURCE)
     .add(STBN_VEC2_RESOURCE)
     .add(LIGHT_DATA_RESOURCE);
 
@@ -73,27 +86,34 @@ resources.createGroup()
     .add(BRICK_OBJECTS_RESOURCE);
 
 /**
- * Trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a ray of the frame's updates, R a listed
- * probe, dispatched through `PROBE_DISPATCH_RAYS`.
+ * Trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a ray of the frame's updates, dispatched
+ * through `PROBE_DISPATCH_RAYS`. The rays are laid out by listed probe (`probe_ray_sums`): a ray finds
+ * its probe by bisecting the sums, and its place among the probe's rays from the probe's first. A thread
+ * past the frame's last ray writes a record of no ray (`PROBE_RAY_NONE`), where the passes after stop.
  *
- * - **Texel**: `probe_clipmap_ray_texel`, all of them an update, or a spread subset below R = n_r².
+ * - **Texel**: on a uniform update (`PROBE_UNIFORM_PERIOD`), `probe_clipmap_ray_texel`: all of them,
+ *   or a spread subset below R = n_r². On a guided one, the walk position whose rays the ray is among
+ *   in the probe's guide (`chunk_probe_clipmap_guide`), found by bisecting the first rays. A texel's rays
+ *   then follow one another, in the walk's order.
  * - **Direction**: the texel's octahedral square, jittered by STBN at the texel, moved by the slot's
  *   hash so that neighbouring probes do not jitter alike, and at the update count: one stratified,
- *   jittered ray a texel, LPV's own pattern.
- * - **Origin**: the probe where relocation left it, `probe_origins`; t_min one voxel of the brick
- *   cascade there.
+ *   jittered ray a texel, LPV's own pattern. A guided texel's later rays rotate that jitter by R2
+ *   (`probe_clipmap_guided_ray_jitter`).
+ * - **Origin**: a point of a small ball around the probe where relocation left it, `probe_origins`, one a
+ *   ray (`probe_clipmap_ray_origin`); t_min one voxel of the brick cascade there.
  * - **Direct light**: a hit off a front face takes E_dir = Σ colour·max(0, n·l)·visibility over the
- *   directional lights (§8.7). The visibility is the brick clipmap's soft shadow toward each of the
- *   first {@link PROBE_SHADOWED_SUNS} lights that cast shadows, in the table's order, from a voxel off
- *   the hit along its normal, outside the half-voxel expand; lights past them are unshadowed at hits. A
- *   surface turned from a light marches no shadow toward it, since the light gives it nothing.
- *   - Measured on Sponza at 1280×720 with 131,072 rays, the shadows are about half of the pass on the
- *     AMD iGPU (7.9 ms against 4.2 without them) and most of it on the RTX 4090 (355 µs against 62). Most
- *     hits are on walls nearly parallel to a high sun, whose shadow rays graze them.
+ *   directional lights (§8.7). The visibility is a shadow ray, traced through the brick clipmap as the
+ *   ray itself was, toward each of the first {@link PROBE_SHADOWED_SUNS} lights that cast shadows, in the
+ *   table's order; lights past them are unshadowed at hits. It starts a voxel off the hit along its
+ *   normal, outside the half-voxel expand, and heads for a point of the light's disk drawn as the path
+ *   tracer draws it (`cone_sample_direction`), from the ray's slot and direction, so that the probe's
+ *   blend of its rays integrates the penumbra. The light is seen whole if the ray misses, and not at all
+ *   if it hits or spends its steps: what the march could not answer is no light, not all of it. A
+ *   surface turned from a light traces no ray toward it, since the light gives it nothing.
  * - **Back face**: a hit whose field's gradient is along the ray, so it came from inside a solid.
  *
  * Writes the ray's `PROBE_RAY_STRUCT`, with the `meshes` row of the hit's surface and E_dir as its
- * light, which shade turns into the ray's radiance.
+ * light, which shade turns into the ray's radiance, and its probe's place in the list in its flags.
  *
  * @type {ComputeShader}
  */
@@ -103,32 +123,71 @@ export const shader_probe_clipmap_trace = ComputeShader.from({
     body: CodeChunk.from(
         //language=WGSL
         `
+// the walk position among whose rays a ray of the probe falls, its guide starting at word base: the last
+// whose first ray is at most it
+fn probe_trace_guided_position(base: u32, ray: u32, texels: u32) -> u32 {
+    var low = 0u;
+    var high = texels;
+
+    // the first ray of position 0 is 0, so the low end always qualifies; log2(n_r²) steps
+    while (high - low > 1u) {
+        let middle = low + ((high - low) >> 1u);
+
+        if (probe_guide[base + middle] <= ray) {
+            low = middle;
+        } else {
+            high = middle;
+        }
+    }
+
+    return low;
+}
+
 @compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
 fn main(
     @builtin(workgroup_id) workgroup_id: vec3<u32>,
     @builtin(local_invocation_index) lane: u32,
 ) {
     let ray = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
-    let rays = settings.rays_per_probe;
+    let k = probe_clipmap_ray_probe(ray);
+
+    if (k >= probe_ray_sums.count) {
+        probe_rays[ray].row = 0u;
+        probe_rays[ray].flags = PROBE_RAY_NONE;
 
-    if (ray >= min(probe_trace.count, settings.trace_capacity) * rays) {
         return;
     }
 
-    let slot = probe_trace.elements[ray / rays];
-    let i = ray % rays;
+    // the update's rays, and this one's place among them
+    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 texels = n * n;
     let state = probe_states[slot];
     let updates = probe_state_updates(state.x);
 
-    let texel = probe_clipmap_ray_texel(i, updates, rays, texels);
-    let jitter = probe_clipmap_ray_jitter(slot, texel, i, updates, rays, n);
+    var texel: u32;
+    var jitter: vec2<f32>;
+
+    if (probe_clipmap_guided(state.x, settings.uniform_period, settings.rays_per_probe, texels)) {
+        let base = k * probe_clipmap_guide_words(n);
+        let position = probe_trace_guided_position(base, i, texels);
+
+        texel = probe_clipmap_guide_texel(position, updates, n);
+        jitter = probe_clipmap_guided_ray_jitter(slot, texel, i - probe_guide[base + position], updates, rays, n);
+    } else {
+        texel = probe_clipmap_ray_texel(i, updates, rays, texels);
+        jitter = probe_clipmap_ray_jitter(slot, texel, i, updates, rays, n);
+    }
 
     let direction = uv_octahedral_unit_decode((vec2<f32>(f32(texel % n), f32(texel / n)) + jitter) / f32(n));
+    let packed = pack2x16unorm(uv_octahedral_unit_encode(direction));
 
-    let origin = probe_origins[ray / rays].xyz;
+    let origin = probe_clipmap_ray_origin(probe_origins[k], slot, packed);
 
     let cascade_count = settings.brick_cascade_count;
     let start = brick_clipmap_start(origin, cascade_count);
@@ -159,10 +218,15 @@ fn main(
             var visible = 1.0;
 
             if ((light.flags & ${LIGHT_FLAGS.CASTS_SHADOW_BIT}u) != 0u && shadowed < ${PROBE_SHADOWED_SUNS}u) {
-                // a surface turned from the light takes none of it whatever the shadow, so it marches none;
+                // a surface turned from the light takes none of it whatever the shadow, so it traces none;
                 // the light keeps its place among the shadowed all the same
                 if (n_dot_l > 0.0) {
-                    visible = brick_clipmap_soft_shadow(lifted, -light.direction, 0.0, settings.t_max, sin(light.disk_radius), cascade_count);
+                    // a point of the disk of its own for each light, apart from the origin's draw
+                    let hash = pcg3d(vec3<u32>(slot, packed, 0x3C6EF372u + shadowed));
+                    let toward = cone_sample_direction(-light.direction, light.disk_radius, vec2<f32>(hash_to_float01(hash.x), hash_to_float01(hash.y)));
+                    let shadow = brick_clipmap_trace(lifted, toward, 0.0, settings.t_max, cascade_count);
+
+                    visible = select(0.0, 1.0, shadow.kind == BRICK_TRACE_MISS);
                 }
 
                 shadowed++;
@@ -173,24 +237,30 @@ fn main(
     }
 
     probe_rays[ray].t = hit.t;
-    probe_rays[ray].direction = pack2x16unorm(uv_octahedral_unit_encode(direction));
+    probe_rays[ray].direction = packed;
     probe_rays[ray].normal = select(0u, pack2x16unorm(uv_octahedral_unit_encode(hit.normal)), is_hit);
     probe_rays[ray].row = brick_clipmap_object(hit);
-    probe_rays[ray].flags = hit.kind | select(0u, PROBE_RAY_BACK_FACE, back_face) | (select(0u, hit.cascade, is_hit) << PROBE_RAY_CASCADE_SHIFT);
-    probe_rays[ray].light_rg = pack2x16float(direct.rg);
-    probe_rays[ray].light_b = pack2x16float(vec2<f32>(direct.b, 0.0));
+    probe_rays[ray].flags = hit.kind | select(0u, PROBE_RAY_BACK_FACE, back_face) | (select(0u, hit.cascade, is_hit) << PROBE_RAY_CASCADE_SHIFT) | (k << PROBE_RAY_PROBE_SHIFT);
+    probe_rays[ray].light = rgbe9995_encode(direct);
 }
 `, [
             chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_layout,
             chunk_probe_clipmap_ray_texel,
             chunk_probe_clipmap_ray_jitter,
+            chunk_probe_clipmap_ray_origin,
+            chunk_probe_clipmap_guide,
+            chunk_probe_clipmap_guided_ray_jitter,
             chunk_folded_workgroup_index,
             chunk_uv_octahedral_unit_decode,
             chunk_uv_octahedral_unit_encode,
             chunk_brick_clipmap_trace,
             chunk_brick_clipmap_object,
-            chunk_brick_clipmap_soft_shadow,
+            chunk_cone_sample_direction,
+            chunk_pcg3d,
+            chunk_hash_to_float01,
             chunk_directional_lights_iteration_mask,
+            chunk_rgbe9995_encode,
             DIRECTIONAL.chunk_read,
         ]),
 });

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

@@ -5,12 +5,16 @@ export const PROBE_TRACE_COMMAND_SETTINGS: WebGPUStruct;
 /**
  * The update's commands (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, once the due passes
  * have listed the frame's updates, the list's count clamped to U:
- * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation and the probes' projection;
- * - a thread a ray of theirs, R a probe, at `PROBE_DISPATCH_RAYS`: trace and shade;
+ * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation, the ray counts and the probes'
+ *   projection;
  * - a thread a texel of their maps, n_r² + n_d² a probe, at `PROBE_DISPATCH_TEXELS`: accumulate;
  * - a thread a row of their radiance maps, n_r a probe, at `PROBE_DISPATCH_ROWS`: the projection's rows;
  * - a thread a texel of their tiles, (n_r + 2)² + (n_d + 2)² a probe, at `PROBE_DISPATCH_PUBLISH`.
  *
+ * It writes the count of the ray counts, the ray requests and the rays' layout, the probes listed, which
+ * the passes after fill in (`shader_probe_clipmap_ray_layout.js`): a probe's rays are its own update's,
+ * even when none is listed.
+ *
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_trace_command: ComputeShader;

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

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