@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -1,484 +1,498 @@
-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();
-    }
-}
+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]
+     * @param {import("../../global_illumination/probe_clipmap/GPUProbeClipmapGI.js").GPUProbeClipmapGI} options.probes
+     *   the renderer's probe clipmap GI, whose probes the build binds in every mode
+     * @param {GPUBuffer} options.view_uniform the view's uniforms, whose frame index jitters the probes' pick
+     * @returns {{Y: number, CoCg: number, uniform: number}}
+     */
+    graph_update({
+        graph,
+        camera,
+        scene_ctx,
+        shadowmap_atlas,
+        shader_switches = ShaderSwitchSet.EMPTY,
+        brick4,
+        lpv,
+        probes,
+        view_uniform,
+    }) {
+        assert.defined(probes, 'probes');
+        assert.defined(view_uniform, 'view_uniform');
+
+        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,
+        ];
+
+        // the uniform's table starts with the cascades' windows, and the tiles' skirt is the border
+        const world_clusters = graph_build_world_light_clusters({
+            graph,
+            lights: scene_ctx.lights,
+            levels: gr_uniform,
+            cascade_count: count,
+            border,
+            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),
+                    view: view_uniform,
+                };
+
+                // in every mode: a clipmap of no cascade while the probe clipmap has none
+                probes.write_sampling_bindings(bindings);
+
+                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();
+    }
+}