@woosh/meep-engine 3.59.0 → 3.60.0

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

@@ -1,32 +1,51 @@
 import { COLLECTION_U32_STRUCT_READ } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
 import { COLLECTION_U32_STRUCT_WRITE } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
 import { CLIPMAP_LEVEL_ARRAY } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { chunk_sphere_sample_volume } from "../../../shader/chunk/geometry/sphere/chunk_sphere_sample_volume.js";
 import { chunk_mod_v3i } from "../../../shader/chunk/geometry/vec3/chunk_mod_v3i.js";
+import { chunk_rgb_to_luminance } from "../../../shader/chunk/color/chunk_rgb_to_luminance.js";
+import { chunk_lower_bound_branchless } from "../../../shader/chunk/math/chunk_lower_bound_branchless.js";
 import { chunk_stbn_sample_vec2 } from "../../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import { chunk_r2_canonical } from "../../../shader/chunk/noise/r/chunk_r2_canonical.js";
 import { chunk_hash_lowbias32 } from "../../../shader/chunk/random/chunk_hash_lowbias32.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 { METRO_L1_IRRADIANCE_STRUCT } from "../../../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
-import { atomic_u32, f32, u32, vec2u, vec3i, vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { atomic_u32, f32, u32, vec2u, vec3i, vec3u, vec4f, vec4u } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
 import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
 import {
     PROBE_BLEND_SKIRT,
     PROBE_CLIPMAP_NONE,
+    PROBE_AGE_BUCKETS,
+    PROBE_COUNTER_AGES,
+    PROBE_COUNTER_EVICTED,
     PROBE_COUNTER_FREE,
     PROBE_COUNTER_PERIOD,
     PROBE_COUNTER_STARVED,
+    PROBE_COUNTER_WAITING,
     PROBE_DISPATCH_ACTIVE,
     PROBE_DISPATCH_ADMIT,
+    PROBE_DISPATCH_ORDER,
     PROBE_DISPATCH_PUBLISH,
     PROBE_DISPATCH_RAYS,
     PROBE_DISPATCH_ROWS,
     PROBE_DISPATCH_TEXELS,
     PROBE_DISPATCH_TRACED,
+    PROBE_GUIDE_SCALE,
+    PROBE_ORDER_RUN,
     PROBE_RAY_BACK_FACE,
+    PROBE_RAY_CASCADE_MASK,
     PROBE_RAY_CASCADE_SHIFT,
     PROBE_RAY_KIND_MASK,
+    PROBE_RAY_NONE,
+    PROBE_RAY_ORIGIN_JITTER,
+    PROBE_RAY_PROBE_SHIFT,
+    PROBE_RECORD_CASCADE_SHIFT,
+    PROBE_RECORD_SCREEN,
     PROBE_RELOCATION_LIMIT,
     PROBE_STATE_ALIVE,
     PROBE_STATE_DEAD,
@@ -34,12 +53,13 @@ import {
     PROBE_STATE_KIND_MASK,
     PROBE_STATE_NEW,
     PROBE_STATE_UPDATES_SHIFT,
+    PROBE_TEXEL_RAYS,
     PROBE_THREAD_WORKGROUP_SIZE,
     PROBE_WANTED_SCREEN
 } from "./PROBE_CLIPMAP.js";
 
 /**
- * A probe's record (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.2), 64 bytes a slot: where it is, when it
+ * A probe's record (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.2), 48 bytes a slot: where it is, when it
  * was wanted and traced, its last update's back faces, whose want it was, and its irradiance. Where
  * relocation moved it is the state's second word, which readers weighing it load with the state.
  *
@@ -48,24 +68,25 @@ import {
 export const PROBE_RECORD_STRUCT = WebGPUStruct.from({
     /** the lattice point, in its cascade's spacing: the probe stands at `cell · spacing` before relocation */
     cell: vec3i,
-    cascade: u32,
-    /** when a pixel or a hit last wanted it: seconds since the clipmap was made */
-    wanted_time: f32,
-    /** when it was last updated, on the same clock */
-    traced_time: f32,
-    /** the share of its last update's resolved rays that hit back faces (§8.4) */
-    back_face: f32,
     /**
-     * 1 when a pixel wanted it in the last frame anything did, 0 when only hits did (§8.3): whether its
-     * hits want in turn.
+     * The share of its last update's resolved rays that hit back faces (§8.4), unorm16 in the low half;
+     * whether a pixel wanted it, `PROBE_RECORD_SCREEN`; and its cascade, `probe_record_cascade`
+     * (`PROBE_CLIPMAP.js`).
      */
-    screen: u32,
-    /** the irradiance its rays saw, the Metro L1 encoding: luma as SH2, chroma constant */
-    sh: METRO_L1_IRRADIANCE_STRUCT,
-}, "ProbeRecord");
+    flags: u32,
+    /** the frame a pixel or a hit last wanted it, of the frames the clipmap has recorded */
+    wanted_frame: u32,
+    /** the frame it was last updated */
+    traced_frame: u32,
+    /**
+     * The irradiance its rays saw, the Metro L1 encoding (luma as SH2, chroma constant) in half floats:
+     * Y's xy, Y's zw, CoCg. `probe_record_sh_decode`.
+     */
+    sh: vec3u,
+}, "ProbeRecord").pack();
 
 /**
- * A ray of a probe's update (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6), 28 bytes, as trace writes it for
+ * A ray of a probe's update (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6), 24 bytes, as trace writes it for
  * the passes after it.
  *
  * @type {WebGPUStruct}
@@ -85,14 +106,13 @@ export const PROBE_RAY_STRUCT = WebGPUStruct.from({
     /** its kind, the back face, and the hit's cascade (`PROBE_CLIPMAP.js`) */
     flags: u32,
     /**
-     * The light, three half floats, red and green here and blue in {@link light_b}'s low half. Trace
-     * writes the direct irradiance at a front-face hit, E_dir (§8.7), zero for any other ray; shade
-     * writes over it the radiance the ray brings back.
+     * The light, RGB9E5 (`rgbe9995_encode`): held to its largest value, 65,408, which the half-float
+     * atlases after it also hold. Trace writes the direct irradiance at a front-face hit, E_dir (§8.7),
+     * zero for any other ray; shade writes over it the radiance the ray brings back, and the light pass
+     * adds what the hit takes from beyond the trace.
      */
