@woosh/meep-engine 3.53.0 → 3.55.0

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

@@ -0,0 +1,60 @@
+import { CLIPMAP_LEVEL_LIMIT } from "../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../texture/SAMPLER_LINEAR_UPSCALE.js";
+
+/**
+ * Default number of cascades in the world-space irradiance clipmap (Decision 6.3).
+ * Covers 8 m, 16 m, 32 m, 64 m, 128 m, 256 m at 32³ and h0 = 0.25 m.
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_DEFAULT_CASCADE_COUNT = 6;
+
+/**
+ * Maximum number of cascades supported by the irradiance clipmap table.
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_CASCADE_LIMIT = CLIPMAP_LEVEL_LIMIT;
+
+/**
+ * Default resolution (cells per axis) of each irradiance clipmap cascade (Decision 6.3).
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_DEFAULT_RESOLUTION = 32;
+
+/**
+ * Default finest cascade cell size h0 in metres (25 cm, Decision 6.3).
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_DEFAULT_CELL_SIZE = 0.25;
+
+/**
+ * Texels of skirt on each side of a cascade's tile in the 3D atlas: 1 texel for hardware trilinear
+ * filtering (`tile_size = resolution + 2`).
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_TILE_BORDER = 1;
+
+/**
+ * Default blend-skirt width in voxels (cells of that cascade) at the outer faces of each cascade
+ * window where blending takes place. At the very outer edge of the border voxel (`edge = 0`), the
+ * finer cascade's weight is `0.0` (`edge_weight = 1.0`); `blend_skirt` voxels inward, the finer
+ * cascade's weight is `1.0` (`edge_weight = 0.0`).
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT = 4;
+
+/**
+ * Format of the two synchronized 3D atlas textures (`Y` and `CoCg`).
+ * @type {GPUTextureFormat}
+ */
+export const IRRADIANCE_CLIPMAP_TILE_FORMAT = "rgba16float";
+
+/**
+ * Sampler used for trilinear taps of the irradiance clipmap atlas textures.
+ */
+export const IRRADIANCE_CLIPMAP_SAMPLER_DESCRIPTOR = SAMPLER_LINEAR_UPSCALE;
+
+/**
+ * Maximum number of point or spot lights evaluated per voxel in the irradiance clipmap build pass.
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_LIGHT_BUDGET = 32;

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

@@ -0,0 +1,25 @@
+/**
+ * Per-cascade atlas placement metadata for the world-space irradiance clipmap. 16 bytes.
+ * @type {WebGPUStruct}
+ */
+export const IRRADIANCE_CASCADE_STRUCT: WebGPUStruct;
+/**
+ * @type {WebGPUArray}
+ */
+export const IRRADIANCE_CASCADE_ARRAY: WebGPUArray;
+/**
+ * Uniform buffer layout for the world-space irradiance clipmap (`irradiance_clipmap`).
+ * Mirrors {@link WIND_FIELD_STRUCT} so `clipmap_select_finest` operates directly on `levels`.
+ *
+ * - `anchor`: continuous world-space camera/placement anchor (`[x, y, z]` in metres), used for
+ *   continuous spherical cascade selection so blend weights never stair-step when integer cascade
+ *   corners step by 1 voxel.
+ * - `blend_skirt`: number of voxels at each cascade window's outer boundary where blending toward
+ *   the parent cascade (or far field) takes place.
+ *
+ * @type {WebGPUStruct}
+ */
+export const IRRADIANCE_CLIPMAP_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+//# sourceMappingURL=IRRADIANCE_CLIPMAP_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IRRADIANCE_CLIPMAP_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/IRRADIANCE_CLIPMAP_STRUCT.js"],"names":[],"mappings":"AAMA;;;GAGG;AACH,wCAFU,YAAY,CASE;AAExB;;GAEG;AACH,uCAFU,WAAW,CAKnB;AAEF;;;;;;;;;;;GAWG;AACH,wCAFU,YAAY,CASE;6BA3CK,mCAAmC;4BADpC,kCAAkC"}

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

