@woosh/meep-engine 3.60.5 → 3.60.7

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

@@ -1,370 +1,371 @@
-import { FAR_FIELD_IRRADIANCE_SH_RESOURCE } from "../../light/environment/FAR_FIELD_IRRADIANCE_SH_RESOURCE.js";
-import { chunk_clipmap_select_finest } from "../../shader/chunk/clipmap/chunk_clipmap_select_finest.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 {
-    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 {
-    IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT,
-    IRRADIANCE_CLIPMAP_SAMPLER_DESCRIPTOR,
-} from "./IRRADIANCE_CLIPMAP.js";
-import { IRRADIANCE_CLIPMAP_STRUCT } from "./IRRADIANCE_CLIPMAP_STRUCT.js";
-
-/**
- * Uniform buffer binding descriptor for `irradiance_clipmap` ({@link IRRADIANCE_CLIPMAP_STRUCT}).
- * @type {ShaderResourceDescriptor}
- */
-export const IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE = ShaderResourceDescriptor.uniform(
-    "irradiance_clipmap",
-    IRRADIANCE_CLIPMAP_STRUCT
-);
-
-/**
- * 3D atlas texture binding descriptor for the luma SH2 (`Y`) texture of the irradiance clipmap.
- * @type {ShaderResourceDescriptor}
- */
-export const IRRADIANCE_CLIPMAP_ATLAS_Y_RESOURCE = ShaderResourceDescriptor.texture(
-    "irradiance_clipmap_atlas_y",
-    "float",
-    "3d"
-);
-
-/**
- * 3D atlas texture binding descriptor for the chroma (`CoCg`) texture of the irradiance clipmap.
- * @type {ShaderResourceDescriptor}
- */
-export const IRRADIANCE_CLIPMAP_ATLAS_COCG_RESOURCE = ShaderResourceDescriptor.texture(
-    "irradiance_clipmap_atlas_cocg",
-    "float",
-    "3d"
-);
-
-/**
- * Linear clamped sampler binding descriptor for the irradiance clipmap atlas textures.
- * @type {ShaderResourceDescriptor}
- */
-export const IRRADIANCE_CLIPMAP_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler(
-    "irradiance_clipmap_sampler",
-    "filtering",
-    IRRADIANCE_CLIPMAP_SAMPLER_DESCRIPTOR
-);
-
-/**
- * Declares the world-space irradiance clipmap's bindings on a shader resource group.
- *
- * @param {import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
- * @param {Object} [options]
- * @param {boolean} [options.include_far_field=false] whether to also declare `far_field_irradiance_sh`
- * @returns {import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor}
- */
-export function irradiance_clipmap_add_resources(group, { include_far_field = false } = {}) {
-    group
-        .add(IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE)
-        .add(IRRADIANCE_CLIPMAP_ATLAS_Y_RESOURCE)
-        .add(IRRADIANCE_CLIPMAP_ATLAS_COCG_RESOURCE)
-        .add(IRRADIANCE_CLIPMAP_SAMPLER_RESOURCE);
-
-    if (include_far_field) {
-        group.add(FAR_FIELD_IRRADIANCE_SH_RESOURCE);
-    }
-
-    return group;
-}
-
-/**
- * World-space irradiance clipmap sampling:
- *
- * - `irradiance_clipmap_cascade_read_stochastic(c, position_ws, &u) -> MetroL1Irradiance`
- *   Evaluates a 2-tap antithetic Quadratic B-Spline (`B_2 = B_1 * B_0`) read of cascade `c`'s tile
- *   in `irradiance_clipmap_atlas_y` and `irradiance_clipmap_atlas_cocg`.
- * - `irradiance_clipmap_cascade_read(c, position_ws) -> MetroL1Irradiance`
- *   Deterministic convenience wrapper around `irradiance_clipmap_cascade_read_stochastic`.
- * - `irradiance_clipmap_sample_stochastic(position_ws, random_u) -> MetroL1Irradiance`
- *   Selects the finest cascade covering `position_ws` via continuous radial distance from `anchor`,
- *   computes a `smoothstep(0.0, 1.0, selection.edge_weight)` transition weight across the outer band
- *   (`blend_skirt` cells), and stochastically reads `selection.level` or `selection.level + 1`.
- *
- * ## Why Hardware Trilinear (`B_1`) Shows Visible Grid Lines (`┐`)
- *
- * In coarse clipmap cascades (`h = 0.5 m .. 1.0 m`), a single voxel spans 50-100 screen pixels across
- * translucent smoke billboards, and near a point light the `1 / r^2` falloff is strongly convex
- * (`d^2 I / dy^2 >> 0`, e.g. slope dropping by >4x from one voxel to the next):
- * 1. **Dirac-Delta Curvature / Mach Bands:** Hardware trilinear interpolation (`B_1`) is piecewise
- *    linear (`C^0`), so inside each 60-pixel voxel cell its second derivative is identically zero
- *    (`d^2 I / dy^2 = 0`), and *all* of the curvature is concentrated into a 1-pixel Dirac delta
- *    spike along the voxel-centre plane `y = k + 0.5`:
- *    `d^2 I_trilinear / dy^2 = sum_k (I_{k+1} - 2*I_k + I_{k-1}) * delta(y - (k + 0.5))`.
- *    Because human vision (lateral inhibition / Mach band illusion) and contrast stretching respond
- *    to the Laplacian `nabla^2 I`, concentrating the entire slope transition onto a single plane
- *    produces a sharp visible bright/dark ridge line at every voxel centre.
- * 2. **Oblique Billboard Saddle Cross-Terms:** Camera-facing particle billboards slice obliquely
- *    through the world-aligned `(x, y, z)` grid. Within each cell, trilinear interpolation is a
- *    hyperbolic paraboloid (`a + b*x + c*y + d*x*y + ...`) that curves along diagonals but collapses
- *    to straight lines on the axis-aligned planes `x = x_k, y = y_k, z = z_k`, creating visible
- *    grid-aligned creases where adjacent saddle patches meet.
- *
- * ## Why `floor(coord)`-Partitioned Sigg & Hadwiger Stochastic WRS Fails
- *
- * Standard 8-tap Sigg & Hadwiger tricubic B-spline (`B_3`) decomposes the 4-texel 1D cubic weights
- * `(w_0, w_1, w_2, w_3)` around `tc = floor(coord)` (`f = coord - tc in [0, 1)`) into two hardware
- * linear taps: tap 0 pairing `(w_0, w_1)` with weight `g_0 = w_0 + w_1`, and tap 1 pairing `(w_2, w_3)`
- * with weight `g_1 = w_2 + w_3`. In deterministic 8-tap evaluation both taps are summed, so the
- * `floor(coord)` partition is invisible. When sub-sampled stochastically via WRS, however:
- * 1. **Tap-Pairing Flip Across `f = 1^- -> 0^+`:** At a voxel-centre plane, the 3 non-zero B-spline
- *    weights are `(1/6, 4/6, 1/6)`. Just below the plane (`f = 0.999`), Sigg & Hadwiger pairs the
- *    central `4/6` texel with the upper texel (`g_1 = 5/6` at `+0.2` voxels, `g_0 = 1/6` at `-1.0`
- *    voxel). Just above the plane (`f = 0.001`), `tc = floor(coord)` increments and switches the
- *    central `4/6` texel into the lower pair (`g_0 = 5/6` at `-0.2` voxels, `g_1 = 1/6` at `+1.0`
- *    voxel). The 83.3% majority tap therefore jumps backwards by `-0.4` voxels and the variance
- *    jumps by 2.8x across every integer coordinate plane.
- * 2. **Double-Weighting Bias (`w_i^2`) in `weight1 / (weight0 + weight1)`:** Because WRS already
- *    selects tap `i` with probability `w_i`, blending two WRS taps by `weight1 / (weight0 + weight1)`
- *    weights each tap by `w_i` a second time (`w_i^2`), creating a >60% step discontinuity in the
- *    expected value across `tc = floor(coord)`.
- *
- * ## Why 2-Tap Antithetic Quadratic B-Spline (`B_2 = B_1 * B_0`) Is the Sweet Spot
- *
- * Hardware `textureSampleLevel` already evaluates the 3D linear tent filter `B_1`. Convolving `B_1`
- * with a uniform unit box filter `B_0` on `[-0.5, +0.5]^3` via two antithetic taps at
- * `center + delta` and `center - delta` (`delta in [-0.5, +0.5]^3`, mixed `0.5 / 0.5`) yields the
- * exact `C^1` Quadratic B-Spline `B_2 = B_1 * B_0`:
- * - **Constant Second Derivative Across Each Cell:** Because the `[-0.5, +0.5]` smoothing window is
- *   exactly 1 voxel wide, adjacent voxel-centre smoothing windows meet edge-to-edge and spread the
- *   slope change `I_{k+1} - 2*I_k + I_{k-1}` uniformly across all 60 pixels of the cell
- *   (`d^2 B_2 / dx^2 = const`), completely eliminating the Mach-band Dirac spike.
- * - **Zero `floor(coord)` Discontinuity:** Neither the tap offsets nor the weights depend on
- *   `floor(coord)`, so both the mean and the variance are 100% continuous across all voxel planes.
- * - **First-Order Gradient Cancellation & Compact Support:** Antithetic pairing (`+delta`, `-delta`)
- *   cancels all linear gradient noise `+/- dot(nabla I, delta)` on every pixel, while keeping taps
- *   within `+/- 0.5` voxels of `center` (half the radius of `B_3 = B_1 * B_1`), avoiding `+/- 1`
- *   voxel fire-bleed grain and staying strictly inside the 1-texel cascade border.
- *
- * @type {CodeChunk}
- */
-export const chunk_irradiance_clipmap_sample = CodeChunk.from(
-    //language=WGSL
-    `
-const IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT: f32 = ${IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT}.0;
-
-fn irradiance_clipmap_select_finest(
-    position_ws: vec3<f32>,
-    band_width: f32,
-) -> ClipmapSelection {
-    let count = irradiance_clipmap.cascade_count;
-    let anchor_ws = irradiance_clipmap.anchor;
-
-    for (var i = 0u; i < 16u; i++) {
-        if (i >= count) {
-            break;
-        }
-
-        let level = irradiance_clipmap.levels[i];
-        let position_cells = position_ws / level.cell_size;
-        let half_size = 0.5 * vec3<f32>(level.size);
-        let level_center = vec3<f32>(level.corner) + half_size;
-        let anchor_cells = anchor_ws / level.cell_size;
-
-        // Use the continuous camera anchor when within the 1-voxel rounding bound of level.corner,
-        // so cascade selection and edge_weight vary C^1-smoothly with camera motion without
-        // stair-stepping at integer corner transitions.
-        let center_cells = select(
-            level_center,
-            anchor_cells,
-            all(abs(anchor_cells - level_center) <= vec3<f32>(0.501))
-        );
-
-        // Subtract 0.5 cells from half_size so that even when anchor_cells is offset by up to
-        // +/-0.5 cells from level_center, the selection sphere stays strictly inside [0, size]^3
-        // and the +/-0.5 voxel B_2 jitter taps stay strictly inside the 1-texel border
-        // [-0.5, size + 0.5]^3 without hitting the border clamp.
-        let radius = max(0.5, min(half_size.x, min(half_size.y, half_size.z)) - 0.5);
-        let edge = radius - length(position_cells - center_cells);
-
-        if (edge <= 0.0) {
-            continue;
-        }
-
-        return ClipmapSelection(i, saturate(1.0 - edge / band_width));
-    }
-
-    return ClipmapSelection(CLIPMAP_LEVEL_NONE, 0.0);
-}
-
-fn irradiance_clipmap_box_jitter(u: ptr<function, f32>, salt: u32) -> vec3<f32> {
-    let h0 = hash_lowbias32(bitcast<u32>(*u) ^ salt);
-    let h1 = hash_lowbias32(h0 ^ 0x9e3779b9u);
-    let h2 = hash_lowbias32(h1 ^ 0x85ebca6bu);
-    *u = hash_to_float01(hash_lowbias32(h2 ^ 0xc2b2ae35u));
-
-    // Uniform box jitter in [-0.5, +0.5]^3 paired antithetically (center + delta, center - delta):
-    // convolving hardware trilinear B_1 with B_0 on [-0.5, +0.5]^3 yields the exact C^1 Quadratic
-    // B-Spline B_2 = B_1 * B_0 with constant second derivative across each cell, zero floor/integer
-    // discontinuity, and support staying strictly within the 1-texel cascade border.
-    return vec3<f32>(
-        hash_to_float01(h0) - 0.5,
-        hash_to_float01(h1) - 0.5,
-        hash_to_float01(h2) - 0.5,
-    );
-}
-
-fn irradiance_clipmap_cascade_read_stochastic(
-    c: u32,
-    position_ws: vec3<f32>,
-    u: ptr<function, f32>,
-) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
-    let level = irradiance_clipmap.levels[c];
-    let cascade = irradiance_clipmap.cascades[c];
-    let inv_atlas = irradiance_clipmap.inverse_atlas_size;
-
-    let local = position_ws / level.cell_size - vec3<f32>(level.corner);
-    let center = cascade.content_origin + local;
-    let delta = irradiance_clipmap_box_jitter(u, (c + 1u) * 0x27d4eb2du);
-
-    // Clamp hardware linear tap coordinates to the cascade tile's valid texel centres (including its 1-texel border)
-    let t_min = cascade.content_origin - vec3<f32>(0.5);
-    let t_max = cascade.content_origin + vec3<f32>(level.size) + vec3<f32>(0.5);
-    let uvw0 = clamp(center + delta, t_min, t_max) * inv_atlas;
-    let uvw1 = clamp(center - delta, t_min, t_max) * inv_atlas;
-
-    let sh0 = ${METRO_L1_IRRADIANCE_STRUCT.make({
-        CoCg: "textureSampleLevel(irradiance_clipmap_atlas_cocg, irradiance_clipmap_sampler, uvw0, 0.0).xy",
-        Y: "textureSampleLevel(irradiance_clipmap_atlas_y, irradiance_clipmap_sampler, uvw0, 0.0)",
-    })};
-    let sh1 = ${METRO_L1_IRRADIANCE_STRUCT.make({
-        CoCg: "textureSampleLevel(irradiance_clipmap_atlas_cocg, irradiance_clipmap_sampler, uvw1, 0.0).xy",
-        Y: "textureSampleLevel(irradiance_clipmap_atlas_y, irradiance_clipmap_sampler, uvw1, 0.0)",
-    })};
-
-    return irradiance_clipmap_mix_sh(sh0, sh1, 0.5);
-}
-
-fn irradiance_clipmap_cascade_read(c: u32, position_ws: vec3<f32>) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
-    let level = irradiance_clipmap.levels[c];
-    let cascade = irradiance_clipmap.cascades[c];
-    let local = position_ws / level.cell_size - vec3<f32>(level.corner);
-    let center = cascade.content_origin + local;
-    let t_min = cascade.content_origin - vec3<f32>(0.5);
-    let t_max = cascade.content_origin + vec3<f32>(level.size) + vec3<f32>(0.5);
-    let uvw = clamp(center, t_min, t_max) * irradiance_clipmap.inverse_atlas_size;
-
-    return ${METRO_L1_IRRADIANCE_STRUCT.make({
-        CoCg: "textureSampleLevel(irradiance_clipmap_atlas_cocg, irradiance_clipmap_sampler, uvw, 0.0).xy",
-        Y: "textureSampleLevel(irradiance_clipmap_atlas_y, irradiance_clipmap_sampler, uvw, 0.0)",
-    })};
-}
-
-fn irradiance_clipmap_mix_sh(
-    a: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref},
-    b: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref},
-    t: f32,
-) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
-    return ${METRO_L1_IRRADIANCE_STRUCT.make({
-        CoCg: "a.CoCg + (b.CoCg - a.CoCg) * t",
-        Y: "a.Y + (b.Y - a.Y) * t",
-    })};
-}
-
-fn irradiance_clipmap_sample_stochastic(
-    position_ws: vec3<f32>,
-    random_u: f32,
-) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
-    let count = irradiance_clipmap.cascade_count;
-    let blend_skirt = select(IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT, irradiance_clipmap.blend_skirt, irradiance_clipmap.blend_skirt > 0.0);
-    let selection = irradiance_clipmap_select_finest(position_ws, blend_skirt);
-
-    if (selection.level == CLIPMAP_LEVEL_NONE) {
-        return ${METRO_L1_IRRADIANCE_STRUCT.make({
-            CoCg: "vec2<f32>(0.0)",
-            Y: "vec4<f32>(0.0)",
-        })};
-    }
-
-    var u = clamp(random_u, 0.0, 0.99999994);
-    let parent = selection.level + 1u;
-    if (selection.edge_weight <= 0.0 || parent >= count) {
-        return irradiance_clipmap_cascade_read_stochastic(selection.level, position_ws, &u);
-    }
-
-    // Non-linear smoothstep transition keeps sampling in the higher-resolution cascade longer,
-    // rescaling u via sample reuse so the downstream WRS tricubic tap gets an independent uniform sample.
-    let blend = smoothstep(0.0, 1.0, selection.edge_weight);
-    var chosen_cascade = selection.level;
-    if (u < blend) {
-        chosen_cascade = parent;
-        u = u / max(blend, 1e-6);
-    } else {
-        u = (u - blend) / max(1.0 - blend, 1e-6);
-    }
-
-    return irradiance_clipmap_cascade_read_stochastic(chosen_cascade, position_ws, &u);
-}
-`, [
-        IRRADIANCE_CLIPMAP_STRUCT.declaration_chunk,
-        METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
-        chunk_clipmap_select_finest,
-        chunk_hash_lowbias32,
-        chunk_hash_to_float01,
-    ]
-);
-
-chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE);
-chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_ATLAS_Y_RESOURCE);
-chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_ATLAS_COCG_RESOURCE);
-chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_SAMPLER_RESOURCE);
-
-/**
- * Samples the world-space irradiance clipmap with deterministic `smoothstep` cascade blending and
- * automatic fallback into the scene's cached `far_field_irradiance_sh` (used by particle lighting):
- *
- * - Outside all cascades (`CLIPMAP_LEVEL_NONE`), returns `far_field_irradiance_sh`.
- * - In the interior of cascade `c` (`edge_weight <= 0.0`), performs a 2-tap antithetic Quadratic
- *   B-Spline (`B_2 = B_1 * B_0`) read of cascade `c`.
- * - In the outer transition band of cascade `c < count - 1` (`edge_weight > 0.0`), smoothly blends
- *   between cascade `c` and parent cascade `c + 1` using `smoothstep(0.0, 1.0, edge_weight)` with
- *   hash-rescaled sample reuse across both cascades.
- * - In the outer transition band of the coarsest cascade (`c == count - 1`), smoothly blends between
- *   the coarsest cascade and `far_field_irradiance_sh` using `smoothstep(0.0, 1.0, edge_weight)`.
- *
- * @type {CodeChunk}
- */
-export const chunk_irradiance_clipmap_sample_with_far_field = CodeChunk.from(
-    //language=WGSL
-    `
-fn irradiance_clipmap_sample_with_far_field(
-    position_ws: vec3<f32>,
-    random_u: f32,
-) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
-    let count = irradiance_clipmap.cascade_count;
-    let blend_skirt = select(IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT, irradiance_clipmap.blend_skirt, irradiance_clipmap.blend_skirt > 0.0);
-    let selection = irradiance_clipmap_select_finest(position_ws, blend_skirt);
-
-    if (selection.level == CLIPMAP_LEVEL_NONE) {
-        return far_field_irradiance_sh;
-    }
-
-    var u = clamp(random_u, 0.0, 0.99999994);
-    let inner = irradiance_clipmap_cascade_read_stochastic(selection.level, position_ws, &u);
-    if (selection.edge_weight <= 0.0) {
-        return inner;
-    }
-
-    let blend = smoothstep(0.0, 1.0, selection.edge_weight);
-    let parent = selection.level + 1u;
-
-    if (parent < count) {
-        let outer = irradiance_clipmap_cascade_read_stochastic(parent, position_ws, &u);
-        return irradiance_clipmap_mix_sh(inner, outer, blend);
-    }
-
-    return irradiance_clipmap_mix_sh(inner, far_field_irradiance_sh, blend);
-}
-`, [
-        chunk_irradiance_clipmap_sample,
-    ]
-);
-
-chunk_irradiance_clipmap_sample_with_far_field.requireResource(IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE);
-chunk_irradiance_clipmap_sample_with_far_field.requireResource(FAR_FIELD_IRRADIANCE_SH_RESOURCE);
+import { FAR_FIELD_IRRADIANCE_SH_RESOURCE } from "../../light/environment/FAR_FIELD_IRRADIANCE_SH_RESOURCE.js";
+import { chunk_clipmap_select_finest } from "../../shader/chunk/clipmap/chunk_clipmap_select_finest.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 {
+    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 {
+    IRRADIANCE_CLIPMAP_CASCADE_LIMIT,
+    IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT,
+    IRRADIANCE_CLIPMAP_SAMPLER_DESCRIPTOR,
+} from "./IRRADIANCE_CLIPMAP.js";
+import { IRRADIANCE_CLIPMAP_STRUCT } from "./IRRADIANCE_CLIPMAP_STRUCT.js";
+
+/**
+ * Uniform buffer binding descriptor for `irradiance_clipmap` ({@link IRRADIANCE_CLIPMAP_STRUCT}).
+ * @type {ShaderResourceDescriptor}
+ */
+export const IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE = ShaderResourceDescriptor.uniform(
+    "irradiance_clipmap",
+    IRRADIANCE_CLIPMAP_STRUCT
+);
+
+/**
+ * 3D atlas texture binding descriptor for the luma SH2 (`Y`) texture of the irradiance clipmap.
+ * @type {ShaderResourceDescriptor}
+ */
+export const IRRADIANCE_CLIPMAP_ATLAS_Y_RESOURCE = ShaderResourceDescriptor.texture(
+    "irradiance_clipmap_atlas_y",
+    "float",
+    "3d"
+);
+
+/**
+ * 3D atlas texture binding descriptor for the chroma (`CoCg`) texture of the irradiance clipmap.
+ * @type {ShaderResourceDescriptor}
+ */
+export const IRRADIANCE_CLIPMAP_ATLAS_COCG_RESOURCE = ShaderResourceDescriptor.texture(
+    "irradiance_clipmap_atlas_cocg",
+    "float",
+    "3d"
+);
+
+/**
+ * Linear clamped sampler binding descriptor for the irradiance clipmap atlas textures.
+ * @type {ShaderResourceDescriptor}
+ */
+export const IRRADIANCE_CLIPMAP_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler(
+    "irradiance_clipmap_sampler",
+    "filtering",
+    IRRADIANCE_CLIPMAP_SAMPLER_DESCRIPTOR
+);
+
+/**
+ * Declares the world-space irradiance clipmap's bindings on a shader resource group.
+ *
+ * @param {import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ * @param {Object} [options]
+ * @param {boolean} [options.include_far_field=false] whether to also declare `far_field_irradiance_sh`
+ * @returns {import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor}
+ */
+export function irradiance_clipmap_add_resources(group, { include_far_field = false } = {}) {
+    group
+        .add(IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE)
+        .add(IRRADIANCE_CLIPMAP_ATLAS_Y_RESOURCE)
+        .add(IRRADIANCE_CLIPMAP_ATLAS_COCG_RESOURCE)
+        .add(IRRADIANCE_CLIPMAP_SAMPLER_RESOURCE);
+
+    if (include_far_field) {
+        group.add(FAR_FIELD_IRRADIANCE_SH_RESOURCE);
+    }
+
+    return group;
+}
+
+/**
+ * World-space irradiance clipmap sampling:
+ *
+ * - `irradiance_clipmap_cascade_read_stochastic(c, position_ws, &u) -> MetroL1Irradiance`
+ *   Evaluates a 2-tap antithetic Quadratic B-Spline (`B_2 = B_1 * B_0`) read of cascade `c`'s tile
+ *   in `irradiance_clipmap_atlas_y` and `irradiance_clipmap_atlas_cocg`.
+ * - `irradiance_clipmap_cascade_read(c, position_ws) -> MetroL1Irradiance`
+ *   Deterministic convenience wrapper around `irradiance_clipmap_cascade_read_stochastic`.
+ * - `irradiance_clipmap_sample_stochastic(position_ws, random_u) -> MetroL1Irradiance`
+ *   Selects the finest cascade covering `position_ws` via continuous radial distance from `anchor`,
+ *   computes a `smoothstep(0.0, 1.0, selection.edge_weight)` transition weight across the outer band
+ *   (`blend_skirt` cells), and stochastically reads `selection.level` or `selection.level + 1`.
+ *
+ * ## Why Hardware Trilinear (`B_1`) Shows Visible Grid Lines (`┐`)
+ *
+ * In coarse clipmap cascades (`h = 0.5 m .. 1.0 m`), a single voxel spans 50-100 screen pixels across
+ * translucent smoke billboards, and near a point light the `1 / r^2` falloff is strongly convex
+ * (`d^2 I / dy^2 >> 0`, e.g. slope dropping by >4x from one voxel to the next):
+ * 1. **Dirac-Delta Curvature / Mach Bands:** Hardware trilinear interpolation (`B_1`) is piecewise
+ *    linear (`C^0`), so inside each 60-pixel voxel cell its second derivative is identically zero
+ *    (`d^2 I / dy^2 = 0`), and *all* of the curvature is concentrated into a 1-pixel Dirac delta
+ *    spike along the voxel-centre plane `y = k + 0.5`:
+ *    `d^2 I_trilinear / dy^2 = sum_k (I_{k+1} - 2*I_k + I_{k-1}) * delta(y - (k + 0.5))`.
+ *    Because human vision (lateral inhibition / Mach band illusion) and contrast stretching respond
+ *    to the Laplacian `nabla^2 I`, concentrating the entire slope transition onto a single plane
+ *    produces a sharp visible bright/dark ridge line at every voxel centre.
+ * 2. **Oblique Billboard Saddle Cross-Terms:** Camera-facing particle billboards slice obliquely
+ *    through the world-aligned `(x, y, z)` grid. Within each cell, trilinear interpolation is a
+ *    hyperbolic paraboloid (`a + b*x + c*y + d*x*y + ...`) that curves along diagonals but collapses
+ *    to straight lines on the axis-aligned planes `x = x_k, y = y_k, z = z_k`, creating visible
+ *    grid-aligned creases where adjacent saddle patches meet.
+ *
+ * ## Why `floor(coord)`-Partitioned Sigg & Hadwiger Stochastic WRS Fails
+ *
+ * Standard 8-tap Sigg & Hadwiger tricubic B-spline (`B_3`) decomposes the 4-texel 1D cubic weights
+ * `(w_0, w_1, w_2, w_3)` around `tc = floor(coord)` (`f = coord - tc in [0, 1)`) into two hardware
+ * linear taps: tap 0 pairing `(w_0, w_1)` with weight `g_0 = w_0 + w_1`, and tap 1 pairing `(w_2, w_3)`
+ * with weight `g_1 = w_2 + w_3`. In deterministic 8-tap evaluation both taps are summed, so the
+ * `floor(coord)` partition is invisible. When sub-sampled stochastically via WRS, however:
+ * 1. **Tap-Pairing Flip Across `f = 1^- -> 0^+`:** At a voxel-centre plane, the 3 non-zero B-spline
+ *    weights are `(1/6, 4/6, 1/6)`. Just below the plane (`f = 0.999`), Sigg & Hadwiger pairs the
+ *    central `4/6` texel with the upper texel (`g_1 = 5/6` at `+0.2` voxels, `g_0 = 1/6` at `-1.0`
+ *    voxel). Just above the plane (`f = 0.001`), `tc = floor(coord)` increments and switches the
+ *    central `4/6` texel into the lower pair (`g_0 = 5/6` at `-0.2` voxels, `g_1 = 1/6` at `+1.0`
+ *    voxel). The 83.3% majority tap therefore jumps backwards by `-0.4` voxels and the variance
+ *    jumps by 2.8x across every integer coordinate plane.
+ * 2. **Double-Weighting Bias (`w_i^2`) in `weight1 / (weight0 + weight1)`:** Because WRS already
+ *    selects tap `i` with probability `w_i`, blending two WRS taps by `weight1 / (weight0 + weight1)`
+ *    weights each tap by `w_i` a second time (`w_i^2`), creating a >60% step discontinuity in the
+ *    expected value across `tc = floor(coord)`.
+ *
+ * ## Why 2-Tap Antithetic Quadratic B-Spline (`B_2 = B_1 * B_0`) Is the Sweet Spot
+ *
+ * Hardware `textureSampleLevel` already evaluates the 3D linear tent filter `B_1`. Convolving `B_1`
+ * with a uniform unit box filter `B_0` on `[-0.5, +0.5]^3` via two antithetic taps at
+ * `center + delta` and `center - delta` (`delta in [-0.5, +0.5]^3`, mixed `0.5 / 0.5`) yields the
+ * exact `C^1` Quadratic B-Spline `B_2 = B_1 * B_0`:
+ * - **Constant Second Derivative Across Each Cell:** Because the `[-0.5, +0.5]` smoothing window is
+ *   exactly 1 voxel wide, adjacent voxel-centre smoothing windows meet edge-to-edge and spread the
+ *   slope change `I_{k+1} - 2*I_k + I_{k-1}` uniformly across all 60 pixels of the cell
+ *   (`d^2 B_2 / dx^2 = const`), completely eliminating the Mach-band Dirac spike.
+ * - **Zero `floor(coord)` Discontinuity:** Neither the tap offsets nor the weights depend on
+ *   `floor(coord)`, so both the mean and the variance are 100% continuous across all voxel planes.
+ * - **First-Order Gradient Cancellation & Compact Support:** Antithetic pairing (`+delta`, `-delta`)
+ *   cancels all linear gradient noise `+/- dot(nabla I, delta)` on every pixel, while keeping taps
+ *   within `+/- 0.5` voxels of `center` (half the radius of `B_3 = B_1 * B_1`), avoiding `+/- 1`
+ *   voxel fire-bleed grain and staying strictly inside the 1-texel cascade border.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_sample = CodeChunk.from(
+    //language=WGSL
+    `
+const IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT: f32 = ${IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT}.0;
+
+fn irradiance_clipmap_select_finest(
+    position_ws: vec3<f32>,
+    band_width: f32,
+) -> ClipmapSelection {
+    let count = irradiance_clipmap.cascade_count;
+    let anchor_ws = irradiance_clipmap.anchor;
+
+    for (var i = 0u; i < ${IRRADIANCE_CLIPMAP_CASCADE_LIMIT}u; i++) {
+        if (i >= count) {
+            break;
+        }
+
+        let level = irradiance_clipmap.levels[i];
+        let position_cells = position_ws / level.cell_size;
+        let half_size = 0.5 * vec3<f32>(level.size);
+        let level_center = vec3<f32>(level.corner) + half_size;
+        let anchor_cells = anchor_ws / level.cell_size;
+
+        // Use the continuous camera anchor when within the 1-voxel rounding bound of level.corner,
+        // so cascade selection and edge_weight vary C^1-smoothly with camera motion without
+        // stair-stepping at integer corner transitions.
+        let center_cells = select(
+            level_center,
+            anchor_cells,
+            all(abs(anchor_cells - level_center) <= vec3<f32>(0.501))
+        );
+
+        // Subtract 0.5 cells from half_size so that even when anchor_cells is offset by up to
+        // +/-0.5 cells from level_center, the selection sphere stays strictly inside [0, size]^3
+        // and the +/-0.5 voxel B_2 jitter taps stay strictly inside the 1-texel border
+        // [-0.5, size + 0.5]^3 without hitting the border clamp.
+        let radius = max(0.5, min(half_size.x, min(half_size.y, half_size.z)) - 0.5);
+        let edge = radius - length(position_cells - center_cells);
+
+        if (edge <= 0.0) {
+            continue;
+        }
+
+        return ClipmapSelection(i, saturate(1.0 - edge / band_width));
+    }
+
+    return ClipmapSelection(CLIPMAP_LEVEL_NONE, 0.0);
+}
+
+fn irradiance_clipmap_box_jitter(u: ptr<function, f32>, salt: u32) -> vec3<f32> {
+    let h0 = hash_lowbias32(bitcast<u32>(*u) ^ salt);
+    let h1 = hash_lowbias32(h0 ^ 0x9e3779b9u);
+    let h2 = hash_lowbias32(h1 ^ 0x85ebca6bu);
+    *u = hash_to_float01(hash_lowbias32(h2 ^ 0xc2b2ae35u));
+
+    // Uniform box jitter in [-0.5, +0.5]^3 paired antithetically (center + delta, center - delta):
+    // convolving hardware trilinear B_1 with B_0 on [-0.5, +0.5]^3 yields the exact C^1 Quadratic
+    // B-Spline B_2 = B_1 * B_0 with constant second derivative across each cell, zero floor/integer
+    // discontinuity, and support staying strictly within the 1-texel cascade border.
+    return vec3<f32>(
+        hash_to_float01(h0) - 0.5,
+        hash_to_float01(h1) - 0.5,
+        hash_to_float01(h2) - 0.5,
+    );
+}
+
+fn irradiance_clipmap_cascade_read_stochastic(
+    c: u32,
+    position_ws: vec3<f32>,
+    u: ptr<function, f32>,
+) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    let level = irradiance_clipmap.levels[c];
+    let cascade = irradiance_clipmap.cascades[c];
+    let inv_atlas = irradiance_clipmap.inverse_atlas_size;
+
+    let local = position_ws / level.cell_size - vec3<f32>(level.corner);
+    let center = cascade.content_origin + local;
+    let delta = irradiance_clipmap_box_jitter(u, (c + 1u) * 0x27d4eb2du);
+
+    // Clamp hardware linear tap coordinates to the cascade tile's valid texel centres (including its 1-texel border)
+    let t_min = cascade.content_origin - vec3<f32>(0.5);
+    let t_max = cascade.content_origin + vec3<f32>(level.size) + vec3<f32>(0.5);
+    let uvw0 = clamp(center + delta, t_min, t_max) * inv_atlas;
+    let uvw1 = clamp(center - delta, t_min, t_max) * inv_atlas;
+
+    let sh0 = ${METRO_L1_IRRADIANCE_STRUCT.make({
+        CoCg: "textureSampleLevel(irradiance_clipmap_atlas_cocg, irradiance_clipmap_sampler, uvw0, 0.0).xy",
+        Y: "textureSampleLevel(irradiance_clipmap_atlas_y, irradiance_clipmap_sampler, uvw0, 0.0)",
+    })};
+    let sh1 = ${METRO_L1_IRRADIANCE_STRUCT.make({
+        CoCg: "textureSampleLevel(irradiance_clipmap_atlas_cocg, irradiance_clipmap_sampler, uvw1, 0.0).xy",
+        Y: "textureSampleLevel(irradiance_clipmap_atlas_y, irradiance_clipmap_sampler, uvw1, 0.0)",
+    })};
+
+    return irradiance_clipmap_mix_sh(sh0, sh1, 0.5);
+}
+
+fn irradiance_clipmap_cascade_read(c: u32, position_ws: vec3<f32>) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    let level = irradiance_clipmap.levels[c];
+    let cascade = irradiance_clipmap.cascades[c];
+    let local = position_ws / level.cell_size - vec3<f32>(level.corner);
+    let center = cascade.content_origin + local;
+    let t_min = cascade.content_origin - vec3<f32>(0.5);
+    let t_max = cascade.content_origin + vec3<f32>(level.size) + vec3<f32>(0.5);
+    let uvw = clamp(center, t_min, t_max) * irradiance_clipmap.inverse_atlas_size;
+
+    return ${METRO_L1_IRRADIANCE_STRUCT.make({
+        CoCg: "textureSampleLevel(irradiance_clipmap_atlas_cocg, irradiance_clipmap_sampler, uvw, 0.0).xy",
+        Y: "textureSampleLevel(irradiance_clipmap_atlas_y, irradiance_clipmap_sampler, uvw, 0.0)",
+    })};
+}
+
+fn irradiance_clipmap_mix_sh(
+    a: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref},
+    b: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref},
+    t: f32,
+) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    return ${METRO_L1_IRRADIANCE_STRUCT.make({
+        CoCg: "a.CoCg + (b.CoCg - a.CoCg) * t",
+        Y: "a.Y + (b.Y - a.Y) * t",
+    })};
+}
+
+fn irradiance_clipmap_sample_stochastic(
+    position_ws: vec3<f32>,
+    random_u: f32,
+) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    let count = irradiance_clipmap.cascade_count;
+    let blend_skirt = select(IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT, irradiance_clipmap.blend_skirt, irradiance_clipmap.blend_skirt > 0.0);
+    let selection = irradiance_clipmap_select_finest(position_ws, blend_skirt);
+
+    if (selection.level == CLIPMAP_LEVEL_NONE) {
+        return ${METRO_L1_IRRADIANCE_STRUCT.make({
+            CoCg: "vec2<f32>(0.0)",
+            Y: "vec4<f32>(0.0)",
+        })};
+    }
+
+    var u = clamp(random_u, 0.0, 0.99999994);
+    let parent = selection.level + 1u;
+    if (selection.edge_weight <= 0.0 || parent >= count) {
+        return irradiance_clipmap_cascade_read_stochastic(selection.level, position_ws, &u);
+    }
+
+    // Non-linear smoothstep transition keeps sampling in the higher-resolution cascade longer,
+    // rescaling u via sample reuse so the downstream WRS tricubic tap gets an independent uniform sample.
+    let blend = smoothstep(0.0, 1.0, selection.edge_weight);
+    var chosen_cascade = selection.level;
+    if (u < blend) {
+        chosen_cascade = parent;
+        u = u / max(blend, 1e-6);
+    } else {
+        u = (u - blend) / max(1.0 - blend, 1e-6);
+    }
+
+    return irradiance_clipmap_cascade_read_stochastic(chosen_cascade, position_ws, &u);
+}
+`, [
+        IRRADIANCE_CLIPMAP_STRUCT.declaration_chunk,
+        METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
+        chunk_clipmap_select_finest,
+        chunk_hash_lowbias32,
+        chunk_hash_to_float01,
+    ]
+);
+
+chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE);
+chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_ATLAS_Y_RESOURCE);
+chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_ATLAS_COCG_RESOURCE);
+chunk_irradiance_clipmap_sample.requireResource(IRRADIANCE_CLIPMAP_SAMPLER_RESOURCE);
+
+/**
+ * Samples the world-space irradiance clipmap with deterministic `smoothstep` cascade blending and
+ * automatic fallback into the scene's cached `far_field_irradiance_sh` (used by particle lighting):
+ *
+ * - Outside all cascades (`CLIPMAP_LEVEL_NONE`), returns `far_field_irradiance_sh`.
+ * - In the interior of cascade `c` (`edge_weight <= 0.0`), performs a 2-tap antithetic Quadratic
+ *   B-Spline (`B_2 = B_1 * B_0`) read of cascade `c`.
+ * - In the outer transition band of cascade `c < count - 1` (`edge_weight > 0.0`), smoothly blends
+ *   between cascade `c` and parent cascade `c + 1` using `smoothstep(0.0, 1.0, edge_weight)` with
+ *   hash-rescaled sample reuse across both cascades.
+ * - In the outer transition band of the coarsest cascade (`c == count - 1`), smoothly blends between
+ *   the coarsest cascade and `far_field_irradiance_sh` using `smoothstep(0.0, 1.0, edge_weight)`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_sample_with_far_field = CodeChunk.from(
+    //language=WGSL
+    `
+fn irradiance_clipmap_sample_with_far_field(
+    position_ws: vec3<f32>,
+    random_u: f32,
+) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    let count = irradiance_clipmap.cascade_count;
+    let blend_skirt = select(IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT, irradiance_clipmap.blend_skirt, irradiance_clipmap.blend_skirt > 0.0);
+    let selection = irradiance_clipmap_select_finest(position_ws, blend_skirt);
+
+    if (selection.level == CLIPMAP_LEVEL_NONE) {
+        return far_field_irradiance_sh;
+    }
+
+    var u = clamp(random_u, 0.0, 0.99999994);
+    let inner = irradiance_clipmap_cascade_read_stochastic(selection.level, position_ws, &u);
+    if (selection.edge_weight <= 0.0) {
+        return inner;
+    }
+
+    let blend = smoothstep(0.0, 1.0, selection.edge_weight);
+    let parent = selection.level + 1u;
+
+    if (parent < count) {
+        let outer = irradiance_clipmap_cascade_read_stochastic(parent, position_ws, &u);
+        return irradiance_clipmap_mix_sh(inner, outer, blend);
+    }
+
+    return irradiance_clipmap_mix_sh(inner, far_field_irradiance_sh, blend);
+}
+`, [
+        chunk_irradiance_clipmap_sample,
+    ]
+);
+
+chunk_irradiance_clipmap_sample_with_far_field.requireResource(IRRADIANCE_CLIPMAP_UNIFORM_RESOURCE);
+chunk_irradiance_clipmap_sample_with_far_field.requireResource(FAR_FIELD_IRRADIANCE_SH_RESOURCE);