@woosh/meep-engine 3.58.0 → 3.59.0

package/src/shade/renderer/volumetrics/irradiance_clipmap/chunk_irradiance_clipmap_gi_sample.d.ts

@@ -14,10 +14,23 @@ export const chunk_irradiance_clipmap_gi_sample_brick4: CodeChunk;
  * @type {CodeChunk}
  */
 export const chunk_irradiance_clipmap_gi_sample_lpv: CodeChunk;
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under the probe clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.5):
+ * the probes' pick at `position_ws`, jittered by the point's hash with the frame (`jitter_from_vectors`). A
+ * voxel is no surface, so there is no normal to bias the point by or to weigh back faces with, nor a view.
+ * Where no probe weighs anything, the environment SH, as under IBL.
+ *
+ * The probes' SH is what the volume accumulates, Metro L1 in the scale under which
+ * `resolve_irradiance_sh_to_diffuse` gives E/π. It is handed over as the radiance SH2 that
+ * `volumetrics_irradiance_sh_add_radiance` turns back into it: 2π × the luma, band 1 in the basis order
+ * (y, z, x), and the chroma, which only the constant band has, over band 0's basis constant. Reads the probes'
+ * group, `view` and `environment_sh`.
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_probe_clipmap: CodeChunk;
 /**
  * Evaluates indirect radiance SH2 (`array<vec3<f32>, 4>`) at a world position `position_ws` according
- * to the renderer's active {@link INDIRECT_LIGHTING} switch. The probe clipmap takes the environment SH
- * until it samples its own probes.
+ * to the renderer's active {@link INDIRECT_LIGHTING} switch.
  *
  * @type {CodeChunkChoice}
  */

package/src/shade/renderer/volumetrics/irradiance_clipmap/chunk_irradiance_clipmap_gi_sample.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_irradiance_clipmap_gi_sample.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/chunk_irradiance_clipmap_gi_sample.js"],"names":[],"mappings":"AAUA;;;GAGG;AACH,qDAFU,SAAS,CAcjB;AAIF;;;;GAIG;AACH,wDAFU,SAAS,CAYjB;AAEF;;;GAGG;AACH,qDAFU,SAAS,CAqBjB;AAEF;;;;;;GAMG;AACH,iDAFU,eAAe,CAEiE;0BAxEhE,oCAAoC;gCAC9B,0CAA0C"}
+{"version":3,"file":"chunk_irradiance_clipmap_gi_sample.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/chunk_irradiance_clipmap_gi_sample.js"],"names":[],"mappings":"AAaA;;;GAGG;AACH,qDAFU,SAAS,CAcjB;AAIF;;;;GAIG;AACH,wDAFU,SAAS,CAYjB;AAEF;;;GAGG;AACH,qDAFU,SAAS,CAqBjB;AAEF;;;;;;;;;;;;GAYG;AACH,+DAFU,SAAS,CAqCjB;AAIF;;;;;GAKG;AACH,iDAFU,eAAe,CAEiE;0BA3HhE,oCAAoC;gCAC9B,0CAA0C"}

package/src/shade/renderer/volumetrics/irradiance_clipmap/chunk_irradiance_clipmap_gi_sample.js

@@ -1,5 +1,8 @@
 import { chunk_brick4_sample_sh } from "../../global_illumination/brick4/gpu/draw/chunk_brick4_sample_sh.js";
+import { chunk_probe_clipmap_pick } from "../../global_illumination/probe_clipmap/probe/chunk_probe_clipmap_pick.js";
 import { INDIRECT_LIGHTING } from "../../INDIRECT_LIGHTING.js";
+import { chunk_YCoCg_to_rgb } from "../../shader/chunk/color/YCoCg/chunk_YCoCg_to_rgb.js";
+import { chunk_jitter_from_vectors } from "../../shader/chunk/random/chunk_jitter_from_vectors.js";
 import { ENVIRONMENT_SH_RESOURCE } from "../../light/environment/ENVIRONMENT_SH_RESOURCE.js";
 import { ShadeIndirectLightingMode } from "../../ShadeIndirectLightingMode.js";
 import { chunk_lpv_mesh_interpolation_probe_sh } from "../../shader/chunk/light/lpv/chunk_lpv_mesh_interpolation_probe_sh.js";