-    light_rg: u32,
-    /** the light's blue, a half float in the low half */
-    light_b: u32,
-}, "ProbeRay");
+    light: u32,
+}, "ProbeRay").pack();
 
 /**
  * The cascades' cage windows, a {@link CLIPMAP_LEVEL_ARRAY} as a uniform, finest first: a cell of
@@ -154,6 +174,29 @@ export const PROBE_COUNTERS_READ_RESOURCE = ShaderResourceDescriptor.storageBuff
  */
 export const PROBE_FREE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_free", WebGPUArray.u32, true);
 
+/**
+ * What the next frame's retire evicts (§8.3), as the frame's schedule leaves it: the oldest `buckets` of the
+ * `PROBE_AGE_BUCKETS` age buckets whole, and `remaining` probes of the bucket below them. Zero, as a new
+ * buffer holds it, evicts nothing.
+ * @type {WebGPUStruct}
+ */
+export const PROBE_EVICTION_STRUCT = WebGPUStruct.from({
+    buckets: u32,
+    remaining: u32,
+}, "ProbeEviction").pack();
+
+/**
+ * The eviction as retire reads it: plainly, every thread.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_EVICTION_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_eviction", PROBE_EVICTION_STRUCT);
+
+/**
+ * The eviction as schedule writes it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_EVICTION_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_eviction", PROBE_EVICTION_STRUCT, true);
+
 /**
  * The live probes' slots as retire reads them: the list the frame before wrote.
  * @type {ShaderResourceDescriptor}
@@ -178,12 +221,6 @@ export const PROBE_ACTIVE_WRITTEN_RESOURCE = ShaderResourceDescriptor.storageBuf
  */
 export const PROBE_WANTED_BITS_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_wanted_bits", WebGPUArray.from(atomic_u32), true);
 