@@ -0,0 +1,47 @@
+import { CLIPMAP_LEVEL_ARRAY } from "../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { f32, u32, vec3f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { IRRADIANCE_CLIPMAP_CASCADE_LIMIT } from "./IRRADIANCE_CLIPMAP.js";
+
+/**
+ * Per-cascade atlas placement metadata for the world-space irradiance clipmap. 16 bytes.
+ * @type {WebGPUStruct}
+ */
+export const IRRADIANCE_CASCADE_STRUCT = WebGPUStruct.from({
+    /**
+     * The atlas texel coordinate of window-local cell 0 (`slot_origin + border`). Window-local
+     * cell `c` has its centre at `content_origin + c + 0.5`.
+     */
+    content_origin: vec3f,
+    pad0: f32,
+}, "IrradianceCascade");
+
+/**
+ * @type {WebGPUArray}
+ */
+export const IRRADIANCE_CASCADE_ARRAY = WebGPUArray.from(
+    IRRADIANCE_CASCADE_STRUCT,
+    IRRADIANCE_CLIPMAP_CASCADE_LIMIT
+);
+
+/**
+ * Uniform buffer layout for the world-space irradiance clipmap (`irradiance_clipmap`).
+ * Mirrors {@link WIND_FIELD_STRUCT} so `clipmap_select_finest` operates directly on `levels`.
+ *
+ * - `anchor`: continuous world-space camera/placement anchor (`[x, y, z]` in metres), used for
+ *   continuous spherical cascade selection so blend weights never stair-step when integer cascade
+ *   corners step by 1 voxel.
+ * - `blend_skirt`: number of voxels at each cascade window's outer boundary where blending toward
+ *   the parent cascade (or far field) takes place.
+ *
+ * @type {WebGPUStruct}
+ */
+export const IRRADIANCE_CLIPMAP_STRUCT = WebGPUStruct.from({
+    levels: CLIPMAP_LEVEL_ARRAY,
+    cascades: IRRADIANCE_CASCADE_ARRAY,
+    inverse_atlas_size: vec3f,
+    cascade_count: u32,
+    anchor: vec3f,
+    blend_skirt: f32,
+}, "IrradianceClipmap");

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