@@ -70,10 +73,61 @@ fn irradiance_clipmap_gi_sample(position_ws: vec3<f32>) -> array<vec3<f32>, 4> {
     ]
 );
 
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under the probe clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.5):
+ * the probes' pick at `position_ws`, jittered by the point's hash with the frame (`jitter_from_vectors`). A
+ * voxel is no surface, so there is no normal to bias the point by or to weigh back faces with, nor a view.
+ * Where no probe weighs anything, the environment SH, as under IBL.
+ *
+ * The probes' SH is what the volume accumulates, Metro L1 in the scale under which
+ * `resolve_irradiance_sh_to_diffuse` gives E/π. It is handed over as the radiance SH2 that
+ * `volumetrics_irradiance_sh_add_radiance` turns back into it: 2π × the luma, band 1 in the basis order
+ * (y, z, x), and the chroma, which only the constant band has, over band 0's basis constant. Reads the probes'
+ * group, `view` and `environment_sh`.
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_probe_clipmap = CodeChunk.from(
+    //language=WGSL
+    `
+fn irradiance_clipmap_gi_sample(position_ws: vec3<f32>) -> array<vec3<f32>, 4> {
+    let no_surface = vec3<f32>(0.0);
+    let probes = probe_clipmap_sample_sh(position_ws, no_surface, no_surface, jitter_from_vectors(position_ws, no_surface));
+
+    if (!probes.found) {
+        return array<vec3<f32>, 4>(
+            environment_sh[0].xyz,
+            environment_sh[1].xyz,
+            environment_sh[2].xyz,
+            environment_sh[3].xyz,
+        );
+    }
+
+    // the inverse of volumetrics_irradiance_sh_add_radiance's 1 / (2 pi) and of its chroma's 1 / band 0
+    const TWO_PI: f32 = 6.283185307179586;
+    const BAND_0_BASIS: f32 = 0.28209479177387814;
+
+    let Y = probes.sh.Y * TWO_PI;
+
+    // the Metro layout is (x, y, z, constant); the basis order is (constant, y, z, x)
+    return array<vec3<f32>, 4>(
+        YCoCg_to_rgb(vec3<f32>(Y.w, probes.sh.CoCg * (BAND_0_BASIS * TWO_PI))),
+        vec3<f32>(Y.y),
+        vec3<f32>(Y.z),
+        vec3<f32>(Y.x),
+    );
+}
+`, [
+        chunk_probe_clipmap_pick,
+        chunk_jitter_from_vectors,
+        chunk_YCoCg_to_rgb,
+    ]
+);
+
+chunk_irradiance_clipmap_gi_sample_probe_clipmap.requireResource(ENVIRONMENT_SH_RESOURCE);
+
 /**
  * Evaluates indirect radiance SH2 (`array<vec3<f32>, 4>`) at a world position `position_ws` according
- * to the renderer's active {@link INDIRECT_LIGHTING} switch. The probe clipmap takes the environment SH
- * until it samples its own probes.
+ * to the renderer's active {@link INDIRECT_LIGHTING} switch.
  *
  * @type {CodeChunkChoice}
  */
@@ -82,4 +136,4 @@ export const chunk_irradiance_clipmap_gi_sample = CodeChunkChoice.from(INDIRECT_
 chunk_irradiance_clipmap_gi_sample.add(ShadeIndirectLightingMode.IBL, chunk_irradiance_clipmap_gi_sample_ibl);
 chunk_irradiance_clipmap_gi_sample.add(ShadeIndirectLightingMode.Brick4, chunk_irradiance_clipmap_gi_sample_brick4);
 chunk_irradiance_clipmap_gi_sample.add(ShadeIndirectLightingMode.LPV, chunk_irradiance_clipmap_gi_sample_lpv);
-chunk_irradiance_clipmap_gi_sample.add(ShadeIndirectLightingMode.ProbeClipmap, chunk_irradiance_clipmap_gi_sample_ibl);
+chunk_irradiance_clipmap_gi_sample.add(ShadeIndirectLightingMode.ProbeClipmap, chunk_irradiance_clipmap_gi_sample_probe_clipmap);

package/src/shade/renderer/volumetrics/irradiance_clipmap/shader_irradiance_clipmap_build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_irradiance_clipmap_build.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/shader_irradiance_clipmap_build.js"],"names":[],"mappings":"AAmCA,oEAA4E;AAE5E,2DAO6B;AAoI7B;;;;;;;;;GASG;AACH,8CAFU,aAAa,CAMpB;6BAvK0B,mCAAmC;8BAJlC,+BAA+B"}
+{"version":3,"file":"shader_irradiance_clipmap_build.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/shader_irradiance_clipmap_build.js"],"names":[],"mappings":"AAqCA,oEAA4E;AAE5E,2DAO6B;AAwI7B;;;;;;;;;GASG;AACH,8CAFU,aAAa,CAMpB;6BA3K0B,mCAAmC;8BAJlC,+BAA+B"}

