@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -2,12 +2,15 @@ import { COLLECTION_U32_STRUCT_READ } from "../../../gpu_primitive/COLLECTION_U3
 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_mod_v3i } from "../../../shader/chunk/geometry/vec3/chunk_mod_v3i.js";
+import { chunk_stbn_sample_vec2 } from "../../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import { chunk_hash_lowbias32 } from "../../../shader/chunk/random/chunk_hash_lowbias32.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 { 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,
@@ -31,13 +34,14 @@ import {
     PROBE_STATE_KIND_MASK,
     PROBE_STATE_NEW,
     PROBE_STATE_UPDATES_SHIFT,
-    PROBE_THREAD_WORKGROUP_SIZE
+    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
- * was wanted and traced, its last update's back faces, and its irradiance. Where relocation moved it
- * is the state's second word, which readers weighing it load with the state.
+ * 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.
  *
  * @type {WebGPUStruct}
  */
@@ -45,12 +49,17 @@ 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 last wanted it: seconds since the clipmap was made */
+    /** 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.
+     */
+    screen: u32,
     /** the irradiance its rays saw, the Metro L1 encoding: luma as SH2, chroma constant */
     sh: METRO_L1_IRRADIANCE_STRUCT,
 }, "ProbeRecord");
@@ -68,7 +77,10 @@ export const PROBE_RAY_STRUCT = WebGPUStruct.from({
     direction: u32,
     /** the hit's normal, octahedral, two unorm16; zero but for a hit */
     normal: u32,
-    /** the `meshes` row whose surface the hit is on, 0 for none */
+    /**
+     * The `meshes` row whose surface the hit is on, 0 for none. After shade, the hit's diffuse albedo,
+     * `pack4x8unorm`, which the light pass reads; zero for any other ray.
+     */
     row: u32,
     /** its kind, the back face, and the hit's cascade (`PROBE_CLIPMAP.js`) */
     flags: u32,
@@ -339,6 +351,8 @@ const PROBE_RAY_KIND_MASK = ${PROBE_RAY_KIND_MASK}u;
 const PROBE_RAY_BACK_FACE = ${PROBE_RAY_BACK_FACE}u;
 const PROBE_RAY_CASCADE_SHIFT = ${PROBE_RAY_CASCADE_SHIFT}u;
 
+const PROBE_WANTED_SCREEN = ${PROBE_WANTED_SCREEN}u;
+
 const PROBE_THREAD_WORKGROUP_SIZE = ${PROBE_THREAD_WORKGROUP_SIZE}u;
 const PROBE_BLEND_SKIRT = ${PROBE_BLEND_SKIRT}.0;
 
@@ -446,3 +460,34 @@ fn probe_clipmap_texel_ray(texel: u32, round: u32, updates: u32, rays: u32, texe
 `, [
     chunk_probe_clipmap,
 ]);
+
+/**
+ * The STBN jitter of a ray in its texel (§8.6): the noise moved by the slot's hash so that neighbouring
+ * probes do not jitter alike, and a fresh sample for each update and each round of a texel's rays. The
+ * trace aims its ray by it, and the light pass picks the probes at its hit with it (§8.7).
+ *
+ * ```wgsl
+ * fn probe_clipmap_ray_jitter(slot: u32, texel: u32, ray: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> // ray: its index among the probe's R; n: n_r
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_ray_jitter = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_ray_jitter(slot: u32, texel: u32, ray: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> {
+    let texels = n * n;
+    let round = select(0u, ray / texels, rays >= texels);
+    let per_texel = max(rays / texels, 1u);
+
+    let scramble = hash_lowbias32(slot);
+    let noise_xy = vec2<u32>(texel % n, texel / n) + vec2<u32>(scramble & 127u, (scramble >> 7u) & 127u);
+
+    return stbn_sample_vec2(vec3<u32>(noise_xy, updates * per_texel + round));
+}
+`, [
+    chunk_hash_lowbias32,
+    chunk_stbn_sample_vec2,
+]);
+
+chunk_probe_clipmap_ray_jitter.requireResource(STBN_VEC2_RESOURCE);

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

@@ -0,0 +1,19 @@
+/**
+ * The cage of a cascade around a receiving point (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3, §9.1): the
+ * lattice cell holding the point moved along `bias_direction` by {@link PROBE_RECEIVER_BIAS} of the
+ * cascade's spacing, whose eight corners are the probes the point reads.
+ *
+ * ```wgsl
+ * fn probe_clipmap_cage(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>, cage: ptr<function, vec3<i32>>) -> bool
+ * fn probe_clipmap_biased(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * `probe_clipmap_cage` writes the cell's least corner and says whether the cascade's cage window holds
+ * it. Want takes it to choose the probes a pixel wants, and the pick to read them, so that a pixel reads
+ * the probes it wanted.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_cage: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_probe_clipmap_cage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_probe_clipmap_cage.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_cage.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH,uCAFU,SAAS,CAkBhB;0BApCuB,uCAAuC"}

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

@@ -0,0 +1,40 @@
+import { chunk_clipmap_contains } from "../../../shader/chunk/clipmap/chunk_clipmap_contains.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { PROBE_LEVELS_RESOURCE } from "./chunk_probe_clipmap.js";
+import { PROBE_RECEIVER_BIAS } from "./PROBE_CLIPMAP.js";
+
+/**
+ * The cage of a cascade around a receiving point (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3, §9.1): the
+ * lattice cell holding the point moved along `bias_direction` by {@link PROBE_RECEIVER_BIAS} of the
+ * cascade's spacing, whose eight corners are the probes the point reads.
+ *
+ * ```wgsl
+ * fn probe_clipmap_cage(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>, cage: ptr<function, vec3<i32>>) -> bool
+ * fn probe_clipmap_biased(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * `probe_clipmap_cage` writes the cell's least corner and says whether the cascade's cage window holds
+ * it. Want takes it to choose the probes a pixel wants, and the pick to read them, so that a pixel reads
+ * the probes it wanted.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_cage = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_biased(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>) -> vec3<f32> {
+    return position + bias_direction * (${PROBE_RECEIVER_BIAS} * probe_levels[cascade].cell_size);
+}
+
+fn probe_clipmap_cage(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>, cage: ptr<function, vec3<i32>>) -> bool {
+    let level = probe_levels[cascade];
+
+    *cage = vec3<i32>(floor(probe_clipmap_biased(cascade, position, bias_direction) / level.cell_size));
+
+    return clipmap_contains(*cage, level.corner, level.size);
+}
+`, [
+    chunk_clipmap_contains,
+]);
+
+chunk_probe_clipmap_cage.requireResource(PROBE_LEVELS_RESOURCE);

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

@@ -0,0 +1,72 @@
+/**
+ * What a reader of the probes needs past the levels: the clipmap's shape, the depth atlas's and the radiance
+ * atlas's.
+ * @type {WebGPUStruct}
+ */
+export const PROBE_SAMPLING_STRUCT: WebGPUStruct;
+/**
+ * The clipmap's shape, a uniform.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_SAMPLING_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The indirection as its readers load it: `r32uint`, a slot or `PROBE_CLIPMAP_NONE` a lattice point.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_INDIRECTION_READ_RESOURCE: ShaderResourceDescriptor;
+/**
+ * Bilinear within a tile, clamped: a tile's skirt makes a tap across its edge read the fold's twin.
+ * @type {SamplerDescriptor}
+ */
+export const PROBE_DEPTH_SAMPLER_DESCRIPTOR: SamplerDescriptor;
+/**
+ * The sampler the depth atlas is tapped through.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_DEPTH_SAMPLER_RESOURCE: ShaderResourceDescriptor;
+/**
+ * A point's picked probes (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.1), and their SH (§9.2):
+ *
+ * ```wgsl
+ * fn probe_clipmap_pick(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, noise: vec2<f32>) -> ProbeClipmapPick
+ * fn probe_clipmap_sh_of(pick: ProbeClipmapPick) -> ProbeClipmapSH
+ * fn probe_clipmap_sample_sh(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, noise: vec2<f32>) -> ProbeClipmapSH
+ * ```
+ *
+ * - **The cage**: `probe_clipmap_cage` along mix(n, v, 0.2), as want takes it, so a pixel reads the
+ *   probes it wanted.
+ * - **The weights**, visibility only, of the cage's eight corners: a corner without an ALIVE probe weighs
+ *   nothing; one with weighs its trilinear weight × `probe_visibility_weight`: the wrap back-face term
+ *   toward the probe from the point itself, and Chebyshev's from one bilinear tap of its depth toward
+ *   the biased point, at the distance in spacings. No SH and no radiance is read for them.
+ * - **The pick**: two of the eight by `pick2_wrs_mat2x4` with the noise, their blend t; in the finest
+ *   cascade's blend skirt, two of the next one's too, the pairs lerped by the skirt's weight. A cascade
+ *   whose corners weigh nothing gives way to the next coarser, without a skirt. With none left the
+ *   weights are zero, and the fallback is the caller's (§9.1, step 6).
+ * - **The SH**: the picked records' Metro L1 structs mixed by their weights; resolved with
+ *   `resolve_irradiance_sh_to_diffuse` at the caller's normal, it gives E/π. `probe_clipmap_sh_of` takes a
+ *   pick already made, so a pass that samples the specular too picks once; `probe_clipmap_sample_sh` picks
+ *   and takes it.
+ *
+ * Per cascade read: 8 indirection loads, 8 state words and 8 depth taps, then 2 indirection loads for
+ * the pair; then two records a cascade read for the SH. A depth tile's place takes no integer division
+ * (`index_to_grid2d_reciprocal`): 7% of the diffuse on the RDNA2 iGPU, whose division is emulated.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_pick: CodeChunk;
+/**
+ * What {@link chunk_probe_clipmap_pick} reads, as a group a reader of the probes adds to its shader (§9.5).
+ * A shader that takes this mode's alternative of an `INDIRECT_LIGHTING` choice binds it in every mode, as
+ * its variants share their resources: from `GPUProbeClipmapGI.write_sampling_bindings`, which writes a
+ * clipmap of no cascade while there are no probes, and the sampler from its descriptor.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const PROBE_CLIPMAP_SAMPLING_GROUP: ShaderResourceGroupDescriptor;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { SamplerDescriptor } from "../../../../descriptor/texture/SamplerDescriptor.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderResourceGroupDescriptor } from "../../../shader/resource/ShaderResourceGroupDescriptor.js";
+//# sourceMappingURL=chunk_probe_clipmap_pick.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_probe_clipmap_pick.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_pick.js"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,oCAFU,YAAY,CAuBF;AAEpB;;;GAGG;AACH,sCAFU,wBAAwB,CAE+E;AAEjH;;;GAGG;AACH,8CAFU,wBAAwB,CAEiF;AAEnH;;;GAGG;AACH,6CAFU,iBAAiB,CAQvB;AAEJ;;;GAGG;AACH,2CAFU,wBAAwB,CAE+G;AAEjJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,uCAFU,SAAS,CA6MhB;AAUH;;;;;;;GAOG;AACH,2CAFU,6BAA6B,CAWG;6BA1Ub,sCAAsC;yCAH1B,sDAAsD;kCAT7D,qDAAqD;0BAQ7D,uCAAuC;8CAEnB,2DAA2D"}

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

@@ -0,0 +1,343 @@
+import { SamplerDescriptor } from "../../../../descriptor/texture/SamplerDescriptor.js";
+import { chunk_clipmap_select_finest } from "../../../shader/chunk/clipmap/chunk_clipmap_select_finest.js";
+import { chunk_uv_octahedral_unit_encode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_encode.js";
+import { chunk_index_to_grid2d_reciprocal } from "../../../shader/chunk/grid/chunk_index_to_grid2d_reciprocal.js";
+import { chunk_probe_visibility_weight } from "../../../shader/chunk/light/probe/chunk_probe_visibility_weight.js";
+import { chunk_pick2_wrs_mat2x4 } from "../../../shader/chunk/random/reservoir/chunk_pick2_wrs_mat2x4.js";
+import { METRO_L1_IRRADIANCE_STRUCT } from "../../../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
+import { chunk_texture_octahedral_skirt_uv } from "../../../shader/chunk/texture/octahedral/chunk_texture_octahedral_skirt_uv.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { ShaderResourceGroupDescriptor } from "../../../shader/resource/ShaderResourceGroupDescriptor.js";
+import { f32, u32, vec2f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_DEPTH_HISTORY_RESOURCE,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_RADIANCE_HISTORY_RESOURCE,
+    PROBE_RECORDS_READ_RESOURCE,
+    PROBE_STATES_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { chunk_probe_clipmap_cage } from "./chunk_probe_clipmap_cage.js";
+import { PROBE_RECEIVER_BIAS_VIEW } from "./PROBE_CLIPMAP.js";
+
+/**
+ * What a reader of the probes needs past the levels: the clipmap's shape, the depth atlas's and the radiance
+ * atlas's.
+ * @type {WebGPUStruct}
+ */
+export const PROBE_SAMPLING_STRUCT = WebGPUStruct.from({
+    /** the cascades, C_p */
+    cascade_count: u32,
+    /** lattice points a side of a cascade's window, N_p, a power of two */
+    resolution: u32,
+    /** octahedral depth texels a side, n_d */
+    depth_resolution: u32,
+    /** tiles a row of the depth atlas */
+    depth_tiles_per_row: u32,
+    /** one over the depth atlas's texels, along x and y */
+    depth_texel: vec2f,
+    /** one over the tiles a row, rounded to f32: a tile's place without an integer division */
+    depth_tiles_per_row_reciprocal: f32,
+    /** octahedral radiance texels a side, n_r */
+    radiance_resolution: u32,
+    /** tiles a row of the radiance atlas */
+    radiance_tiles_per_row: u32,
+    /** one over the radiance atlas's texels, along x and y */
+    radiance_texel: vec2f,
+    /** one over the radiance atlas's tiles a row, rounded to f32 */
+    radiance_tiles_per_row_reciprocal: f32,
+}, "ProbeSampling");
+
+/**
+ * The clipmap's shape, a uniform.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_SAMPLING_RESOURCE = ShaderResourceDescriptor.uniform("probe_sampling", PROBE_SAMPLING_STRUCT);
+
+/**
+ * The indirection as its readers load it: `r32uint`, a slot or `PROBE_CLIPMAP_NONE` a lattice point.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_INDIRECTION_READ_RESOURCE = ShaderResourceDescriptor.texture("probe_indirection", "uint", "3d");
+
+/**
+ * Bilinear within a tile, clamped: a tile's skirt makes a tap across its edge read the fold's twin.
+ * @type {SamplerDescriptor}
+ */
+export const PROBE_DEPTH_SAMPLER_DESCRIPTOR = Object.freeze(SamplerDescriptor.from({
+    magFilter: "linear",
+    minFilter: "linear",
+    mipmapFilter: "nearest",
+    addressModeU: "clamp-to-edge",
+    addressModeV: "clamp-to-edge",
+}));
+
+/**
+ * The sampler the depth atlas is tapped through.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_DEPTH_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler("probe_depth_sampler", "filtering", PROBE_DEPTH_SAMPLER_DESCRIPTOR);
+
+/**
+ * A point's picked probes (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.1), and their SH (§9.2):
+ *
+ * ```wgsl
+ * fn probe_clipmap_pick(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, noise: vec2<f32>) -> ProbeClipmapPick
+ * fn probe_clipmap_sh_of(pick: ProbeClipmapPick) -> ProbeClipmapSH
+ * fn probe_clipmap_sample_sh(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, noise: vec2<f32>) -> ProbeClipmapSH
+ * ```
+ *
+ * - **The cage**: `probe_clipmap_cage` along mix(n, v, 0.2), as want takes it, so a pixel reads the
+ *   probes it wanted.
+ * - **The weights**, visibility only, of the cage's eight corners: a corner without an ALIVE probe weighs
+ *   nothing; one with weighs its trilinear weight × `probe_visibility_weight`: the wrap back-face term
+ *   toward the probe from the point itself, and Chebyshev's from one bilinear tap of its depth toward
+ *   the biased point, at the distance in spacings. No SH and no radiance is read for them.
+ * - **The pick**: two of the eight by `pick2_wrs_mat2x4` with the noise, their blend t; in the finest
+ *   cascade's blend skirt, two of the next one's too, the pairs lerped by the skirt's weight. A cascade
+ *   whose corners weigh nothing gives way to the next coarser, without a skirt. With none left the
+ *   weights are zero, and the fallback is the caller's (§9.1, step 6).
+ * - **The SH**: the picked records' Metro L1 structs mixed by their weights; resolved with
+ *   `resolve_irradiance_sh_to_diffuse` at the caller's normal, it gives E/π. `probe_clipmap_sh_of` takes a
+ *   pick already made, so a pass that samples the specular too picks once; `probe_clipmap_sample_sh` picks
+ *   and takes it.
+ *
+ * Per cascade read: 8 indirection loads, 8 state words and 8 depth taps, then 2 indirection loads for
+ * the pair; then two records a cascade read for the SH. A depth tile's place takes no integer division
+ * (`index_to_grid2d_reciprocal`): 7% of the diffuse on the RDNA2 iGPU, whose division is emulated.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_pick = CodeChunk.from(
+    //language=WGSL
+    `
+struct ProbeClipmapPick {
+    // the pair of the cascade picked from, then the next one's in its skirt
+    slots: vec4<u32>,
+    // each slot's share, summing to one; all zero where no probe weighs anything
+    weights: vec4<f32>,
+}
+
+struct ProbeClipmapPair {
+    slots: vec2<u32>,
+    weights: vec2<f32>,
+}
+
+struct ProbeClipmapSH {
+    sh: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref},
+    found: bool,
+}
+
+fn probe_clipmap_corner_slot(cascade: u32, point: vec3<i32>) -> u32 {
+    let resolution = probe_sampling.resolution;
+    let storage = vec3<u32>(point) & vec3<u32>(resolution - 1u);
+
+    return textureLoad(probe_indirection, probe_clipmap_indirection_texel(cascade, storage, resolution), 0).r;
+}
+
+fn probe_clipmap_corner(k: u32) -> vec3<i32> {
+    return vec3<i32>(vec3<u32>(k & 1u, (k >> 1u) & 1u, (k >> 2u) & 1u));
+}
+
+// a slot's depth moments toward a direction, in spacings: one bilinear tap of its tile, through its skirt
+fn probe_clipmap_depth_moments(slot: u32, direction: vec3<f32>) -> vec2<f32> {
+    let side = probe_sampling.depth_resolution + 2u;
+    let place = index_to_grid2d_reciprocal(slot, probe_sampling.depth_tiles_per_row, probe_sampling.depth_tiles_per_row_reciprocal);
+    let tile = vec2<f32>(place * side);
+    let in_tile = texture_octahedral_skirt_uv(uv_octahedral_unit_encode(direction), f32(side)) * f32(side);
+
+    return textureSampleLevel(probe_depth, probe_depth_sampler, (tile + in_tile) * probe_sampling.depth_texel, 0.0).rg;
+}
+
+fn probe_clipmap_corner_weight(cascade: u32, cage: vec3<i32>, k: u32, position: vec3<f32>, normal: vec3<f32>, biased: vec3<f32>) -> f32 {
+    let point = cage + probe_clipmap_corner(k);
+    let slot = probe_clipmap_corner_slot(cascade, point);
+
+    if (slot == PROBE_CLIPMAP_NONE) {
+        return 0.0;
+    }
+
+    let state = probe_states[slot];
+
+    if (probe_state_kind(state.x) != PROBE_STATE_ALIVE) {
+        return 0.0;
+    }
+
+    let spacing = probe_levels[cascade].cell_size;
+    let probe = vec3<f32>(point) * spacing + probe_clipmap_offset_decode(state.y, spacing);
+
+    let f = biased / spacing - vec3<f32>(cage);
+    let corner = vec3<f32>(probe_clipmap_corner(k));
+    let axes = mix(1.0 - f, f, corner);
+    let trilinear = axes.x * axes.y * axes.z;
+
+    let to_point = biased - probe;
+    let distance = length(to_point);
+    let moments = probe_clipmap_depth_moments(slot, to_point / max(distance, 1e-6));
+    let visibility = probe_visibility_chebyshev(moments, distance / spacing);
+
+    // the back-face term from the point itself, not the biased one
+    return trilinear * probe_visibility_weight(normalize(probe - position), normal, visibility);
+}
+
+fn probe_clipmap_pick_cascade(cascade: u32, position: vec3<f32>, normal: vec3<f32>, bias_direction: vec3<f32>, noise: vec2<f32>) -> ProbeClipmapPair {
+    var out: ProbeClipmapPair;
+    var cage: vec3<i32>;
+
+    if (!probe_clipmap_cage(cascade, position, bias_direction, &cage)) {
+        return out;
+    }
+
+    let biased = probe_clipmap_biased(cascade, position, bias_direction);
+
+    // each corner by name: a dynamic index would put the weights in local memory
+    let weights = mat2x4<f32>(
+        vec4<f32>(
+            probe_clipmap_corner_weight(cascade, cage, 0u, position, normal, biased),
+            probe_clipmap_corner_weight(cascade, cage, 1u, position, normal, biased),
+            probe_clipmap_corner_weight(cascade, cage, 2u, position, normal, biased),
+            probe_clipmap_corner_weight(cascade, cage, 3u, position, normal, biased),
+        ),
+        vec4<f32>(
+            probe_clipmap_corner_weight(cascade, cage, 4u, position, normal, biased),
+            probe_clipmap_corner_weight(cascade, cage, 5u, position, normal, biased),
+            probe_clipmap_corner_weight(cascade, cage, 6u, position, normal, biased),
+            probe_clipmap_corner_weight(cascade, cage, 7u, position, normal, biased),
+        ),
+    );
+
+    if (dot(weights[0], vec4<f32>(1.0)) + dot(weights[1], vec4<f32>(1.0)) <= 0.0) {
+        return out;
+    }
+
+    let pick = pick2_wrs_mat2x4(weights, noise);
+
+    out.slots = vec2<u32>(
+        probe_clipmap_corner_slot(cascade, cage + probe_clipmap_corner(pick.indices.x)),
+        probe_clipmap_corner_slot(cascade, cage + probe_clipmap_corner(pick.indices.y)),
+    );
+    out.weights = vec2<f32>(1.0 - pick.blend, pick.blend);
+
+    return out;
+}
+
+fn probe_clipmap_pick(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, noise: vec2<f32>) -> ProbeClipmapPick {
+    var out: ProbeClipmapPick;
+
+    let count = probe_sampling.cascade_count;
+    let selection = clipmap_select_finest(&probe_levels, count, position, PROBE_BLEND_SKIRT);
+
+    if (selection.level == CLIPMAP_LEVEL_NONE) {
+        return out;
+    }
+
+    let bias_direction = mix(normal, view_direction, ${PROBE_RECEIVER_BIAS_VIEW});
+
+    var cascade = selection.level;
+    var skirt = selection.edge_weight;
+    var pair = probe_clipmap_pick_cascade(cascade, position, normal, bias_direction, noise);
+
+    // a cascade whose corners weigh nothing gives way to the next coarser, whole
+    for (var next = cascade + 1u; next < count; next++) {
+        if (pair.weights.x + pair.weights.y > 0.0) {
+            break;
+        }
+
+        cascade = next;
+        skirt = 0.0;
+        pair = probe_clipmap_pick_cascade(cascade, position, normal, bias_direction, noise);
+    }
+
+    out.slots = vec4<u32>(pair.slots, pair.slots);
+    out.weights = vec4<f32>(pair.weights, 0.0, 0.0);
+
+    if (skirt > 0.0 && cascade + 1u < count && pair.weights.x + pair.weights.y > 0.0) {
+        let coarse = probe_clipmap_pick_cascade(cascade + 1u, position, normal, bias_direction, noise);
+
+        if (coarse.weights.x + coarse.weights.y > 0.0) {
+            out.slots = vec4<u32>(pair.slots, coarse.slots);
+            out.weights = vec4<f32>(pair.weights * (1.0 - skirt), coarse.weights * skirt);
+        }
+    }
+
+    return out;
+}
+
+fn probe_clipmap_sh_of(pick: ProbeClipmapPick) -> ProbeClipmapSH {
+    var out: ProbeClipmapSH;
+
+    out.found = dot(pick.weights, vec4<f32>(1.0)) > 0.0;
+
+    if (!out.found) {
+        return out;
+    }
+
+    // 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;
+        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;
+        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;
+        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;
+        out.sh.CoCg += pick.weights.w * sh.CoCg;
+        out.sh.Y += pick.weights.w * sh.Y;
+    }
+
+    return out;
+}
+
+fn probe_clipmap_sample_sh(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, noise: vec2<f32>) -> ProbeClipmapSH {
+    return probe_clipmap_sh_of(probe_clipmap_pick(position, normal, view_direction, noise));
+}
+
+`, [
+    chunk_probe_clipmap,
+    chunk_clipmap_select_finest,
+    chunk_probe_clipmap_cage,
+    chunk_index_to_grid2d_reciprocal,
+    chunk_uv_octahedral_unit_encode,
+    chunk_texture_octahedral_skirt_uv,
+    chunk_probe_visibility_weight,
+    chunk_pick2_wrs_mat2x4,
+    METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
+]);
+
+chunk_probe_clipmap_pick.requireResource(PROBE_LEVELS_RESOURCE);
+chunk_probe_clipmap_pick.requireResource(PROBE_SAMPLING_RESOURCE);
+chunk_probe_clipmap_pick.requireResource(PROBE_INDIRECTION_READ_RESOURCE);
+chunk_probe_clipmap_pick.requireResource(PROBE_STATES_READ_RESOURCE);
+chunk_probe_clipmap_pick.requireResource(PROBE_RECORDS_READ_RESOURCE);
+chunk_probe_clipmap_pick.requireResource(PROBE_DEPTH_HISTORY_RESOURCE);
+chunk_probe_clipmap_pick.requireResource(PROBE_DEPTH_SAMPLER_RESOURCE);
+
+/**
+ * What {@link chunk_probe_clipmap_pick} reads, as a group a reader of the probes adds to its shader (§9.5).
+ * A shader that takes this mode's alternative of an `INDIRECT_LIGHTING` choice binds it in every mode, as
+ * its variants share their resources: from `GPUProbeClipmapGI.write_sampling_bindings`, which writes a
+ * clipmap of no cascade while there are no probes, and the sampler from its descriptor.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const PROBE_CLIPMAP_SAMPLING_GROUP = new ShaderResourceGroupDescriptor()
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_SAMPLING_RESOURCE)
+    .add(PROBE_INDIRECTION_READ_RESOURCE)
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(PROBE_RECORDS_READ_RESOURCE)
+    .add(PROBE_DEPTH_HISTORY_RESOURCE)
+    .add(PROBE_DEPTH_SAMPLER_RESOURCE)
+    // the radiance the specular samples (chunk_probe_clipmap_sample_radiance), through the depth's sampler
+    .add(PROBE_RADIANCE_HISTORY_RESOURCE);

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

@@ -0,0 +1,29 @@
+/**
+ * A point's specular radiance from its probes (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.3), before Fresnel:
+ *
+ * ```wgsl
+ * fn probe_clipmap_radiance_of(pick: ProbeClipmapPick, position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, roughness: f32) -> ProbeClipmapRadiance
+ * fn probe_clipmap_sample_radiance(position: vec3<f32>, normal: vec3<f32>, view_direction: vec3<f32>, roughness: f32, noise: vec2<f32>) -> ProbeClipmapRadiance
+ * ```
+ *
+ * - **The pick is the diffuse's** (`probe_clipmap_pick`), by the normal and the view, so a pass that does
+ *   both picks once: `probe_clipmap_radiance_of` takes a pick already made, with the point, normal and view it
+ *   was made by. Its shares are re-weighted for the lobe, as Brick4's fused pass re-weights its pair:
+ *   each probe's weight taken again with the sample vector in place of the normal, over the weight it was
+ *   picked by, at the visibility it was picked at. The trilinear part cancels.
+ * - **The sample vector** is Lagarde's dominant direction, `normalize(mix(r, n, α))` with r the
+ *   reflection of the view and α the roughness squared.
+ * - **A radiance tap** a probe, along the sample vector after a one-step sphere parallax: the reflected ray
+ *   is met with a sphere about the probe whose radius is its mean depth along the vector. The depth is held
+ *   at the cage's diagonal (§8.2), past which no parallax is taken. One bilinear tap of the tile, through
+ *   its skirt and the depth's sampler.
+ * - **The rough end** is the probes' SH, mixed by the same shares and resolved for the GGX lobe
+ *   (`resolve_irradiance_sh_to_specular`). The two are blended by `roughness_to_mip_ratio`: SH alone from
+ *   roughness 0.7.
+ * - Where no probe weighs anything, nothing is found and the fallback is the caller's.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_sample_radiance: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_probe_clipmap_sample_radiance.d.ts.map

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

@@ -0,0 +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"}