@@ -0,0 +1,74 @@
+/**
+ * Stateless, hysteresis-free 1-voxel-step window placement for {@link GPUIrradianceClipmap}.
+ *
+ * Cascade `c` has voxel size `cell_size * 2^c` and resolution `N = resolution[axis]`; its window is
+ * `[corner, corner + N)` in its own cells, covering `[corner * h_c, (corner + N) * h_c)` in world
+ * space.
+ *
+ * Unlike `FluidCascadePlacement` (which steps in 4-cell bricks with a 2.1-cell hysteretic deadband
+ * for persistent Eulerian fluid grids), the irradiance clipmap is rebuilt directly from scene lights
+ * and GI probes whenever a cascade shifts. Placement therefore uses a pure, stateless 1-voxel
+ * rounding rule (`Math.round(anchor / h_c - N * 0.5)`) with zero hysteresis:
+ * - Any given camera position `(x, y, z)` produces identical cascade windows regardless of the
+ *   camera's prior trajectory (zooming in vs. zooming out).
+ * - Each cascade shifts by 1 voxel at a time, which is smaller than `blend_skirt`, so world-space
+ *   positions always transition smoothly through the outer blend skirt rather than jumping past it.
+ */
+export class IrradianceCascadePlacement {
+    /**
+     * @param {object} options
+     * @param {number} options.cascade_count 1 to {@link IRRADIANCE_CLIPMAP_CASCADE_LIMIT}
+     * @param {ArrayLike<number>} options.resolution cells on each axis, powers of two
+     * @param {number} options.cell_size metres, cascade 0's voxel size
+     */
+    constructor({ cascade_count, resolution, cell_size }: {
+        cascade_count: number;
+        resolution: ArrayLike<number>;
+        cell_size: number;
+    });
+    /** @returns {number} */
+    get cascade_count(): number;
+    /** @returns {Readonly<Int32Array>} */
+    get resolution(): Readonly<Int32Array>;
+    /** @returns {boolean} */
+    get placed(): boolean;
+    /**
+     * Cascade `c`'s voxel size in metres (`cell_size * 2^c`).
+     * @param {number} cascade
+     * @returns {number}
+     */
+    cell_size(cascade: number): number;
+    /**
+     * @param {number} cascade
+     * @param {number} axis 0, 1, or 2
+     * @returns {number} the cascade's corner on `axis`, in its own cells
+     */
+    corner(cascade: number, axis: number): number;
+    /**
+     * @param {number} cascade
+     * @param {number} axis 0, 1, or 2
+     * @returns {number} the corner recorded at the last {@link begin}
+     */
+    previous_corner(cascade: number, axis: number): number;
+    /**
+     * @param {number} cascade
+     * @returns {boolean} whether the cascade's corner changed since the last {@link begin}
+     */
+    moved(cascade: number): boolean;
+    /**
+     * Snapshot every cascade's current corner before a {@link place_all} call so {@link moved} can
+     * report which cascades shifted.
+     */
+    begin(): void;
+    /**
+     * Place every cascade around `(x, y, z)` in world metres, coarsest first, using a stateless
+     * 1-voxel rounding rule with zero hysteresis.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    place_all(x: number, y: number, z: number): void;
+    #private;
+}
+//# sourceMappingURL=IrradianceCascadePlacement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IrradianceCascadePlacement.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/IrradianceCascadePlacement.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH;IAmBI;;;;;OAKG;IACH;QAJ2B,aAAa,EAA7B,MAAM;QACqB,UAAU,EAArC,UAAU,MAAM,CAAC;QACD,SAAS,EAAzB,MAAM;OAkBhB;IAED,wBAAwB;IACxB,4BAEC;IAED,sCAAsC;IACtC,uCAEC;IAED,yBAAyB;IACzB,sBAEC;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,yBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,OAAO,CAQnB;IAED;;;OAGG;IACH,cAOC;IAED;;;;;;;OAOG;IACH,aAJW,MAAM,KACN,MAAM,KACN,MAAM,QAmChB;;CACJ"}

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

@@ -0,0 +1,173 @@
+import { assert } from "../../../../core/assert.js";
+import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
+import { IRRADIANCE_CLIPMAP_CASCADE_LIMIT } from "./IRRADIANCE_CLIPMAP.js";
+
+/**
+ * Stateless, hysteresis-free 1-voxel-step window placement for {@link GPUIrradianceClipmap}.
+ *
+ * Cascade `c` has voxel size `cell_size * 2^c` and resolution `N = resolution[axis]`; its window is
+ * `[corner, corner + N)` in its own cells, covering `[corner * h_c, (corner + N) * h_c)` in world
+ * space.
+ *
+ * Unlike `FluidCascadePlacement` (which steps in 4-cell bricks with a 2.1-cell hysteretic deadband
+ * for persistent Eulerian fluid grids), the irradiance clipmap is rebuilt directly from scene lights
+ * and GI probes whenever a cascade shifts. Placement therefore uses a pure, stateless 1-voxel
+ * rounding rule (`Math.round(anchor / h_c - N * 0.5)`) with zero hysteresis:
+ * - Any given camera position `(x, y, z)` produces identical cascade windows regardless of the
+ *   camera's prior trajectory (zooming in vs. zooming out).
+ * - Each cascade shifts by 1 voxel at a time, which is smaller than `blend_skirt`, so world-space
+ *   positions always transition smoothly through the outer blend skirt rather than jumping past it.
+ */
+export class IrradianceCascadePlacement {
+    /** @type {Int32Array} */
+    #resolution = new Int32Array(3);
+
+    /** @type {number} */
+    #cell_size;
+
+    /** @type {number} */
+    #cascade_count;
+
+    /** @type {Int32Array} */
+    #corner;
+
+    /** @type {Int32Array} */
+    #previous;
+
+    /** @type {boolean} */
+    #placed = false;
+
+    /**
+     * @param {object} options
+     * @param {number} options.cascade_count 1 to {@link IRRADIANCE_CLIPMAP_CASCADE_LIMIT}
+     * @param {ArrayLike<number>} options.resolution cells on each axis, powers of two
+     * @param {number} options.cell_size metres, cascade 0's voxel size
+     */
+    constructor({ cascade_count, resolution, cell_size }) {
+        assert.isPositiveInteger(cascade_count, "cascade_count");
+        assert.lessThanOrEqual(cascade_count, IRRADIANCE_CLIPMAP_CASCADE_LIMIT, "cascade_count");
+        assert.isFinite(cell_size, "cell_size");
+        assert.greaterThan(cell_size, 0, "cell_size");
+
+        for (let axis = 0; axis < 3; axis++) {
+            assert.isPositiveInteger(resolution[axis], "resolution");
+            assert.ok(isPowerOfTwo(resolution[axis]), "resolution is a power of two on each axis");
+            this.#resolution[axis] = resolution[axis];
+        }
+
+        this.#cascade_count = cascade_count;
+        this.#cell_size = cell_size;
+        this.#corner = new Int32Array(3 * cascade_count);
+        this.#previous = new Int32Array(3 * cascade_count);
+    }
+
+    /** @returns {number} */
+    get cascade_count() {
+        return this.#cascade_count;
+    }
+
+    /** @returns {Readonly<Int32Array>} */
+    get resolution() {
+        return this.#resolution;
+    }
+
+    /** @returns {boolean} */
+    get placed() {
+        return this.#placed;
+    }
+
+    /**
+     * Cascade `c`'s voxel size in metres (`cell_size * 2^c`).
+     * @param {number} cascade
+     * @returns {number}
+     */
+    cell_size(cascade) {
+        return this.#cell_size * 2 ** cascade;
+    }
+
+    /**
+     * @param {number} cascade
+     * @param {number} axis 0, 1, or 2
+     * @returns {number} the cascade's corner on `axis`, in its own cells
+     */
+    corner(cascade, axis) {
+        return this.#corner[3 * cascade + axis];
+    }
+
+    /**
+     * @param {number} cascade
+     * @param {number} axis 0, 1, or 2
+     * @returns {number} the corner recorded at the last {@link begin}
+     */
+    previous_corner(cascade, axis) {
+        return this.#previous[3 * cascade + axis];
+    }
+
+    /**
+     * @param {number} cascade
+     * @returns {boolean} whether the cascade's corner changed since the last {@link begin}
+     */
+    moved(cascade) {
+        const base = 3 * cascade;
+
+        return this.#previous[base] !== this.#corner[base]
+            || this.#previous[base + 1] !== this.#corner[base + 1]
+            || this.#previous[base + 2] !== this.#corner[base + 2];
+    }
+
+    /**
+     * Snapshot every cascade's current corner before a {@link place_all} call so {@link moved} can
+     * report which cascades shifted.
+     */
+    begin() {
+        if (!this.#placed) {
+            this.#previous.fill(0x7fffffff);
+            return;
+        }
+
+        this.#previous.set(this.#corner);
+    }
+
+    /**
+     * Place every cascade around `(x, y, z)` in world metres, coarsest first, using a stateless
+     * 1-voxel rounding rule with zero hysteresis.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    place_all(x, y, z) {
+        assert.isFinite(x, "x");
+        assert.isFinite(y, "y");
+        assert.isFinite(z, "z");
+
+        const res = this.#resolution;
+        const corner = this.#corner;
+
+        for (let c = this.#cascade_count - 1; c >= 0; c--) {
+            const h = this.cell_size(c);
+            const base = 3 * c;
+
+            let cx = Math.round(x / h - res[0] * 0.5) | 0;
+            let cy = Math.round(y / h - res[1] * 0.5) | 0;
+            let cz = Math.round(z / h - res[2] * 0.5) | 0;
+
+            if (c + 1 < this.#cascade_count) {
+                const p_base = 3 * (c + 1);
+                const px = 2 * corner[p_base];
+                const py = 2 * corner[p_base + 1];
+                const pz = 2 * corner[p_base + 2];
+
+                cx = Math.min(px + res[0], Math.max(px, cx));
+                cy = Math.min(py + res[1], Math.max(py, cy));
+                cz = Math.min(pz + res[2], Math.max(pz, cz));
+            }
+
+            corner[base] = cx;
+            corner[base + 1] = cy;
+            corner[base + 2] = cz;
+        }
+
+        this.#placed = true;
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under IBL: the environment SH (`environment_sh`).
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_ibl: CodeChunk;
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under Brick4: the sparse volumetric light map's probes
+ * interpolated at `position_ws` with a zero normal (open-space omnidirectional weighting).
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_brick4: CodeChunk;
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under LPV: tetrahedral probe interpolation at `position_ws`.
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_lpv: 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.
+ *
+ * @type {CodeChunkChoice}
+ */
+export const chunk_irradiance_clipmap_gi_sample: CodeChunkChoice;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { CodeChunkChoice } from "../../shader/compiler/CodeChunkChoice.js";
+//# sourceMappingURL=chunk_irradiance_clipmap_gi_sample.d.ts.map

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

@@ -0,0 +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;;;;;GAKG;AACH,iDAFU,eAAe,CAEiE;0BAvEhE,oCAAoC;gCAC9B,0CAA0C"}

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

@@ -0,0 +1,83 @@
+import { chunk_brick4_sample_sh } from "../../global_illumination/brick4/gpu/draw/chunk_brick4_sample_sh.js";
+import { INDIRECT_LIGHTING } from "../../INDIRECT_LIGHTING.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";
+import { chunk_lpv_mesh_lookup_nearest_cell } from "../../shader/chunk/light/lpv/chunk_lpv_mesh_lookup_nearest_cell.js";
+import { INVALID_TET_DECLARATION } from "../../shader/chunk/light/lpv/INVALID_TET_DECLARATION.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { CodeChunkChoice } from "../../shader/compiler/CodeChunkChoice.js";
+
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under IBL: the environment SH (`environment_sh`).
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_ibl = CodeChunk.from(
+    //language=WGSL
+    `
+fn irradiance_clipmap_gi_sample(position_ws: vec3<f32>) -> array<vec3<f32>, 4> {
+    return array<vec3<f32>, 4>(
+        environment_sh[0].xyz,
+        environment_sh[1].xyz,
+        environment_sh[2].xyz,
+        environment_sh[3].xyz,
+    );
+}
+`, []
+);
+
+chunk_irradiance_clipmap_gi_sample_ibl.requireResource(ENVIRONMENT_SH_RESOURCE);
+
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under Brick4: the sparse volumetric light map's probes
+ * interpolated at `position_ws` with a zero normal (open-space omnidirectional weighting).
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_brick4 = CodeChunk.from(
+    //language=WGSL
+    `
+fn irradiance_clipmap_gi_sample(position_ws: vec3<f32>) -> array<vec3<f32>, 4> {
+    let sh = brick4_sample_sh(position_ws, vec3<f32>(0.0));
+    return array<vec3<f32>, 4>(sh[0], sh[1], sh[2], sh[3]);
+}
+`, [
+        chunk_brick4_sample_sh,
+    ]
+);
+
+/**
+ * {@link chunk_irradiance_clipmap_gi_sample} under LPV: tetrahedral probe interpolation at `position_ws`.
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_gi_sample_lpv = CodeChunk.from(
+    //language=WGSL
+    `
+fn irradiance_clipmap_gi_sample(position_ws: vec3<f32>) -> array<vec3<f32>, 4> {
+    var weights: vec4<f32>;
+    let tet = lpv_mesh_lookup_nearest_cell(position_ws, &weights);
+
+    var radiance = array<vec3<f32>, 4>();
+    if (tet != INVALID_TET) {
+        radiance = lpv_mesh_interpolation_probe_sh(weights, tet);
+    }
+
+    return radiance;
+}
+`, [
+        chunk_lpv_mesh_lookup_nearest_cell,
+        chunk_lpv_mesh_interpolation_probe_sh,
+        INVALID_TET_DECLARATION,
+    ]
+);
+
+/**
+ * Evaluates indirect radiance SH2 (`array<vec3<f32>, 4>`) at a world position `position_ws` according
+ * to the renderer's active {@link INDIRECT_LIGHTING} switch.
+ *
+ * @type {CodeChunkChoice}
+ */
+export const chunk_irradiance_clipmap_gi_sample = CodeChunkChoice.from(INDIRECT_LIGHTING);
+
+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);

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

@@ -0,0 +1,36 @@
+/**
+ * Radially symmetric (isotropic) voxel-footprint-aware point and spot light evaluation for
+ * {@link shader_irradiance_clipmap_build}.
+ *
+ * When a local light of small physical radius `r` sits inside a coarse clipmap voxel grid of spacing
+ * `h` (`h > r`), the 8 surrounding voxel centres are displaced radially from the light by up to
+ * `sqrt(3)/2 * h ≈ 0.866 * h` (and ~`0.71 * h` across a shared corner/edge). Without radial distance
+ * regularization, coarse cascades under-sample the near-light `1 / d^2` peak relative to finer cascades.
+ *
+ * ## Why Axis-Aligned Box Clamping (`max(abs(L) - 0.5*h, 0)`) Must Not Be Used
+ *
+ * Clamping each axis independently via `d_box = length(max(abs(L) - vec3(0.5 * h), vec3(0.0)))`
+ * zeroes out any coordinate axis within `+/- 0.5 * h` of the light source:
+ * - Every voxel inside the central `[-0.5*h, +0.5*h]^3` cube gets `d_box = 0` (a flat-topped cube).
+ * - Outside that cube, along the coordinate slabs `|L_x| <= 0.5*h` or `|L_y| <= 0.5*h`, the level
+ *   sets of `d_box` are flat axis-aligned planes meeting at 90-degree corners (`┐`) instead of
+ *   spheres, baking rectilinear box boundaries directly into the 3D irradiance texture.
+ *
+ * To match brightness across cascades without introducing axis-aligned cubic plateaus or directional
+ * distortion:
+ * - `result.direction` is `L / max(d_center, max(light.radius, 0.5 * cell_size))`: exact Euclidean
+ *   radial unit vector outside the half-voxel / source sphere, and decaying smoothly (`C^1`) through
+ *   `0` as `L -> 0` so L1 directional SH coefficients never flip sign across `180°` when a light
+ *   crosses a voxel centre.
+ * - `irradiance_clipmap_regularize_light_distance(d, cell_size)` evaluates a `C^1`-smooth, strictly
+ *   monotonic quartic polynomial on `t = d / (1.75 * h) in [0, 1]` with `f(0) = 0.35 * h`,
+ *   `f'(0) = 0` (differentiable across `L = 0`), `f(1) = 1.75 * h`, and `f'(1) = 1.0`, equalling `d`
+ *   identically in the far field (`d >= 1.75 * h`) with zero `max()` slope kink.
+ * - When `light.radius > cell_size` (fine cascades already resolving a large area sphere), the
+ *   sub-voxel pull blends smoothly toward `d_center` so the sphere cap is not artificially widened.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_local_light: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_irradiance_clipmap_local_light.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_irradiance_clipmap_local_light.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/chunk_irradiance_clipmap_local_light.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,mDAFU,SAAS,CAoFjB;0BA/HwB,oCAAoC"}

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

@@ -0,0 +1,129 @@
+import { LIGHT_DATABASE_SPEC } from "../../light/LIGHT_DATABASE_SPEC.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { INCIDENT_LIGHT_STRUCT } from "../../shader/chunk/light/INCIDENT_LIGHT_STRUCT.js";
+import {
+    chunk_light_get_spot_attenuation
+} from "../../shader/chunk/light/io/chunk_light_get_spot_attenuation.js";
+import {
+    chunk_light_sphere_distance_attenuation
+} from "../../shader/chunk/light/io/chunk_light_sphere_distance_attenuation.js";
+
+const POINT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get("light_point");
+const SPOT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get("light_spot");
+
+/**
+ * Radially symmetric (isotropic) voxel-footprint-aware point and spot light evaluation for
+ * {@link shader_irradiance_clipmap_build}.
+ *
+ * When a local light of small physical radius `r` sits inside a coarse clipmap voxel grid of spacing
+ * `h` (`h > r`), the 8 surrounding voxel centres are displaced radially from the light by up to
+ * `sqrt(3)/2 * h ≈ 0.866 * h` (and ~`0.71 * h` across a shared corner/edge). Without radial distance
+ * regularization, coarse cascades under-sample the near-light `1 / d^2` peak relative to finer cascades.
+ *
+ * ## Why Axis-Aligned Box Clamping (`max(abs(L) - 0.5*h, 0)`) Must Not Be Used
+ *
+ * Clamping each axis independently via `d_box = length(max(abs(L) - vec3(0.5 * h), vec3(0.0)))`
+ * zeroes out any coordinate axis within `+/- 0.5 * h` of the light source:
+ * - Every voxel inside the central `[-0.5*h, +0.5*h]^3` cube gets `d_box = 0` (a flat-topped cube).
+ * - Outside that cube, along the coordinate slabs `|L_x| <= 0.5*h` or `|L_y| <= 0.5*h`, the level
+ *   sets of `d_box` are flat axis-aligned planes meeting at 90-degree corners (`┐`) instead of
+ *   spheres, baking rectilinear box boundaries directly into the 3D irradiance texture.
+ *
+ * To match brightness across cascades without introducing axis-aligned cubic plateaus or directional
+ * distortion:
+ * - `result.direction` is `L / max(d_center, max(light.radius, 0.5 * cell_size))`: exact Euclidean
+ *   radial unit vector outside the half-voxel / source sphere, and decaying smoothly (`C^1`) through
+ *   `0` as `L -> 0` so L1 directional SH coefficients never flip sign across `180°` when a light
+ *   crosses a voxel centre.
+ * - `irradiance_clipmap_regularize_light_distance(d, cell_size)` evaluates a `C^1`-smooth, strictly
+ *   monotonic quartic polynomial on `t = d / (1.75 * h) in [0, 1]` with `f(0) = 0.35 * h`,
+ *   `f'(0) = 0` (differentiable across `L = 0`), `f(1) = 1.75 * h`, and `f'(1) = 1.0`, equalling `d`
+ *   identically in the far field (`d >= 1.75 * h`) with zero `max()` slope kink.
+ * - When `light.radius > cell_size` (fine cascades already resolving a large area sphere), the
+ *   sub-voxel pull blends smoothly toward `d_center` so the sphere cap is not artificially widened.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_irradiance_clipmap_local_light = CodeChunk.from(
+    //language=WGSL
+    `
+const IRRADIANCE_CLIPMAP_VOXEL_FOOTPRINT_RADIUS: f32 = 0.35;
+const IRRADIANCE_CLIPMAP_VOXEL_RADIAL_SUPPORT: f32 = 1.75;
+
+fn irradiance_clipmap_regularize_light_distance(distance: f32, cell_size: f32) -> f32 {
+    let h = max(cell_size, 1e-5);
+    let support = IRRADIANCE_CLIPMAP_VOXEL_RADIAL_SUPPORT * h;
+    if (distance >= support) {
+        return distance;
+    }
+
+    let t = max(0.0, distance / support);
+    let t2 = t * t;
+    return h * (IRRADIANCE_CLIPMAP_VOXEL_FOOTPRINT_RADIUS + t2 * (0.45 + t * (2.95 - 2.00 * t)));
+}
+
+fn irradiance_clipmap_get_point_light_info_by_index(
+    database: ptr<storage, array<u32>>,
+    index: u32,
+    position_ws: vec3<f32>,
+    cell_size: f32,
+) -> ${INCIDENT_LIGHT_STRUCT.wgsl_ref} {
+    let light = ${POINT_DESCRIPTOR.marshalling_method_read}(database, index);
+    let L = light.position.xyz - position_ws;
+    let d_center = max(length(L), 1e-5);
+    let d_reg = irradiance_clipmap_regularize_light_distance(d_center, cell_size);
+    let resolved_blend = saturate(light.radius / max(cell_size, 1e-5) - 1.0);
+    let d_eval = mix(d_reg, d_center, resolved_blend);
+
+    var result: ${INCIDENT_LIGHT_STRUCT.wgsl_ref};
+    let dir_radius = max(max(light.radius, 0.5 * cell_size), 1e-5);
+    result.direction = L / max(d_center, dir_radius);
+
+    let attenuation = light_sphere_distance_attenuation(d_eval, light.radius, light.distance);
+    result.color = light.color * attenuation;
+    result.radius = light.radius / d_center;
+    result.distance = max(0.0, d_center - light.radius);
+
+    return result;
+}
+
+fn irradiance_clipmap_get_spot_light_info_by_index(
+    database: ptr<storage, array<u32>>,
+    index: u32,
+    position_ws: vec3<f32>,
+    cell_size: f32,
+) -> ${INCIDENT_LIGHT_STRUCT.wgsl_ref} {
+    let light = ${SPOT_DESCRIPTOR.marshalling_method_read}(database, index);
+    let L = light.position - position_ws;
+    let d_center = max(length(L), 1e-5);
+    let d_reg = irradiance_clipmap_regularize_light_distance(d_center, cell_size);
+    let resolved_blend = saturate(light.radius / max(cell_size, 1e-5) - 1.0);
+    let d_eval = mix(d_reg, d_center, resolved_blend);
+    let unit_dir = L / d_center;
+
+    var result: ${INCIDENT_LIGHT_STRUCT.wgsl_ref};
+    let dir_radius = max(max(light.radius, 0.5 * cell_size), 1e-5);
+    result.direction = L / max(d_center, dir_radius);
+    result.distance = max(0.0, d_center - light.radius);
+    result.radius = light.radius / d_center;
+
+    let angle_cos = dot(unit_dir, -light.direction);
+    let spot_attenuation = light_get_spot_attenuation(light.coneCos, light.penumbraCos, angle_cos);
+
+    if (spot_attenuation > 0.0) {
+        result.color = light.color * spot_attenuation;
+        result.color *= light_sphere_distance_attenuation(d_eval, light.radius, light.distance);
+    } else {
+        result.color = vec3<f32>(0.0);
+    }
+
+    return result;
+}
+`, [
+        POINT_DESCRIPTOR.chunk_read,
+        SPOT_DESCRIPTOR.chunk_read,
+        INCIDENT_LIGHT_STRUCT.declaration_chunk,
+        chunk_light_get_spot_attenuation,
+        chunk_light_sphere_distance_attenuation,
+    ]
+);