package/src/shade/renderer/volumetrics/irradiance_clipmap/shader_irradiance_clipmap_build.js

@@ -1,191 +1,197 @@
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { INDIRECT_LIGHT_INTENSITY } from "../../deferred/INDIRECT_LIGHT_INTENSITY.js";
-import { BRICK4_DATA_STRUCT } from "../../global_illumination/brick4/gpu/BRICK4_DATA_STRUCT.js";
-import { LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS } from "../../global_illumination/probe/octahedral/LPV_SHADER_RESOURCE_GROUP.js";
-import { chunk_light_cluster_counts } from "../../light/cluster/chunk_light_cluster_counts.js";
-import { LIGHT_CLUSTER_LOOKUP_STRUCT } from "../../light/cluster/shader_cluster_assign_lights.js";
-import { ENVIRONMENT_SH_TYPE } from "../../light/environment/shader_project_environment_sh.js";
-import { chunk_world_light_cluster_lookup } from "../../light/world_cluster/chunk_world_light_cluster_lookup.js";
-import { chunk_mat4_extract_position } from "../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
-import {
-    chunk_directional_lights_iteration_mask
-} from "../../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
-import {
-    chunk_get_directional_light_info_by_index
-} from "../../shader/chunk/light/io/chunk_get_directional_light_info_by_index.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 { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { f32, i32, u32, vec3i, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-import { chunk_shadowmap_get_light_visibility } from "../../shadow/map/shader/chunk_shadowmap_get_light_visibility.js";
-import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
-import { chunk_volumetrics_irradiance_sh } from "../chunk_volumetrics_irradiance_sh.js";
-import { chunk_volumetrics_local_light_shadow } from "../chunk_volumetrics_local_light_shadow.js";
-import { chunk_irradiance_clipmap_gi_sample } from "./chunk_irradiance_clipmap_gi_sample.js";
-import { chunk_irradiance_clipmap_local_light } from "./chunk_irradiance_clipmap_local_light.js";
-import {
-    IRRADIANCE_CLIPMAP_LIGHT_BUDGET,
-    IRRADIANCE_CLIPMAP_TILE_FORMAT,
-} from "./IRRADIANCE_CLIPMAP.js";
-
-export const IRRADIANCE_CLIPMAP_BUILD_GROUP_SIZE = Object.freeze([4, 4, 4]);
-
-export const IRRADIANCE_CLIPMAP_BUILD_STRUCT = WebGPUStruct.from({
-    tile_origin: vec3u,
-    cascade_index: u32,
-    corner: vec3i,
-    cell_size: f32,
-    tile_size: vec3u,
-    border: i32,
-}, "IrradianceClipmapBuild");
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("build_settings", IRRADIANCE_CLIPMAP_BUILD_STRUCT)
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addUniform("environment_sh", ENVIRONMENT_SH_TYPE)
-    .addStorageBuffer("brick4", BRICK4_DATA_STRUCT, false, true)
-    .addStorageBuffer("light_data", WebGPUArray.u32, false)
-    .addStorageBuffer("world_cluster_lookup", LIGHT_CLUSTER_LOOKUP_STRUCT, false)
-    .addStorageBuffer("world_cluster_data", WebGPUArray.u32, false)
-    .addTexture("shadowmapAtlas", "depth")
-    .addSampler("sCompareLinear", "comparison", SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR)
-    .addStorageTexture("atlas_y", IRRADIANCE_CLIPMAP_TILE_FORMAT, "3d", "write-only")
-    .addStorageTexture("atlas_cocg", IRRADIANCE_CLIPMAP_TILE_FORMAT, "3d", "write-only");
-
-resources.addGroup(LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(${IRRADIANCE_CLIPMAP_BUILD_GROUP_SIZE.join(", ")})
-fn main(@builtin(global_invocation_id) local_texel: vec3<u32>) {
-    let tile_size = build_settings.tile_size;
-    if (any(local_texel >= tile_size)) {
-        return;
-    }
-
-    let local_cell = vec3<i32>(local_texel) - vec3<i32>(build_settings.border);
-    let world_cell = build_settings.corner + local_cell;
-    let position_ws = (vec3<f32>(world_cell) + vec3<f32>(0.5)) * build_settings.cell_size;
-
-    const INDIRECT_INTENSITY: f32 = ${INDIRECT_LIGHT_INTENSITY};
-    let gi_radiance = irradiance_clipmap_gi_sample(position_ws);
-    let scaled_gi = array<vec3<f32>, 4>(
-        gi_radiance[0] * INDIRECT_INTENSITY,
-        gi_radiance[1] * INDIRECT_INTENSITY,
-        gi_radiance[2] * INDIRECT_INTENSITY,
-        gi_radiance[3] * INDIRECT_INTENSITY,
-    );
-
-    var irradiance: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
-    irradiance = volumetrics_irradiance_sh_add_radiance(irradiance, scaled_gi);
-
-    let to_camera = mat4_extract_position(camera.transform) - position_ws;
-    let to_camera_len = max(length(to_camera), 1e-5);
-    let toward_camera = to_camera / to_camera_len;
-
-    var directional_bits = directional_lights_iteration_mask(&light_data);
-    while (directional_bits != 0u) {
-        let directional_index = countTrailingZeros(directional_bits);
-        directional_bits &= ~(1u << directional_index);
-
-        let sun = get_directional_light_info_by_index(&light_data, directional_index);
-
-        let shadow_term = shadowmap_get_directional_light_visibility(
-            &light_data,
-            directional_index,
-            position_ws,
-            toward_camera,
-            sun.direction
-        );
-
-        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * sun.color, sun.direction);
-    }
-
-    let cluster_meta = world_light_cluster_metadata_by_texel(
-        build_settings.cascade_index,
-        local_texel,
-        tile_size
-    );
-
-    let cluster_offset = cluster_meta.offset;
-    let point_count = light_cluster_count_point(cluster_meta.counts);
-    let spot_count = light_cluster_count_spot(cluster_meta.counts);
-
-    for (var j = 0u; j < min(point_count, ${IRRADIANCE_CLIPMAP_LIGHT_BUDGET}u); j++) {
-        let light_index = world_cluster_data[cluster_offset + j];
-        let direct_light = irradiance_clipmap_get_point_light_info_by_index(
-            &light_data,
-            light_index,
-            position_ws,
-            build_settings.cell_size
-        );
-
-        if (all(direct_light.color == vec3<f32>(0.0))) {
-            continue;
-        }
-
-        let shadow_term = volumetrics_point_light_shadow(&light_data, light_index, position_ws);
-        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * direct_light.color, direct_light.direction);
-    }
-
-    for (var k = 0u; k < min(spot_count, ${IRRADIANCE_CLIPMAP_LIGHT_BUDGET}u); k++) {
-        let light_index = world_cluster_data[cluster_offset + point_count + k];
-        let direct_light = irradiance_clipmap_get_spot_light_info_by_index(
-            &light_data,
-            light_index,
-            position_ws,
-            build_settings.cell_size
-        );
-
-        if (all(direct_light.color == vec3<f32>(0.0))) {
-            continue;
-        }
-
-        let shadow_term = volumetrics_spot_light_shadow(&light_data, light_index, position_ws);
-        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * direct_light.color, direct_light.direction);
-    }
-
-    let stored = volumetrics_irradiance_sh_storable(irradiance);
-    let atlas_texel = build_settings.tile_origin + local_texel;
-
-    textureStore(atlas_y, atlas_texel, stored.Y);
-    textureStore(atlas_cocg, atlas_texel, vec4<f32>(stored.CoCg, 0.0, 0.0));
-}
-`, [
-        METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
-        chunk_mat4_extract_position,
-        chunk_irradiance_clipmap_gi_sample,
-        chunk_world_light_cluster_lookup,
-        chunk_light_cluster_counts,
-        chunk_directional_lights_iteration_mask,
-        chunk_get_directional_light_info_by_index,
-        chunk_irradiance_clipmap_local_light,
-        chunk_shadowmap_get_light_visibility,
-        chunk_volumetrics_local_light_shadow,
-        chunk_volumetrics_irradiance_sh,
-    ]
-);
-
-/**
- * Populates one cascade's tile (including its 1-texel trilinear skirt) in the synchronized `Y` and
- * `CoCg` 3D tile atlases of the world-space irradiance clipmap.
- *
- * Evaluates indirect lighting (`INDIRECT_LIGHTING`), directional lights (`SHADOW_DIRECTIONAL_TECHNIQUE`),
- * and world-space clustered point and spot lights with shadow maps at deterministic world-space
- * voxel centres.
- *
- * @type {ComputeShader}
- */
-export const shader_irradiance_clipmap_build = ComputeShader.from({
-    label: "Volumetrics / irradiance clipmap build",
-    resources,
-    body,
-});
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { INDIRECT_LIGHT_INTENSITY } from "../../deferred/INDIRECT_LIGHT_INTENSITY.js";
+import { BRICK4_DATA_STRUCT } from "../../global_illumination/brick4/gpu/BRICK4_DATA_STRUCT.js";
+import { LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS } from "../../global_illumination/probe/octahedral/LPV_SHADER_RESOURCE_GROUP.js";
+import { PROBE_CLIPMAP_SAMPLING_GROUP } from "../../global_illumination/probe_clipmap/probe/chunk_probe_clipmap_pick.js";
+import { VIEW_RESOURCE } from "../../view/VIEW_RESOURCE.js";
+import { chunk_light_cluster_counts } from "../../light/cluster/chunk_light_cluster_counts.js";
+import { LIGHT_CLUSTER_LOOKUP_STRUCT } from "../../light/cluster/shader_cluster_assign_lights.js";
+import { ENVIRONMENT_SH_TYPE } from "../../light/environment/shader_project_environment_sh.js";
+import { chunk_world_light_cluster_lookup } from "../../light/world_cluster/chunk_world_light_cluster_lookup.js";
+import { chunk_mat4_extract_position } from "../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
+import {
+    chunk_directional_lights_iteration_mask
+} from "../../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
+import {
+    chunk_get_directional_light_info_by_index
+} from "../../shader/chunk/light/io/chunk_get_directional_light_info_by_index.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 { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, i32, u32, vec3i, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { chunk_shadowmap_get_light_visibility } from "../../shadow/map/shader/chunk_shadowmap_get_light_visibility.js";
+import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
+import { chunk_volumetrics_irradiance_sh } from "../chunk_volumetrics_irradiance_sh.js";
+import { chunk_volumetrics_local_light_shadow } from "../chunk_volumetrics_local_light_shadow.js";
+import { chunk_irradiance_clipmap_gi_sample } from "./chunk_irradiance_clipmap_gi_sample.js";
+import { chunk_irradiance_clipmap_local_light } from "./chunk_irradiance_clipmap_local_light.js";
+import {
+    IRRADIANCE_CLIPMAP_LIGHT_BUDGET,
+    IRRADIANCE_CLIPMAP_TILE_FORMAT,
+} from "./IRRADIANCE_CLIPMAP.js";
+
+export const IRRADIANCE_CLIPMAP_BUILD_GROUP_SIZE = Object.freeze([4, 4, 4]);
+
+export const IRRADIANCE_CLIPMAP_BUILD_STRUCT = WebGPUStruct.from({
+    tile_origin: vec3u,
+    cascade_index: u32,
+    corner: vec3i,
+    cell_size: f32,
+    tile_size: vec3u,
+    border: i32,
+}, "IrradianceClipmapBuild");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("build_settings", IRRADIANCE_CLIPMAP_BUILD_STRUCT)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("environment_sh", ENVIRONMENT_SH_TYPE)
+    .addStorageBuffer("brick4", BRICK4_DATA_STRUCT, false, true)
+    .addStorageBuffer("light_data", WebGPUArray.u32, false)
+    .addStorageBuffer("world_cluster_lookup", LIGHT_CLUSTER_LOOKUP_STRUCT, false)
+    .addStorageBuffer("world_cluster_data", WebGPUArray.u32, false)
+    .addTexture("shadowmapAtlas", "depth")
+    .addSampler("sCompareLinear", "comparison", SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR)
+    .addStorageTexture("atlas_y", IRRADIANCE_CLIPMAP_TILE_FORMAT, "3d", "write-only")
+    .addStorageTexture("atlas_cocg", IRRADIANCE_CLIPMAP_TILE_FORMAT, "3d", "write-only")
+    // the frame index the probe clipmap's pick is jittered by
+    .add(VIEW_RESOURCE);
+
+resources.addGroup(LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS);
+// the probe clipmap's probes, which their owner binds in every mode
+resources.addGroup(PROBE_CLIPMAP_SAMPLING_GROUP);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${IRRADIANCE_CLIPMAP_BUILD_GROUP_SIZE.join(", ")})
+fn main(@builtin(global_invocation_id) local_texel: vec3<u32>) {
+    let tile_size = build_settings.tile_size;
+    if (any(local_texel >= tile_size)) {
+        return;
+    }
+
+    let local_cell = vec3<i32>(local_texel) - vec3<i32>(build_settings.border);
+    let world_cell = build_settings.corner + local_cell;
+    let position_ws = (vec3<f32>(world_cell) + vec3<f32>(0.5)) * build_settings.cell_size;
+
+    const INDIRECT_INTENSITY: f32 = ${INDIRECT_LIGHT_INTENSITY};
+    let gi_radiance = irradiance_clipmap_gi_sample(position_ws);
+    let scaled_gi = array<vec3<f32>, 4>(
+        gi_radiance[0] * INDIRECT_INTENSITY,
+        gi_radiance[1] * INDIRECT_INTENSITY,
+        gi_radiance[2] * INDIRECT_INTENSITY,
+        gi_radiance[3] * INDIRECT_INTENSITY,
+    );
+
+    var irradiance: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
+    irradiance = volumetrics_irradiance_sh_add_radiance(irradiance, scaled_gi);
+
+    let to_camera = mat4_extract_position(camera.transform) - position_ws;
+    let to_camera_len = max(length(to_camera), 1e-5);
+    let toward_camera = to_camera / to_camera_len;
+
+    var directional_bits = directional_lights_iteration_mask(&light_data);
+    while (directional_bits != 0u) {
+        let directional_index = countTrailingZeros(directional_bits);
+        directional_bits &= ~(1u << directional_index);
+
+        let sun = get_directional_light_info_by_index(&light_data, directional_index);
+
+        let shadow_term = shadowmap_get_directional_light_visibility(
+            &light_data,
+            directional_index,
+            position_ws,
+            toward_camera,
+            sun.direction
+        );
+
+        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * sun.color, sun.direction);
+    }
+
+    let cluster_meta = world_light_cluster_metadata_by_texel(
+        build_settings.cascade_index,
+        local_texel,
+        tile_size
+    );
+
+    let cluster_offset = cluster_meta.offset;
+    let point_count = light_cluster_count_point(cluster_meta.counts);
+    let spot_count = light_cluster_count_spot(cluster_meta.counts);
+
+    for (var j = 0u; j < min(point_count, ${IRRADIANCE_CLIPMAP_LIGHT_BUDGET}u); j++) {
+        let light_index = world_cluster_data[cluster_offset + j];
+        let direct_light = irradiance_clipmap_get_point_light_info_by_index(
+            &light_data,
+            light_index,
+            position_ws,
+            build_settings.cell_size
+        );
+
+        if (all(direct_light.color == vec3<f32>(0.0))) {
+            continue;
+        }
+
+        let shadow_term = volumetrics_point_light_shadow(&light_data, light_index, position_ws);
+        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * direct_light.color, direct_light.direction);
+    }
+
+    for (var k = 0u; k < min(spot_count, ${IRRADIANCE_CLIPMAP_LIGHT_BUDGET}u); k++) {
+        let light_index = world_cluster_data[cluster_offset + point_count + k];
+        let direct_light = irradiance_clipmap_get_spot_light_info_by_index(
+            &light_data,
+            light_index,
+            position_ws,
+            build_settings.cell_size
+        );
+
+        if (all(direct_light.color == vec3<f32>(0.0))) {
+            continue;
+        }
+
+        let shadow_term = volumetrics_spot_light_shadow(&light_data, light_index, position_ws);
+        irradiance = volumetrics_irradiance_sh_add(irradiance, shadow_term * direct_light.color, direct_light.direction);
+    }
+
+    let stored = volumetrics_irradiance_sh_storable(irradiance);
+    let atlas_texel = build_settings.tile_origin + local_texel;
+
+    textureStore(atlas_y, atlas_texel, stored.Y);
+    textureStore(atlas_cocg, atlas_texel, vec4<f32>(stored.CoCg, 0.0, 0.0));
+}
+`, [
+        METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
+        chunk_mat4_extract_position,
+        chunk_irradiance_clipmap_gi_sample,
+        chunk_world_light_cluster_lookup,
+        chunk_light_cluster_counts,
+        chunk_directional_lights_iteration_mask,
+        chunk_get_directional_light_info_by_index,
+        chunk_irradiance_clipmap_local_light,
+        chunk_shadowmap_get_light_visibility,
+        chunk_volumetrics_local_light_shadow,
+        chunk_volumetrics_irradiance_sh,
+    ]
+);
+
+/**
+ * Populates one cascade's tile (including its 1-texel trilinear skirt) in the synchronized `Y` and
+ * `CoCg` 3D tile atlases of the world-space irradiance clipmap.
+ *
+ * Evaluates indirect lighting (`INDIRECT_LIGHTING`), directional lights (`SHADOW_DIRECTIONAL_TECHNIQUE`),
+ * and world-space clustered point and spot lights with shadow maps at deterministic world-space
+ * voxel centres.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_irradiance_clipmap_build = ComputeShader.from({
+    label: "Volumetrics / irradiance clipmap build",
+    resources,
+    body,
+});

package/src/shade/renderer/volumetrics/taa/shader_volumetrics_taa.js

@@ -1,5 +1,5 @@
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { F16_MAX_DEFINITION } from "../../shader/chunk/math/F16_MAX_DEFINITION.js";
+import { F16_MAX_DEFINITION } from "../../shader/chunk/math/F16_MAX_DEFINITION.js";
 import { F32_MAX_DEFINITION } from "../../shader/chunk/math/F32_MAX_DEFINITION.js";
 import { chunk_rgb_to_YCoCg } from "../../shader/chunk/color/YCoCg/chunk_rgb_to_YCoCg.js";
 import { chunk_YCoCg_to_rgb } from "../../shader/chunk/color/YCoCg/chunk_YCoCg_to_rgb.js";
@@ -128,7 +128,7 @@ fn main(@builtin(global_invocation_id) voxel_id: vec3<u32>) {
      value is history, get_std_dev4 in the neighbourhood box turns Inf - Inf into NaN, the clip
      returns NaN, and mix(NaN, center, 0.05) is NaN for every frame after that. Camera motion does
      not clear it and the aerial LUT reads the whole screen column behind it through it; only a
-     resize or a curve change does, via history_reset.
+     curve change does, via history_reset.
 
      Guarding the STORE rather than the two blend operands is what makes that a closed statement:
      whatever the resolve did, the froxel this frame either carries a finite value or carries this
@@ -142,12 +142,12 @@ fn main(@builtin(global_invocation_id) voxel_id: vec3<u32>) {
 
     let final_finite = all(final_color == final_color) && all(abs(final_color) < vec4f(F32_MAX));
 
-    let final_safe = select(current_safe, clamp(final_color, vec4f(0.0), vec4f(F16_MAX)), final_finite);
+    let final_safe = select(current_safe, clamp(final_color, vec4f(0.0), vec4f(F16_MAX)), final_finite);
     textureStore(t_output, voxel_id, final_safe);
 }
     `,
     [
-        F16_MAX_DEFINITION,
+        F16_MAX_DEFINITION,
         F32_MAX_DEFINITION,
         chunk_rgb_to_YCoCg,
         chunk_YCoCg_to_rgb,

package/src/shade/renderer/water/GPUWaterRenderer.d.ts

@@ -42,7 +42,7 @@ export class GPUWaterRenderer {
     /** Optional single-pixel readback on the next rendered water frame. No per-frame readback. */
     request_probe(uv: any): Promise<any>;
     dispose(): void;
