@woosh/meep-engine 3.34.0 → 3.36.0

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

@@ -1,436 +1,488 @@
-import { vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
-import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_rgb_to_luminance } from "../shader/chunk/color/chunk_rgb_to_luminance.js";
-import { chunk_stbn_sample_vec3 } from "../shader/chunk/noise/chunk_stbn_sample_vec3.js";
-import { chunk_camera_ray_from_uv } from "../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.js";
-import { RAY_STRUCT } from "../shader/chunk/geometry/ray/RAY_STRUCT.js";
-import {
-    chunk_directional_lights_iteration_mask
-} from "../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
-import {
-    chunk_get_directional_light_info_by_index
-} from "../shader/chunk/light/io/chunk_get_directional_light_info_by_index.js";
-import {
-    chunk_get_point_light_info_by_index
-} from "../shader/chunk/light/io/chunk_get_point_light_info_by_index.js";
-import { chunk_get_spot_light_info_by_index } from "../shader/chunk/light/io/chunk_get_spot_light_info_by_index.js";
-import { chunk_texel_coordinate_to_uv } from "../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
-import { chunk_uv_to_texel_coordinate } from "../shader/chunk/texture/chunk_uv_to_texel_coordinate.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { chunk_shadowmap_get_light_visibility } from "../shadow/map/shader/chunk_shadowmap_get_light_visibility.js";
-import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
-import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
-import { VIEW_UNIFORM_STRUCT } from "../view/VIEW_UNIFORM_STRUCT.js";
-import { chunk_cluster_depth_from_z_slice } from "../light/cluster/chunk_cluster_depth_from_z_slice.js";
-import { chunk_cluster_depth_to_z_slice } from "../light/cluster/chunk_cluster_depth_to_z_slice.js";
-import { chunk_light_cluster_counts } from "../light/cluster/chunk_light_cluster_counts.js";
-import { chunk_light_cluster_metadata_by_position } from "../light/cluster/chunk_light_cluster_metadata_by_position.js";
-import { LIGHT_CLUSTER_LOOKUP_STRUCT } from "../light/cluster/shader_cluster_assign_lights.js";
-import { chunk_sky_lut_compute_uv } from "../atmosphere/chunk_sky_lut_compute_uv.js";
-import { chunk_calculate_multiscattering } from "./chunk_calculate_multiscattering.js";
-import { chunk_camera_ray_planar_depth_scale } from "./chunk_camera_ray_planar_depth_scale.js";
-import { chunk_volumetrics_froxel_content_offset } from "./chunk_volumetrics_froxel_content_offset.js";
-import { chunk_integrate_optical_depth } from "./chunk_integrate_optical_depth.js";
-import {
-    chunk_volumetrics_sun_optical_depth,
-    volumetrics_sun_shadow_texture_name
-} from "./chunk_volumetrics_sun_optical_depth.js";
-import { VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
-import { chunk_volumetrics_column_jitter } from "./chunk_volumetrics_column_jitter.js";
-import { chunk_volumetrics_local_light_shadow } from "./chunk_volumetrics_local_light_shadow.js";
-import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
-
-/**
- * Workgroup shape of this pass, `[x, y, z]` in froxels, stated to the `@workgroup_size` below.
- * That attribute is where the dispatch gets the shape from in turn: `graph_build_volumetrics` asks
- * for a thread count and `ComputeShader` divides by the size it read back out of the WGSL.
- *
- * Flat in z. Lights are binned into 3D clusters and the largest distance between neighbouring
- * clusters is along depth, so a group spanning z is the one spanning the most unrelated light
- * lists.
- *
- * 64 invocations — one wave64, two warps — is a deliberate trade: 16x16x1 measures faster on the
- * RTX 4090 this was benchmarked on, and is kept off because that part's register file is unusually
- * large and the result is not expected to generalize (AMD favours smaller groups). NOTES.md carries
- * the numbers and the reasoning.
- *
- * @type {number[]}
- */
-export const VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION = [8, 8, 1];
-
-const resources = new ShaderResourceSetDescriptor();
-
-const primary_group = resources.createGroup()
-    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addUniform("view", VIEW_UNIFORM_STRUCT)
-    .addTexture("tSunTransmittance", "float", "2d")
-    .addTexture("tMultiScattering", "float", "2d")
-    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
-    .addTexture("tSTBN_vec3", "unfilterable-float", "3d")
-    .addTexture("tParticipatingMedia0", "float", "3d")
-    .addTexture("tParticipatingMedia1", "float", "3d");
-
-// Q-04: the sun's optical depth, pre-integrated along the light axis by
-// shader_volumetrics_build_sun_shadow_volume, one cascade per texture and innermost first.
-// Sampled, not marched.
-for (let cascade = 0; cascade < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT; cascade++) {
-    primary_group.addTexture(volumetrics_sun_shadow_texture_name(cascade), "float", "3d");
-}
-
-primary_group.addStorageTexture("tLighting", "rgba16float", "3d", "write-only")
-
-// Lighting information
-resources.createGroup()
-
-    .addStorageBuffer("light_data", WebGPUArray.u32)
-    // clusters
-    .addUniform("cluster_parameters", vec3f)
-    .addStorageBuffer("cluster_lookup", LIGHT_CLUSTER_LOOKUP_STRUCT)
-    .addStorageBuffer("cluster_data", WebGPUArray.u32)
-    // shadows
-    .addTexture("shadowmapAtlas", "depth")
-    .addSampler("sCompareLinear", "comparison", SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR)
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(${VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION.join(",")})
-fn main(
-    @builtin(global_invocation_id) voxel_coord : vec3<u32>
-){
-    let resolution = textureDimensions(tParticipatingMedia0);
-
-    if(any(voxel_coord >= resolution)){
-        // overflow
-        return;
-    }
-
-    // Logical near/far, NOT the projection-derived range: the projection is infinite-far
-    // reverse-Z, so its far resolves to ~3.4e38 (FLOAT32_MAX). That value would leave the last
-    // froxel slice's z1 (and z1*z1*z1 below) at +Inf. clip_near_far is the bounded logical range,
-    // matching the participating-media build shader.
-    let near_far = camera.clip_near_far;
-
-    // same jitter valud for all voxels in Z column
-    // must be the same for PM and Lights
-    let z_jitter = volumetrics_column_jitter(voxel_coord.xy, view.frame_index);
-
-    let z_slice_0 = f32(voxel_coord.z ) + z_jitter;
-    let z_slice_1 = f32(voxel_coord.z + 1) + z_jitter;
-
-    let z0 = max(near_far.x, cluster_depth_from_z_slice( z_slice_0, volumetrics_metadata.froxel_cluster_parameters, f32(resolution.z) ));
-    let z1 = min(near_far.y, cluster_depth_from_z_slice( z_slice_1, volumetrics_metadata.froxel_cluster_parameters, f32(resolution.z) ));
-
-    // 2. Cubic mix gives uniform distribution in World Space Volume
-    let z3_min = z0 * z0 * z0;
-    let z3_max = z1 * z1 * z1;
-
-    var inScatteringSum = vec3<f32>(0.0);
-    var extinctionSum = 0.0;
-
-
-    // One sample per froxel. The 0.95-blend TAA downstream is a ~39-effective-sample temporal
-    // integrator; supersampling here as well spends N times this pass removing variance that filter
-    // removes anyway — and spends it at the Monte Carlo rate, because the samples were independent
-    // white noise and converged as 1/sqrt(N). Raising this is only worth it with the temporal
-    // filter off.
-    const SAMPLE_COUNT = 1u;
-
-    for(var i = 0u; i < SAMPLE_COUNT; i++){
-
-        // Spatiotemporal blue noise rather than a per-froxel hash. What lets 1 spp survive a
-        // temporal filter is each froxel seeing a well-distributed sequence over frames, which is
-        // STBN's defining property and exactly what white noise lacks — measured against the murmur
-        // hash it reaches the same error in roughly half the frames, across the whole window the
-        // 0.95 blend spans.
-        //
-        // The xy offset is load-bearing, not decoration. The aerial pass reads this same volume at
-        // (voxel_coord.xy, frame_index) and consumes all three channels, so sampling it there would
-        // not merely correlate the two passes' jitters — it would make them the same number. Two
-        // nuisance variables locked together stop covering the sample domain and the estimator
-        // converges to the wrong value, a bias that does NOT shrink with more frames, so no TAA
-        // window recovers it. Measured worst case |r| against any aerial channel: 1.0000 at zero
-        // offset, 0.0027 here.
-        //
-        // froxel z rides the temporal axis so froxels down a column do not all share one value —
-        // the fetch is indexed by column, and STBN's z axis is the one built to be well distributed.
-        const STBN_DECORRELATION_OFFSET = vec2<u32>(37u, 71u);
-
-        let noise = stbn_sample_vec3(vec3(
-            voxel_coord.xy + STBN_DECORRELATION_OFFSET,
-            (view.frame_index + voxel_coord.z) * SAMPLE_COUNT + i
-        ));
-
-        // [0..1] — offset (jitter - 0.5) must be centered on the froxel for every axis. The depth
-        // axis is stratified so that raising SAMPLE_COUNT converges faster than 1/sqrt(N); a no-op
-        // while it is 1.
-        let jitter = vec3(noise.xy, (f32(i) + noise.z) / f32(SAMPLE_COUNT));
-
-
-        // Interpolate the cubes, then take the cube root
-        let z3_sample = mix(z3_min, z3_max, jitter.z);
-        let view_depth = pow(z3_sample, 0.333333);
-
-        let sample_z_index:f32 = cluster_depth_to_z_slice(
-            view_depth,
-            volumetrics_metadata.froxel_cluster_parameters,
-            f32(resolution.z)
-        );
-
-        // 'saturate' prevents accidental out-of-bounds samples
-        let tile_uv = saturate(
-            texel_coordinate_to_uv(vec2f(voxel_coord.xy) + (jitter.xy - 0.5), resolution.xy)
-        );
-        let view_ray = camera_ray_from_uv(tile_uv, camera);
-
-        // The PM volumes are CELL-AVERAGED: texel k holds the slab [k+j, k+1+j], so its content
-        // sits at slice k + j + delta, not at slice k. Addressing them with the plain texel-centre
-        // convention is what the boundary-sampled aerial LUT wants, and reads the medium about half
-        // a froxel too far out. delta is a property of the depth curve — see the chunk.
-        let content_offset = volumetrics_froxel_content_offset(volumetrics_metadata.froxel_cluster_parameters.z);
-
-        let uvw = vec3<f32>(tile_uv, (sample_z_index + 0.5 - content_offset) / f32(resolution.z));
-
-        let participating_media0 = textureSampleLevel(tParticipatingMedia0, sLinear, uvw, 0.0);
-        let participating_media1 = textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0);
-
-        let participating_media_scattering = participating_media0.rgb;
-        let participating_media_extinction = participating_media1.rgb;
-        let participating_media_phase_g = participating_media1.a;
-
-        // Accumulate the (linear) mono extinction coefficient. Carried in tLighting.a below so the
-        // 3D TAA accumulates sigma_t alongside the in-scatter (Hillaire: temporally integrate the
-        // LINEAR extinction, never the non-linear transmittance).
-        extinctionSum += rgb_to_luminance(participating_media_extinction);
-
-        let view_pixel_coord = uv_to_texel_coordinate(tile_uv, vec2(view.width, view.height));
-
-        // view_depth is a PLANAR view-space depth and view_ray.direction is unit length, so the
-        // depth has to be converted to a distance along the ray before stepping. Multiplying them
-        // directly stops on the arc of constant distance instead of the plane of constant depth,
-        // short by cos(theta) — exact on the centre axis, ~72% of the intended depth in the corners
-        // of a 50 degree vertical FOV. Radial, which is why it reads as "the fog looks a bit off"
-        // rather than as an offset.
-        //
-        // Everything downstream assumes the planar reading: the light cluster is looked up at the
-        // planar depth, the shadow lookup happens at this position, and the TAA reconstructs froxel
-        // centres as planar slabs.
-        let position_ws = view_ray.origin
-            + view_ray.direction * (view_depth * camera_ray_planar_depth_scale(view_ray.direction, camera));
-
-        // Global lights (directional) — iterate over the first 32 slots
-        // of the directional light table (max enforced by GPULightCollection).
-        var directional_bits = directional_lights_iteration_mask(&light_data);
-        while (directional_bits != 0u) {
-            let directional_index = countTrailingZeros(directional_bits);
-            directional_bits &= ~(1u << directional_index);
-
-            let sun = get_directional_light_info_by_index(&light_data, directional_index);
-
-            let sun_lut_uv = sky_lut_compute_uv(position_ws, sun.direction, vec2<f32>(textureDimensions(tSunTransmittance)));
-
-            let shadow_term = shadowmap_get_directional_light_visibility(
-                &light_data,
-                directional_index,
-                position_ws,
-                // toward-camera, matching the deferred cascade-blend convention. The consumer
-                // (shadowmap_csm_compute_cascade_blended) negates this internally; the deferred
-                // caller passes the surface->camera vector, whereas view_ray.direction is
-                // camera->scene, so it must be negated here to agree.
-                -view_ray.direction,
-                sun.direction
-            );
-
-            let u = dot(sun.direction, view_ray.direction);
-
-            // sample atmospheric transmittance
-            let transmittance_atmospheric = textureSampleLevel(
-                tSunTransmittance,
-                sLinear,
-                sun_lut_uv, 0.0
-            ).rgb;
-
-            // Q-04. Every froxel on this sun ray is asking for the same integral, one increment
-            // apart, and the march recomputes all of it from scratch for each: O(froxels * steps)
-            // to produce O(froxels) of information. The sun is where that is worst, because its
-            // tmax is the distance to the sun clipped to the frustum, so the march spans the whole
-            // grid rather than the few metres a lamp's does.
-            //
-            // So read the answer out of the cascades built once this frame with their axis on the
-            // sun, where the increment relation IS the storage — see
-            // shader_volumetrics_build_sun_shadow_volume. Same quantity, same units, one fetch.
-            //
-            // The march below is not an alternative to it, it is what is left for the lights the
-            // cascades do not cover: a second directional light, since there is one ladder and it
-            // is aligned to one direction, and the two cases that cannot place a box at all, which
-            // sun_shadow_light_index reports by holding a value no light index can equal.
-            var optical_depth: vec3<f32>;
-
-            if (directional_index == volumetrics_metadata.sun_shadow_light_index) {
-
-                optical_depth = volumetrics_sun_optical_depth(position_ws);
-
-            } else {
-
-                // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
-                let shadow_ray = ${RAY_STRUCT.make({
-                    origin: "position_ws",
-                    direction: "sun.direction",
-                    tmax: "sun.distance",
-                })};
-
-                optical_depth = integrate_optical_depth(shadow_ray);
-            }
-
-            let ms = calculate_multiscattering(
-                optical_depth,
-                participating_media_scattering,
-                participating_media_extinction,
-                u,
-                participating_media_phase_g,
-                volumetrics_metadata.ms_octave_count,
-                volumetrics_metadata.ms_extinction_decay
-            );
-
-            inScatteringSum += shadow_term * ms * transmittance_atmospheric * sun.color;
-        }
-
-        // Local lights
-        let cluster_metadata = light_cluster_metadata_by_position(
-            view_pixel_coord,
-            view_depth,
-            vec2( view.width, view.height )
-        );
-
-        let cluster_offset = cluster_metadata.offset;
-        let point_count = light_cluster_count_point(cluster_metadata.counts);
-        let spot_count = light_cluster_count_spot(cluster_metadata.counts);
-
-        for (var j = 0u; j < point_count; j++) {
-            let light_index = cluster_data[cluster_offset + j];
-            var direct_light = get_point_light_info_by_index(&light_data, light_index, position_ws);
-
-            if (all(direct_light.color == vec3(0.0))) {
-                continue;
-            }
-
-            let u = dot(direct_light.direction, view_ray.direction);
-
-            // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
-            let shadow_ray = ${RAY_STRUCT.make({
-                origin: "position_ws",
-                direction: "direct_light.direction",
-                tmax: "direct_light.distance",
-            })};
-
-            let optical_depth = integrate_optical_depth(shadow_ray);
-
-            let ms = calculate_multiscattering(
-                optical_depth,
-                participating_media_scattering,
-                participating_media_extinction,
-                u,
-                participating_media_phase_g,
-                volumetrics_metadata.ms_octave_count,
-                volumetrics_metadata.ms_extinction_decay
-            );
-
-            // Before this, integrate_optical_depth was the ONLY thing occluding a local light:
-            // the medium shadowed itself and geometry did not shadow it at all, so a torch behind a
-            // wall lit the fog through the wall and a light through a window cast no shaft. The
-            // directional loop above has always multiplied its shadow map in; this is the same
-            // operation for the clustered lights, which is what Frostbite and UE both do in the
-            // froxel pass. One nearest atlas tap rather than the deferred path's filter kernel —
-            // see the chunk for why that is not a compromise here.
-            let shadow_term = volumetrics_point_light_shadow(&light_data, light_index, position_ws);
-
-            inScatteringSum += shadow_term * ms * direct_light.color;
-        }
-
-        for (var k = 0u; k < spot_count; k++) {
-            let light_index = cluster_data[cluster_offset + point_count + k];
-            var direct_light = get_spot_light_info_by_index(&light_data, light_index, position_ws);
-
-            if (all(direct_light.color == vec3(0.0))) {
-                continue;
-            }
-
-            let u = dot(direct_light.direction, view_ray.direction);
-
-            // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
-            let shadow_ray = ${RAY_STRUCT.make({
-                origin: "position_ws",
-                direction: "direct_light.direction",
-                tmax: "direct_light.distance",
-            })};
-
-            let optical_depth = integrate_optical_depth(shadow_ray);
-
-            let ms = calculate_multiscattering(
-                optical_depth,
-                participating_media_scattering,
-                participating_media_extinction,
-                u,
-                participating_media_phase_g,
-                volumetrics_metadata.ms_octave_count,
-                volumetrics_metadata.ms_extinction_decay
-            );
-
-            // see the point loop above
-            let shadow_term = volumetrics_spot_light_shadow(&light_data, light_index, position_ws);
-
-            inScatteringSum += shadow_term * ms * direct_light.color;
-        }
-    }
-
-
-    var inScattering = inScatteringSum / f32(SAMPLE_COUNT);
-
-    // .a carries the mono extinction coefficient so the aerial pass can read a temporally-stable
-    // sigma_t (after the 3D TAA) instead of re-sampling the raw per-frame-jittered PM extinction.
-    // The composited fog transmittance is already mono (rgb_to_luminance of the integrated
-    // throughput), so collapsing extinction to luminance only drops the subtle chromatic
-    // depth-attenuation of the in-scatter.
-    let extinction = extinctionSum / f32(SAMPLE_COUNT);
-
-    textureStore(tLighting, voxel_coord, vec4<f32>(inScattering, extinction));
-}
-    `, [
-        chunk_cluster_depth_from_z_slice,
-        chunk_cluster_depth_to_z_slice,
-        chunk_texel_coordinate_to_uv,
-        chunk_camera_ray_from_uv,
-        chunk_camera_ray_planar_depth_scale,
-        chunk_volumetrics_froxel_content_offset,
-        chunk_uv_to_texel_coordinate,
-
-        chunk_stbn_sample_vec3,
-
-        chunk_light_cluster_metadata_by_position,
-        chunk_light_cluster_counts,
-        chunk_directional_lights_iteration_mask,
-        chunk_get_directional_light_info_by_index,
-        chunk_get_point_light_info_by_index,
-        chunk_get_spot_light_info_by_index,
-        chunk_shadowmap_get_light_visibility,
-        chunk_volumetrics_local_light_shadow,
-        chunk_sky_lut_compute_uv,
-
-        RAY_STRUCT.declaration_chunk,
-        chunk_integrate_optical_depth,
-        chunk_volumetrics_sun_optical_depth,
-        chunk_calculate_multiscattering,
-        chunk_rgb_to_luminance,
-        chunk_volumetrics_column_jitter,
-    ]
-)
-
-export const shader_volumetrics_build_lighting = ComputeShader.from({
-    label: "Volumetrics / build lighting",
-    resources,
-    body
-})
+import { vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_rgb_to_luminance } from "../shader/chunk/color/chunk_rgb_to_luminance.js";
+import { chunk_stbn_sample_vec3 } from "../shader/chunk/noise/chunk_stbn_sample_vec3.js";
+import { chunk_camera_ray_from_uv } from "../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.js";
+import { RAY_STRUCT } from "../shader/chunk/geometry/ray/RAY_STRUCT.js";
+import {
+    chunk_directional_lights_iteration_mask
+} from "../shader/chunk/light/io/chunk_directional_lights_iteration_mask.js";
+import {
+    chunk_get_directional_light_info_by_index
+} from "../shader/chunk/light/io/chunk_get_directional_light_info_by_index.js";
+import {
+    chunk_get_point_light_info_by_index
+} from "../shader/chunk/light/io/chunk_get_point_light_info_by_index.js";
+import { chunk_get_spot_light_info_by_index } from "../shader/chunk/light/io/chunk_get_spot_light_info_by_index.js";
+import { chunk_texel_coordinate_to_uv } from "../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
+import { chunk_uv_to_texel_coordinate } from "../shader/chunk/texture/chunk_uv_to_texel_coordinate.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_shadowmap_get_light_visibility } from "../shadow/map/shader/chunk_shadowmap_get_light_visibility.js";
+import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { VIEW_UNIFORM_STRUCT } from "../view/VIEW_UNIFORM_STRUCT.js";
+import { chunk_cluster_depth_from_z_slice } from "../light/cluster/chunk_cluster_depth_from_z_slice.js";
+import { chunk_cluster_depth_to_z_slice } from "../light/cluster/chunk_cluster_depth_to_z_slice.js";
+import { chunk_light_cluster_counts } from "../light/cluster/chunk_light_cluster_counts.js";
+import { chunk_light_cluster_metadata_by_position } from "../light/cluster/chunk_light_cluster_metadata_by_position.js";
+import { LIGHT_CLUSTER_LOOKUP_STRUCT } from "../light/cluster/shader_cluster_assign_lights.js";
+import { chunk_sky_lut_compute_uv } from "../atmosphere/chunk_sky_lut_compute_uv.js";
+import { chunk_calculate_multiscattering } from "./chunk_calculate_multiscattering.js";
+import { chunk_camera_ray_planar_depth_scale } from "./chunk_camera_ray_planar_depth_scale.js";
+import { chunk_volumetrics_froxel_content_offset } from "./chunk_volumetrics_froxel_content_offset.js";
+import { chunk_integrate_optical_depth } from "./chunk_integrate_optical_depth.js";
+import {
+    chunk_volumetrics_sun_optical_depth,
+    volumetrics_sun_shadow_texture_name
+} from "./chunk_volumetrics_sun_optical_depth.js";
+import { VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
+import { chunk_volumetrics_column_jitter } from "./chunk_volumetrics_column_jitter.js";
+import { chunk_volumetrics_local_light_shadow } from "./chunk_volumetrics_local_light_shadow.js";
+import { chunk_volumetrics_irradiance_sh } from "./chunk_volumetrics_irradiance_sh.js";
+import {
+    METRO_L1_IRRADIANCE_STRUCT
+} from "../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
+
+/**
+ * Workgroup shape of this pass, `[x, y, z]` in froxels, stated to the `@workgroup_size` below.
+ * That attribute is where the dispatch gets the shape from in turn: `graph_build_volumetrics` asks
+ * for a thread count and `ComputeShader` divides by the size it read back out of the WGSL.
+ *
+ * Flat in z. Lights are binned into 3D clusters and the largest distance between neighbouring
+ * clusters is along depth, so a group spanning z is the one spanning the most unrelated light
+ * lists.
+ *
+ * 64 invocations — one wave64, two warps — is a deliberate trade: 16x16x1 measures faster on the
+ * RTX 4090 this was benchmarked on, and is kept off because that part's register file is unusually
+ * large and the result is not expected to generalize (AMD favours smaller groups). NOTES.md carries
+ * the numbers and the reasoning.
+ *
+ * @type {number[]}
+ */
+export const VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION = [8, 8, 1];
+
+const resources = new ShaderResourceSetDescriptor();
+
+const primary_group = resources.createGroup()
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("view", VIEW_UNIFORM_STRUCT)
+    .addTexture("tSunTransmittance", "float", "2d")
+    .addTexture("tMultiScattering", "float", "2d")
+    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
+    .addTexture("tSTBN_vec3", "unfilterable-float", "3d")
+    .addTexture("tParticipatingMedia0", "float", "3d")
+    .addTexture("tParticipatingMedia1", "float", "3d");
+
+// Q-04: the sun's optical depth, pre-integrated along the light axis by
+// shader_volumetrics_build_sun_shadow_volume, one cascade per texture and innermost first.
+// Sampled, not marched.
+for (let cascade = 0; cascade < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT; cascade++) {
+    primary_group.addTexture(volumetrics_sun_shadow_texture_name(cascade), "float", "3d");
+}
+
+primary_group.addStorageTexture("tLighting", "rgba16float", "3d", "write-only")
+
+// The froxel irradiance volume (chunk_volumetrics_irradiance_sh): luma SH2 in one, chroma in the
+// .rg of the other. rgba16float for both, because rg16float is not a storage format without
+// texture-formats-tier1. It is what the froxel GI stage (gi/) wrote to tGIY / tGICoCg, plus the lights.
+primary_group.addTexture("tGIY", "float", "3d")
+primary_group.addTexture("tGICoCg", "float", "3d")
+primary_group.addStorageTexture("tIrradianceY", "rgba16float", "3d", "write-only")
+primary_group.addStorageTexture("tIrradianceCoCg", "rgba16float", "3d", "write-only")
+
+// Lighting information
+resources.createGroup()
+
+    .addStorageBuffer("light_data", WebGPUArray.u32)
+    // clusters
+    .addUniform("cluster_parameters", vec3f)
+    .addStorageBuffer("cluster_lookup", LIGHT_CLUSTER_LOOKUP_STRUCT)
+    .addStorageBuffer("cluster_data", WebGPUArray.u32)
+    // shadows
+    .addTexture("shadowmapAtlas", "depth")
+    .addSampler("sCompareLinear", "comparison", SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR)
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION.join(",")})
+fn main(
+    @builtin(global_invocation_id) voxel_coord : vec3<u32>
+){
+    let resolution = textureDimensions(tParticipatingMedia0);
+
+    if(any(voxel_coord >= resolution)){
+        // overflow
+        return;
+    }
+
+    // Logical near/far, NOT the projection-derived range: the projection is infinite-far
+    // reverse-Z, so its far resolves to ~3.4e38 (FLOAT32_MAX). That value would leave the last
+    // froxel slice's z1 (and z1*z1*z1 below) at +Inf. clip_near_far is the bounded logical range,
+    // matching the participating-media build shader.
+    let near_far = camera.clip_near_far;
+
+    // same jitter valud for all voxels in Z column
+    // must be the same for PM and Lights
+    let z_jitter = volumetrics_column_jitter(voxel_coord.xy, view.frame_index);
+
+    let z_slice_0 = f32(voxel_coord.z ) + z_jitter;
+    let z_slice_1 = f32(voxel_coord.z + 1) + z_jitter;
+
+    let z0 = max(near_far.x, cluster_depth_from_z_slice( z_slice_0, volumetrics_metadata.froxel_cluster_parameters, f32(resolution.z) ));
+    let z1 = min(near_far.y, cluster_depth_from_z_slice( z_slice_1, volumetrics_metadata.froxel_cluster_parameters, f32(resolution.z) ));
+
+    // 2. Cubic mix gives uniform distribution in World Space Volume
+    let z3_min = z0 * z0 * z0;
+    let z3_max = z1 * z1 * z1;
+
+    var inScatteringSum = vec3<f32>(0.0);
+    var extinctionSum = 0.0;
+
+    // What a transparent surface at the sample receives from the same lights: their shadowed
+    // colour, attenuated by the medium toward each light, before any scattering by it.
+    var irradianceSum: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
+
+
+    // One sample per froxel. The 0.95-blend TAA downstream is a ~39-effective-sample temporal
+    // integrator; supersampling here as well spends N times this pass removing variance that filter
+    // removes anyway — and spends it at the Monte Carlo rate, because the samples were independent
+    // white noise and converged as 1/sqrt(N). Raising this is only worth it with the temporal
+    // filter off.
+    const SAMPLE_COUNT = 1u;
+
+    for(var i = 0u; i < SAMPLE_COUNT; i++){
+
+        // Spatiotemporal blue noise rather than a per-froxel hash. What lets 1 spp survive a
+        // temporal filter is each froxel seeing a well-distributed sequence over frames, which is
+        // STBN's defining property and exactly what white noise lacks — measured against the murmur
+        // hash it reaches the same error in roughly half the frames, across the whole window the
+        // 0.95 blend spans.
+        //
+        // The xy offset is load-bearing, not decoration. The aerial pass reads this same volume at
+        // (voxel_coord.xy, frame_index) and consumes all three channels, so sampling it there would
+        // not merely correlate the two passes' jitters — it would make them the same number. Two
+        // nuisance variables locked together stop covering the sample domain and the estimator
+        // converges to the wrong value, a bias that does NOT shrink with more frames, so no TAA
+        // window recovers it. Measured worst case |r| against any aerial channel: 1.0000 at zero
+        // offset, 0.0027 here.
+        //
+        // froxel z rides the temporal axis so froxels down a column do not all share one value —
+        // the fetch is indexed by column, and STBN's z axis is the one built to be well distributed.
+        const STBN_DECORRELATION_OFFSET = vec2<u32>(37u, 71u);
+
+        let noise = stbn_sample_vec3(vec3(
+            voxel_coord.xy + STBN_DECORRELATION_OFFSET,
+            (view.frame_index + voxel_coord.z) * SAMPLE_COUNT + i
+        ));
+
+        // [0..1] — offset (jitter - 0.5) must be centered on the froxel for every axis. The depth
+        // axis is stratified so that raising SAMPLE_COUNT converges faster than 1/sqrt(N); a no-op
+        // while it is 1.
+        let jitter = vec3(noise.xy, (f32(i) + noise.z) / f32(SAMPLE_COUNT));
+
+
+        // Interpolate the cubes, then take the cube root
+        let z3_sample = mix(z3_min, z3_max, jitter.z);
+        let view_depth = pow(z3_sample, 0.333333);
+
+        let sample_z_index:f32 = cluster_depth_to_z_slice(
+            view_depth,
+            volumetrics_metadata.froxel_cluster_parameters,
+            f32(resolution.z)
+        );
+
+        // 'saturate' prevents accidental out-of-bounds samples
+        let tile_uv = saturate(
+            texel_coordinate_to_uv(vec2f(voxel_coord.xy) + (jitter.xy - 0.5), resolution.xy)
+        );
+        let view_ray = camera_ray_from_uv(tile_uv, camera);
+
+        // The PM volumes are CELL-AVERAGED: texel k holds the slab [k+j, k+1+j], so its content
+        // sits at slice k + j + delta, not at slice k. Addressing them with the plain texel-centre
+        // convention is what the boundary-sampled aerial LUT wants, and reads the medium about half
+        // a froxel too far out. delta is a property of the depth curve — see the chunk.
+        let content_offset = volumetrics_froxel_content_offset(volumetrics_metadata.froxel_cluster_parameters.z);
+
+        let uvw = vec3<f32>(tile_uv, (sample_z_index + 0.5 - content_offset) / f32(resolution.z));
+
+        let participating_media0 = textureSampleLevel(tParticipatingMedia0, sLinear, uvw, 0.0);
+        let participating_media1 = textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0);
+
+        let participating_media_scattering = participating_media0.rgb;
+        let participating_media_extinction = participating_media1.rgb;
+        let participating_media_phase_g = participating_media1.a;
+
+        // Accumulate the (linear) mono extinction coefficient. Carried in tLighting.a below so the
+        // 3D TAA accumulates sigma_t alongside the in-scatter (Hillaire: temporally integrate the
+        // LINEAR extinction, never the non-linear transmittance).
+        extinctionSum += rgb_to_luminance(participating_media_extinction);
+
+        let view_pixel_coord = uv_to_texel_coordinate(tile_uv, vec2(view.width, view.height));
+
+        // view_depth is a PLANAR view-space depth and view_ray.direction is unit length, so the
+        // depth has to be converted to a distance along the ray before stepping. Multiplying them
+        // directly stops on the arc of constant distance instead of the plane of constant depth,
+        // short by cos(theta) — exact on the centre axis, ~72% of the intended depth in the corners
+        // of a 50 degree vertical FOV. Radial, which is why it reads as "the fog looks a bit off"
+        // rather than as an offset.
+        //
+        // Everything downstream assumes the planar reading: the light cluster is looked up at the
+        // planar depth, the shadow lookup happens at this position, and the TAA reconstructs froxel
+        // centres as planar slabs.
+        let position_ws = view_ray.origin
+            + view_ray.direction * (view_depth * camera_ray_planar_depth_scale(view_ray.direction, camera));
+
+        // Global lights (directional) — iterate over the first 32 slots
+        // of the directional light table (max enforced by GPULightCollection).
+        var directional_bits = directional_lights_iteration_mask(&light_data);
+        while (directional_bits != 0u) {
+            let directional_index = countTrailingZeros(directional_bits);
+            directional_bits &= ~(1u << directional_index);
+
+            let sun = get_directional_light_info_by_index(&light_data, directional_index);
+
+            let sun_lut_uv = sky_lut_compute_uv(position_ws, sun.direction, vec2<f32>(textureDimensions(tSunTransmittance)));
+
+            let shadow_term = shadowmap_get_directional_light_visibility(
+                &light_data,
+                directional_index,
+                position_ws,
+                // toward-camera, matching the deferred cascade-blend convention. The consumer
+                // (shadowmap_csm_compute_cascade_blended) negates this internally; the deferred
+                // caller passes the surface->camera vector, whereas view_ray.direction is
+                // camera->scene, so it must be negated here to agree.
+                -view_ray.direction,
+                sun.direction
+            );
+
+            let u = dot(sun.direction, view_ray.direction);
+
+            // sample atmospheric transmittance
+            let transmittance_atmospheric = textureSampleLevel(
+                tSunTransmittance,
+                sLinear,
+                sun_lut_uv, 0.0
+            ).rgb;
+
+            // Q-04. Every froxel on this sun ray is asking for the same integral, one increment
+            // apart, and the march recomputes all of it from scratch for each: O(froxels * steps)
+            // to produce O(froxels) of information. The sun is where that is worst, because its
+            // tmax is the distance to the sun clipped to the frustum, so the march spans the whole
+            // grid rather than the few metres a lamp's does.
+            //
+            // So read the answer out of the cascades built once this frame with their axis on the
+            // sun, where the increment relation IS the storage — see
+            // shader_volumetrics_build_sun_shadow_volume. Same quantity, same units, one fetch.
+            //
+            // The march below is not an alternative to it, it is what is left for the lights the
+            // cascades do not cover: a second directional light, since there is one ladder and it
+            // is aligned to one direction, and the two cases that cannot place a box at all, which
+            // sun_shadow_light_index reports by holding a value no light index can equal.
+            var optical_depth: vec3<f32>;
+
+            if (directional_index == volumetrics_metadata.sun_shadow_light_index) {
+
+                optical_depth = volumetrics_sun_optical_depth(position_ws);
+
+            } else {
+
+                // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
+                let shadow_ray = ${RAY_STRUCT.make({
+                    origin: "position_ws",
+                    direction: "sun.direction",
+                    tmax: "sun.distance",
+                })};
+
+                optical_depth = integrate_optical_depth(shadow_ray);
+            }
+
+            let ms = calculate_multiscattering(
+                optical_depth,
+                participating_media_scattering,
+                participating_media_extinction,
+                u,
+                participating_media_phase_g,
+                volumetrics_metadata.ms_octave_count,
+                volumetrics_metadata.ms_extinction_decay
+            );
+
+            inScatteringSum += shadow_term * ms * transmittance_atmospheric * sun.color;
+
+            // No atmospheric transmittance: that is the air's, and a surface in the volume is lit
+            // the way the surfaces around it are — the deferred and forward paths light meshes by
+            // sun.color as it stands, and a lit particle beside a lit log has to agree with it.
+            irradianceSum = volumetrics_irradiance_sh_add(
+                irradianceSum,
+                shadow_term * exp(-optical_depth) * sun.color,
+                sun.direction
+            );
+        }
+
+        // Local lights
+        let cluster_metadata = light_cluster_metadata_by_position(
+            view_pixel_coord,
+            view_depth,
+            vec2( view.width, view.height )
+        );
+
+        let cluster_offset = cluster_metadata.offset;
+        let point_count = light_cluster_count_point(cluster_metadata.counts);
+        let spot_count = light_cluster_count_spot(cluster_metadata.counts);
+
+        for (var j = 0u; j < point_count; j++) {
+            let light_index = cluster_data[cluster_offset + j];
+            var direct_light = get_point_light_info_by_index(&light_data, light_index, position_ws);
+
+            if (all(direct_light.color == vec3(0.0))) {
+                continue;
+            }
+
+            let u = dot(direct_light.direction, view_ray.direction);
+
+            // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
+            let shadow_ray = ${RAY_STRUCT.make({
+                origin: "position_ws",
+                direction: "direct_light.direction",
+                tmax: "direct_light.distance",
+            })};
+
+            let optical_depth = integrate_optical_depth(shadow_ray);
+
+            let ms = calculate_multiscattering(
+                optical_depth,
+                participating_media_scattering,
+                participating_media_extinction,
+                u,
+                participating_media_phase_g,
+                volumetrics_metadata.ms_octave_count,
+                volumetrics_metadata.ms_extinction_decay
+            );
+
+            // Before this, integrate_optical_depth was the ONLY thing occluding a local light:
+            // the medium shadowed itself and geometry did not shadow it at all, so a torch behind a
+            // wall lit the fog through the wall and a light through a window cast no shaft. The
+            // directional loop above has always multiplied its shadow map in; this is the same
+            // operation for the clustered lights, which is what Frostbite and UE both do in the
+            // froxel pass. One nearest atlas tap rather than the deferred path's filter kernel —
+            // see the chunk for why that is not a compromise here.
+            let shadow_term = volumetrics_point_light_shadow(&light_data, light_index, position_ws);
+
+            inScatteringSum += shadow_term * ms * direct_light.color;
+
+            irradianceSum = volumetrics_irradiance_sh_add(
+                irradianceSum,
+                shadow_term * exp(-optical_depth) * direct_light.color,
+                direct_light.direction
+            );
+        }
+
+        for (var k = 0u; k < spot_count; k++) {
+            let light_index = cluster_data[cluster_offset + point_count + k];
+            var direct_light = get_spot_light_info_by_index(&light_data, light_index, position_ws);
+
+            if (all(direct_light.color == vec3(0.0))) {
+                continue;
+            }
+
+            let u = dot(direct_light.direction, view_ray.direction);
+
+            // .direction points TOWARD the light; march the optical-depth ray toward the light (+direction).
+            let shadow_ray = ${RAY_STRUCT.make({
+                origin: "position_ws",
+                direction: "direct_light.direction",
+                tmax: "direct_light.distance",
+            })};
+
+            let optical_depth = integrate_optical_depth(shadow_ray);
+
+            let ms = calculate_multiscattering(
+                optical_depth,
+                participating_media_scattering,
+                participating_media_extinction,
+                u,
+                participating_media_phase_g,
+                volumetrics_metadata.ms_octave_count,
+                volumetrics_metadata.ms_extinction_decay
+            );
+
+            // see the point loop above
+            let shadow_term = volumetrics_spot_light_shadow(&light_data, light_index, position_ws);
+
+            inScatteringSum += shadow_term * ms * direct_light.color;
+
+            irradianceSum = volumetrics_irradiance_sh_add(
+                irradianceSum,
+                shadow_term * exp(-optical_depth) * direct_light.color,
+                direct_light.direction
+            );
+        }
+    }
+
+
+    var inScattering = inScatteringSum / f32(SAMPLE_COUNT);
+
+    // .a carries the mono extinction coefficient so the aerial pass can read a temporally-stable
+    // sigma_t (after the 3D TAA) instead of re-sampling the raw per-frame-jittered PM extinction.
+    // The composited fog transmittance is already mono (rgb_to_luminance of the integrated
+    // throughput), so collapsing extinction to luminance only drops the subtle chromatic
+    // depth-attenuation of the in-scatter.
+    let extinction = extinctionSum / f32(SAMPLE_COUNT);
+
+    textureStore(tLighting, voxel_coord, vec4<f32>(inScattering, extinction));
+
+    irradianceSum.Y /= f32(SAMPLE_COUNT);
+    irradianceSum.CoCg /= f32(SAMPLE_COUNT);
+
+    // What the renderer's indirect lighting gives this froxel, in the same encoding; the lights add
+    // to it. Written by the froxel GI module the mode selects, which is all this pass knows of GI.
+    irradianceSum.Y += textureLoad(tGIY, voxel_coord, 0);
+    irradianceSum.CoCg += textureLoad(tGICoCg, voxel_coord, 0).xy;
+
+    // nothing TAA-filters this volume, so nothing downstream would stop an Inf or a NaN here
+    let irradiance = volumetrics_irradiance_sh_storable(irradianceSum);
+
+    textureStore(tIrradianceY, voxel_coord, irradiance.Y);
+    textureStore(tIrradianceCoCg, voxel_coord, vec4<f32>(irradiance.CoCg, 0.0, 0.0));
+}
+    `, [
+        chunk_cluster_depth_from_z_slice,
+        chunk_cluster_depth_to_z_slice,
+        chunk_texel_coordinate_to_uv,
+        chunk_camera_ray_from_uv,
+        chunk_camera_ray_planar_depth_scale,
+        chunk_volumetrics_froxel_content_offset,
+        chunk_uv_to_texel_coordinate,
+
+        chunk_stbn_sample_vec3,
+
+        chunk_light_cluster_metadata_by_position,
+        chunk_light_cluster_counts,
+        chunk_directional_lights_iteration_mask,
+        chunk_get_directional_light_info_by_index,
+        chunk_get_point_light_info_by_index,
+        chunk_get_spot_light_info_by_index,
+        chunk_shadowmap_get_light_visibility,
+        chunk_volumetrics_local_light_shadow,
+        chunk_volumetrics_irradiance_sh,
+        chunk_sky_lut_compute_uv,
+
+        RAY_STRUCT.declaration_chunk,
+        chunk_integrate_optical_depth,
+        chunk_volumetrics_sun_optical_depth,
+        chunk_calculate_multiscattering,
+        chunk_rgb_to_luminance,
+        chunk_volumetrics_column_jitter,
+    ]
+)
+
+export const shader_volumetrics_build_lighting = ComputeShader.from({
+    label: "Volumetrics / build lighting",
+    resources,
+    body
+})