@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -1,578 +1,592 @@
-
-
-import { assert } from "../../../core/assert.js";
-import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.js";
-import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
-import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
-import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
-import { DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR } from "../texture/DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR.js";
-import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
-import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
-import { shader_multiscatter_lut } from "../atmosphere/shader_multiscatter_lut.js";
-import { shader_transmittance_lut } from "../atmosphere/shader_transmittance_lut.js";
-import { shader_volumetrics_build_lighting } from "./shader_volumetrics_build_lighting.js";
-import { shader_volumetrics_build_participating_media } from "./shader_volumetrics_build_participating_media.js";
-import { shader_volumetrics_build_scattering_lut } from "./shader_volumetrics_build_scattering_lut.js";
-import { shader_volumetrics_build_sun_shadow_volume } from "./shader_volumetrics_build_sun_shadow_volume.js";
-import {
-    VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT,
-    VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION
-} from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
-import { volumetrics_sun_shadow_texture_name } from "./chunk_volumetrics_sun_optical_depth.js";
-import { shader_volumetrics_taa } from "./taa/shader_volumetrics_taa.js";
-
-/**
- *
- * @param {FrameGraph} graph
- */
-function graph_integrate_sky({ graph }) {
-    const t_data = {};
-
-    const t_pass = graph.add("transmittance", t_data, (data, resources, context) => {
-
-        const output = resources.get(data.output);
-
-        const encoder = context.encoder;
-
-        const settings_type = shader_transmittance_lut.descriptor.resources.getResourceByName("settings").buffer_type;
-
-        const settings = encoder.allocateTransientValueBuffer(settings_type, {
-            steps: 40
-        });
-
-        shader_transmittance_lut.draw({
-            encoder: encoder,
-            bindings: {
-                settings
-            },
-            colorAttachments: [{
-                view: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                loadOp: "clear",
-                storeOp: "store",
-            }]
-        })
-    });
-
-    t_data.output = t_pass.create("transmittance lut", TextureResourceDescriptor.from({
-        resolution: [256, 64],
-        format: "rgba16float",
-        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
-    }));
-
-    const m_data = {};
-
-    const m_pass = graph.add("multiscatter lut", m_data, (data, resources, context) => {
-        const output = resources.get(data.output);
-
-        const settings_type = shader_multiscatter_lut.descriptor.resources.getResourceByName("settings").buffer_type;
-
-        const encoder = context.encoder;
-
-        const settings = encoder.allocateTransientValueBuffer(settings_type, {
-            steps: 20,
-            sqrt_samples: 8,
-        });
-
-        const tSkyLutTransmittance = resources.get(data.tSkyLutTransmittance);
-
-        shader_multiscatter_lut.draw({
-            encoder: encoder,
-            bindings: {
-                settings,
-                tSkyLutTransmittance
-            },
-            colorAttachments: [{
-                view: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                loadOp: "clear",
-                storeOp: "store",
-            }]
-        })
-    });
-
-    m_data.output = m_pass.create("multiscatter lut", TextureResourceDescriptor.from({
-        resolution: [32, 32],
-        format: "rgba16float",
-        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
-    }))
-
-    m_data.tSkyLutTransmittance = m_pass.read(t_data.output);
-
-
-    return { transmittance_lut: t_data.output, multiscatted_lut: m_data.output };
-}
-
-
-/**
- *
- * @param {FrameGraph} graph
- * @param {GPUCameraContext} camera
- * @param {GPUSceneContext} scene
- * @param {GPUViewContext} view
- * @param {number} volumetrics_metadata
- * @param {number[]} resolution output resolution
- */
-function graph_integrate_participating_media({
-                                                 graph,
-                                                 camera,
-                                                 scene,
-                                                 view,
-                                                 volumetrics_metadata,
-                                                 resolution,
-                                             }) {
-
-    const data = {};
-
-
-    const pass = graph.add(
-        "aerial lut",
-        data,
-        /**
-         *
-         * @param {} data
-         * @param {FramePassResources} resources
-         * @param {GraphicsExecutionContext} context
-         */
-        (data, resources, context) => {
-
-            /**
-             * @type {GPUTextureContext}
-             */
-            const output0 = resources.get(data.output0);
-            /**
-             * @type {GPUTextureContext}
-             */
-            const output1 = resources.get(data.output1);
-
-            const encoder = context.encoder;
-
-            const volumetrics_metadata = resources.get(data.volumetrics_metadata);
-
-            shader_volumetrics_build_participating_media.dispatch({
-                encoder,
-                group_count_x: Math.ceil(output0.width / 16),
-                group_count_y: Math.ceil(output0.height / 16),
-                group_count_z: output0.depth,
-                bindings: {
-                    camera: camera.buffer.buffer,
-                    view: view.uniform_buffer.buffer,
-                    volumetrics_metadata,
-                    scene_volumetrics_metadata: scene.volumetrics.metadata_buffer.buffer,
-                    scene_volumes: scene.volumetrics.table.buffer,
-                    tOutput0: output0.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                    tOutput1: output1.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                }
-            });
-
-
-        });
-
-    data.volumetrics_metadata = pass.read(volumetrics_metadata);
-
-    data.output0 = pass.create("Participating Media 0", TextureResourceDescriptor.from({
-        resolution,
-        dimension: "3d",
-        format: "rgba16float",
-        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
-    }));
-    data.output1 = pass.create("Participating Media 1", TextureResourceDescriptor.from({
-        resolution,
-        dimension: "3d",
-        format: "rgba16float",
-        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
-    }));
-
-    return {
-        participating_media0: data.output0,
-        participating_media1: data.output1,
-        volumetrics_metadata: data.volumetrics_metadata,
-    };
-}
-
-/**
- * Q-04. The sun's optical depth, integrated once per frame into cascaded light-aligned volumes so
- * the lighting pass can read it in a single fetch instead of marching toward the sun from every
- * froxel.
- *
- * Sits between the participating-media build and the lighting pass because it reads the former and
- * is read by the latter; the frame graph derives that ordering from the handles alone. The cascades
- * are ordered among themselves for the same reason: each one is seeded from the value the cascade
- * outside it already computed at its entry face, so the outermost is built first and the handle it
- * returns is what makes the next pass wait for it.
- *
- * A texture per cascade rather than one texture with the cascades stacked along w. Stacking would
- * put a pass's own output and its input in the same texture, which WebGPU rejects — a subresource
- * cannot be bound as writable storage and as a sampled texture at once — and there is no
- * subresource finer than the whole 3D texture to split it on.
- *
- * Always present, even with the mode off — the volumes are then dispatched at 1x1x1 (see
- * `GPUViewVolumetrics`), which keeps the graph's topology identical on both sides of the A/B. A
- * pass appearing and disappearing would change resource aliasing and pass scheduling along with the
- * thing being measured, and this subsystem has already produced one confident wrong answer from a
- * measurement where the two sides did not pay the same fixed costs.
- *
- * @param {FrameGraph} graph
- * @param {GPUCameraContext} camera
- * @param {number} participating_media1
- * @param {number} volumetrics_metadata
- * @param {number[]} resolution voxel counts of one cascade
- * @returns {number[]} handles of the cascades, innermost first
- */
-function graph_build_sun_shadow_volume({
-                                           graph,
-                                           camera,
-                                           participating_media1,
-                                           volumetrics_metadata,
-                                           resolution,
-                                       }) {
-
-    const camera_buffer = graph_import_buffer(graph, camera.buffer.buffer, "volumetrics sun shadow camera");
-
-    const group_count = [
-        // one invocation per COLUMN along the sun axis, so only x and y are dispatched
-        Math.ceil(resolution[0] / VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION[0]),
-        Math.ceil(resolution[1] / VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION[1]),
-        1,
-    ];
-
-    const cascades = [];
-
-    for (let cascade = VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1; cascade >= 0; cascade--) {
-
-        const bindings = {
-            camera: camera_buffer,
-            volumetrics_metadata,
-            tParticipatingMedia1: participating_media1,
-            tSunShadowVolume: TextureResourceDescriptor.from({
-                resolution,
-                dimension: "3d",
-                format: "rgba16float",
-                usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING
-            }),
-        };
-
-        if (cascade < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1) {
-            bindings.tSunShadowOuter = cascades[cascade + 1];
-        }
-
-        const outputs = graph_compute_pass({
-            graph,
-            shader: shader_volumetrics_build_sun_shadow_volume[cascade],
-            group_count,
-            bindings,
-        });
-
-        cascades[cascade] = outputs.tSunShadowVolume;
-    }
-
-    return cascades;
-}
-
-/**
- *
- * @param {FrameGraph} graph
- * @param participating_media0
- * @param participating_media1
- * @param volumetrics_metadata
- * @param light_cluster_data
- * @param light_cluster_lookup
- * @param light_cluster_parameters
- * @param shadowmap_atlas
- * @param sun_transmittance_lut
- * @param sun_multiple_scattering_lut
- * @param {number[]} sun_shadow_cascades handles of the Q-04 optical-depth cascades, innermost first
- * @param lights
- * @param view
- * @param camera
- * @param resolution
- */
-function graph_integrate_light_scattering({
-                                              graph,
-                                              participating_media0,
-                                              participating_media1,
-                                              volumetrics_metadata,
-                                              light_cluster_data,
-                                              light_cluster_lookup,
-                                              light_cluster_parameters,
-                                              shadowmap_atlas,
-                                              sun_transmittance_lut,
-                                              sun_multiple_scattering_lut,
-                                              sun_shadow_cascades,
-                                              lights,
-                                              view,
-                                              camera,
-                                              resolution,
-                                          }) {
-
-    const data = {};
-
-    const pass = graph.add("scattering lut", data, (data, resources, context) => {
-        const output = resources.get(data.output);
-
-        const volumetrics_metadata = resources.get(data.volumetrics_metadata);
-
-        const participating_media0 = resources.get(data.participating_media0);
-        const participating_media1 = resources.get(data.participating_media1);
-
-        const light_cluster_data = resources.get(data.light_cluster_data);
-        const light_cluster_lookup = resources.get(data.light_cluster_lookup);
-        const light_cluster_parameters = resources.get(data.light_cluster_parameters);
-        const shadowmap_atlas = resources.get(data.shadowmap_atlas);
-
-        const sun_transmittance_lut = resources.get(data.sun_transmittance_lut);
-        const sun_multiple_scattering_lut = resources.get(data.sun_multiple_scattering_lut);
-        const sun_shadow_cascades = data.sun_shadow_cascades.map(handle => resources.get(handle));
-
-        const sampler_shadowmap = context.graphics.samplers.obtain(SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR);
-        const sLinear = context.graphics.samplers.obtain(SamplerDescriptor.from({
-            magFilter: "linear",
-        }));
-
-        // Spatiotemporal blue noise for the per-froxel sample offset. The pass takes one sample and
-        // leans on the volumetric TAA to integrate, which only works if each froxel's sequence over
-        // frames is well distributed — the property a per-froxel hash does not have.
-        const tSTBN_vec3 = context.graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
-
-        const encoder = context.encoder;
-
-        shader_volumetrics_build_lighting.dispatch({
-            encoder,
-            group_count_x: Math.ceil(output.width / 16),
-            group_count_y: Math.ceil(output.height / 16),
-            group_count_z: output.depth,
-            bindings: {
-                camera: camera.buffer.buffer,
-                view: view.uniform_buffer.buffer,
-                volumetrics_metadata,
-                sLinear,
-                tSunTransmittance: sun_transmittance_lut.obtainView(),
-                tMultiScattering: sun_multiple_scattering_lut.obtainView(),
-                tSTBN_vec3: tSTBN_vec3.obtainView(),
-                tParticipatingMedia0: participating_media0.obtainView(),
-                tParticipatingMedia1: participating_media1.obtainView(),
-                ...Object.fromEntries(sun_shadow_cascades.map(
-                    (texture, cascade) => [volumetrics_sun_shadow_texture_name(cascade), texture.obtainView()]
-                )),
-                tLighting: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                //
-                light_data: lights.buffer_data,
-
-                cluster_data: light_cluster_data,
-                cluster_lookup: light_cluster_lookup,
-                cluster_parameters: light_cluster_parameters,
-
-                shadowmapAtlas: shadowmap_atlas.obtainView(),
-                sCompareLinear: sampler_shadowmap,
-            }
-        })
-    });
-
-    data.participating_media0 = pass.read(participating_media0);
-    data.participating_media1 = pass.read(participating_media1);
-    data.volumetrics_metadata = pass.read(volumetrics_metadata);
-
-    data.shadowmap_atlas = pass.read(shadowmap_atlas);
-    data.light_cluster_data = pass.read(light_cluster_data);
-    data.light_cluster_lookup = pass.read(light_cluster_lookup);
-    data.light_cluster_parameters = pass.read(light_cluster_parameters);
-
-    data.sun_transmittance_lut = pass.read(sun_transmittance_lut);
-    data.sun_multiple_scattering_lut = pass.read(sun_multiple_scattering_lut);
-    data.sun_shadow_cascades = sun_shadow_cascades.map(handle => pass.read(handle));
-
-    data.output = pass.create("Light Scattering LUT", TextureResourceDescriptor.from({
-        resolution,
-        dimension: "3d",
-        format: "rgba16float",
-        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
-    }));
-
-
-    return data.output;
-
-}
-
-/**
- *
- * @param {FrameGraph} graph
- * @param {GPUCameraContext} camera
- * @param {GPULightCollection} lights
- * @param {GPUViewContext} view
- * @param {number} light_cluster_data
- * @param {number} light_cluster_lookup
- * @param {number} light_cluster_parameters
- * @param {number} shadowmap_atlas
- * @param {number[]} volumetric_resolution
- * @param {number[]} sun_shadow_resolution voxel counts of one Q-04 sun optical-depth cascade;
- * `[1, 1, 1]` when the froxels are marching instead, which keeps the passes in the graph without
- * doing any work
- * @param {number} volumetrics_metadata
- * @param {number} [taa_history] imported previous-frame accumulated scattering volume
- * @param {number} [taa_output] imported destination for this frame's accumulated scattering volume
- * @param {GPUCameraContext} [camera_previous] previous-frame camera, for temporal reprojection
- */
-export function graph_build_volumetrics({
-                                            graph,
-                                            camera,
-                                            lights,
-                                            view,
-                                            light_cluster_data,
-                                            light_cluster_lookup,
-                                            light_cluster_parameters,
-                                            shadowmap_atlas,
-                                            volumetric_resolution,
-                                            sun_shadow_resolution,
-                                            volumetrics_metadata,
-                                            taa_history,
-                                            taa_output,
-                                            camera_previous,
-                                        }) {
-
-    assert.defined(view, 'view');
-    assert.defined(volumetric_resolution, 'volumetric_resolution');
-    assert.defined(sun_shadow_resolution, 'sun_shadow_resolution');
-
-    const { transmittance_lut, multiscatted_lut } = graph_integrate_sky({ graph: graph });
-
-    const {
-        participating_media0,
-        participating_media1,
-    } = graph_integrate_participating_media({
-        graph,
-        scene: view.scene,
-        view,
-        resolution: volumetric_resolution,
-        volumetrics_metadata,
-        camera,
-    });
-
-    const sun_shadow_cascades = graph_build_sun_shadow_volume({
-        graph,
-        camera,
-        participating_media1,
-        volumetrics_metadata,
-        resolution: sun_shadow_resolution,
-    });
-
-    const light_scattering_lut = graph_integrate_light_scattering({
-        graph,
-        resolution: volumetric_resolution,
-        camera,
-        view,
-        sun_transmittance_lut: transmittance_lut,
-        sun_multiple_scattering_lut: multiscatted_lut,
-        sun_shadow_cascades,
-        participating_media0,
-        participating_media1,
-        volumetrics_metadata,
-        light_cluster_data,
-        light_cluster_lookup,
-        light_cluster_parameters,
-        shadowmap_atlas,
-        lights,
-    })
-
-    // Temporal reprojection of the per-froxel lit scattering volume, applied BEFORE aerial
-    // integration — reprojecting the already-integrated aerial LUT would double-integrate along the
-    // view ray. Optional: skipped when no history ping-pong is supplied (TAA disabled), in which
-    // case the aerial pass consumes the raw (noisier) scattering LUT directly.
-    let volume_lighting_resolved = light_scattering_lut;
-
-    if (taa_history !== undefined && taa_output !== undefined) {
-        const taa_outputs = graph_compute_pass({
-            graph,
-            shader: shader_volumetrics_taa,
-            group_count: [
-                Math.ceil(volumetric_resolution[0] / 8),
-                Math.ceil(volumetric_resolution[1] / 8),
-                Math.ceil(volumetric_resolution[2] / 4),
-            ],
-            bindings: {
-                t_current: light_scattering_lut,
-                t_history: taa_history,
-                t_output: taa_output,
-                volumetrics_metadata,
-                camera_current: graph_import_buffer(graph, camera.buffer.buffer, "volumetrics taa camera"),
-                camera_previous: graph_import_buffer(graph, camera_previous.buffer.buffer, "volumetrics taa camera previous"),
-            },
-        });
-
-        volume_lighting_resolved = taa_outputs.t_output;
-    }
-
-    const a_data = {};
-
-    const a_pass = graph.add("aerial lut", a_data, (data, resources, context) => {
-        const output = resources.get(data.output);
-
-        const participating_media0 = resources.get(data.participating_media0);
-        const participating_media1 = resources.get(data.participating_media1);
-        const volumetrics_metadata = resources.get(data.volumetrics_metadata);
-
-        const light_scattering_lut = resources.get(data.light_scattering_lut);
-        const sun_transmittance_lut = resources.get(data.sun_transmittance_lut);
-
-        const encoder = context.encoder;
-
-
-        const graphics = context.graphics;
-        const device = graphics.device;
-
-        const sLinear = graphics.samplers.obtain(SamplerDescriptor.from({
-            magFilter: "linear",
-        }));
-
-        const tSTBN_vec3 = graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
-
-        shader_volumetrics_build_scattering_lut.dispatch({
-            encoder,
-            group_count_x: Math.ceil(output.width / 16),
-            group_count_y: Math.ceil(output.height / 16),
-            bindings: {
-                camera: camera.buffer.buffer,
-                view: view.uniform_buffer.buffer,
-                volumetrics_metadata,
-                tSTBN_vec3: tSTBN_vec3.obtainView(),
-                sLinear,
-
-                tVolumeLighting: light_scattering_lut.obtainView(),
-                tParticipatingMedia0: participating_media0.obtainView(),
-                tParticipatingMedia1: participating_media1.obtainView(),
-
-                // RDR2-style far-field march inputs (used beyond froxel_far)
-                scene_volumetrics_metadata: view.scene.volumetrics.metadata_buffer.buffer,
-                scene_volumes: view.scene.volumetrics.table.buffer,
-                light_data: lights.buffer_data,
-                tSunTransmittance: sun_transmittance_lut.obtainView(),
-
-                tOutput: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-            }
-        });
-
-
-    });
-
-    a_data.participating_media0 = a_pass.read(participating_media0);
-    a_data.participating_media1 = a_pass.read(participating_media1);
-    a_data.volumetrics_metadata = a_pass.read(volumetrics_metadata);
-    a_data.sun_transmittance_lut = a_pass.read(transmittance_lut);
-
-    a_data.output = a_pass.create("Integrated Volumetrics", TextureResourceDescriptor.from({
-        resolution: volumetric_resolution,
-        dimension: "3d",
-        format: "rgba16float",
-        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING
-    }))
-
-
-    a_data.light_scattering_lut = a_pass.read(volume_lighting_resolved);
-
-
-    // TODO add temporal reprojection
-
-    return {
-        lut_transmittance: transmittance_lut,
-        lut_multiple_scattering: multiscatted_lut,
-        lut_aerial: a_data.output,
-        volumetrics_metadata,
-    };
+import { assert } from "../../../core/assert.js";
+import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.js";
+import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
+import { shader_multiscatter_lut } from "../atmosphere/shader_multiscatter_lut.js";
+import { shader_transmittance_lut } from "../atmosphere/shader_transmittance_lut.js";
+import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
+import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
+import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
+import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
+import { DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR } from "../texture/DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR.js";
+import { volumetrics_sun_shadow_texture_name } from "./chunk_volumetrics_sun_optical_depth.js";
+import { shader_volumetrics_build_lighting } from "./shader_volumetrics_build_lighting.js";
+import { shader_volumetrics_build_participating_media } from "./shader_volumetrics_build_participating_media.js";
+import { shader_volumetrics_build_scattering_lut } from "./shader_volumetrics_build_scattering_lut.js";
+import {
+    shader_volumetrics_build_sun_shadow_volume_outermost,
+    shader_volumetrics_build_sun_shadow_volume_seeded
+} from "./shader_volumetrics_build_sun_shadow_volume.js";
+import { shader_volumetrics_taa } from "./taa/shader_volumetrics_taa.js";
+import {
+    VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT,
+    VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION,
+    volumetrics_sun_shadow_sub_steps
+} from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
+
+/**
+ * Transmittance LUT, then the multiple-scattering LUT that reads it. Exported for
+ * `graph_integrate_sky.spec.js`, which pins the dispatch shape and the transient's usage
+ * flags -- neither of which the WGSL validity gate can see.
+ *
+ * @param {FrameGraph} graph
+ * @returns {{transmittance_lut: number, multiscatted_lut: number}} resource handles
+ */
+export function graph_integrate_sky({ graph }) {
+
+    graph.push_scope("integrate sky");
+
+    const t_data = {};
+
+    const t_pass = graph.add("transmittance", t_data, (data, resources, context) => {
+
+        const output = resources.get(data.output);
+
+        const encoder = context.encoder;
+
+        const settings_type = shader_transmittance_lut.descriptor.resources.getResourceByName("settings").buffer_type;
+
+        const settings = encoder.allocateTransientValueBuffer(settings_type, {
+            steps: 40,
+            // taken off the target being drawn into, so the generator cannot be told a size
+            // the texture does not have
+            resolution: [output.width, output.height],
+        });
+
+        shader_transmittance_lut.draw({
+            encoder: encoder,
+            bindings: {
+                settings
+            },
+            colorAttachments: [{
+                view: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+                loadOp: "clear",
+                storeOp: "store",
+            }]
+        })
+    });
+
+    t_data.output = t_pass.create("transmittance lut", TextureResourceDescriptor.from({
+        resolution: [256, 64],
+        format: "rgba16float",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
+    }));
+
+    // The transient does not exist yet at graph-build time, so the dispatch cannot be
+    // counted off it the way GPUSky does; one local value feeds both instead.
+    const multiscatter_resolution = [32, 32];
+
+    const multiscatter_outputs = graph_compute_pass({
+        graph,
+        shader: shader_multiscatter_lut,
+        // one workgroup per LUT texel, each thread integrating one direction
+        group_count: [multiscatter_resolution[0], multiscatter_resolution[1], 1],
+        bindings: {
+            tSkyLutTransmittance: t_data.output,
+            tSkyLutMultiscatterOut: TextureResourceDescriptor.from({
+                resolution: multiscatter_resolution,
+                format: "rgba16float",
+                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING
+            })
+        }
+    });
+
+    graph.pop_scope();
+
+    return { transmittance_lut: t_data.output, multiscatted_lut: multiscatter_outputs.tSkyLutMultiscatterOut };
+}
+
+
+/**
+ *
+ * @param {FrameGraph} graph
+ * @param {GPUCameraContext} camera
+ * @param {GPUSceneContext} scene
+ * @param {GPUViewContext} view
+ * @param {number} volumetrics_metadata
+ * @param {number[]} resolution output resolution
+ */
+function graph_integrate_participating_media({
+                                                 graph,
+                                                 camera,
+                                                 scene,
+                                                 view,
+                                                 volumetrics_metadata,
+                                                 resolution,
+                                             }) {
+
+    const data = {};
+
+
+    const pass = graph.add(
+        "aerial lut",
+        data,
+        /**
+         *
+         * @param {} data
+         * @param {FramePassResources} resources
+         * @param {GraphicsExecutionContext} context
+         */
+        (data, resources, context) => {
+
+            /**
+             * @type {GPUTextureContext}
+             */
+            const output0 = resources.get(data.output0);
+            /**
+             * @type {GPUTextureContext}
+             */
+            const output1 = resources.get(data.output1);
+
+            const encoder = context.encoder;
+
+            const volumetrics_metadata = resources.get(data.volumetrics_metadata);
+
+            shader_volumetrics_build_participating_media.dispatchThreads({
+                encoder,
+                thread_count_x: output0.width,
+                thread_count_y: output0.height,
+                thread_count_z: output0.depth,
+                bindings: {
+                    camera: camera.buffer.buffer,
+                    view: view.uniform_buffer.buffer,
+                    volumetrics_metadata,
+                    scene_volumetrics_metadata: scene.volumetrics.metadata_buffer.buffer,
+                    scene_volumes: scene.volumetrics.table.buffer,
+                    tOutput0: output0.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+                    tOutput1: output1.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+                }
+            });
+
+
+        });
+
+    data.volumetrics_metadata = pass.read(volumetrics_metadata);
+
+    data.output0 = pass.create("Participating Media 0", TextureResourceDescriptor.from({
+        resolution,
+        dimension: "3d",
+        format: "rgba16float",
+        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
+    }));
+    data.output1 = pass.create("Participating Media 1", TextureResourceDescriptor.from({
+        resolution,
+        dimension: "3d",
+        format: "rgba16float",
+        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
+    }));
+
+    return {
+        participating_media0: data.output0,
+        participating_media1: data.output1,
+        volumetrics_metadata: data.volumetrics_metadata,
+    };
+}
+
+/**
+ * Q-04. The sun's optical depth, integrated once per frame into cascaded light-aligned volumes so
+ * the lighting pass can read it in a single fetch instead of marching toward the sun from every
+ * froxel.
+ *
+ * Sits between the participating-media build and the lighting pass because it reads the former and
+ * is read by the latter; the frame graph derives that ordering from the handles alone. The cascades
+ * are ordered among themselves for the same reason: each one is seeded from the value the cascade
+ * outside it already computed at its entry face, so the outermost is built first and the handle it
+ * returns is what makes the next pass wait for it.
+ *
+ * A texture per cascade rather than one texture with the cascades stacked along w. Stacking would
+ * put a pass's own output and its input in the same texture, which WebGPU rejects — a subresource
+ * cannot be bound as writable storage and as a sampled texture at once — and there is no
+ * subresource finer than the whole 3D texture to split it on.
+ *
+ * Always present, even with the mode off — the volumes are then dispatched at 1x1x1 (see
+ * `GPUViewVolumetrics`), which keeps the graph's topology identical on both sides of the A/B. A
+ * pass appearing and disappearing would change resource aliasing and pass scheduling along with the
+ * thing being measured, and this subsystem has already produced one confident wrong answer from a
+ * measurement where the two sides did not pay the same fixed costs.
+ *
+ * @param {FrameGraph} graph
+ * @param {GPUCameraContext} camera
+ * @param {number} participating_media1
+ * @param {number} volumetrics_metadata
+ * @param {number[]} resolution voxel counts of one cascade
+ * @returns {number[]} handles of the cascades, innermost first
+ */
+function graph_build_sun_shadow_volume({
+                                           graph,
+                                           camera,
+                                           participating_media1,
+                                           volumetrics_metadata,
+                                           resolution,
+                                       }) {
+
+    const camera_buffer = graph_import_buffer(graph, camera.buffer.buffer, "volumetrics sun shadow camera");
+
+    const group_count = [
+        // one invocation per COLUMN along the sun axis, so only x and y are dispatched
+        Math.ceil(resolution[0] / VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION[0]),
+        Math.ceil(resolution[1] / VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION[1]),
+        1,
+    ];
+
+    const cascades = [];
+
+    for (let cascade = VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1; cascade >= 0; cascade--) {
+
+        // Every cascade but the outermost starts its scan from the one outside it — which the
+        // descending loop has already added, and which is the one difference the two build shaders
+        // exist for.
+        const seeded = cascade < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1;
+
+        const bindings = {
+            // which cascade this dispatch is building; the shader is shared across all of them
+            settings: {
+                cascade,
+                sub_steps: volumetrics_sun_shadow_sub_steps(cascade),
+            },
+            camera: camera_buffer,
+            volumetrics_metadata,
+            tParticipatingMedia1: participating_media1,
+            tSunShadowVolume: TextureResourceDescriptor.from({
+                resolution,
+                dimension: "3d",
+                format: "rgba16float",
+                usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING
+            }),
+        };
+
+        if (seeded) {
+            bindings.tSunShadowOuter = cascades[cascade + 1];
+        }
+
+        const outputs = graph_compute_pass({
+            graph,
+            shader: seeded
+                ? shader_volumetrics_build_sun_shadow_volume_seeded
+                : shader_volumetrics_build_sun_shadow_volume_outermost,
+            group_count,
+            bindings,
+        });
+
+        cascades[cascade] = outputs.tSunShadowVolume;
+    }
+
+    return cascades;
+}
+
+/**
+ *
+ * @param {FrameGraph} graph
+ * @param participating_media0
+ * @param participating_media1
+ * @param volumetrics_metadata
+ * @param light_cluster_data
+ * @param light_cluster_lookup
+ * @param light_cluster_parameters
+ * @param shadowmap_atlas
+ * @param sun_transmittance_lut
+ * @param sun_multiple_scattering_lut
+ * @param {number[]} sun_shadow_cascades handles of the Q-04 optical-depth cascades, innermost first
+ * @param lights
+ * @param view
+ * @param camera
+ * @param resolution
+ */
+function graph_integrate_light_scattering({
+                                              graph,
+                                              participating_media0,
+                                              participating_media1,
+                                              volumetrics_metadata,
+                                              light_cluster_data,
+                                              light_cluster_lookup,
+                                              light_cluster_parameters,
+                                              shadowmap_atlas,
+                                              sun_transmittance_lut,
+                                              sun_multiple_scattering_lut,
+                                              sun_shadow_cascades,
+                                              lights,
+                                              view,
+                                              camera,
+                                              resolution,
+                                          }) {
+
+    const data = {};
+
+    const pass = graph.add("scattering lut", data, (data, resources, context) => {
+        const output = resources.get(data.output);
+
+        const volumetrics_metadata = resources.get(data.volumetrics_metadata);
+
+        const participating_media0 = resources.get(data.participating_media0);
+        const participating_media1 = resources.get(data.participating_media1);
+
+        const light_cluster_data = resources.get(data.light_cluster_data);
+        const light_cluster_lookup = resources.get(data.light_cluster_lookup);
+        const light_cluster_parameters = resources.get(data.light_cluster_parameters);
+        const shadowmap_atlas = resources.get(data.shadowmap_atlas);
+
+        const sun_transmittance_lut = resources.get(data.sun_transmittance_lut);
+        const sun_multiple_scattering_lut = resources.get(data.sun_multiple_scattering_lut);
+        const sun_shadow_cascades = data.sun_shadow_cascades.map(handle => resources.get(handle));
+
+        const sampler_shadowmap = context.graphics.samplers.obtain(SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR);
+        const sLinear = context.graphics.samplers.obtain(SamplerDescriptor.from({
+            magFilter: "linear",
+        }));
+
+        // Spatiotemporal blue noise for the per-froxel sample offset. The pass takes one sample and
+        // leans on the volumetric TAA to integrate, which only works if each froxel's sequence over
+        // frames is well distributed — the property a per-froxel hash does not have.
+        const tSTBN_vec3 = context.graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
+
+        const encoder = context.encoder;
+
+        const bindings = {
+            camera: camera.buffer.buffer,
+            view: view.uniform_buffer.buffer,
+            volumetrics_metadata,
+            sLinear,
+            tSunTransmittance: sun_transmittance_lut.obtainView(),
+            tMultiScattering: sun_multiple_scattering_lut.obtainView(),
+            tSTBN_vec3: tSTBN_vec3.obtainView(),
+            tParticipatingMedia0: participating_media0.obtainView(),
+            tParticipatingMedia1: participating_media1.obtainView(),
+            tLighting: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+            //
+            light_data: lights.buffer_data,
+
+            cluster_data: light_cluster_data,
+            cluster_lookup: light_cluster_lookup,
+            cluster_parameters: light_cluster_parameters,
+
+            shadowmapAtlas: shadowmap_atlas.obtainView(),
+            sCompareLinear: sampler_shadowmap,
+        };
+
+        // One texture per cascade, under the names the read side declares. Bound here rather than
+        // above because the count is a constant of the structure, not of this pass.
+        for (let cascade = 0; cascade < sun_shadow_cascades.length; cascade++) {
+            bindings[volumetrics_sun_shadow_texture_name(cascade)] = sun_shadow_cascades[cascade].obtainView();
+        }
+
+        shader_volumetrics_build_lighting.dispatchThreads({
+            encoder,
+            thread_count_x: output.width,
+            thread_count_y: output.height,
+            thread_count_z: output.depth,
+            bindings
+        })
+    });
+
+    data.participating_media0 = pass.read(participating_media0);
+    data.participating_media1 = pass.read(participating_media1);
+    data.volumetrics_metadata = pass.read(volumetrics_metadata);
+
+    data.shadowmap_atlas = pass.read(shadowmap_atlas);
+    data.light_cluster_data = pass.read(light_cluster_data);
+    data.light_cluster_lookup = pass.read(light_cluster_lookup);
+    data.light_cluster_parameters = pass.read(light_cluster_parameters);
+
+    data.sun_transmittance_lut = pass.read(sun_transmittance_lut);
+    data.sun_multiple_scattering_lut = pass.read(sun_multiple_scattering_lut);
+    data.sun_shadow_cascades = sun_shadow_cascades.map(handle => pass.read(handle));
+
+    data.output = pass.create("Light Scattering LUT", TextureResourceDescriptor.from({
+        resolution,
+        dimension: "3d",
+        format: "rgba16float",
+        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
+    }));
+
+
+    return data.output;
+
+}
+
+/**
+ *
+ * @param {FrameGraph} graph
+ * @param {GPUCameraContext} camera
+ * @param {GPULightCollection} lights
+ * @param {GPUViewContext} view
+ * @param {number} light_cluster_data
+ * @param {number} light_cluster_lookup
+ * @param {number} light_cluster_parameters
+ * @param {number} shadowmap_atlas
+ * @param {number[]} volumetric_resolution
+ * @param {number[]} sun_shadow_resolution voxel counts of one Q-04 sun optical-depth cascade;
+ * `[1, 1, 1]` when the froxels are marching instead, which keeps the passes in the graph without
+ * doing any work
+ * @param {number} volumetrics_metadata
+ * @param {number} [taa_history] imported previous-frame accumulated scattering volume
+ * @param {number} [taa_output] imported destination for this frame's accumulated scattering volume
+ * @param {GPUCameraContext} [camera_previous] previous-frame camera, for temporal reprojection
+ */
+export function graph_build_volumetrics({
+                                            graph,
+                                            camera,
+                                            lights,
+                                            view,
+                                            light_cluster_data,
+                                            light_cluster_lookup,
+                                            light_cluster_parameters,
+                                            shadowmap_atlas,
+                                            volumetric_resolution,
+                                            sun_shadow_resolution,
+                                            volumetrics_metadata,
+                                            taa_history,
+                                            taa_output,
+                                            camera_previous,
+                                        }) {
+
+    assert.defined(view, 'view');
+    assert.defined(volumetric_resolution, 'volumetric_resolution');
+    assert.defined(sun_shadow_resolution, 'sun_shadow_resolution');
+
+    graph.push_scope("build volumetrics");
+
+    const { transmittance_lut, multiscatted_lut } = graph_integrate_sky({ graph: graph });
+
+    const {
+        participating_media0,
+        participating_media1,
+    } = graph_integrate_participating_media({
+        graph,
+        scene: view.scene,
+        view,
+        resolution: volumetric_resolution,
+        volumetrics_metadata,
+        camera,
+    });
+
+    const sun_shadow_cascades = graph_build_sun_shadow_volume({
+        graph,
+        camera,
+        participating_media1,
+        volumetrics_metadata,
+        resolution: sun_shadow_resolution,
+    });
+
+    const light_scattering_lut = graph_integrate_light_scattering({
+        graph,
+        resolution: volumetric_resolution,
+        camera,
+        view,
+        sun_transmittance_lut: transmittance_lut,
+        sun_multiple_scattering_lut: multiscatted_lut,
+        sun_shadow_cascades,
+        participating_media0,
+        participating_media1,
+        volumetrics_metadata,
+        light_cluster_data,
+        light_cluster_lookup,
+        light_cluster_parameters,
+        shadowmap_atlas,
+        lights,
+    })
+
+    // Temporal reprojection of the per-froxel lit scattering volume, applied BEFORE aerial
+    // integration — reprojecting the already-integrated aerial LUT would double-integrate along the
+    // view ray. Optional: skipped when no history ping-pong is supplied (TAA disabled), in which
+    // case the aerial pass consumes the raw (noisier) scattering LUT directly.
+    let volume_lighting_resolved = light_scattering_lut;
+
+    if (taa_history !== undefined && taa_output !== undefined) {
+        const taa_outputs = graph_compute_pass({
+            graph,
+            shader: shader_volumetrics_taa,
+            group_count: [
+                Math.ceil(volumetric_resolution[0] / 8),
+                Math.ceil(volumetric_resolution[1] / 8),
+                Math.ceil(volumetric_resolution[2] / 4),
+            ],
+            bindings: {
+                t_current: light_scattering_lut,
+                t_history: taa_history,
+                t_output: taa_output,
+                volumetrics_metadata,
+                camera_current: graph_import_buffer(graph, camera.buffer.buffer, "volumetrics taa camera"),
+                camera_previous: graph_import_buffer(graph, camera_previous.buffer.buffer, "volumetrics taa camera previous"),
+            },
+        });
+
+        volume_lighting_resolved = taa_outputs.t_output;
+    }
+
+    const a_data = {};
+
+    const a_pass = graph.add("aerial lut", a_data, (data, resources, context) => {
+        const output = resources.get(data.output);
+
+        const participating_media0 = resources.get(data.participating_media0);
+        const participating_media1 = resources.get(data.participating_media1);
+        const volumetrics_metadata = resources.get(data.volumetrics_metadata);
+
+        const light_scattering_lut = resources.get(data.light_scattering_lut);
+        const sun_transmittance_lut = resources.get(data.sun_transmittance_lut);
+
+        const encoder = context.encoder;
+
+
+        const graphics = context.graphics;
+
+        const sLinear = graphics.samplers.obtain(SamplerDescriptor.from({
+            magFilter: "linear",
+        }));
+
+        const tSTBN_vec3 = graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
+
+        shader_volumetrics_build_scattering_lut.dispatchThreads({
+            encoder,
+            thread_count_x: output.width,
+            thread_count_y: output.height,
+            bindings: {
+                camera: camera.buffer.buffer,
+                view: view.uniform_buffer.buffer,
+                volumetrics_metadata,
+                tSTBN_vec3: tSTBN_vec3.obtainView(),
+                sLinear,
+
+                tVolumeLighting: light_scattering_lut.obtainView(),
+                tParticipatingMedia0: participating_media0.obtainView(),
+                tParticipatingMedia1: participating_media1.obtainView(),
+
+                // RDR2-style far-field march inputs (used beyond froxel_far)
+                scene_volumetrics_metadata: view.scene.volumetrics.metadata_buffer.buffer,
+                scene_volumes: view.scene.volumetrics.table.buffer,
+                light_data: lights.buffer_data,
+                tSunTransmittance: sun_transmittance_lut.obtainView(),
+
+                tOutput: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+            }
+        });
+
+
+    });
+
+    a_data.participating_media0 = a_pass.read(participating_media0);
+    a_data.participating_media1 = a_pass.read(participating_media1);
+    a_data.volumetrics_metadata = a_pass.read(volumetrics_metadata);
+    a_data.sun_transmittance_lut = a_pass.read(transmittance_lut);
+
+    a_data.output = a_pass.create("Integrated Volumetrics", TextureResourceDescriptor.from({
+        resolution: volumetric_resolution,
+        dimension: "3d",
+        format: "rgba16float",
+        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING
+    }))
+
+
+    a_data.light_scattering_lut = a_pass.read(volume_lighting_resolved);
+
+
+    // TODO add temporal reprojection
+
+    graph.pop_scope();
+
+    return {
+        lut_transmittance: transmittance_lut,
+        lut_multiple_scattering: multiscatted_lut,
+        lut_aerial: a_data.output,
+        volumetrics_metadata,
+    };
 }