@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -0,0 +1,101 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_get_ibl_irradiance } from "../../../deferred/indirect/chunk_get_ibl_irradiance.js";
+import { DEPTH_STENCIL_FOREGROUND_ONLY } from "../../../depth/DEPTH_STENCIL_FOREGROUND_ONLY.js";
+import { ENVIRONMENT_MAP_RESOURCE } from "../../../light/environment/ENVIRONMENT_MAP_RESOURCE.js";
+import { ENVIRONMENT_MAP_SAMPLER_RESOURCE } from "../../../light/environment/ENVIRONMENT_MAP_SAMPLER_RESOURCE.js";
+import { chunk_project_position_from_depth } from "../../../shader/chunk/camera/chunk_project_position_from_depth.js";
+import { chunk_mat4_extract_position } from "../../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
+import { chunk_decode_g_buffer_normal } from "../../../shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { PI_DECLARATION } from "../../../shader/chunk/math/PI_DECLARATION.js";
+import { chunk_stbn_sample_vec2 } from "../../../shader/chunk/noise/chunk_stbn_sample_vec2.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 { ImageShader } from "../../../shader/ImageShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../../shader/ShaderDescriptor.js";
+import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import { VIEW_UNIFORM_STRUCT } from "../../../view/VIEW_UNIFORM_STRUCT.js";
+import { chunk_probe_clipmap_pick, PROBE_CLIPMAP_SAMPLING_GROUP } from "./chunk_probe_clipmap_pick.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addTexture("tDepth")
+    .addTexture("tNormals", "uint")
+    .addTexture("tBentNormals", "uint")
+    .addTexture("tGBufferAlbedo")
+    .add(STBN_VEC2_RESOURCE)
+    .addUniform("view", VIEW_UNIFORM_STRUCT)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .add(ENVIRONMENT_MAP_RESOURCE)
+    .add(ENVIRONMENT_MAP_SAMPLER_RESOURCE);
+
+// the whole group the GI hands its readers: a graph pass must declare every input it is given
+resources.addGroup(PROBE_CLIPMAP_SAMPLING_GROUP);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@fragment
+fn main(
+    @builtin(position) coord: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+) -> @location(0) vec4<f32> {
+    let i_coord = vec2<u32>(coord.xy);
+
+    let depth = textureLoad(tDepth, i_coord, 0).r;
+    let position = project_position_from_depth(uv, depth, camera.view_projection_matrix_inverse);
+    let view_direction = normalize(mat4_extract_position(camera.transform) - position);
+
+    // the surface's own normal picks, as want chose by it; the bent normal resolves, as IBL's does
+    let normal = decode_g_buffer_normal(textureLoad(tNormals, i_coord, 0).xy);
+    let bent_normal = decode_g_buffer_normal(textureLoad(tBentNormals, i_coord, 0).xy);
+
+    let noise = stbn_sample_vec2(vec3<u32>(i_coord, view.frame_index));
+    let probes = probe_clipmap_sample_sh(position, normal, view_direction, noise);
+
+    var irradiance = get_ibl_irradiance(bent_normal);
+
+    if (probes.found) {
+        irradiance = PI * resolve_irradiance_sh_to_diffuse(probes.sh.Y, probes.sh.CoCg, bent_normal);
+    }
+
+    // AO baked in at the source, as the IBL pass does, so the resolve need not know which path ran
+    let occlusion = textureLoad(tGBufferAlbedo, i_coord, 0).a;
+
+    return vec4<f32>(irradiance * occlusion, 0.0);
+}
+`, [
+    chunk_project_position_from_depth,
+    chunk_mat4_extract_position,
+    chunk_decode_g_buffer_normal,
+    chunk_stbn_sample_vec2,
+    chunk_probe_clipmap_pick,
+    chunk_resolve_irradiance_sh_to_diffuse,
+    chunk_get_ibl_irradiance,
+    PI_DECLARATION,
+]);
+
+/**
+ * The probe clipmap's deferred diffuse (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.2, §9.6): each pixel's
+ * irradiance from the probes `probe_clipmap_sample_sh` picks around it, with the frame's STBN for the
+ * pick, resolved at its bent normal and multiplied by π, the resolve giving E/π. A pixel no probe weighs
+ * anything for takes the environment's irradiance, as the IBL pass would give it. AO multiplies it, as in
+ * the IBL pass.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_diffuse = ImageShader.from({
+    descriptor: ShaderDescriptor.from({
+        label: "Probe Clipmap / Indirect Diffuse",
+        resources,
+        body,
+    }),
+    depthStencil: DEPTH_STENCIL_FOREGROUND_ONLY,
+    targets: [{
+        label: "Diffuse Indirect lighting",
+        format: "rgba16float"
+    }]
+});

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

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

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

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

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

@@ -12,10 +12,9 @@ import {
     PROBE_COUNTERS_READ_RESOURCE,
     PROBE_RECORDS_READ_RESOURCE,
     PROBE_STATES_READ_RESOURCE,
-    PROBE_TRACE_WRITE_RESOURCE,
-    PROBE_WANTED_BITS_READ_RESOURCE
+    PROBE_TRACE_WRITE_RESOURCE
 } from "./chunk_probe_clipmap.js";
-import { PROBE_DEAD_PERIODS, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
 
 /**
  * @type {WebGPUStruct}
@@ -23,8 +22,6 @@ import { PROBE_DEAD_PERIODS, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP
 export const PROBE_DUE_SETTINGS = WebGPUStruct.from({
     /** slots, which no active list outgrows */
     capacity: u32,
-    /** lattice points a cascade's window has a side */
-    resolution: u32,
     /** probes a frame updates at most, U = ⌊ray_budget / rays_per_probe⌋: the trace list's bound */
     trace_capacity: u32,
     /** the frame's index, what a probe's turn in its period is counted by */
@@ -41,21 +38,29 @@ resources.createGroup()
     .add(PROBE_STATES_READ_RESOURCE)
     .add(PROBE_RECORDS_READ_RESOURCE)
     .add(PROBE_COUNTERS_READ_RESOURCE)
-    .add(PROBE_WANTED_BITS_READ_RESOURCE)
     .add(PROBE_ACTIVE_WRITTEN_RESOURCE)
     .add(PROBE_TRACE_WRITE_RESOURCE);
 
 /**
  * Due (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): a thread an entry of the frame's active list,
  * dispatched twice through `PROBE_DISPATCH_ACTIVE` after schedule has set the period T. A probe is due
- * when a pixel wanted it this frame, its point's bit set, and:
- * - it is NEW, in the first pass, which lists them first;
- * - in the second pass, it is ALIVE and `(frame + h(slot)) mod T` is 0, or DEAD and
- *   `(frame + h(slot)) mod 8T` is 0, so that a probe inside a solid notices when the scene changes.
+ * when a want waits on it:
+ * - it is NEW, in the first pass, which lists them first: it has had no update;
+ * - in the second pass, it is ALIVE or DEAD, a pixel or a hit wanted it since its last update, its
+ *   wanted time past its traced time, and `(frame + h(slot)) mod T` is 0. A DEAD probe's update casts
+ *   the fewest rays (`PROBE_RAYS_PER_TEXEL_MIN`), every period rather than every eighth at R, so that a
+ *   probe inside a solid notices when the scene changes sooner, for fewer rays (Enshrouded's dead probes
+ *   trace 16 a frame).
+ *
+ * Wanted since its last update, not this frame: a hit wants a probe the frame after its own probe's
+ * update, so a probe that only hits keep is wanted on few of its turns. Measured on Sponza with the
+ * point's bit as the test, the hits' probes were updated 0.8 times a second at p10 against the screen's
+ * 6.6 at the least, and 6 s had passed since the last update at p99 (§8.3). A want an update served
+ * waits on nothing: the update comes after admit in its frame, so its traced time is the want's or later.
  *
  * The due go on the trace list, which holds the frame's updates, at most U: past it the count still
- * rises and nothing is written, and a probe not listed waits its next turn. With T = ⌈P_w / U⌉ the
- * expected count a frame is under U, so only NEW probes past U, a camera cut, wait.
+ * rises and nothing is written, and a probe not listed waits its next turn. With T = ⌈P_w / U⌉ over the
+ * probes waiting, the expected count a frame is under U, so only NEW probes past U, a camera cut, wait.
  *
  * @type {ComputeShader}
  */
@@ -80,22 +85,16 @@ fn main(
 
         let kind = probe_state_kind(probe_states[slot].x);
 
-        // wanted this frame: its point's bit
-        let resolution = settings.resolution;
-        let storage = vec3<u32>(probe_records[slot].cell) & vec3<u32>(resolution - 1u);
-        let key = probe_clipmap_key(probe_records[slot].cascade, storage, resolution);
-        let wanted = (probe_wanted_bits[key >> 5u] & (1u << (key & 31u))) != 0u;
+        // wanted since its last update
+        let waiting = probe_records[slot].wanted_frame > probe_records[slot].traced_frame;
 
         let period = max(probe_counters[PROBE_COUNTER_PERIOD], 1u);
         let turn = settings.frame + hash_lowbias32(slot);
 
         if (settings.new_only != 0u) {
-            due = wanted && kind == PROBE_STATE_NEW;
+            due = kind == PROBE_STATE_NEW;
         } else {
-            due = wanted && (
-                (kind == PROBE_STATE_ALIVE && turn % period == 0u)
-                || (kind == PROBE_STATE_DEAD && turn % (${PROBE_DEAD_PERIODS}u * period) == 0u)
-            );
+            due = waiting && (kind == PROBE_STATE_ALIVE || kind == PROBE_STATE_DEAD) && turn % period == 0u;
         }
     }
 

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

@@ -0,0 +1,36 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_GUIDE_SETTINGS: WebGPUStruct;
+/**
+ * The guide, rows (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a row of each listed probe's
+ * radiance map, dispatched through `PROBE_DISPATCH_ROWS`. It sums the luminance of the row's history
+ * texels, which the weights' pass totals.
+ *
+ * The guide is built for every update. A guided update's trace casts its rays by it, and accumulation
+ * takes each texel's share of the guided updates' rays from it, uniform update or not.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_rows: ComputeShader;
+/**
+ * The guide, weights (§8.6): a thread a row of each listed probe's radiance map, dispatched through
+ * `PROBE_DISPATCH_ROWS`. It totals the rows' luminance, then weighs each of the row's texels by its share
+ * (`probe_clipmap_guide_weight`) and sums the row's weights, which the starts' pass totals.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_weights: ComputeShader;
+/**
+ * The guide, starts (§8.6): a thread a row of the walk of each listed probe's radiance map, dispatched
+ * through `PROBE_DISPATCH_ROWS`. It totals the weights and spreads what they leave of
+ * `PROBE_GUIDE_SCALE` evenly. It takes the weight the walk covers before its row from the row weights,
+ * then writes the first ray of each of its walk positions. The walk's first row writes the total and the
+ * even share as well.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_starts: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_guide.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_guide.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_guide.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH,mCAFU,YAAY,CAWG;AAkEzB;;;;;;;;;GASG;AACH,8CAFU,aAAa,CAgCpB;AAEH;;;;;;GAMG;AACH,iDAFU,aAAa,CA4CpB;AAEH;;;;;;;;GAQG;AACH,gDAFU,aAAa,CA2DpB;6BA1P0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -0,0 +1,257 @@
+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 { 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 {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    chunk_probe_clipmap_ray_layout,
+    PROBE_GUIDE_WRITE_RESOURCE,
+    PROBE_RADIANCE_HISTORY_RESOURCE,
+    PROBE_RAY_SUMS_READ_RESOURCE,
+    PROBE_STATES_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_GUIDE_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** rays a uniform update casts, R; the guide walks its probe's own (`probe_ray_sums`) */
+    rays_per_probe: u32,
+    /** octahedral radiance texels a side, n_r */
+    radiance_resolution: u32,
+    /** tiles a row of the radiance atlas */
+    radiance_tiles_per_row: u32,
+}, "ProbeGuideSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_GUIDE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(PROBE_RADIANCE_HISTORY_RESOURCE)
+    .add(PROBE_RAY_SUMS_READ_RESOURCE)
+    .add(PROBE_GUIDE_WRITE_RESOURCE);
+
+/**
+ * What every guide pass opens with: the thread's listed probe `k` and row, the rays its update casts,
+ * and where the probe's guide and history tile start. A thread past the list returns.
+ */
+const chunk_probe_clipmap_guide_thread = CodeChunk.from(
+    //language=WGSL
+    `
+struct ProbeGuideThread {
+    valid: bool,
+    k: u32,
+    row: u32,
+    rays: u32,
+    slot: u32,
+    updates: u32,
+    base: u32,
+    tile: vec2<u32>,
+}
+
+fn probe_guide_thread(workgroup_id: vec3<u32>, lane: u32) -> ProbeGuideThread {
+    var out: ProbeGuideThread;
+
+    let thread = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+    let n = settings.radiance_resolution;
+
+    out.valid = thread < min(probe_trace.count, settings.trace_capacity) * n;
+
+    if (!out.valid) {
+        return out;
+    }
+
+    out.k = thread / n;
+    out.row = thread % n;
+    out.rays = probe_clipmap_probe_rays(out.k).y;
+    out.slot = probe_trace.elements[out.k];
+    out.updates = probe_state_updates(probe_states[out.slot].x);
+    out.base = out.k * probe_clipmap_guide_words(n);
+    out.tile = index_to_grid2d(out.slot, settings.radiance_tiles_per_row) * (n + 2u) + 1u;
+
+    return out;
+}
+
+// the luminance of the history's texel (x, y) in the thread's tile
+fn probe_guide_texel_luminance(thread: ProbeGuideThread, x: u32, y: u32) -> f32 {
+    return probe_clipmap_guide_luminance(textureLoad(probe_radiance, thread.tile + vec2<u32>(x, y), 0).rgb);
+}
+`, [
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    chunk_probe_clipmap_ray_layout,
+    chunk_folded_workgroup_index,
+    chunk_index_to_grid2d,
+]);
+
+/**
+ * The guide, rows (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a row of each listed probe's
+ * radiance map, dispatched through `PROBE_DISPATCH_ROWS`. It sums the luminance of the row's history
+ * texels, which the weights' pass totals.
+ *
+ * The guide is built for every update. A guided update's trace casts its rays by it, and accumulation
+ * takes each texel's share of the guided updates' rays from it, uniform update or not.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_rows = ComputeShader.from({
+    label: "Probe Clipmap Guide Rows",
+    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 thread = probe_guide_thread(workgroup_id, lane);
+
+    if (!thread.valid) {
+        return;
+    }
+
+    let n = settings.radiance_resolution;
+
+    var sum = 0.0;
+
+    for (var x = 0u; x < n; x++) {
+        sum += probe_guide_texel_luminance(thread, x, thread.row);
+    }
+
+    probe_guide[thread.base + 2u * n * n + thread.row] = bitcast<u32>(sum);
+}
+`, [
+            chunk_probe_clipmap_guide_thread,
+        ]),
+});
+
+/**
+ * The guide, weights (§8.6): a thread a row of each listed probe's radiance map, dispatched through
+ * `PROBE_DISPATCH_ROWS`. It totals the rows' luminance, then weighs each of the row's texels by its share
+ * (`probe_clipmap_guide_weight`) and sums the row's weights, which the starts' pass totals.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_weights = ComputeShader.from({
+    label: "Probe Clipmap Guide Weights",
+    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 thread = probe_guide_thread(workgroup_id, lane);
+
+    if (!thread.valid) {
+        return;
+    }
+
+    let n = settings.radiance_resolution;
+    let texels = n * n;
+    let rows = thread.base + 2u * texels;
+
+    var total = 0.0;
+
+    for (var y = 0u; y < n; y++) {
+        total += bitcast<f32>(probe_guide[rows + y]);
+    }
+
+    var row_weight = 0u;
+
+    for (var x = 0u; x < n; x++) {
+        let texel = thread.row * n + x;
+        let weight = probe_clipmap_guide_weight(probe_guide_texel_luminance(thread, x, thread.row), total, thread.rays, texels);
+
+        probe_guide[thread.base + texels + texel] = weight;
+        row_weight += weight;
+    }
+
+    probe_guide[rows + n + thread.row] = row_weight;
+}
+`, [
+            chunk_probe_clipmap_guide_thread,
+        ]),
+});
+
+/**
+ * The guide, starts (§8.6): a thread a row of the walk of each listed probe's radiance map, dispatched
+ * through `PROBE_DISPATCH_ROWS`. It totals the weights and spreads what they leave of
+ * `PROBE_GUIDE_SCALE` evenly. It takes the weight the walk covers before its row from the row weights,
+ * then writes the first ray of each of its walk positions. The walk's first row writes the total and the
+ * even share as well.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_starts = ComputeShader.from({
+    label: "Probe Clipmap Guide Starts",
+    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 thread = probe_guide_thread(workgroup_id, lane);
+
+    if (!thread.valid) {
+        return;
+    }
+
+    let n = settings.radiance_resolution;
+    let texels = n * n;
+    let rays = thread.rays;
+    let row_weights = thread.base + 2u * texels + n;
+
+    var weights = 0u;
+
+    for (var y = 0u; y < n; y++) {
+        weights += probe_guide[row_weights + y];
+    }
+
+    // the shares, each rounded to f32, may sum a few units past the scale
+    let share = select(0u, (PROBE_GUIDE_SCALE - weights) / texels, weights < PROBE_GUIDE_SCALE);
+    let total = weights + share * texels;
+
+    // the walk's rows before this one, each a row of the map
+    var before = 0u;
+
+    for (var r = 0u; r < thread.row; r++) {
+        before += probe_guide[row_weights + probe_clipmap_guide_texel(r * n, thread.updates, n) / n] + share * n;
+    }
+
+    let phase = probe_clipmap_guide_phase(thread.slot, thread.updates);
+
+    for (var c = 0u; c < n; c++) {
+        let position = thread.row * n + c;
+
+        probe_guide[thread.base + position] = probe_clipmap_guide_start(before, total, rays, phase);
+
+        before += probe_guide[thread.base + texels + probe_clipmap_guide_texel(position, thread.updates, n)] + share;
+    }
+
+    if (thread.row == 0u) {
+        probe_guide[row_weights + n] = total;
+        probe_guide[row_weights + n + 1u] = share;
+    }
+}
+`, [
+            chunk_probe_clipmap_guide_thread,
+        ]),
+});

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

@@ -0,0 +1,15 @@
+/**
+ * The probe clipmap's deferred indirect light in one pass (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.6), for SSR
+ * off: one pick a pixel, by its own normal and the view, with the frame's STBN, for both lobes.
+ * - The diffuse is `shader_probe_clipmap_diffuse`'s: the picked SH resolved at the bent normal, times π. Its
+ *   shares are the pick's, not re-weighted for the bent normal, so SSR on and off light the diffuse alike.
+ * - The specular is the pick's radiance (`probe_clipmap_radiance_of`), its shares re-weighted for the lobe.
+ * - A pixel no probe weighs anything for takes the environment's for both.
+ * - The two are resolved as `shader_resolve_indirect_lighting` resolves the IBL pair: AO multiplies the
+ *   diffuse, the specular is occluded along its lobe, and the result is added to the scene's colour.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_indirect_lighting: ImageShader;
+import { ImageShader } from "../../../shader/ImageShader.js";
+//# sourceMappingURL=shader_probe_clipmap_indirect_lighting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_indirect_lighting.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_indirect_lighting.js"],"names":[],"mappings":"AA0IA;;;;;;;;;;;GAWG;AACH,qDAFU,WAAW,CA0BlB;4BAxJyB,gCAAgC"}