@woosh/meep-engine 3.52.0 → 3.54.0

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

@@ -0,0 +1,113 @@
+/**
+ * World-space irradiance clipmap (`GPUIrradianceClipmap`):
+ *
+ * Replaces the camera-frustum froxel irradiance volume with nested world-space clipmap cascades
+ * stored in a multi-texture {@link GPUTileAtlas3D} (`Y` in texture 0, `CoCg` in texture 1).
+ *
+ * - **Defaults (Decision 6.3):** 6 cascades (`c = 0..5`) of `32 × 32 × 32` content cells (plus a
+ *   1-texel trilinear skirt -> `34³` texels per tile), with finest voxel size `h0 = 0.25 m`
+ *   (covering `8 m, 16 m, 32 m, 64 m, 128 m, 256 m`).
+ * - **Amortized Updates & Warp Detection (Decision 3.2):** Cascade `0` and the dyadic ruler cascade
+ *   `fluid_cascade_ruler(tick, count)` update every frame. In addition, whenever a cascade's window
+ *   shifts by 1 voxel (`placement.moved(c)`), an immediate update is forced on that cascade so the
+ *   linear atlas tile never holds stale pre-shift texels.
+ */
+export class GPUIrradianceClipmap {
+    /**
+     * @param {GPUDevice} device
+     * @param {Object} [options]
+     * @param {number} [options.cascade_count=IRRADIANCE_CLIPMAP_DEFAULT_CASCADE_COUNT]
+     * @param {number|ArrayLike<number>} [options.resolution=IRRADIANCE_CLIPMAP_DEFAULT_RESOLUTION]
+     * @param {number} [options.cell_size=IRRADIANCE_CLIPMAP_DEFAULT_CELL_SIZE]
+     * @param {number} [options.blend_skirt=IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT]
+     */
+    constructor(device: GPUDevice, { cascade_count, resolution, cell_size, blend_skirt, }?: {
+        cascade_count?: number;
+        resolution?: number | ArrayLike<number>;
+        cell_size?: number;
+        blend_skirt?: number;
+    });
+    /**
+     * @returns {GPUTileAtlas3D}
+     */
+    get atlas(): GPUTileAtlas3D;
+    /**
+     * @returns {GPUTextureContext}
+     */
+    get texture_y(): GPUTextureContext;
+    /**
+     * @returns {GPUTextureContext}
+     */
+    get texture_cocg(): GPUTextureContext;
+    /**
+     * @returns {GPUBuffer}
+     */
+    get uniform(): GPUBuffer;
+    /**
+     * @returns {number}
+     */
+    get cascade_count(): number;
+    /**
+     * Number of voxels at each cascade window's outer faces where blending takes place.
+     * @returns {number}
+     */
+    get blend_skirt(): number;
+    /**
+     * @returns {IrradianceCascadePlacement}
+     */
+    get placement(): IrradianceCascadePlacement;
+    /**
+     * Forces all cascades to rebuild on the next executed frame.
+     */
+    invalidate_all(): void;
+    /**
+     * Updates cascade window placements around `anchor` (`[x, y, z]` in world metres), detects
+     * warp events (`placement.moved(c)`), schedules cascade updates, and uploads the uniform table.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {ShaderSwitchSet} [shader_switches]
+     */
+    update_placement(x: number, y: number, z: number, shader_switches?: ShaderSwitchSet): void;
+    /**
+     * Records the world-space light cluster clipmap build and the irradiance clipmap cascade update
+     * passes into `graph`.
+     *
+     * Neither pass is marked a side effect, so if nothing in the frame reads `Y` or `CoCg` (e.g. a
+     * frame with no volumetrics and no lit particles), the frame graph culls both passes and `#dirty`
+     * remains set until a frame actually executes them.
+     *
+     * @param {Object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {import("../../camera/GPUCameraContext.js").GPUCameraContext} options.camera
+     * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene_ctx
+     * @param {number} options.shadowmap_atlas
+     * @param {ShaderSwitchSet} [options.shader_switches]
+     * @param {import("../../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap} [options.brick4]
+     * @param {import("../../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume} [options.lpv]
+     * @returns {{Y: number, CoCg: number, uniform: number}}
+     */
+    graph_update({ graph, camera, scene_ctx, shadowmap_atlas, shader_switches, brick4, lpv, }: {
+        graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        camera: import("../../camera/GPUCameraContext.js").GPUCameraContext;
+        scene_ctx: import("../../scene/GPUSceneContext.js").GPUSceneContext;
+        shadowmap_atlas: number;
+        shader_switches?: ShaderSwitchSet;
+        brick4?: import("../../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap;
+        lpv?: import("../../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume;
+    }): {
+        Y: number;
+        CoCg: number;
+        uniform: number;
+    };
+    /**
+     * Releases GPU resources owned by the clipmap. Safe to call twice.
+     */
+    destroy(): void;
+    #private;
+}
+import { GPUTileAtlas3D } from "../../texture/atlas/GPUTileAtlas3D.js";
+import { IrradianceCascadePlacement } from "./IrradianceCascadePlacement.js";
+import { ShaderSwitchSet } from "../../shader/compiler/ShaderSwitchSet.js";
+//# sourceMappingURL=GPUIrradianceClipmap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUIrradianceClipmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/GPUIrradianceClipmap.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;GAaG;AACH;IA2CI;;;;;;;OAOG;IACH;QAL4B,aAAa,GAA9B,MAAM;QAC6B,UAAU,GAA7C,MAAM,GAAC,UAAU,MAAM,CAAC;QACP,SAAS,GAA1B,MAAM;QACW,WAAW,GAA5B,MAAM;OA8DhB;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,mCAEC;IAED;;OAEG;IACH,sCAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;OAEG;IACH,4CAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;;;;OAQG;IACH,oBALW,MAAM,KACN,MAAM,KACN,MAAM,oBACN,eAAe,QAgFzB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QATsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;QACZ,MAAM,EAA3E,OAAO,kCAAkC,EAAE,gBAAgB;QACO,SAAS,EAA3E,OAAO,gCAAgC,EAAE,eAAe;QACxC,eAAe,EAA/B,MAAM;QACoB,eAAe,GAAzC,eAAe;QACuE,MAAM,GAA5F,OAAO,oDAAoD,EAAE,cAAc;QACkB,GAAG,GAAhG,OAAO,sDAAsD,EAAE,mBAAmB;QAChF;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAuItD;IAED;;OAEG;IACH,gBAQC;;CACJ;+BAzd8B,uCAAuC;2CAe3B,iCAAiC;gCApB5C,0CAA0C"}

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

@@ -0,0 +1,484 @@
+import { assert } from "../../../../core/assert.js";
+import { fluid_cascade_ruler } from "../../fluid/fluid_cascade_ruler.js";
+import { INDIRECT_LIGHTING } from "../../INDIRECT_LIGHTING.js";
+import { graph_build_world_light_clusters } from "../../light/world_cluster/graph_build_world_light_clusters.js";
+import { CLIPMAP_LEVEL_STRUCT } from "../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { ShaderSwitchSet } from "../../shader/compiler/ShaderSwitchSet.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
+import { graph_import_texture } from "../../shader/graph/graph_import_texture.js";
+import { encoder_prepare_shader_bindings_defaults } from "../../shader/resource/encoder_prepare_shader_bindings_defaults.js";
+import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
+import { GPUTileAtlas3D } from "../../texture/atlas/GPUTileAtlas3D.js";
+import { DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR } from "../../texture/DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR.js";
+import {
+    IRRADIANCE_CLIPMAP_CASCADE_LIMIT,
+    IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT,
+    IRRADIANCE_CLIPMAP_DEFAULT_CASCADE_COUNT,
+    IRRADIANCE_CLIPMAP_DEFAULT_CELL_SIZE,
+    IRRADIANCE_CLIPMAP_DEFAULT_RESOLUTION,
+    IRRADIANCE_CLIPMAP_TILE_BORDER,
+    IRRADIANCE_CLIPMAP_TILE_FORMAT,
+} from "./IRRADIANCE_CLIPMAP.js";
+import {
+    IRRADIANCE_CASCADE_STRUCT,
+    IRRADIANCE_CLIPMAP_STRUCT,
+} from "./IRRADIANCE_CLIPMAP_STRUCT.js";
+import { IrradianceCascadePlacement } from "./IrradianceCascadePlacement.js";
+import {
+    IRRADIANCE_CLIPMAP_BUILD_STRUCT,
+    shader_irradiance_clipmap_build,
+} from "./shader_irradiance_clipmap_build.js";
+
+// Word offsets in IRRADIANCE_CLIPMAP_STRUCT
+const LEVELS = IRRADIANCE_CLIPMAP_STRUCT.get("levels").offset >>> 2;
+const LEVEL_STRIDE = CLIPMAP_LEVEL_STRUCT.aligned_size >>> 2;
+const LEVEL_CORNER = CLIPMAP_LEVEL_STRUCT.get("corner").offset >>> 2;
+const LEVEL_CELL_SIZE = CLIPMAP_LEVEL_STRUCT.get("cell_size").offset >>> 2;
+const LEVEL_SIZE = CLIPMAP_LEVEL_STRUCT.get("size").offset >>> 2;
+const CASCADES = IRRADIANCE_CLIPMAP_STRUCT.get("cascades").offset >>> 2;
+const CASCADE_STRIDE = IRRADIANCE_CASCADE_STRUCT.aligned_size >>> 2;
+const CASCADE_CONTENT_ORIGIN = IRRADIANCE_CASCADE_STRUCT.get("content_origin").offset >>> 2;
+const INVERSE_ATLAS_SIZE = IRRADIANCE_CLIPMAP_STRUCT.get("inverse_atlas_size").offset >>> 2;
+const CASCADE_COUNT = IRRADIANCE_CLIPMAP_STRUCT.get("cascade_count").offset >>> 2;
+const ANCHOR = IRRADIANCE_CLIPMAP_STRUCT.get("anchor").offset >>> 2;
+const BLEND_SKIRT = IRRADIANCE_CLIPMAP_STRUCT.get("blend_skirt").offset >>> 2;
+
+/**
+ * World-space irradiance clipmap (`GPUIrradianceClipmap`):
+ *
+ * Replaces the camera-frustum froxel irradiance volume with nested world-space clipmap cascades
+ * stored in a multi-texture {@link GPUTileAtlas3D} (`Y` in texture 0, `CoCg` in texture 1).
+ *
+ * - **Defaults (Decision 6.3):** 6 cascades (`c = 0..5`) of `32 × 32 × 32` content cells (plus a
+ *   1-texel trilinear skirt -> `34³` texels per tile), with finest voxel size `h0 = 0.25 m`
+ *   (covering `8 m, 16 m, 32 m, 64 m, 128 m, 256 m`).
+ * - **Amortized Updates & Warp Detection (Decision 3.2):** Cascade `0` and the dyadic ruler cascade
+ *   `fluid_cascade_ruler(tick, count)` update every frame. In addition, whenever a cascade's window
+ *   shifts by 1 voxel (`placement.moved(c)`), an immediate update is forced on that cascade so the
+ *   linear atlas tile never holds stale pre-shift texels.
+ */
+export class GPUIrradianceClipmap {
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {GPUTileAtlas3D} */
+    #atlas;
+
+    /** @type {IrradianceCascadePlacement} */
+    #placement;
+
+    /** @type {GPUBuffer} */
+    #uniform;
+
+    /** @type {ArrayBuffer} */
+    #bytes = new ArrayBuffer(IRRADIANCE_CLIPMAP_STRUCT.size);
+    #f32 = new Float32Array(this.#bytes);
+    #i32 = new Int32Array(this.#bytes);
+    #u32 = new Uint32Array(this.#bytes);
+
+    /** @type {Uint32Array} */
+    #slots = new Uint32Array(IRRADIANCE_CLIPMAP_CASCADE_LIMIT);
+
+    /** @type {Uint8Array} */
+    #dirty = new Uint8Array(IRRADIANCE_CLIPMAP_CASCADE_LIMIT);
+
+    /** @type {Object[]} */
+    #build_records = [];
+
+    /** @type {number[]} */
+    #origin = [0, 0, 0];
+
+    /** @type {number} */
+    #tick = 0;
+
+    /** @type {number} */
+    #blend_skirt;
+
+    /** @type {number} */
+    #last_indirect_mode = -1;
+
+    /** @type {boolean} */
+    #destroyed = false;
+
+    /**
+     * @param {GPUDevice} device
+     * @param {Object} [options]
+     * @param {number} [options.cascade_count=IRRADIANCE_CLIPMAP_DEFAULT_CASCADE_COUNT]
+     * @param {number|ArrayLike<number>} [options.resolution=IRRADIANCE_CLIPMAP_DEFAULT_RESOLUTION]
+     * @param {number} [options.cell_size=IRRADIANCE_CLIPMAP_DEFAULT_CELL_SIZE]
+     * @param {number} [options.blend_skirt=IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT]
+     */
+    constructor(device, {
+        cascade_count = IRRADIANCE_CLIPMAP_DEFAULT_CASCADE_COUNT,
+        resolution = IRRADIANCE_CLIPMAP_DEFAULT_RESOLUTION,
+        cell_size = IRRADIANCE_CLIPMAP_DEFAULT_CELL_SIZE,
+        blend_skirt = IRRADIANCE_CLIPMAP_DEFAULT_BLEND_SKIRT,
+    } = {}) {
+        assert.defined(device, "device");
+        assert.isPositiveInteger(cascade_count, "cascade_count");
+        assert.lessThanOrEqual(cascade_count, IRRADIANCE_CLIPMAP_CASCADE_LIMIT, "cascade_count");
+        assert.isNumber(blend_skirt, "blend_skirt");
+        assert.greaterThan(blend_skirt, 0, "blend_skirt");
+
+        const res = typeof resolution === "number"
+            ? [resolution, resolution, resolution]
+            : [resolution[0], resolution[1], resolution[2]];
+
+        this.#device = device;
+        this.#blend_skirt = blend_skirt;
+        this.#placement = new IrradianceCascadePlacement({
+            cascade_count,
+            resolution: res,
+            cell_size,
+        });
+
+        const tile_z = res[2] + 2 * IRRADIANCE_CLIPMAP_TILE_BORDER;
+
+        this.#atlas = new GPUTileAtlas3D({
+            device,
+            formats: [IRRADIANCE_CLIPMAP_TILE_FORMAT, IRRADIANCE_CLIPMAP_TILE_FORMAT],
+            content_size: res,
+            border: IRRADIANCE_CLIPMAP_TILE_BORDER,
+            slots_x: 1,
+            slots_y: 1,
+            capacity: Math.max(1, Math.min(cascade_count, Math.floor(device.limits.maxTextureDimension3D / tile_z))),
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+            label: "GPUIrradianceClipmap/atlas",
+        });
+
+        for (let c = 0; c < cascade_count; c++) {
+            this.#slots[c] = this.#atlas.allocate();
+            this.#dirty[c] = 1;
+            this.#build_records.push({
+                tile_origin: [0, 0, 0],
+                cascade_index: c,
+                corner: [0, 0, 0],
+                cell_size: this.#placement.cell_size(c),
+                tile_size: [
+                    this.#atlas.tile_size[0],
+                    this.#atlas.tile_size[1],
+                    this.#atlas.tile_size[2],
+                ],
+                border: IRRADIANCE_CLIPMAP_TILE_BORDER,
+            });
+        }
+
+        this.#uniform = device.createBuffer({
+            label: "GPUIrradianceClipmap/table",
+            size: IRRADIANCE_CLIPMAP_STRUCT.size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+
+    /**
+     * @returns {GPUTileAtlas3D}
+     */
+    get atlas() {
+        return this.#atlas;
+    }
+
+    /**
+     * @returns {GPUTextureContext}
+     */
+    get texture_y() {
+        return this.#atlas.texture_at(0);
+    }
+
+    /**
+     * @returns {GPUTextureContext}
+     */
+    get texture_cocg() {
+        return this.#atlas.texture_at(1);
+    }
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get uniform() {
+        return this.#uniform;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get cascade_count() {
+        return this.#placement.cascade_count;
+    }
+
+    /**
+     * Number of voxels at each cascade window's outer faces where blending takes place.
+     * @returns {number}
+     */
+    get blend_skirt() {
+        return this.#blend_skirt;
+    }
+
+    /**
+     * @returns {IrradianceCascadePlacement}
+     */
+    get placement() {
+        return this.#placement;
+    }
+
+    /**
+     * Forces all cascades to rebuild on the next executed frame.
+     */
+    invalidate_all() {
+        this.#dirty.fill(1, 0, this.#placement.cascade_count);
+    }
+
+    /**
+     * Updates cascade window placements around `anchor` (`[x, y, z]` in world metres), detects
+     * warp events (`placement.moved(c)`), schedules cascade updates, and uploads the uniform table.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {ShaderSwitchSet} [shader_switches]
+     */
+    update_placement(x, y, z, shader_switches = ShaderSwitchSet.EMPTY) {
+        assert.notOk(this.#destroyed, "destroyed");
+
+        const placement = this.#placement;
+        const count = placement.cascade_count;
+        const res = placement.resolution;
+
+        const indirect_mode = shader_switches.get(INDIRECT_LIGHTING);
+        if (indirect_mode !== this.#last_indirect_mode) {
+            this.#last_indirect_mode = indirect_mode;
+            this.#dirty.fill(1, 0, count);
+        }
+
+        placement.begin();
+        placement.place_all(x, y, z);
+
+        // Always schedule cascade 0 and the dyadic ruler cascade
+        this.#dirty[0] = 1;
+        const ruler_cascade = fluid_cascade_ruler(this.#tick, count);
+        if (ruler_cascade >= 0) {
+            this.#dirty[ruler_cascade] = 1;
+        }
+
+        // Force immediate update on any cascade whose window crossed a hysteretic voxel boundary (warp)
+        for (let c = 0; c < count; c++) {
+            if (placement.moved(c)) {
+                this.#dirty[c] = 1;
+            }
+        }
+
+        const atlas = this.#atlas;
+        const origin = this.#origin;
+        const f32 = this.#f32;
+        const i32 = this.#i32;
+
+        for (let c = 0; c < count; c++) {
+            const cx = placement.corner(c, 0);
+            const cy = placement.corner(c, 1);
+            const cz = placement.corner(c, 2);
+            const h = placement.cell_size(c);
+
+            const level = LEVELS + c * LEVEL_STRIDE;
+            i32[level + LEVEL_CORNER] = cx;
+            i32[level + LEVEL_CORNER + 1] = cy;
+            i32[level + LEVEL_CORNER + 2] = cz;
+            f32[level + LEVEL_CELL_SIZE] = h;
+            i32[level + LEVEL_SIZE] = res[0];
+            i32[level + LEVEL_SIZE + 1] = res[1];
+            i32[level + LEVEL_SIZE + 2] = res[2];
+
+            atlas.slot_origin(this.#slots[c], origin);
+
+            const cascade = CASCADES + c * CASCADE_STRIDE + CASCADE_CONTENT_ORIGIN;
+            f32[cascade] = origin[0] + IRRADIANCE_CLIPMAP_TILE_BORDER;
+            f32[cascade + 1] = origin[1] + IRRADIANCE_CLIPMAP_TILE_BORDER;
+            f32[cascade + 2] = origin[2] + IRRADIANCE_CLIPMAP_TILE_BORDER;
+
+            const record = this.#build_records[c];
+            record.tile_origin[0] = origin[0];
+            record.tile_origin[1] = origin[1];
+            record.tile_origin[2] = origin[2];
+            record.corner[0] = cx;
+            record.corner[1] = cy;
+            record.corner[2] = cz;
+            record.cell_size = h;
+        }
+
+        const tile = atlas.tile_size;
+        f32[INVERSE_ATLAS_SIZE] = 1 / (atlas.slots_x * tile[0]);
+        f32[INVERSE_ATLAS_SIZE + 1] = 1 / (atlas.slots_y * tile[1]);
+        f32[INVERSE_ATLAS_SIZE + 2] = 1 / (atlas.slots_z * tile[2]);
+        this.#u32[CASCADE_COUNT] = count;
+        f32[ANCHOR] = x;
+        f32[ANCHOR + 1] = y;
+        f32[ANCHOR + 2] = z;
+        f32[BLEND_SKIRT] = this.#blend_skirt;
+
+        this.#device.queue.writeBuffer(this.#uniform, 0, this.#bytes);
+    }
+
+    /**
+     * Records the world-space light cluster clipmap build and the irradiance clipmap cascade update
+     * passes into `graph`.
+     *
+     * Neither pass is marked a side effect, so if nothing in the frame reads `Y` or `CoCg` (e.g. a
+     * frame with no volumetrics and no lit particles), the frame graph culls both passes and `#dirty`
+     * remains set until a frame actually executes them.
+     *
+     * @param {Object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {import("../../camera/GPUCameraContext.js").GPUCameraContext} options.camera
+     * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene_ctx
+     * @param {number} options.shadowmap_atlas
+     * @param {ShaderSwitchSet} [options.shader_switches]
+     * @param {import("../../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap} [options.brick4]
+     * @param {import("../../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume} [options.lpv]
+     * @returns {{Y: number, CoCg: number, uniform: number}}
+     */
+    graph_update({
+        graph,
+        camera,
+        scene_ctx,
+        shadowmap_atlas,
+        shader_switches = ShaderSwitchSet.EMPTY,
+        brick4,
+        lpv,
+    }) {
+        const transform = camera?.camera?.transform;
+        const x = transform !== undefined ? transform.translation_x : 0;
+        const y = transform !== undefined ? transform.translation_y : 0;
+        const z = transform !== undefined ? transform.translation_z : 0;
+
+        this.update_placement(x, y, z, shader_switches);
+
+        const gr_uniform = graph_import_buffer(graph, this.#uniform, "irradiance clipmap table");
+        const count = this.#placement.cascade_count;
+        const coarsest = count - 1;
+        const coarsest_record = this.#build_records[coarsest];
+        const coarsest_h = coarsest_record.cell_size;
+        const border = IRRADIANCE_CLIPMAP_TILE_BORDER;
+        const res = this.#placement.resolution;
+
+        const coarsest_min = [
+            (coarsest_record.corner[0] - border) * coarsest_h,
+            (coarsest_record.corner[1] - border) * coarsest_h,
+            (coarsest_record.corner[2] - border) * coarsest_h,
+        ];
+        const coarsest_max = [
+            (coarsest_record.corner[0] + res[0] + border) * coarsest_h,
+            (coarsest_record.corner[1] + res[1] + border) * coarsest_h,
+            (coarsest_record.corner[2] + res[2] + border) * coarsest_h,
+        ];
+
+        const world_clusters = graph_build_world_light_clusters({
+            graph,
+            lights: scene_ctx.lights,
+            irradiance_clipmap_uniform: gr_uniform,
+            cascade_count: count,
+            coarsest_min,
+            coarsest_max,
+        });
+
+        const gr_atlas_y = graph_import_texture(graph, this.texture_y, "irradiance clipmap Y");
+        const gr_atlas_cocg = graph_import_texture(graph, this.texture_cocg, "irradiance clipmap CoCg");
+
+        const data = {};
+
+        const pass = graph.add(shader_irradiance_clipmap_build.descriptor.label, data, (data, resources, context) => {
+            if (this.#destroyed) {
+                return;
+            }
+
+            const encoder = context.encoder;
+            const output_Y = resources.get(data.irradiance_Y);
+            const output_CoCg = resources.get(data.irradiance_CoCg);
+            const world_cluster_lookup = resources.get(data.world_cluster_lookup);
+            const world_cluster_data = resources.get(data.world_cluster_data);
+            const shadowmap_view = resources.get(data.shadowmap_atlas).obtainView();
+            const sCompareLinear = context.graphics.samplers.obtain(SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR);
+
+            const tile = this.#atlas.tile_size;
+            const count = this.#placement.cascade_count;
+            const variant = shader_irradiance_clipmap_build.variant(shader_switches);
+
+            for (let c = 0; c < count; c++) {
+                if (this.#dirty[c] === 0) {
+                    continue;
+                }
+
+                const bindings = {
+                    build_settings: encoder.allocateTransientValueBuffer(
+                        IRRADIANCE_CLIPMAP_BUILD_STRUCT,
+                        this.#build_records[c],
+                        GPUBufferUsage.UNIFORM
+                    ),
+                    camera: camera.buffer.buffer,
+                    environment_sh: scene_ctx.lights.environment_sh,
+                    light_data: scene_ctx.lights.buffer_data,
+                    world_cluster_lookup,
+                    world_cluster_data,
+                    shadowmapAtlas: shadowmap_view,
+                    sCompareLinear,
+                    atlas_y: output_Y.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+                    atlas_cocg: output_CoCg.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+                };
+
+                if (brick4 !== undefined) {
+                    bindings.brick4 = brick4.buffer;
+                }
+
+                if (lpv !== undefined) {
+                    bindings.lpv_lookup = lpv.buffer_mesh_bvh;
+                    bindings.lpv_metadata = lpv.buffer_metadata;
+                    bindings.lpv_mesh = lpv.buffer_mesh;
+                    bindings.lpv_probes = lpv.buffer_probes;
+                }
+
+                encoder_prepare_shader_bindings_defaults(bindings, context, variant.descriptor.resources);
+
+                variant.dispatchThreads({
+                    encoder,
+                    thread_count_x: tile[0],
+                    thread_count_y: tile[1],
+                    thread_count_z: tile[2],
+                    bindings,
+                });
+
+                this.#dirty[c] = 0;
+            }
+
+            this.#tick++;
+        });
+
+        data.world_cluster_lookup = pass.read(world_clusters.lookup);
+        data.world_cluster_data = pass.read(world_clusters.data);
+        data.shadowmap_atlas = pass.read(shadowmap_atlas);
+        pass.read(gr_atlas_y);
+        data.irradiance_Y = pass.write(gr_atlas_y);
+        pass.read(gr_atlas_cocg);
+        data.irradiance_CoCg = pass.write(gr_atlas_cocg);
+
+        // Allow the frame graph to cull the clipmap build (and upstream world cluster passes) on
+        // frames where neither volumetric fog nor lit particles read `Y` or `CoCg`. `#dirty` stays
+        // set until a surviving frame actually executes the pass.
+        graph.__pass_nodes[graph.__pass_nodes.length - 1].has_side_effects = false;
+
+        return {
+            Y: data.irradiance_Y,
+            CoCg: data.irradiance_CoCg,
+            uniform: gr_uniform,
+        };
+    }
+
+    /**
+     * Releases GPU resources owned by the clipmap. Safe to call twice.
+     */
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+        this.#atlas.destroy();
+        this.#uniform.destroy();
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * 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: number;
+/**
+ * Maximum number of cascades supported by the irradiance clipmap table.
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_CASCADE_LIMIT: number;
+/**
+ * Default resolution (cells per axis) of each irradiance clipmap cascade (Decision 6.3).
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_DEFAULT_RESOLUTION: number;
+/**
+ * Default finest cascade cell size h0 in metres (25 cm, Decision 6.3).
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_DEFAULT_CELL_SIZE: number;
+/**
+ * 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: number;
+/**
+ * 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: number;
+/**
+ * Format of the two synchronized 3D atlas textures (`Y` and `CoCg`).
+ * @type {GPUTextureFormat}
+ */
+export const IRRADIANCE_CLIPMAP_TILE_FORMAT: GPUTextureFormat;
+/**
+ * Sampler used for trilinear taps of the irradiance clipmap atlas textures.
+ */
+export const IRRADIANCE_CLIPMAP_SAMPLER_DESCRIPTOR: Readonly<import("../../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor>;
+/**
+ * Maximum number of point or spot lights evaluated per voxel in the irradiance clipmap build pass.
+ * @type {number}
+ */
+export const IRRADIANCE_CLIPMAP_LIGHT_BUDGET: number;
+//# sourceMappingURL=IRRADIANCE_CLIPMAP.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IRRADIANCE_CLIPMAP.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/irradiance_clipmap/IRRADIANCE_CLIPMAP.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,uDAFU,MAAM,CAE0C;AAE1D;;;GAGG;AACH,+CAFU,MAAM,CAEoD;AAEpE;;;GAGG;AACH,oDAFU,MAAM,CAEwC;AAExD;;;GAGG;AACH,mDAFU,MAAM,CAEyC;AAEzD;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,qDAFU,MAAM,CAEwC;AAExD;;;GAGG;AACH,8DAA4D;AAE5D;;GAEG;AACH,2IAA4E;AAE5E;;;GAGG;AACH,8CAFU,MAAM,CAEkC"}