-/**
- * The wanted bits, read plainly once want has set them.
- * @type {ShaderResourceDescriptor}
- */
-export const PROBE_WANTED_BITS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_wanted_bits", WebGPUArray.u32);
-
 /**
  * The probes the frame updates, as the due passes list them, at most U (§8.5).
  * @type {ShaderResourceDescriptor}
@@ -196,6 +233,13 @@ export const PROBE_TRACE_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer
  */
 export const PROBE_TRACE_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_trace", COLLECTION_U32_STRUCT_READ);
 
+/**
+ * The probes the frame updates, as the order pass sorts them in place: the count read plainly, the
+ * entries written.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_TRACE_ORDER_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_trace", COLLECTION_U32_STRUCT_READ, true);
+
 /**
  * The keys wanted this frame, each once, as want lists them.
  * @type {ShaderResourceDescriptor}
@@ -239,6 +283,76 @@ export const PROBE_RAYS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer(
  */
 export const PROBE_RAYS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_rays", WebGPUArray.from(PROBE_RAY_STRUCT));
 
+/**
+ * Each listed probe's rays this update that the budget does not scale, `{count, elements}` by its place in
+ * the trace list: a uniform update's R and a DEAD probe's fewest, zero for a guided update. The trace
+ * command writes the count, the ray counts pass the elements.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_COUNTS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_counts", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * Each listed probe's rays this update that the budget scales, laid out as `probe_ray_counts`: a guided
+ * update's request, zero for any other.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_REQUESTS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_requests", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * The inclusive sums of `probe_ray_counts`, as the scan leaves them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_COUNT_SUMS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_count_sums", COLLECTION_U32_STRUCT_READ);
+
+/**
+ * The inclusive sums of `probe_ray_requests`, as the scan leaves them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_REQUEST_SUMS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_request_sums", COLLECTION_U32_STRUCT_READ);
+
+/**
+ * The frame's rays laid out by listed probe (§8.6): inclusive sums of each listed probe's rays, so that the
+ * k-th listed probe's rays are the frame's `[sums[k − 1], sums[k])`, the first from 0, and the frame's
+ * count of rays is the last sum. The ray layout pass writes them, the trace command their count.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_SUMS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_sums", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * The frame's rays laid out by listed probe, as the passes after the layout read them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_SUMS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_sums", COLLECTION_U32_STRUCT_READ);
+
+/**
+ * A slot's ray request (§8.6), as projection writes it after each update: the rays its next guided update
+ * asks for, and what tells it the probe's light moved.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PROBE_REQUEST_STRUCT = WebGPUStruct.from({
+    /** the rays the probe's next guided update asks for */
+    rays: u32,
+    /** the running mean of the update's change score: its texels' falls from their means, each in its own deviation, summed over the root of their count */
+    change_mean: f32,
+    /** the running variance of the change score */
+    change_variance: f32,
+    /** the scores its running statistics hold, up to `PROBE_RADIANCE_SAMPLES_LIMIT` */
+    changes: u32,
+}, "ProbeRequest").pack();
+
+/**
+ * Each slot's {@link PROBE_REQUEST_STRUCT}, as projection writes it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_REQUESTS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_requests", WebGPUArray.from(PROBE_REQUEST_STRUCT), true);
+
+/**
+ * Each slot's ray request, as the ray counts pass reads it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_REQUESTS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_requests", WebGPUArray.from(PROBE_REQUEST_STRUCT));
+
 /**
  * The listed probes' maps, as accumulation writes them for projection and publish, in list order,
  * `probe_clipmap_maps_words` a probe.
@@ -252,6 +366,15 @@ export const PROBE_MAPS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer(
  */
 export const PROBE_MAPS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_maps", WebGPUArray.u32);
 
+/**
+ * Each slot's radiance estimators (§8.8), n_r² a slot by texel, as accumulation reads and writes them: the
+ * texel's multi-scale mean past its mean, which the radiance atlas holds. Four words of half floats: the short
+ * mean's r and g; its b and the deviation's r; the deviation's g and b; the blend reduction and the
+ * inconsistency.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_ESTIMATORS_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_estimators", WebGPUArray.from(vec4u), true);
+
 /**
  * A row of a listed probe's radiance map, projected: its irradiance SH, and its rays this update.
  * @type {WebGPUStruct}
@@ -262,7 +385,11 @@ export const PROBE_PROJECTION_ROW_STRUCT = WebGPUStruct.from({
     resolved: u32,
     /** of them, the back faces */
     back_faces: u32,