-    avboit_prepare({ graph, view_ctx, camera, color_texture, depth_texture, normal_texture, hzb_texture, environment_texture, light_cluster_parameters, light_cluster_lookup, light_cluster_data, shadowmap_atlas, shader_switches }: {
+    avboit_prepare({ graph, view_ctx, camera, color_texture, depth_texture, normal_texture, hzb_texture, environment_texture, light_cluster_parameters, light_cluster_lookup, light_cluster_data, shadowmap_atlas, shader_switches, probes }: {
         graph: any;
         view_ctx: any;
         camera: any;
@@ -56,6 +56,7 @@ export class GPUWaterRenderer {
         light_cluster_data: any;
         shadowmap_atlas: any;
         shader_switches?: ShaderSwitchSet;
+        probes: any;
     }): {
         background_color: any;
     };

package/src/shade/renderer/water/GPUWaterRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUWaterRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/GPUWaterRenderer.js"],"names":[],"mappings":"AAmBA,sFAAsF;AACtF;IACI,WAAa;IACb,mBAAe;IACf,yBAAqB;IACrB,aAAS;IACT,WAAa;IACb;;;;;;;;;;;MAE6B;IAC7B;;;;OAIG;IACH,QAFU,OAAO,4BAA4B,EAAE,cAAc,GAAC,IAAI,CAEpD;IAmBd;;;OAGG;IACH;;;;;MAA8F;IAC9F;;;OAGG;IACH,wBAAyD;IAMzD,oCAIC;IAED,8FAA8F;IAC9F,qCAgBC;IAED,gBASC;IAuDD;;;;;;;;;;;;;;;;MAoIC;IAQD;;;;;YAMC;IAED;;;;;;;;;;MAOC;IAED;;;;;;;;;;;;;;MAwBC;IAED,gGAAgG;IAChG,mEAYC;;CA2BJ;gCAxX+B,uCAAuC"}
+{"version":3,"file":"GPUWaterRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/GPUWaterRenderer.js"],"names":[],"mappings":"AAoBA,sFAAsF;AACtF;IACI,WAAa;IACb,mBAAe;IACf,yBAAqB;IACrB,aAAS;IACT,WAAa;IACb;;;;;;;;;;;MAE6B;IAC7B;;;;OAIG;IACH,QAFU,OAAO,4BAA4B,EAAE,cAAc,GAAC,IAAI,CAEpD;IAmBd;;;OAGG;IACH;;;;;MAA8F;IAC9F;;;OAGG;IACH,wBAAyD;IAMzD,oCAIC;IAED,8FAA8F;IAC9F,qCAgBC;IAED,gBASC;IAuDD;;;;;;;;;;;;;;;;;MAuIC;IAQD;;;;;YAMC;IAED;;;;;;;;;;MAOC;IAED;;;;;;;;;;;;;;MAwBC;IAED,gGAAgG;IAChG,mEAYC;;CA2BJ;gCA3X+B,uCAAuC"}

package/src/shade/renderer/water/GPUWaterRenderer.js

@@ -1,3 +1,4 @@
+import { assert } from "../../../core/assert.js";
 import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
 import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
 import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
@@ -157,7 +158,8 @@ export class GPUWaterRenderer {
 
     avboit_prepare({ graph, view_ctx, camera, color_texture, depth_texture, normal_texture,
         hzb_texture, environment_texture, light_cluster_parameters, light_cluster_lookup, light_cluster_data,
-        shadowmap_atlas, shader_switches = ShaderSwitchSet.EMPTY }) {
+        shadowmap_atlas, shader_switches = ShaderSwitchSet.EMPTY, probes }) {
+        assert.defined(probes, 'probes');
         const scene = view_ctx.scene;
         const settings = { ...this.settings };
         const probe = this.#probe;
@@ -257,6 +259,8 @@ export class GPUWaterRenderer {
                 brick4: view_ctx.scene.volumetric_light_map.buffer,
                 view: view_ctx.uniform_buffer.buffer,
             };
+            // the probes in every mode: a clipmap of no cascade while the probe clipmap has none
+            probes.write_sampling_bindings(shared);
             const bindings = WATER_FINALIZE_RESOURCES.generateBindings(shared, encoder);
             const copy_pipeline = shader_water_background_copy.pipeline;
             const copy_bindings = shader_water_background_copy.descriptor.resources.generateBindings({tScene: shared.tScene}, encoder);

package/src/shade/renderer/water/chunk_water_gi.d.ts

@@ -11,9 +11,19 @@ export const chunk_water_gi_ibl: CodeChunk;
  */
 export const chunk_water_gi_brick4: CodeChunk;
 /**
- * The water's indirect lighting by the renderer's mode ({@link INDIRECT_LIGHTING}): IBL, LPV and
- * ProbeClipmap {@link chunk_water_gi_ibl}, Brick4 {@link chunk_water_gi_brick4}. A pipeline that links it binds
- * `tEnvironment`, `brick4` and `view`, and reads only its own mode's.
+ * The probe clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.5): each call one pick at the point, jittered by a
+ * hash of the point and the normal, as Brick4's is. The irradiance is π × the picked SH resolved at the normal,
+ * the normal standing in for the view, which the irradiance call has none of. The specular is the probes'
+ * radiance picked by the normal and the view (§9.3). Where no probe weighs anything, each is the environment's.
+ * Reads the probes' group, `view` and `tEnvironment`.
+ * @type {CodeChunk}
+ */
+export const chunk_water_gi_probe_clipmap: CodeChunk;
+/**
+ * The water's indirect lighting by the renderer's mode ({@link INDIRECT_LIGHTING}): IBL and LPV
+ * {@link chunk_water_gi_ibl}, Brick4 {@link chunk_water_gi_brick4}, ProbeClipmap
+ * {@link chunk_water_gi_probe_clipmap}. A pipeline that links it binds `tEnvironment`, `brick4`, the probes'
+ * group and `view`, and reads only its own mode's.
  * @type {CodeChunkChoice}
  */
 export const chunk_water_gi: CodeChunkChoice;

package/src/shade/renderer/water/chunk_water_gi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_water_gi.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/chunk_water_gi.js"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,iCAFU,SAAS,CAUoC;AAEvD;;;;GAIG;AACH,oCAFU,SAAS,CAgBwB;AAE3C;;;;;GAKG;AACH,6BAFU,eAAe,CAE6C;0BA3D5C,iCAAiC;gCAC3B,uCAAuC"}
+{"version":3,"file":"chunk_water_gi.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/chunk_water_gi.js"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,iCAFU,SAAS,CAUoC;AAEvD;;;;GAIG;AACH,oCAFU,SAAS,CAgBwB;AAE3C;;;;;;;GAOG;AACH,2CAFU,SAAS,CAwB+E;AAElG;;;;;;GAMG;AACH,6BAFU,eAAe,CAE6C;0BA5F5C,iCAAiC;gCAC3B,uCAAuC"}