@woosh/meep-engine 3.54.0 → 3.56.0

package/src/shade/renderer/volumetrics/GPUViewVolumetrics.js

@@ -1,583 +1,660 @@
-import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
-import { build_light_cluster_parameters } from "../light/cluster/build_light_cluster_parameters.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 { update_frustum_far_plane } from "../shadow/map/update_frustum_far_plane.js";
-import { GPUTextureContext } from "../texture/GPUTextureContext.js";
-import { slice_flat_array } from "../util/slice_flat_array.js";
-import {
-    build_volumetrics_sun_shadow_transform,
-    volumetrics_sun_shadow_cascade_far
-} from "./build_volumetrics_sun_shadow_transform.js";
-import { graph_build_volumetrics } from "./graph_build_volumetrics.js";
-import { GPUIrradianceClipmap } from "./irradiance_clipmap/GPUIrradianceClipmap.js";
-import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
-import { VOLUMETRICS_RESOLUTION_Z } from "./VOLUMETRICS_RESOLUTION_Z.js";
-import {
-    VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT,
-    VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO,
-    VOLUMETRICS_SUN_SHADOW_LIGHT_NONE,
-    VOLUMETRICS_SUN_SHADOW_RESOLUTION
-} from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
-
-/**
- * @typedef {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
- * @typedef {import("../view/GPUViewContext.js").GPUViewContext} GPUViewContext
- */
-
-/**
- * resolution of a single froxel in XY, in pixels
- */
-const TILE_SIZE = 16;
-
-export class GPUViewVolumetrics {
-
-    /**
-     * @type {GPUViewContext}
-     */
-    #view
-
-    /**
-     * NOTE: Initialized in the constructor
-     * @type {GPUTextureContext[]}
-     */
-    #volumetrics_textures = [];
-
-    /**
-     * Should we perform temporal integration, or not?
-     * If set to true - the next update will discard history.
-     * Useful for significant scene transitions and screen resizing.
-     * @type {boolean}
-     */
-    #reset_history = true;
-
-    /**
-     * Whether to run the 3D temporal reprojection (volumetric TAA) over the per-froxel scattering
-     * volume. When disabled, the aerial pass integrates the raw (noisier) scattering LUT directly —
-     * a safe fallback if temporal artifacts appear.
-     * @type {boolean}
-     */
-    #taa_enabled = true;
-
-    /**
-     * @returns {boolean}
-     */
-    get taa_enabled() {
-        return this.#taa_enabled;
-    }
-
-    /**
-     * @param {boolean} v
-     */
-    set taa_enabled(v) {
-        if (v === this.#taa_enabled) {
-            return;
-        }
-        this.#taa_enabled = v;
-        // re-enabling must not blend against a stale / never-written history texture
-        this.#reset_history = true;
-    }
-
-    /**
-     * View-space distance at which the froxel grid ends and the aerial pass switches to a direct
-     * RDR2-style volume ray-march. Clamped to camera.far at upload, so the default (Infinity) means
-     * "grid covers the whole range" and the far march is a no-op.
-     * @type {number}
-     */
-    #froxel_far = Infinity;
-
-    /**
-     * The froxel depth curve uploaded last frame. The TAA history is addressed on the curve it was
-     * accumulated with, so when the curve changes the history is wrong at every slice and must be
-     * dropped. Comparing the built parameters catches every input to the curve at once -- camera
-     * near, camera far, the froxel-far override -- rather than watching each separately.
-     * @type {Float32Array}
-     */
-    #froxel_curve_previous = new Float32Array(3);
-
-    /**
-     * @returns {number}
-     */
-    get froxel_far() {
-        return this.#froxel_far;
-    }
-
-    /**
-     * @param {number} v
-     */
-    set froxel_far(v) {
-        this.#froxel_far = v;
-    }
-
-    /**
-     * Q-04. World -> volume and back for each cascade, innermost first, rebuilt every frame by
-     * {@link build_volumetrics_sun_shadow_transform} and uploaded in the metadata.
-     * @type {Float32Array[]}
-     */
-    #sun_shadow_ws_to_uvw = Array.from({ length: VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT }, () => new Float32Array(16));
-
-    /**
-     * @type {Float32Array[]}
-     */
-    #sun_shadow_uvw_to_ws = Array.from({ length: VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT }, () => new Float32Array(16));
-
-    /**
-     * Voxel counts one sun optical-depth cascade is dispatched at this frame. Collapses to
-     * `[1, 1, 1]` when the froxels are marching instead, so the passes stay in the frame graph and
-     * cost nothing — see `graph_build_sun_shadow_volume` for why they stay rather than going.
-     * @type {number[]}
-     */
-    #sun_shadow_resolution = [1, 1, 1];
-
-    /**
-     * World-space size of one voxel along the sun axis per cascade, i.e. each scan's step, packed
-     * for the `vec4f` the metadata carries.
-     * @type {Float32Array}
-     */
-    #sun_shadow_step_ws = new Float32Array(4);
-
-    /**
-     * Which directional light this frame's cascades were built for, or
-     * {@link VOLUMETRICS_SUN_SHADOW_LIGHT_NONE} when there was nothing to build for.
-     * @type {number}
-     */
-    #sun_shadow_light_index = VOLUMETRICS_SUN_SHADOW_LIGHT_NONE;
-
-    /**
-     * View depth each cascade covers out to, packed the same way. Trailing lanes repeat the
-     * outermost so a read past the end of the ladder still lands on a real cascade.
-     * @type {Float32Array}
-     */
-    #sun_shadow_cascade_far = new Float32Array(4);
-
-    /**
-     * What the fog integrates to through no medium: nothing in-scattered (.rgb 0), everything
-     * transmitted (.a 1). Handed out in place of the aerial LUT on a frame whose scene has no
-     * participating-media volume, so every surface that samples the fog keeps doing so and reads
-     * it as none, for one texel and no pass. Written once, at construction.
-     * @type {GPUTextureContext}
-     */
-    #no_medium;
-
-    /**
-     * @type {GPUTypedBuffer}
-     */
-    #metadata;
-
-    /**
-     * World-space irradiance clipmap (`GPUIrradianceClipmap`) used by particle lighting.
-     * @type {GPUIrradianceClipmap}
-     */
-    #irradiance_clipmap;
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device
-
-    /**
-     *
-     * @param {GPUViewContext} view
-     * @param {GPUDevice} device
-     */
-    constructor(view, device) {
-        this.#device = device;
-        this.#view = view;
-
-        // initialize textures
-        for (let i = 0; i < 2; i++) {
-            const texture = new GPUTextureContext(device);
-
-            texture.descriptor.format = "rgba16float";
-            texture.descriptor.dimension = "3d";
-            texture.descriptor.usage = GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING;
-
-            this.#volumetrics_textures[i] = texture;
-        }
-
-        const no_medium = new GPUTextureContext(device);
-        no_medium.descriptor.label = "volumetrics/no medium";
-        no_medium.descriptor.format = "rgba16float";
-        no_medium.descriptor.dimension = "3d";
-        no_medium.descriptor.size = [1, 1, 1];
-        no_medium.descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST;
-
-        device.queue.writeTexture(
-            { texture: no_medium.gpu_texture },
-            new Float16Array([0, 0, 0, 1]),
-            { bytesPerRow: 8, rowsPerImage: 1 },
-            [1, 1, 1]
-        );
-        no_medium.incrementVersion();
-
-        this.#no_medium = no_medium;
-
-        this.#metadata = GPUTypedBuffer.create({
-            type: VOLUMETRICS_METADATA_STRUCT,
-            device,
-            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-        });
-
-        this.#irradiance_clipmap = new GPUIrradianceClipmap(device);
-
-    }
-
-    /**
-     * @returns {GPUIrradianceClipmap}
-     */
-    get irradiance_clipmap() {
-        return this.#irradiance_clipmap;
-    }
-
-    destroy() {
-
-        const textures = this.#volumetrics_textures;
-
-        for (let i = 0; i < 2; i++) {
-
-            textures[i].destroy();
-
-            textures[i] = null;
-        }
-
-        this.#no_medium.destroy();
-        this.#irradiance_clipmap.destroy();
-
-    }
-
-    #update_resolution() {
-
-
-        const screen_resolution = this.#view.resolution;
-
-        const output_resolution_x = Math.ceil(screen_resolution[0] / TILE_SIZE);
-        const output_resolution_y = Math.ceil(screen_resolution[1] / TILE_SIZE);
-
-        const t_first = this.#volumetrics_textures[0];
-
-        if (t_first.width === output_resolution_x
-            && t_first.height === output_resolution_y
-        ) {
-            // already at the right resolution
-            return;
-        }
-
-        for (let i = 0; i < 2; i++) {
-
-            this.#volumetrics_textures[i].resize(
-                output_resolution_x,
-                output_resolution_y,
-                VOLUMETRICS_RESOLUTION_Z
-            );
-
-        }
-
-        // drop history
-        this.#reset_history = true;
-    }
-
-    /**
-     * Place this frame's sun optical-depth cascades, and say which light they cover.
-     *
-     * This is how the sun's media self-shadowing is computed — there is no second path to select
-     * between. The march in `chunk_integrate_optical_depth` remains for the lights the cascades do
-     * not cover: every point and spot light, whose rays are short enough that there is little to
-     * amortize, and any directional light past the first, since there is one ladder of boxes and it
-     * is aligned to one direction. Two situations leave the cascades covering nothing at all, and
-     * `VOLUMETRICS_SUN_SHADOW_LIGHT_NONE` is how they say so.
-     *
-     * The light is the first entry of the `light_directional` table, which is the first
-     * `DirectionalLight` in scene order — `GPULightCollection.#build` packs them in that order, so
-     * walking the same list here recovers the same index. In practice a scene has one sun.
-     *
-     * Every cascade is placed by the same call with a different `far`, which is what makes the
-     * stability argument transfer: each box is sized from the bounding sphere of the sub-frustum it
-     * covers, that sphere is a function of the projection alone, and the origin is snapped to whole
-     * voxels — so each cascade's world-space lattice is the same set of points from frame to frame
-     * no matter how the camera moves.
-     *
-     * @returns {number} the light index the cascades cover, or the sentinel
-     */
-    #update_sun_shadow() {
-        const camera = this.#view.camera.camera;
-
-        // One voxel per cascade rather than no pass at all: the lighting pass binds these textures
-        // unconditionally and WebGPU has no optional bindings. Nothing samples them, because the
-        // sentinel below matches no light index.
-        this.#sun_shadow_resolution = [1, 1, 1];
-
-        // an orthographic view has no fov to derive a bounding sphere from, and no volumetrics
-        // camera path that reaches here today — bail rather than invent one
-        if (typeof camera.fov !== "number") {
-            return VOLUMETRICS_SUN_SHADOW_LIGHT_NONE;
-        }
-
-        const lights = this.#view.scene.lights.source.elements;
-
-        let sun = null;
-
-        for (let i = 0; i < lights.length; i++) {
-            if (lights[i].isDirectionalLight === true) {
-                sun = lights[i];
-                break;
-            }
-        }
-
-        if (sun === null) {
-            return VOLUMETRICS_SUN_SHADOW_LIGHT_NONE;
-        }
-
-        const resolution = VOLUMETRICS_SUN_SHADOW_RESOLUTION;
-
-        // `forward` is the direction light TRAVELS — the same vector light_record_directional
-        // writes into the table, which the shader then negates to point at the light. Read off the
-        // CPU copy of the pose: the cascade is built here, on this side.
-        const direction = sun.transform.forward;
-
-        const view_matrix = camera.view_matrix;
-        const position = camera.transform;
-
-        // the medium lives in the froxel grid and the grid stops here, so there is nothing to
-        // integrate past it
-        const far = Math.min(this.#froxel_far, camera.far);
-
-        const cascade_count = VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT;
-        const cascade_ratio = VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO;
-
-        // the view matrix's z row, negated: view space looks down -Z, and the row is unit length
-        // because the linear part is a rotation
-        const camera_forward = [-view_matrix[2], -view_matrix[6], -view_matrix[10]];
-
-        for (let cascade = 0; cascade < cascade_count; cascade++) {
-
-            const cascade_far = volumetrics_sun_shadow_cascade_far(far, cascade, cascade_count, cascade_ratio);
-
-            this.#sun_shadow_step_ws[cascade] = build_volumetrics_sun_shadow_transform({
-                ws_to_uvw: this.#sun_shadow_ws_to_uvw[cascade],
-                uvw_to_ws: this.#sun_shadow_uvw_to_ws[cascade],
-                light_direction: [direction[0], direction[1], direction[2]],
-                camera_position: [position.translation_x, position.translation_y, position.translation_z],
-                camera_forward,
-                fov_y: camera.fov,
-                aspect: camera.aspect,
-                near: camera.near,
-                far: cascade_far,
-                resolution,
-            });
-
-            this.#sun_shadow_cascade_far[cascade] = cascade_far;
-        }
-
-        // Trailing lanes repeat the outermost cascade rather than holding zero: the read side walks
-        // the ladder comparing view depth against these, and a zero would read as a cascade that
-        // ends at the camera.
-        for (let lane = cascade_count; lane < 4; lane++) {
-            this.#sun_shadow_cascade_far[lane] = far;
-            this.#sun_shadow_step_ws[lane] = this.#sun_shadow_step_ws[cascade_count - 1];
-        }
-
-        this.#sun_shadow_resolution = resolution;
-
-        return 0;
-    }
-
-    #update_metadata() {
-        const view = this.#view;
-        const camera = view.camera;
-
-        const resolution = this.#volumetrics_textures[0].size;
-
-        this.#sun_shadow_light_index = this.#update_sun_shadow();
-
-        const volumetrics_cluster_parameters = new Float32Array(3);
-
-        // The depth-curve `scale` must grow with the slice count. The hard-coded 4.06 was tuned for
-        // the light-cluster grid (24 slices); reusing it with 64 froxel slices collapses the log
-        // curve so ~half the slices bunch into the first fraction of a unit of depth, leaving almost
-        // none for the actual scene. Derive scale for a log-uniform distribution over
-        // [near + near_offset, far] instead (gives O ~= 0, i.e. depth ~ offset * (far/offset)^(s/(N-1))).
-        const NEAR_OFFSET = 0.1;
-        const depth_offset = camera.camera.near + NEAR_OFFSET;
-        const depth_scale = (VOLUMETRICS_RESOLUTION_Z - 1) / Math.log2(camera.camera.far / depth_offset);
-
-        build_light_cluster_parameters(
-            volumetrics_cluster_parameters,
-            0,
-            VOLUMETRICS_RESOLUTION_Z,
-            camera.camera.near,
-            camera.camera.far,
-            NEAR_OFFSET,
-            depth_scale
-        );
-
-        // Froxel-grid curve: same construction but ending at froxel_far (<= camera.far). The grid's
-        // slices pack into [near, froxel_far] for extra near detail; beyond froxel_far the aerial
-        // pass ray-marches the volumes. froxel_far == camera.far -> identical to the LUT curve (no-op).
-        const froxel_far = Math.min(this.#froxel_far, camera.camera.far);
-        const froxel_depth_scale = (VOLUMETRICS_RESOLUTION_Z - 1) / Math.log2(froxel_far / depth_offset);
-        const volumetrics_froxel_cluster_parameters = new Float32Array(3);
-        build_light_cluster_parameters(
-            volumetrics_froxel_cluster_parameters,
-            0,
-            VOLUMETRICS_RESOLUTION_Z,
-            camera.camera.near,
-            froxel_far,
-            NEAR_OFFSET,
-            froxel_depth_scale
-        );
-
-        // Recomputed deterministically, so a steady camera compares bitwise equal and never resets.
-        {
-            const curve = volumetrics_froxel_cluster_parameters;
-            const previous = this.#froxel_curve_previous;
-
-            if (curve[0] !== previous[0] || curve[1] !== previous[1] || curve[2] !== previous[2]) {
-                previous.set(curve);
-                this.#reset_history = true;
-            }
-        }
-
-        // The projection is infinite-far reverse-Z, so the camera frustum's far plane is zeroed and
-        // can't be sliced into froxel slabs. Rebuild a finite far plane at the logical far for the
-        // participating-media coverage test — exactly as the light-cluster assignment does.
-        const clipped_frustum = new Float32Array(24);
-        clipped_frustum.set(camera.camera.frustum);
-        update_frustum_far_plane(clipped_frustum, camera.camera.view_matrix, camera.camera.far);
-
-        this.#metadata.upload({
-            cluster_parameters: volumetrics_cluster_parameters,
-            froxel_cluster_parameters: volumetrics_froxel_cluster_parameters,
-            resolution,
-            frustum: slice_flat_array(clipped_frustum, 0, 4, 6),
-            history_reset: this.#reset_history ? 1 : 0,
-            froxel_far,
-            // multiscatter knobs (GUI-tunable via globals); engine defaults 6 / 0.5
-            ms_octave_count: globalThis.__VOL_MS_OCTAVES ?? 6,
-            ms_extinction_decay: globalThis.__VOL_MS_EXT_DECAY ?? 0.5,
-            // Q-04. The sun's media self-shadowing, out of a 16-step per-froxel march and into one
-            // fetch of the cascades built earlier this frame — see #update_sun_shadow.
-            sun_shadow_ws_to_uvw: this.#sun_shadow_ws_to_uvw,
-            sun_shadow_uvw_to_ws: this.#sun_shadow_uvw_to_ws,
-            sun_shadow_step_ws: this.#sun_shadow_step_ws,
-            sun_shadow_cascade_far: this.#sun_shadow_cascade_far,
-            sun_shadow_light_index: this.#sun_shadow_light_index,
-        }, this.#device.queue);
-    }
-
-    /**
-     *
-     * @param {Object} options
-     * @param {FrameGraph} options.graph
-     * @param {number} options.light_cluster_data
-     * @param {number} options.light_cluster_lookup
-     * @param {number} options.light_cluster_parameters
-     * @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 {{resolved: number, metadata: number, irradiance: {Y: number, CoCg: number, uniform: number}}}
-     */
-    graph_update({
-                     graph,
-                     light_cluster_data,
-                     light_cluster_lookup,
-                     light_cluster_parameters,
-                     shadowmap_atlas,
-                     shader_switches = ShaderSwitchSet.EMPTY,
-                     brick4,
-                     lpv,
-                 }) {
-
-        const view = this.#view;
-        const lights = view.scene.lights;
-        const camera = view.camera;
-
-        const taa_requested = globalThis.__VOL_TAA_ENABLED;
-        if (taa_requested !== undefined && taa_requested !== this.#taa_enabled) {
-            this.taa_enabled = taa_requested;
-        }
-
-        const froxel_far_requested = globalThis.__VOL_FROXEL_FAR;
-        if (froxel_far_requested !== undefined && froxel_far_requested !== this.#froxel_far) {
-            this.#froxel_far = froxel_far_requested;
-            // the froxel grid's depth curve just changed; the TAA history is on the old curve, reset it
-            this.#reset_history = true;
-        }
-
-        this.#update_resolution();
-        this.#update_metadata();
-
-        const gr_metadata = graph_import_buffer(graph, this.#metadata.buffer, "volumetrics metadata");
-
-        const resolution = this.#volumetrics_textures[0].size;
-
-        // World-space irradiance clipmap for particle lighting.
-        // Culled by the frame graph when no lit particles read it.
-        const irradiance = this.#irradiance_clipmap.graph_update({
-            graph,
-            camera,
-            scene_ctx: view.scene,
-            shadowmap_atlas,
-            shader_switches,
-            brick4,
-            lpv,
-        });
-
-        if (view.scene.volumetrics.source.volumes.length === 0) {
-            // No medium: nothing scatters and nothing absorbs, so the fog is the identity everywhere
-            // and the passes that would integrate it to that are not recorded. Nothing accumulates
-            // either, which leaves the history stale for whenever a volume arrives.
-            this.#reset_history = true;
-
-            return {
-                resolved: graph_import_texture(graph, this.#no_medium, "volumetrics no medium"),
-                metadata: gr_metadata,
-                irradiance,
-            };
-        }
-
-        let taa_history;
-        let taa_output;
-
-        if (this.#taa_enabled) {
-            const parity = view.frame_index & 1;
-            taa_history = graph_import_texture(graph, this.#volumetrics_textures[parity ^ 1], "volumetrics taa history");
-            taa_output = graph_import_texture(graph, this.#volumetrics_textures[parity], "volumetrics taa output");
-        }
-
-        const sky = view.scene.sky;
-
-        sky.update();
-
-        const { lut_aerial } = graph_build_volumetrics({
-            graph,
-            camera,
-            lights,
-            view,
-            sky,
-            light_cluster_data,
-            light_cluster_lookup,
-            light_cluster_parameters,
-            shadowmap_atlas,
-
-            volumetrics_metadata: gr_metadata,
-            volumetric_resolution: resolution,
-            sun_shadow_resolution: this.#sun_shadow_resolution,
-
-            taa_history,
-            taa_output,
-            camera_previous: view.gpu_previous_camera_state,
-            shader_switches,
-        });
-
-        this.#reset_history = false;
-
-        return {
-            resolved: lut_aerial,
-            metadata: gr_metadata,
-            irradiance,
-        };
-    }
-
-}
+import { assert } from "../../../core/assert.js";
+import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
+import { build_light_cluster_parameters } from "../light/cluster/build_light_cluster_parameters.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 { update_frustum_far_plane } from "../shadow/map/update_frustum_far_plane.js";
+import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+import { slice_flat_array } from "../util/slice_flat_array.js";
+import {
+    build_volumetrics_sun_shadow_transform,
+    volumetrics_sun_shadow_cascade_far
+} from "./build_volumetrics_sun_shadow_transform.js";
+import { graph_build_volumetrics } from "./graph_build_volumetrics.js";
+import { GPUIrradianceClipmap } from "./irradiance_clipmap/GPUIrradianceClipmap.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
+import {
+    VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT,
+    VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO,
+    VOLUMETRICS_SUN_SHADOW_LIGHT_NONE,
+    VOLUMETRICS_SUN_SHADOW_RESOLUTION
+} from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
+
+/**
+ * @typedef {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ */
+
+export class GPUViewVolumetrics {
+
+    /**
+     * NOTE: Initialized in the constructor
+     * @type {GPUTextureContext[]}
+     */
+    #volumetrics_textures = [];
+
+    /**
+     * Should we perform temporal integration, or not?
+     * If set to true - the next update will discard history.
+     * Useful for significant scene transitions and screen resizing.
+     * @type {boolean}
+     */
+    #reset_history = true;
+
+    /**
+     * {@link GPUViewContext#id} of the view the history was accumulated from. The history is that
+     * view's fog; a frame from any other view must not blend against it.
+     * @type {number}
+     */
+    #history_view_id = -1;
+
+    /**
+     * Whether to run the 3D temporal reprojection (volumetric TAA) over the per-froxel scattering
+     * volume. When disabled, the aerial pass integrates the raw (noisier) scattering LUT directly —
+     * a safe fallback if temporal artifacts appear.
+     * @type {boolean}
+     */
+    #taa_enabled = true;
+
+    /**
+     * @returns {boolean}
+     */
+    get taa_enabled() {
+        return this.#taa_enabled;
+    }
+
+    /**
+     * @param {boolean} v
+     */
+    set taa_enabled(v) {
+        if (v === this.#taa_enabled) {
+            return;
+        }
+        this.#taa_enabled = v;
+        // re-enabling must not blend against a stale / never-written history texture
+        this.#reset_history = true;
+    }
+
+    /**
+     * Size of one froxel in XY, in screen pixels.
+     * @type {number}
+     */
+    #tile_size = 16;
+
+    /**
+     * Number of froxel slices along the view.
+     * @type {number}
+     */
+    #resolution_z = 64;
+
+    /**
+     * Size of one froxel in XY, in screen pixels. Smaller is finer fog detail at a cost that grows
+     * with the inverse square. The grid is resized on the next update and the TAA history dropped,
+     * so the frame after a change starts its accumulation over.
+     *
+     * The grid's XY extent, `ceil(view resolution / tile_size)`, must stay within the device's
+     * `maxTextureDimension3D`.
+     * @returns {number}
+     */
+    get tile_size() {
+        return this.#tile_size;
+    }
+
+    /**
+     * @param {number} v positive integer
+     */
+    set tile_size(v) {
+        assert.isPositiveInteger(v, 'tile_size');
+
+        this.#tile_size = v;
+    }
+
+    /**
+     * Number of froxel slices between the camera near and {@link froxel_far}. Cost grows linearly.
+     * The grid is resized on the next update and the TAA history dropped, as for {@link tile_size}.
+     * @returns {number}
+     */
+    get resolution_z() {
+        return this.#resolution_z;
+    }
+
+    /**
+     * @param {number} v integer, at least 2 (the depth curve needs a first and a last slice) and at
+     * most the device's `maxTextureDimension3D`
+     */
+    set resolution_z(v) {
+        assert.isPositiveInteger(v, 'resolution_z');
+        assert.greaterThanOrEqual(v, 2, 'resolution_z');
+        assert.lessThanOrEqual(v, this.#device.limits.maxTextureDimension3D, 'resolution_z must fit maxTextureDimension3D');
+
+        this.#resolution_z = v;
+    }
+
+    /**
+     * View-space distance at which the froxel grid ends and the aerial pass switches to a direct
+     * RDR2-style volume ray-march. Clamped to camera.far at upload, so the default (Infinity) means
+     * "grid covers the whole range" and the far march is a no-op.
+     * @type {number}
+     */
+    #froxel_far = Infinity;
+
+    /**
+     * The froxel depth curve uploaded last frame. The TAA history is addressed on the curve it was
+     * accumulated with, so when the curve changes the history is wrong at every slice and must be
+     * dropped. Comparing the built parameters catches every input to the curve at once -- camera
+     * near, camera far, the froxel-far override -- rather than watching each separately.
+     * @type {Float32Array}
+     */
+    #froxel_curve_previous = new Float32Array(3);
+
+    /**
+     * @returns {number}
+     */
+    get froxel_far() {
+        return this.#froxel_far;
+    }
+
+    /**
+     * @param {number} v
+     */
+    set froxel_far(v) {
+        this.#froxel_far = v;
+    }
+
+    /**
+     * Q-04. World -> volume and back for each cascade, innermost first, rebuilt every frame by
+     * {@link build_volumetrics_sun_shadow_transform} and uploaded in the metadata.
+     * @type {Float32Array[]}
+     */
+    #sun_shadow_ws_to_uvw = Array.from({ length: VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT }, () => new Float32Array(16));
+
+    /**
+     * @type {Float32Array[]}
+     */
+    #sun_shadow_uvw_to_ws = Array.from({ length: VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT }, () => new Float32Array(16));
+
+    /**
+     * Voxel counts one sun optical-depth cascade is dispatched at this frame. Collapses to
+     * `[1, 1, 1]` when the froxels are marching instead, so the passes stay in the frame graph and
+     * cost nothing — see `graph_build_sun_shadow_volume` for why they stay rather than going.
+     * @type {number[]}
+     */
+    #sun_shadow_resolution = [1, 1, 1];
+
+    /**
+     * World-space size of one voxel along the sun axis per cascade, i.e. each scan's step, packed
+     * for the `vec4f` the metadata carries.
+     * @type {Float32Array}
+     */
+    #sun_shadow_step_ws = new Float32Array(4);
+
+    /**
+     * Which directional light this frame's cascades were built for, or
+     * {@link VOLUMETRICS_SUN_SHADOW_LIGHT_NONE} when there was nothing to build for.
+     * @type {number}
+     */
+    #sun_shadow_light_index = VOLUMETRICS_SUN_SHADOW_LIGHT_NONE;
+
+    /**
+     * View depth each cascade covers out to, packed the same way. Trailing lanes repeat the
+     * outermost so a read past the end of the ladder still lands on a real cascade.
+     * @type {Float32Array}
+     */
+    #sun_shadow_cascade_far = new Float32Array(4);
+
+    /**
+     * What the fog integrates to through no medium: nothing in-scattered (.rgb 0), everything
+     * transmitted (.a 1). Handed out in place of the aerial LUT on a frame whose scene has no
+     * participating-media volume, so every surface that samples the fog keeps doing so and reads
+     * it as none, for one texel and no pass. Written once, at construction.
+     * @type {GPUTextureContext}
+     */
+    #no_medium;
+
+    /**
+     * @type {GPUTypedBuffer}
+     */
+    #metadata;
+
+    /**
+     * World-space irradiance clipmap (`GPUIrradianceClipmap`) used by particle lighting.
+     * @type {GPUIrradianceClipmap}
+     */
+    #irradiance_clipmap;
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device
+
+    /**
+     *
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        this.#device = device;
+
+        // initialize textures
+        for (let i = 0; i < 2; i++) {
+            const texture = new GPUTextureContext(device);
+
+            texture.descriptor.format = "rgba16float";
+            texture.descriptor.dimension = "3d";
+            texture.descriptor.usage = GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING;
+
+            this.#volumetrics_textures[i] = texture;
+        }
+
+        const no_medium = new GPUTextureContext(device);
+        no_medium.descriptor.label = "volumetrics/no medium";
+        no_medium.descriptor.format = "rgba16float";
+        no_medium.descriptor.dimension = "3d";
+        no_medium.descriptor.size = [1, 1, 1];
+        no_medium.descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST;
+
+        device.queue.writeTexture(
+            { texture: no_medium.gpu_texture },
+            new Float16Array([0, 0, 0, 1]),
+            { bytesPerRow: 8, rowsPerImage: 1 },
+            [1, 1, 1]
+        );
+        no_medium.incrementVersion();
+
+        this.#no_medium = no_medium;
+
+        this.#metadata = GPUTypedBuffer.create({
+            type: VOLUMETRICS_METADATA_STRUCT,
+            device,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#irradiance_clipmap = new GPUIrradianceClipmap(device);
+
+    }
+
+    /**
+     * @returns {GPUIrradianceClipmap}
+     */
+    get irradiance_clipmap() {
+        return this.#irradiance_clipmap;
+    }
+
+    /**
+     * Drop the TAA history, so the next frame integrates without blending against what came before
+     * it. For a cut the grid, the depth curve and the view cannot see: the camera jumped, or the
+     * scene changed significantly.
+     */
+    reset_history() {
+        this.#reset_history = true;
+    }
+
+    destroy() {
+
+        const textures = this.#volumetrics_textures;
+
+        for (let i = 0; i < 2; i++) {
+
+            textures[i].destroy();
+
+            textures[i] = null;
+        }
+
+        this.#no_medium.destroy();
+        this.#irradiance_clipmap.destroy();
+
+    }
+
+    /**
+     * @param {GPUViewContext} view
+     */
+    #update_resolution(view) {
+
+        const screen_resolution = view.resolution;
+
+        const output_resolution_x = Math.ceil(screen_resolution[0] / this.#tile_size);
+        const output_resolution_y = Math.ceil(screen_resolution[1] / this.#tile_size);
+        const output_resolution_z = this.#resolution_z;
+
+        const t_first = this.#volumetrics_textures[0];
+
+        if (t_first.width === output_resolution_x
+            && t_first.height === output_resolution_y
+            && t_first.depth === output_resolution_z
+        ) {
+            // already at the right resolution
+            return;
+        }
+
+        for (let i = 0; i < 2; i++) {
+
+            this.#volumetrics_textures[i].resize(
+                output_resolution_x,
+                output_resolution_y,
+                output_resolution_z
+            );
+
+        }
+
+        // drop history
+        this.#reset_history = true;
+    }
+
+    /**
+     * Place this frame's sun optical-depth cascades, and say which light they cover.
+     *
+     * This is how the sun's media self-shadowing is computed — there is no second path to select
+     * between. The march in `chunk_integrate_optical_depth` remains for the lights the cascades do
+     * not cover: every point and spot light, whose rays are short enough that there is little to
+     * amortize, and any directional light past the first, since there is one ladder of boxes and it
+     * is aligned to one direction. Two situations leave the cascades covering nothing at all, and
+     * `VOLUMETRICS_SUN_SHADOW_LIGHT_NONE` is how they say so.
+     *
+     * The light is the first entry of the `light_directional` table, which is the first
+     * `DirectionalLight` in scene order — `GPULightCollection.#build` packs them in that order, so
+     * walking the same list here recovers the same index. In practice a scene has one sun.
+     *
+     * Every cascade is placed by the same call with a different `far`, which is what makes the
+     * stability argument transfer: each box is sized from the bounding sphere of the sub-frustum it
+     * covers, that sphere is a function of the projection alone, and the origin is snapped to whole
+     * voxels — so each cascade's world-space lattice is the same set of points from frame to frame
+     * no matter how the camera moves.
+     *
+     * @param {GPUViewContext} view
+     * @returns {number} the light index the cascades cover, or the sentinel
+     */
+    #update_sun_shadow(view) {
+        const camera = view.camera.camera;
+
+        // One voxel per cascade rather than no pass at all: the lighting pass binds these textures
+        // unconditionally and WebGPU has no optional bindings. Nothing samples them, because the
+        // sentinel below matches no light index.
+        this.#sun_shadow_resolution = [1, 1, 1];
+
+        // an orthographic view has no fov to derive a bounding sphere from, and no volumetrics
+        // camera path that reaches here today — bail rather than invent one
+        if (typeof camera.fov !== "number") {
+            return VOLUMETRICS_SUN_SHADOW_LIGHT_NONE;
+        }
+
+        const lights = view.scene.lights.source.elements;
+
+        let sun = null;
+
+        for (let i = 0; i < lights.length; i++) {
+            if (lights[i].isDirectionalLight === true) {
+                sun = lights[i];
+                break;
+            }
+        }
+
+        if (sun === null) {
+            return VOLUMETRICS_SUN_SHADOW_LIGHT_NONE;
+        }
+
+        const resolution = VOLUMETRICS_SUN_SHADOW_RESOLUTION;
+
+        // `forward` is the direction light TRAVELS — the same vector light_record_directional
+        // writes into the table, which the shader then negates to point at the light. Read off the
+        // CPU copy of the pose: the cascade is built here, on this side.
+        const direction = sun.transform.forward;
+
+        const view_matrix = camera.view_matrix;
+        const position = camera.transform;
+
+        // the medium lives in the froxel grid and the grid stops here, so there is nothing to
+        // integrate past it
+        const far = Math.min(this.#froxel_far, camera.far);
+
+        const cascade_count = VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT;
+        const cascade_ratio = VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO;
+
+        // the view matrix's z row, negated: view space looks down -Z, and the row is unit length
+        // because the linear part is a rotation
+        const camera_forward = [-view_matrix[2], -view_matrix[6], -view_matrix[10]];
+
+        for (let cascade = 0; cascade < cascade_count; cascade++) {
+
+            const cascade_far = volumetrics_sun_shadow_cascade_far(far, cascade, cascade_count, cascade_ratio);
+
+            this.#sun_shadow_step_ws[cascade] = build_volumetrics_sun_shadow_transform({
+                ws_to_uvw: this.#sun_shadow_ws_to_uvw[cascade],
+                uvw_to_ws: this.#sun_shadow_uvw_to_ws[cascade],
+                light_direction: [direction[0], direction[1], direction[2]],
+                camera_position: [position.translation_x, position.translation_y, position.translation_z],
+                camera_forward,
+                fov_y: camera.fov,
+                aspect: camera.aspect,
+                near: camera.near,
+                far: cascade_far,
+                resolution,
+            });
+
+            this.#sun_shadow_cascade_far[cascade] = cascade_far;
+        }
+
+        // Trailing lanes repeat the outermost cascade rather than holding zero: the read side walks
+        // the ladder comparing view depth against these, and a zero would read as a cascade that
+        // ends at the camera.
+        for (let lane = cascade_count; lane < 4; lane++) {
+            this.#sun_shadow_cascade_far[lane] = far;
+            this.#sun_shadow_step_ws[lane] = this.#sun_shadow_step_ws[cascade_count - 1];
+        }
+
+        this.#sun_shadow_resolution = resolution;
+
+        return 0;
+    }
+
+    /**
+     * @param {GPUViewContext} view
+     */
+    #update_metadata(view) {
+        const camera = view.camera;
+
+        const resolution = this.#volumetrics_textures[0].size;
+        // the grid as allocated, so the curve always spans the slices the textures actually have
+        const resolution_z = resolution[2];
+
+        this.#sun_shadow_light_index = this.#update_sun_shadow(view);
+
+        const volumetrics_cluster_parameters = new Float32Array(3);
+
+        // The depth-curve `scale` must grow with the slice count. The hard-coded 4.06 was tuned for
+        // the light-cluster grid (24 slices); reusing it with 64 froxel slices collapses the log
+        // curve so ~half the slices bunch into the first fraction of a unit of depth, leaving almost
+        // none for the actual scene. Derive scale for a log-uniform distribution over
+        // [near + near_offset, far] instead (gives O ~= 0, i.e. depth ~ offset * (far/offset)^(s/(N-1))).
+        const NEAR_OFFSET = 0.1;
+        const depth_offset = camera.camera.near + NEAR_OFFSET;
+        const depth_scale = (resolution_z - 1) / Math.log2(camera.camera.far / depth_offset);
+
+        build_light_cluster_parameters(
+            volumetrics_cluster_parameters,
+            0,
+            resolution_z,
+            camera.camera.near,
+            camera.camera.far,
+            NEAR_OFFSET,
+            depth_scale
+        );
+
+        // Froxel-grid curve: same construction but ending at froxel_far (<= camera.far). The grid's
+        // slices pack into [near, froxel_far] for extra near detail; beyond froxel_far the aerial
+        // pass ray-marches the volumes. froxel_far == camera.far -> identical to the LUT curve (no-op).
+        const froxel_far = Math.min(this.#froxel_far, camera.camera.far);
+        const froxel_depth_scale = (resolution_z - 1) / Math.log2(froxel_far / depth_offset);
+        const volumetrics_froxel_cluster_parameters = new Float32Array(3);
+        build_light_cluster_parameters(
+            volumetrics_froxel_cluster_parameters,
+            0,
+            resolution_z,
+            camera.camera.near,
+            froxel_far,
+            NEAR_OFFSET,
+            froxel_depth_scale
+        );
+
+        // Recomputed deterministically, so a steady camera compares bitwise equal and never resets.
+        {
+            const curve = volumetrics_froxel_cluster_parameters;
+            const previous = this.#froxel_curve_previous;
+
+            if (curve[0] !== previous[0] || curve[1] !== previous[1] || curve[2] !== previous[2]) {
+                previous.set(curve);
+                this.#reset_history = true;
+            }
+        }
+
+        // The projection is infinite-far reverse-Z, so the camera frustum's far plane is zeroed and
+        // can't be sliced into froxel slabs. Rebuild a finite far plane at the logical far for the
+        // participating-media coverage test — exactly as the light-cluster assignment does.
+        const clipped_frustum = new Float32Array(24);
+        clipped_frustum.set(camera.camera.frustum);
+        update_frustum_far_plane(clipped_frustum, camera.camera.view_matrix, camera.camera.far);
+
+        this.#metadata.upload({
+            cluster_parameters: volumetrics_cluster_parameters,
+            froxel_cluster_parameters: volumetrics_froxel_cluster_parameters,
+            resolution,
+            frustum: slice_flat_array(clipped_frustum, 0, 4, 6),
+            history_reset: this.#reset_history ? 1 : 0,
+            froxel_far,
+            // multiscatter knobs (GUI-tunable via globals); engine defaults 6 / 0.5
+            ms_octave_count: globalThis.__VOL_MS_OCTAVES ?? 6,
+            ms_extinction_decay: globalThis.__VOL_MS_EXT_DECAY ?? 0.5,
+            // Q-04. The sun's media self-shadowing, out of a 16-step per-froxel march and into one
+            // fetch of the cascades built earlier this frame — see #update_sun_shadow.
+            sun_shadow_ws_to_uvw: this.#sun_shadow_ws_to_uvw,
+            sun_shadow_uvw_to_ws: this.#sun_shadow_uvw_to_ws,
+            sun_shadow_step_ws: this.#sun_shadow_step_ws,
+            sun_shadow_cascade_far: this.#sun_shadow_cascade_far,
+            sun_shadow_light_index: this.#sun_shadow_light_index,
+        }, this.#device.queue);
+    }
+
+    /**
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view what the fog is seen from: its resolution sizes the
+     *   froxel grid, its camera places it, its scene fills it
+     * @param {number} options.light_cluster_data
+     * @param {number} options.light_cluster_lookup
+     * @param {number} options.light_cluster_parameters
+     * @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 {{resolved: number, metadata: number, irradiance: {Y: number, CoCg: number, uniform: number}}}
+     */
+    graph_update({
+                     graph,
+                     view,
+                     light_cluster_data,
+                     light_cluster_lookup,
+                     light_cluster_parameters,
+                     shadowmap_atlas,
+                     shader_switches = ShaderSwitchSet.EMPTY,
+                     brick4,
+                     lpv,
+                 }) {
+
+        assert.defined(view, 'view');
+
+        const lights = view.scene.lights;
+        const camera = view.camera;
+
+        const taa_requested = globalThis.__VOL_TAA_ENABLED;
+        if (taa_requested !== undefined && taa_requested !== this.#taa_enabled) {
+            this.taa_enabled = taa_requested;
+        }
+
+        const froxel_far_requested = globalThis.__VOL_FROXEL_FAR;
+        if (froxel_far_requested !== undefined && froxel_far_requested !== this.#froxel_far) {
+            this.#froxel_far = froxel_far_requested;
+            // the froxel grid's depth curve just changed; the TAA history is on the old curve, reset it
+            this.#reset_history = true;
+        }
+
+        if (view.id !== this.#history_view_id) {
+            this.#history_view_id = view.id;
+            this.#reset_history = true;
+        }
+
+        this.#update_resolution(view);
+        this.#update_metadata(view);
+
+        const gr_metadata = graph_import_buffer(graph, this.#metadata.buffer, "volumetrics metadata");
+
+        const resolution = this.#volumetrics_textures[0].size;
+
+        // World-space irradiance clipmap for particle lighting.
+        // Culled by the frame graph when no lit particles read it.
+        const irradiance = this.#irradiance_clipmap.graph_update({
+            graph,
+            camera,
+            scene_ctx: view.scene,
+            shadowmap_atlas,
+            shader_switches,
+            brick4,
+            lpv,
+        });
+
+        if (view.scene.volumetrics.source.volumes.length === 0) {
+            // No medium: nothing scatters and nothing absorbs, so the fog is the identity everywhere
+            // and the passes that would integrate it to that are not recorded. Nothing accumulates
+            // either, which leaves the history stale for whenever a volume arrives.
+            this.#reset_history = true;
+
+            return {
+                resolved: graph_import_texture(graph, this.#no_medium, "volumetrics no medium"),
+                metadata: gr_metadata,
+                irradiance,
+            };
+        }
+
+        let taa_history;
+        let taa_output;
+
+        if (this.#taa_enabled) {
+            const parity = view.frame_index & 1;
+            taa_history = graph_import_texture(graph, this.#volumetrics_textures[parity ^ 1], "volumetrics taa history");
+            taa_output = graph_import_texture(graph, this.#volumetrics_textures[parity], "volumetrics taa output");
+        }
+
+        const sky = view.scene.sky;
+
+        sky.update();
+
+        const { lut_aerial } = graph_build_volumetrics({
+            graph,
+            camera,
+            lights,
+            view,
+            sky,
+            light_cluster_data,
+            light_cluster_lookup,
+            light_cluster_parameters,
+            shadowmap_atlas,
+
+            volumetrics_metadata: gr_metadata,
+            volumetric_resolution: resolution,
+            sun_shadow_resolution: this.#sun_shadow_resolution,
+
+            taa_history,
+            taa_output,
+            camera_previous: view.gpu_previous_camera_state,
+            shader_switches,
+        });
+
+        this.#reset_history = false;
+
+        return {
+            resolved: lut_aerial,
+            metadata: gr_metadata,
+            irradiance,
+        };
+    }
+
+}