-}, "ProbeProjectionRow");
+    /** how far the update's samples fell from their texels' means, each in its own deviation, luminance, summed */
+    change: f32,
+    /** the texels that blended a sample */
+    blended: f32,
+}, "ProbeProjectionRow").pack();
 
 /**
  * The listed probes' rows, n_r a probe, as the projection's rows write them.
@@ -315,11 +442,19 @@ export const PROBE_DEPTH_STORE_RESOURCE = ShaderResourceDescriptor.storageTextur
  * fn probe_state_kind(state: u32) -> u32 // of the state's first word
  * fn probe_state_updates(state: u32) -> u32
  * fn probe_state(kind: u32, updates: u32) -> u32
+ * fn probe_clipmap_age_bucket(age: u32) -> u32 // the bucket of frames unwanted that eviction orders by
+ * fn probe_record_flags(back_face: f32, screen: bool, cascade: u32) -> u32
+ * fn probe_record_cascade(flags: u32) -> u32
+ * fn probe_record_sh_encode(sh: MetroL1) -> vec3<u32> // held to the half float's largest, ±65,504
+ * fn probe_record_sh_decode(sh: vec3<u32>) -> MetroL1
  * fn probe_clipmap_offset_encode(offset: vec3<f32>, spacing: f32) -> u32 // the state's second word
  * fn probe_clipmap_offset_decode(word: u32, spacing: f32) -> vec3<f32>
  * fn probe_clipmap_maps_words(radiance_resolution: u32, depth_resolution: u32) -> u32 // a listed probe's, in probe_maps
  * ```
  *
+ * An age's bucket is its count of binary digits: 0 frames the first, 1 the second, 2 and 3 the third, and
+ * the last everything from 2^(`PROBE_AGE_BUCKETS` − 2) frames on.
+ *
  * The offset's fields are of `PROBE_RELOCATION_LIMIT` of the spacing, 511 steps each way: under a
  * thousandth of the spacing apart, and zero at the lattice point.
  *
@@ -338,6 +473,10 @@ const PROBE_STATE_DEAD = ${PROBE_STATE_DEAD}u;
 const PROBE_COUNTER_FREE = ${PROBE_COUNTER_FREE}u;
 const PROBE_COUNTER_STARVED = ${PROBE_COUNTER_STARVED}u;
 const PROBE_COUNTER_PERIOD = ${PROBE_COUNTER_PERIOD}u;
+const PROBE_COUNTER_WAITING = ${PROBE_COUNTER_WAITING}u;
+const PROBE_COUNTER_EVICTED = ${PROBE_COUNTER_EVICTED}u;
+const PROBE_COUNTER_AGES = ${PROBE_COUNTER_AGES}u;
+const PROBE_AGE_BUCKETS = ${PROBE_AGE_BUCKETS}u;
 
 const PROBE_DISPATCH_ACTIVE = ${PROBE_DISPATCH_ACTIVE}u;
 const PROBE_DISPATCH_ADMIT = ${PROBE_DISPATCH_ADMIT}u;
@@ -346,13 +485,21 @@ const PROBE_DISPATCH_RAYS = ${PROBE_DISPATCH_RAYS}u;
 const PROBE_DISPATCH_TEXELS = ${PROBE_DISPATCH_TEXELS}u;
 const PROBE_DISPATCH_ROWS = ${PROBE_DISPATCH_ROWS}u;
 const PROBE_DISPATCH_PUBLISH = ${PROBE_DISPATCH_PUBLISH}u;
+const PROBE_DISPATCH_ORDER = ${PROBE_DISPATCH_ORDER}u;
+const PROBE_ORDER_RUN = ${PROBE_ORDER_RUN}u;
 
 const PROBE_RAY_KIND_MASK = ${PROBE_RAY_KIND_MASK}u;
+const PROBE_RAY_NONE = ${PROBE_RAY_NONE}u;
 const PROBE_RAY_BACK_FACE = ${PROBE_RAY_BACK_FACE}u;
 const PROBE_RAY_CASCADE_SHIFT = ${PROBE_RAY_CASCADE_SHIFT}u;
+const PROBE_RAY_CASCADE_MASK = ${PROBE_RAY_CASCADE_MASK}u;
+const PROBE_RAY_PROBE_SHIFT = ${PROBE_RAY_PROBE_SHIFT}u;
 
 const PROBE_WANTED_SCREEN = ${PROBE_WANTED_SCREEN}u;
 
+const PROBE_RECORD_SCREEN = ${PROBE_RECORD_SCREEN}u;
+const PROBE_RECORD_CASCADE_SHIFT = ${PROBE_RECORD_CASCADE_SHIFT}u;
+
 const PROBE_THREAD_WORKGROUP_SIZE = ${PROBE_THREAD_WORKGROUP_SIZE}u;
 const PROBE_BLEND_SKIRT = ${PROBE_BLEND_SKIRT}.0;
 
@@ -390,8 +537,36 @@ fn probe_state(kind: u32, updates: u32) -> u32 {
     return kind | (updates << ${PROBE_STATE_UPDATES_SHIFT}u);
 }
 
+fn probe_clipmap_age_bucket(age: u32) -> u32 {
+    return min(32u - countLeadingZeros(age), PROBE_AGE_BUCKETS - 1u);
+}
+
+fn probe_record_flags(back_face: f32, screen: bool, cascade: u32) -> u32 {
+    return (pack2x16unorm(vec2<f32>(back_face, 0.0)) & 0xFFFFu) | select(0u, PROBE_RECORD_SCREEN, screen) | (cascade << PROBE_RECORD_CASCADE_SHIFT);
+}
+
+fn probe_record_cascade(flags: u32) -> u32 {
+    return flags >> PROBE_RECORD_CASCADE_SHIFT;
+}
+
+fn probe_record_sh_encode(sh: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref}) -> vec3<u32> {
+    let y = clamp(sh.Y, vec4<f32>(-65504.0), vec4<f32>(65504.0));
+    let cocg = clamp(sh.CoCg, vec2<f32>(-65504.0), vec2<f32>(65504.0));
+
+    return vec3<u32>(pack2x16float(y.xy), pack2x16float(y.zw), pack2x16float(cocg));
+}
+
+fn probe_record_sh_decode(sh: vec3<u32>) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    var out: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
+
+    out.Y = vec4<f32>(unpack2x16float(sh.x), unpack2x16float(sh.y));
+    out.CoCg = unpack2x16float(sh.z);
+
+    return out;
+}
+
 fn probe_clipmap_maps_words(radiance_resolution: u32, depth_resolution: u32) -> u32 {
-    return 3u * radiance_resolution * radiance_resolution + depth_resolution * depth_resolution;
+    return 4u * radiance_resolution * radiance_resolution + depth_resolution * depth_resolution;
 }
 
 fn probe_clipmap_offset_encode(offset: vec3<f32>, spacing: f32) -> u32 {
@@ -409,9 +584,53 @@ fn probe_clipmap_offset_decode(word: u32, spacing: f32) -> vec3<f32> {
 }
 `, [
     PROBE_RECORD_STRUCT.declaration_chunk,
+    METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
     chunk_mod_v3i,
 ]);
 
+/**
+ * Where the frame's rays are, by listed probe (§8.6): the scan of each listed probe's count of rays this
+ * update, `probe_ray_sums`. A probe's rays follow one another, in the trace list's order.
+ *
+ * ```wgsl
+ * fn probe_clipmap_ray_probe(ray: u32) -> u32 // the listed probe the frame's ray is one of, by its place in the list; the list's count or more for none
+ * fn probe_clipmap_probe_rays(k: u32) -> vec2<u32> // the k-th listed probe's first ray, and how many it has
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_ray_layout = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_ray_probe(ray: u32) -> u32 {
+    let listed = probe_ray_sums.count;
+
+    if (listed == 0u) {
+        return 0u;
+    }
+
+    // the first whose rays end past this one
+    return lower_bound_branchless(&probe_ray_sums.elements, ray + 1u, listed);
+}
+
+fn probe_clipmap_probe_rays(k: u32) -> vec2<u32> {
+    let end = probe_ray_sums.elements[k];
+
+    var first = 0u;
+
+    // not a select, which reads both sides, k − 1 wrapping at the first
+    if (k > 0u) {
+        first = probe_ray_sums.elements[k - 1u];
+    }
+
+    return vec2<u32>(first, end - first);
+}
+`, [
+    chunk_lower_bound_branchless,
+]);
+
+chunk_probe_clipmap_ray_layout.requireResource(PROBE_RAY_SUMS_READ_RESOURCE);
+
 /**
  * Which octahedral radiance texel a ray of an update is, and the way back (§8.6). An update casts R rays
  * over the n_r² texels:
@@ -491,3 +710,165 @@ fn probe_clipmap_ray_jitter(slot: u32, texel: u32, ray: u32, updates: u32, rays:
 ]);
 
 chunk_probe_clipmap_ray_jitter.requireResource(STBN_VEC2_RESOURCE);
+
+/**
+ * Where a ray of an update starts (§8.6): a point of the ball of `PROBE_RAY_ORIGIN_JITTER` of the spacing
+ * around the probe, uniform in its volume, as Brick4's bake jitters its probes. The point is drawn from the
+ * probe's slot and the ray's direction as its record packs it, so every pass that puts a hit back together
+ * from `t` (shade, light, want hits) draws the same one. The trace's jitter moves the direction every
+ * update, and the point with it.
+ *
+ * ```wgsl
+ * fn probe_clipmap_ray_origin(probe: vec4<f32>, slot: u32, direction: u32) -> vec3<f32> // probe: its `probe_origins` entry; direction: as the ray's record packs it
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_ray_origin = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_ray_origin(probe: vec4<f32>, slot: u32, direction: u32) -> vec3<f32> {
+    let hash = pcg3d(vec3<u32>(slot, direction, 0xBB67AE85u));
+    let uvw = vec3<f32>(hash_to_float01(hash.x), hash_to_float01(hash.y), hash_to_float01(hash.z));
+
+    return probe.xyz + ${PROBE_RAY_ORIGIN_JITTER} * probe.w * sphere_sample_volume(uvw);
+}
+`, [
+    chunk_pcg3d,
+    chunk_hash_to_float01,
+    chunk_sphere_sample_volume,
+]);
+
+/**
+ * The listed probes' guides, `probe_guide_words` a probe in list order, as the guide passes write them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_GUIDE_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_guide", WebGPUArray.u32, true);
+
+/**
+ * The listed probes' guides, as trace, accumulation and projection read them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_GUIDE_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_guide", WebGPUArray.u32);
+
+/**
+ * The guide's walk over a probe's octahedral texels, and the weights it walks (§8.6). A guided update
+ * gives each texel `R·(w + e)/W` rays: `w` is its weight, `e` the even share of the leftover, `W` the
+ * total. Its rays follow one another in the order of the walk. That order is the radiance map's rows,
+ * from the corner the update's count names (`updates mod 4` mirrors x, y, or both), and it is its own
+ * inverse.
+ *
+ * A probe's first n_r²/R updates are uniform, so that together they reach every texel (Enshrouded gives a new
+ * probe its most rays for the same reason): the guide would weigh a texel no ray has reached as dark.
+ *
+ * A DEAD probe's updates are all uniform. Readers weigh it at nothing, so its light is not worth guiding.
+ * Its updates exist to reclassify it, and only uniform rays do that (§8.4); guided ones would leave it
+ * dead for `PROBE_UNIFORM_PERIOD` of its already rare updates.
+ *
+ * - A texel's weight is its share of the probe's luminance in units of 1/`PROBE_GUIDE_SCALE`, held to
+ *   `(PROBE_TEXEL_RAYS − 2 − R/n_r²)/R`. With the even share added, that leaves a texel under
+ *   `PROBE_TEXEL_RAYS` rays. What the hold takes off, and what flooring the weights leaves over, is
+ *   spread evenly over every texel. A dark probe's rays are therefore an even, stratified spread.
+ * - The walk position `p` starts at ray `⌈R·Σ_{q<p}(w_q + e)/W − φ⌉`, `φ` being the update's phase in
+ *   [0, 1). That is systematic sampling: every texel takes ⌊its share⌋ or ⌈its share⌉ rays.
+ * - A guide's words (`probe_clipmap_guide_words`, by offset from the probe's): the first rays by walk
+ *   position at 0; the weights by texel at n_r²; the row luminances at 2·n_r²; the row weights at
+ *   2·n_r² + n_r; the total at 2·n_r² + 2·n_r, and the even share after it.
+ *
+ * ```wgsl
+ * fn probe_clipmap_guided(state: u32, period: u32, rays: u32, texels: u32) -> bool // the state's first word: the update's rays follow the guide
+ * fn probe_clipmap_guide_words(n: u32) -> u32
+ * fn probe_clipmap_guide_texel(position: u32, updates: u32, n: u32) -> u32 // and the other way: the walk is its own inverse
+ * fn probe_clipmap_guide_luminance(radiance: vec3<f32>) -> f32
+ * fn probe_clipmap_guide_weight(luminance: f32, total: f32, rays: u32, texels: u32) -> u32
+ * fn probe_clipmap_guide_phase(slot: u32, updates: u32) -> f32
+ * fn probe_clipmap_guide_start(before: u32, total: u32, rays: u32, phase: f32) -> u32 // before: the weight walked before
+ * fn probe_clipmap_guide_rate(expected: f32, rays: u32, texels: u32, period: u32) -> f32 // the share of updates a texel takes rays in
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_guide = CodeChunk.from(
+    //language=WGSL
+    `
+const PROBE_GUIDE_SCALE = ${PROBE_GUIDE_SCALE}u;
+const PROBE_TEXEL_RAYS = ${PROBE_TEXEL_RAYS}u;
+
+fn probe_clipmap_guided(state: u32, period: u32, rays: u32, texels: u32) -> bool {
+    let updates = probe_state_updates(state);
+
+    return probe_state_kind(state) != PROBE_STATE_DEAD && updates >= texels / rays && updates % period != 0u;
+}
+
+fn probe_clipmap_guide_words(n: u32) -> u32 {
+    return 2u * n * n + 2u * n + 2u;
+}
+
+fn probe_clipmap_guide_texel(position: u32, updates: u32, n: u32) -> u32 {
+    let corner = updates % 4u;
+    let column = position % n;
+    let row = position / n;
+    let x = select(column, n - 1u - column, (corner & 1u) != 0u);
+    let y = select(row, n - 1u - row, (corner & 2u) != 0u);
+
+    return y * n + x;
+}
+
+fn probe_clipmap_guide_luminance(radiance: vec3<f32>) -> f32 {
+    return max(rgb_to_luminance(radiance), 0.0);
+}
+
+fn probe_clipmap_guide_weight(luminance: f32, total: f32, rays: u32, texels: u32) -> u32 {
+    if (total <= 0.0) {
+        return 0u;
+    }
+
+    let hold = max(f32(PROBE_TEXEL_RAYS) - 2.0 - f32(rays) / f32(texels), 0.0) / f32(rays);
+
+    return u32(floor(min(luminance / total, hold) * f32(PROBE_GUIDE_SCALE)));
+}
+
+fn probe_clipmap_guide_phase(slot: u32, updates: u32) -> f32 {
+    return hash_to_float01(pcg3d(vec3<u32>(slot, updates, 0x6A09E667u)).x);
+}
+
+fn probe_clipmap_guide_start(before: u32, total: u32, rays: u32, phase: f32) -> u32 {
+    let at = ceil(f32(before) / f32(total) * f32(rays) - phase);
+
+    return u32(clamp(at, 0.0, f32(rays)));
+}
+
+fn probe_clipmap_guide_rate(expected: f32, rays: u32, texels: u32, period: u32) -> f32 {
+    let uniform = min(f32(rays) / f32(texels), 1.0);
+    let guided = min(expected, 1.0);
+
+    return (uniform + f32(period - 1u) * guided) / f32(period);
+}
+`, [
+    chunk_probe_clipmap,
+    chunk_rgb_to_luminance,
+    chunk_hash_to_float01,
+    chunk_pcg3d,
+]);
+
+/**
+ * The jitter of a guided update's ray in its texel. The first ray takes the texel's STBN jitter
+ * (`probe_clipmap_ray_jitter` at round 0). The rest rotate it by the R2 sequence, so a texel's rays
+ * spread over it the way a lattice does.
+ *
+ * ```wgsl
+ * fn probe_clipmap_guided_ray_jitter(slot: u32, texel: u32, round: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> // round: the ray's place among its texel's
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_guided_ray_jitter = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_guided_ray_jitter(slot: u32, texel: u32, round: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> {
+    return fract(probe_clipmap_ray_jitter(slot, texel, 0u, updates, rays, n) + r2_canonical(round) - 0.5);
+}
+`, [
+    chunk_probe_clipmap_ray_jitter,
+    chunk_r2_canonical,
+]);

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

@@ -276,22 +276,22 @@ fn probe_clipmap_sh_of(pick: ProbeClipmapPick) -> ProbeClipmapSH {
 
     // each by name, the slots of a weight of zero not read
     if (pick.weights.x > 0.0) {
-        let sh = probe_records[pick.slots.x].sh;
+        let sh = probe_record_sh_decode(probe_records[pick.slots.x].sh);
         out.sh.CoCg += pick.weights.x * sh.CoCg;
         out.sh.Y += pick.weights.x * sh.Y;
     }
     if (pick.weights.y > 0.0) {
-        let sh = probe_records[pick.slots.y].sh;
+        let sh = probe_record_sh_decode(probe_records[pick.slots.y].sh);
         out.sh.CoCg += pick.weights.y * sh.CoCg;
         out.sh.Y += pick.weights.y * sh.Y;
     }
     if (pick.weights.z > 0.0) {
-        let sh = probe_records[pick.slots.z].sh;
+        let sh = probe_record_sh_decode(probe_records[pick.slots.z].sh);
         out.sh.CoCg += pick.weights.z * sh.CoCg;
         out.sh.Y += pick.weights.z * sh.Y;
     }
     if (pick.weights.w > 0.0) {
-        let sh = probe_records[pick.slots.w].sh;
+        let sh = probe_record_sh_decode(probe_records[pick.slots.w].sh);
         out.sh.CoCg += pick.weights.w * sh.CoCg;
         out.sh.Y += pick.weights.w * sh.Y;
     }

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_probe_clipmap_sample_radiance.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_sample_radiance.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,kDAFU,SAAS,CAoIZ;0BA3KmB,uCAAuC"}
+{"version":3,"file":"chunk_probe_clipmap_sample_radiance.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_sample_radiance.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,kDAFU,SAAS,CAqIZ;0BA5KmB,uCAAuC"}

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

@@ -76,11 +76,12 @@ fn probe_clipmap_radiance(slot: u32, direction: vec3<f32>) -> vec3<f32> {
 // a picked probe's share for the lobe, its radiance along it and its SH
 fn probe_clipmap_lobe(slot: u32, share: f32, position: vec3<f32>, normal: vec3<f32>, bias_direction: vec3<f32>, lobe: vec3<f32>) -> ProbeClipmapLobe {
     let record = probe_records[slot];
-    let spacing = probe_levels[record.cascade].cell_size;
+    let cascade = probe_record_cascade(record.flags);
+    let spacing = probe_levels[cascade].cell_size;
     let probe = vec3<f32>(record.cell) * spacing + probe_clipmap_offset_decode(probe_states[slot].y, spacing);
 
     // the visibility it was picked at: Chebyshev's from its depth toward the biased point
-    let biased = probe_clipmap_biased(record.cascade, position, bias_direction);
+    let biased = probe_clipmap_biased(cascade, position, bias_direction);
     let to_point = biased - probe;
     let distance = length(to_point);
     let visibility = probe_visibility_chebyshev(probe_clipmap_depth_moments(slot, to_point / max(distance, 1e-6)), distance / spacing);
@@ -89,7 +90,7 @@ fn probe_clipmap_lobe(slot: u32, share: f32, position: vec3<f32>, normal: vec3<f
 
     var out: ProbeClipmapLobe;
     out.weight = share * probe_visibility_weight(toward, lobe, visibility) / probe_visibility_weight(toward, normal, visibility);
-    out.sh = record.sh;
+    out.sh = probe_record_sh_decode(record.sh);
 
     // the reflected ray met with a sphere about the probe, its radius the probe's mean depth along the lobe
     let radius = probe_clipmap_depth_moments(slot, lobe).x * spacing;