@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -1,261 +1,261 @@
-import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_stbn_sample_vec3 } from "../shader/chunk/noise/chunk_stbn_sample_vec3.js";
-import {
-    chunk_compute_near_far_from_projection
-} from "../shader/chunk/camera/chunk_compute_near_far_from_projection.js";
-import { chunk_rgb_to_luminance } from "../shader/chunk/color/chunk_rgb_to_luminance.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 { 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 { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
-import { chunk_camera_ray_from_uv } from "../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.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_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 { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
-import { SCENE_VOLUMETRICS_METADATA_STRUCT } from "./SCENE_VOLUMETRICS_METADATA_STRUCT.js";
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addUniform("view", VIEW_UNIFORM_STRUCT)
-    .addTexture("tSTBN_vec3", "unfilterable-float", "3d")
-    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
-    .addTexture("tParticipatingMedia0", "float", "3d")
-    .addTexture("tParticipatingMedia1", "float", "3d")
-    .addTexture("tVolumeLighting", "float", "3d") // pre-integrated volumetric light scattering
-    // RDR2-style far field: beyond froxel_far the pass ray-marches the scene volumes directly,
-    // lit by the directional sun + atmosphere (single scattering, no self-shadow).
-    .addUniform("scene_volumetrics_metadata", SCENE_VOLUMETRICS_METADATA_STRUCT)
-    .addStorageBuffer("scene_volumes", WebGPUArray.from(PARTICIPATING_MEDIA_VOLUME_STRUCT))
-    .addStorageBuffer("light_data", WebGPUArray.u32)
-    .addTexture("tSunTransmittance", "float", "2d")
-    .addSampler("sLinear")
-    .addStorageTexture("tOutput", "rgba16float", "3d", "write-only");
-
-
-/**
- * see https://github.com/GPUOpen-Effects/Hybrid-Stochastic-Reflections/blob/b3eef4be70db3522c54d289766e6db797777163c/sample/src/Shaders/Atmosphere.h#L149
- * see https://github.com/AirGuanZ/AtmosphereRenderer/blob/94055f272814a850aafa072555a839311b3d2924/asset/aerial_lut.hlsl#L33
- * @type {CodeChunk}
- */
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-struct FarVolumeSample {
-    scattering: vec3<f32>,
-    extinction: vec3<f32>,
-    phase_g: f32,
-}
-
-// Point-sample the scene participating-media volumes (coarse: full density inside the box, no edge
-// fade — that is a near-field nicety). Used only beyond the froxel grid.
-fn far_sample_volumes(world_pos: vec3<f32>) -> FarVolumeSample {
-    var scattering = vec3<f32>(0.0);
-    var extinction = vec3<f32>(0.0);
-    var g_weighted = 0.0;
-    var scattering_luma = 0.0;
-
-    let count = scene_volumetrics_metadata.instance_count;
-    for (var i = 0u; i < count; i++) {
-        let volume = scene_volumes[i];
-        let local = (volume.transform_inverse * vec4<f32>(world_pos, 1.0)).xyz;
-        if (any(abs(local) > vec3<f32>(0.5))) {
-            continue;
-        }
-        let weight = volume.density;
-        let vs = volume.particle_spec.scattering * weight;
-        let ve = volume.particle_spec.extinction * weight;
-        scattering += vs;
-        extinction += ve;
-        let luma = rgb_to_luminance(vs);
-        g_weighted += volume.particle_spec.g * luma;
-        scattering_luma += luma;
-    }
-    var g = 0.0;
-    if (scattering_luma > 0.0) {
-        g = g_weighted / scattering_luma;
-    }
-    return FarVolumeSample(scattering, extinction, g);
-}
-
-// In-scatter (.rgb) + mono extinction (.a) at a march point. Inside the froxel grid (depth <=
-// froxel_far) this is the pre-lit grid sample; beyond it we ray-march the volumes directly and light
-// them with the directional sun + atmospheric transmittance (single scattering, no self-shadow).
-fn far_sample_lighting(depth: f32, uvw_grid: vec3<f32>, world_pos: vec3<f32>, ray_dir: vec3<f32>) -> vec4<f32> {
-    if (depth <= volumetrics_metadata.froxel_far) {
-        // The froxel grid uses its own (tighter) depth curve, so map this LUT depth to the grid
-        // slice before sampling (identity when froxel_far == camera.far).
-        let res_z = f32(textureDimensions(tVolumeLighting).z);
-        let grid_slice = cluster_depth_to_z_slice(depth, volumetrics_metadata.froxel_cluster_parameters, res_z);
-        let vl = textureSampleLevel(tVolumeLighting, sLinear, vec3<f32>(uvw_grid.xy, grid_slice / res_z), 0.0);
-        return vec4<f32>(vl.rgb, vl.a);
-    }
-
-    let s = far_sample_volumes(world_pos);
-
-    var inscatter = vec3<f32>(0.0);
-    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 u = dot(sun.direction, ray_dir);
-        let sun_lut_uv = sky_lut_compute_uv(world_pos, sun.direction);
-        let transmittance_atmospheric = textureSampleLevel(tSunTransmittance, sLinear, sun_lut_uv, 0.0).rgb;
-
-        let ms = calculate_multiscattering(vec3<f32>(0.0), s.scattering, s.extinction, u, s.phase_g, volumetrics_metadata.ms_octave_count, volumetrics_metadata.ms_extinction_decay);
-        inscatter += ms * transmittance_atmospheric * sun.color;
-    }
-
-    return vec4<f32>(inscatter, rgb_to_luminance(s.extinction));
-}
-
-@compute @workgroup_size(16, 16, 1)
-fn main(
-    @builtin(global_invocation_id) voxel_coord: vec3<u32>
-){
-    let resolution = textureDimensions(tOutput);
-
-    if (any(voxel_coord.xy >= resolution.xy)) {
-        return;
-    }
-
-    let noise = stbn_sample_vec3(vec3(voxel_coord.xy, view.frame_index));
-
-    let tile_uv = saturate(
-        texel_coordinate_to_uv(vec2f(voxel_coord.xy) + vec2(noise.xy - 0.5), resolution.xy)
-    );
-
-    let camera_near_far = compute_near_far_from_projection(camera.projection_matrix);
-    let camera_far = camera_near_far.y;
-
-    // view ray for this froxel column, used to place far-field march samples in world space
-    let view_ray = camera_ray_from_uv(tile_uv, camera);
-
-    var inScatter = vec3<f32>(0.0);
-    var throughput = vec3<f32>(1.0);
-
-    // Every t below is a PLANAR view-space depth off the froxel curve, but the loop uses their
-    // difference as a segment length in Beer's law and walks them along a unit ray to place world
-    // positions. Both want arc length, which is longer by 1/cos(theta). Uncorrected, the optical
-    // path is under-integrated by cos(theta) and fog thins toward the frame edges.
-    //
-    // Constant for the whole column, so this is one reciprocal per invocation rather than per slice.
-    let depth_to_distance = camera_ray_planar_depth_scale(view_ray.direction, camera);
-
-    // start at the near plane
-    var t_prev = camera_near_far.x;
-
-    // --- TRAPEZOIDAL SETUP ---
-    // Prime the loop with the value at the start (Slice 0)
-    let uvw_start = vec3<f32>(tile_uv, 0.0);
-
-    // in-scatter (.rgb) and the TAA-accumulated mono extinction coefficient (.a) now share the
-    // volume-lighting texture, so a single sample provides both.
-    let vl_start = far_sample_lighting(camera_near_far.x, uvw_start, view_ray.origin + view_ray.direction * (camera_near_far.x * depth_to_distance), view_ray.direction);
-    var light_prev = vl_start.rgb;
-    var extinction_prev = vl_start.a;
-
-    for (var z_index: u32 = 0u; z_index < resolution.z; z_index++ ) {
-
-        // --- STORE BEFORE INTEGRATE ---
-        // Texel z_index holds the cumulative in-scatter / transmittance integrated from the near
-        // plane up to the NEAR face of this slab, i.e. up to depth from_z_slice(z_index). Storing
-        // the running accumulator BEFORE integrating this slab's segment is what aligns texel
-        // z_index with from_z_slice(z_index) -- the same convention the deferred read samples back
-        // with (slice + 0.5) / resolution.z (see chunk_sample_volumetrics and
-        // volumetrics_position_world_to_froxel_uvw). Storing after-integrate instead would shift
-        // every texel one slab deeper, over-attenuating the read by a full froxel.
-        let transmittance = rgb_to_luminance( throughput );
-
-        textureStore(
-            tOutput,
-            vec3<u32>(voxel_coord.x, voxel_coord.y, z_index),
-            vec4<f32>(inScatter, transmittance)
-        );
-
-        // We clamp the index to not sample outside the texture
-        let next_index = min(z_index + 1u, resolution.z - 1u);
-        let next_index_dithered = f32(next_index) + noise.z;
-
-        // 1. Calculate Geometry
-        let t_next = min(camera_far, cluster_depth_from_z_slice(
-            next_index_dithered,
-            volumetrics_metadata.cluster_parameters,
-            f32(resolution.z)
-        ));
-
-        // planar depth difference -> arc length along the view ray (C-01b)
-        let dt = max(0.0, t_next - t_prev) * depth_to_distance;
-
-        // 2. Fetch "Next" Value (The end of this segment)
-        let uvw_next = vec3<f32>(tile_uv, next_index_dithered / f32(resolution.z));
-
-        let world_pos_next = view_ray.origin + view_ray.direction * (t_next * depth_to_distance);
-        let vl_next = far_sample_lighting(t_next, uvw_next, world_pos_next, view_ray.direction);
-        let media_extinction = vl_next.a;
-        let light_next = vl_next.rgb;
-
-        // TODO we should probably offset this to be linear in view-space distance
-        const SAMPLE_CENTER_POINT = 0.5;
-
-        // 3. Trapezoidal Average
-        // Instead of taking just the center, we average start and end to form a slope
-        let extinction_step = mix(extinction_prev, media_extinction, SAMPLE_CENTER_POINT);
-        let light_step = mix(light_prev, light_next, SAMPLE_CENTER_POINT);
-
-        // 4. Integration (Hillaire) using the averaged values. Extinction is a mono sigma_t scalar,
-        // so transmittance is mono and broadcasts to weight the RGB throughput / in-scatter.
-        let sample_extinction = dt * extinction_step;
-        let sample_transmittance = exp(-sample_extinction);
-
-        let media_extinction_safe = max(extinction_step, 1e-9);
-
-        // "S - S * T" is the integral of constant L over the interval.
-        // Since we trapezoid-averaged L (light_step), this is a much better approximation
-        // for the interval than just using L_center.
-        let light_scattering_integrated = (light_step - light_step * sample_transmittance) / media_extinction_safe;
-
-        inScatter += throughput * light_scattering_integrated;
-        throughput *= sample_transmittance;
-
-        // Advance
-        t_prev = t_next;
-        extinction_prev = media_extinction;
-        light_prev = light_next;
-
-    }
-}
-    `, [
-        chunk_rgb_to_luminance,
-        chunk_compute_near_far_from_projection,
-        chunk_texel_coordinate_to_uv,
-        chunk_uv_to_texel_coordinate,
-        chunk_cluster_depth_from_z_slice,
-        chunk_cluster_depth_to_z_slice,
-        chunk_stbn_sample_vec3,
-        chunk_camera_ray_from_uv,
-        chunk_camera_ray_planar_depth_scale,
-        chunk_directional_lights_iteration_mask,
-        chunk_get_directional_light_info_by_index,
-        chunk_sky_lut_compute_uv,
-        chunk_calculate_multiscattering,
-    ]
-)
-
-export const shader_volumetrics_build_scattering_lut = ComputeShader.from({
-    label: "Volumetrics / build scattering lut",
-    resources,
-    body
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_stbn_sample_vec3 } from "../shader/chunk/noise/chunk_stbn_sample_vec3.js";
+import {
+    chunk_compute_near_far_from_projection
+} from "../shader/chunk/camera/chunk_compute_near_far_from_projection.js";
+import { chunk_rgb_to_luminance } from "../shader/chunk/color/chunk_rgb_to_luminance.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 { 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 { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { chunk_camera_ray_from_uv } from "../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.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_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 { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
+import { SCENE_VOLUMETRICS_METADATA_STRUCT } from "./SCENE_VOLUMETRICS_METADATA_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("view", VIEW_UNIFORM_STRUCT)
+    .addTexture("tSTBN_vec3", "unfilterable-float", "3d")
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addTexture("tParticipatingMedia0", "float", "3d")
+    .addTexture("tParticipatingMedia1", "float", "3d")
+    .addTexture("tVolumeLighting", "float", "3d") // pre-integrated volumetric light scattering
+    // RDR2-style far field: beyond froxel_far the pass ray-marches the scene volumes directly,
+    // lit by the directional sun + atmosphere (single scattering, no self-shadow).
+    .addUniform("scene_volumetrics_metadata", SCENE_VOLUMETRICS_METADATA_STRUCT)
+    .addStorageBuffer("scene_volumes", WebGPUArray.from(PARTICIPATING_MEDIA_VOLUME_STRUCT))
+    .addStorageBuffer("light_data", WebGPUArray.u32)
+    .addTexture("tSunTransmittance", "float", "2d")
+    .addSampler("sLinear")
+    .addStorageTexture("tOutput", "rgba16float", "3d", "write-only");
+
+
+/**
+ * see https://github.com/GPUOpen-Effects/Hybrid-Stochastic-Reflections/blob/b3eef4be70db3522c54d289766e6db797777163c/sample/src/Shaders/Atmosphere.h#L149
+ * see https://github.com/AirGuanZ/AtmosphereRenderer/blob/94055f272814a850aafa072555a839311b3d2924/asset/aerial_lut.hlsl#L33
+ * @type {CodeChunk}
+ */
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+struct FarVolumeSample {
+    scattering: vec3<f32>,
+    extinction: vec3<f32>,
+    phase_g: f32,
+}
+
+// Point-sample the scene participating-media volumes (coarse: full density inside the box, no edge
+// fade — that is a near-field nicety). Used only beyond the froxel grid.
+fn far_sample_volumes(world_pos: vec3<f32>) -> FarVolumeSample {
+    var scattering = vec3<f32>(0.0);
+    var extinction = vec3<f32>(0.0);
+    var g_weighted = 0.0;
+    var scattering_luma = 0.0;
+
+    let count = scene_volumetrics_metadata.instance_count;
+    for (var i = 0u; i < count; i++) {
+        let volume = scene_volumes[i];
+        let local = (volume.transform_inverse * vec4<f32>(world_pos, 1.0)).xyz;
+        if (any(abs(local) > vec3<f32>(0.5))) {
+            continue;
+        }
+        let weight = volume.density;
+        let vs = volume.particle_spec.scattering * weight;
+        let ve = volume.particle_spec.extinction * weight;
+        scattering += vs;
+        extinction += ve;
+        let luma = rgb_to_luminance(vs);
+        g_weighted += volume.particle_spec.g * luma;
+        scattering_luma += luma;
+    }
+    var g = 0.0;
+    if (scattering_luma > 0.0) {
+        g = g_weighted / scattering_luma;
+    }
+    return FarVolumeSample(scattering, extinction, g);
+}
+
+// In-scatter (.rgb) + mono extinction (.a) at a march point. Inside the froxel grid (depth <=
+// froxel_far) this is the pre-lit grid sample; beyond it we ray-march the volumes directly and light
+// them with the directional sun + atmospheric transmittance (single scattering, no self-shadow).
+fn far_sample_lighting(depth: f32, uvw_grid: vec3<f32>, world_pos: vec3<f32>, ray_dir: vec3<f32>) -> vec4<f32> {
+    if (depth <= volumetrics_metadata.froxel_far) {
+        // The froxel grid uses its own (tighter) depth curve, so map this LUT depth to the grid
+        // slice before sampling (identity when froxel_far == camera.far).
+        let res_z = f32(textureDimensions(tVolumeLighting).z);
+        let grid_slice = cluster_depth_to_z_slice(depth, volumetrics_metadata.froxel_cluster_parameters, res_z);
+        let vl = textureSampleLevel(tVolumeLighting, sLinear, vec3<f32>(uvw_grid.xy, grid_slice / res_z), 0.0);
+        return vec4<f32>(vl.rgb, vl.a);
+    }
+
+    let s = far_sample_volumes(world_pos);
+
+    var inscatter = vec3<f32>(0.0);
+    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 u = dot(sun.direction, ray_dir);
+        let sun_lut_uv = sky_lut_compute_uv(world_pos, sun.direction, vec2<f32>(textureDimensions(tSunTransmittance)));
+        let transmittance_atmospheric = textureSampleLevel(tSunTransmittance, sLinear, sun_lut_uv, 0.0).rgb;
+
+        let ms = calculate_multiscattering(vec3<f32>(0.0), s.scattering, s.extinction, u, s.phase_g, volumetrics_metadata.ms_octave_count, volumetrics_metadata.ms_extinction_decay);
+        inscatter += ms * transmittance_atmospheric * sun.color;
+    }
+
+    return vec4<f32>(inscatter, rgb_to_luminance(s.extinction));
+}
+
+@compute @workgroup_size(16, 16, 1)
+fn main(
+    @builtin(global_invocation_id) voxel_coord: vec3<u32>
+){
+    let resolution = textureDimensions(tOutput);
+
+    if (any(voxel_coord.xy >= resolution.xy)) {
+        return;
+    }
+
+    let noise = stbn_sample_vec3(vec3(voxel_coord.xy, view.frame_index));
+
+    let tile_uv = saturate(
+        texel_coordinate_to_uv(vec2f(voxel_coord.xy) + vec2(noise.xy - 0.5), resolution.xy)
+    );
+
+    let camera_near_far = compute_near_far_from_projection(camera.projection_matrix);
+    let camera_far = camera_near_far.y;
+
+    // view ray for this froxel column, used to place far-field march samples in world space
+    let view_ray = camera_ray_from_uv(tile_uv, camera);
+
+    var inScatter = vec3<f32>(0.0);
+    var throughput = vec3<f32>(1.0);
+
+    // Every t below is a PLANAR view-space depth off the froxel curve, but the loop uses their
+    // difference as a segment length in Beer's law and walks them along a unit ray to place world
+    // positions. Both want arc length, which is longer by 1/cos(theta). Uncorrected, the optical
+    // path is under-integrated by cos(theta) and fog thins toward the frame edges.
+    //
+    // Constant for the whole column, so this is one reciprocal per invocation rather than per slice.
+    let depth_to_distance = camera_ray_planar_depth_scale(view_ray.direction, camera);
+
+    // start at the near plane
+    var t_prev = camera_near_far.x;
+
+    // --- TRAPEZOIDAL SETUP ---
+    // Prime the loop with the value at the start (Slice 0)
+    let uvw_start = vec3<f32>(tile_uv, 0.0);
+
+    // in-scatter (.rgb) and the TAA-accumulated mono extinction coefficient (.a) now share the
+    // volume-lighting texture, so a single sample provides both.
+    let vl_start = far_sample_lighting(camera_near_far.x, uvw_start, view_ray.origin + view_ray.direction * (camera_near_far.x * depth_to_distance), view_ray.direction);
+    var light_prev = vl_start.rgb;
+    var extinction_prev = vl_start.a;
+
+    for (var z_index: u32 = 0u; z_index < resolution.z; z_index++ ) {
+
+        // --- STORE BEFORE INTEGRATE ---
+        // Texel z_index holds the cumulative in-scatter / transmittance integrated from the near
+        // plane up to the NEAR face of this slab, i.e. up to depth from_z_slice(z_index). Storing
+        // the running accumulator BEFORE integrating this slab's segment is what aligns texel
+        // z_index with from_z_slice(z_index) -- the same convention the deferred read samples back
+        // with (slice + 0.5) / resolution.z (see chunk_sample_volumetrics and
+        // volumetrics_position_world_to_froxel_uvw). Storing after-integrate instead would shift
+        // every texel one slab deeper, over-attenuating the read by a full froxel.
+        let transmittance = rgb_to_luminance( throughput );
+
+        textureStore(
+            tOutput,
+            vec3<u32>(voxel_coord.x, voxel_coord.y, z_index),
+            vec4<f32>(inScatter, transmittance)
+        );
+
+        // We clamp the index to not sample outside the texture
+        let next_index = min(z_index + 1u, resolution.z - 1u);
+        let next_index_dithered = f32(next_index) + noise.z;
+
+        // 1. Calculate Geometry
+        let t_next = min(camera_far, cluster_depth_from_z_slice(
+            next_index_dithered,
+            volumetrics_metadata.cluster_parameters,
+            f32(resolution.z)
+        ));
+
+        // planar depth difference -> arc length along the view ray (C-01b)
+        let dt = max(0.0, t_next - t_prev) * depth_to_distance;
+
+        // 2. Fetch "Next" Value (The end of this segment)
+        let uvw_next = vec3<f32>(tile_uv, next_index_dithered / f32(resolution.z));
+
+        let world_pos_next = view_ray.origin + view_ray.direction * (t_next * depth_to_distance);
+        let vl_next = far_sample_lighting(t_next, uvw_next, world_pos_next, view_ray.direction);
+        let media_extinction = vl_next.a;
+        let light_next = vl_next.rgb;
+
+        // TODO we should probably offset this to be linear in view-space distance
+        const SAMPLE_CENTER_POINT = 0.5;
+
+        // 3. Trapezoidal Average
+        // Instead of taking just the center, we average start and end to form a slope
+        let extinction_step = mix(extinction_prev, media_extinction, SAMPLE_CENTER_POINT);
+        let light_step = mix(light_prev, light_next, SAMPLE_CENTER_POINT);
+
+        // 4. Integration (Hillaire) using the averaged values. Extinction is a mono sigma_t scalar,
+        // so transmittance is mono and broadcasts to weight the RGB throughput / in-scatter.
+        let sample_extinction = dt * extinction_step;
+        let sample_transmittance = exp(-sample_extinction);
+
+        let media_extinction_safe = max(extinction_step, 1e-9);
+
+        // "S - S * T" is the integral of constant L over the interval.
+        // Since we trapezoid-averaged L (light_step), this is a much better approximation
+        // for the interval than just using L_center.
+        let light_scattering_integrated = (light_step - light_step * sample_transmittance) / media_extinction_safe;
+
+        inScatter += throughput * light_scattering_integrated;
+        throughput *= sample_transmittance;
+
+        // Advance
+        t_prev = t_next;
+        extinction_prev = media_extinction;
+        light_prev = light_next;
+
+    }
+}
+    `, [
+        chunk_rgb_to_luminance,
+        chunk_compute_near_far_from_projection,
+        chunk_texel_coordinate_to_uv,
+        chunk_uv_to_texel_coordinate,
+        chunk_cluster_depth_from_z_slice,
+        chunk_cluster_depth_to_z_slice,
+        chunk_stbn_sample_vec3,
+        chunk_camera_ray_from_uv,
+        chunk_camera_ray_planar_depth_scale,
+        chunk_directional_lights_iteration_mask,
+        chunk_get_directional_light_info_by_index,
+        chunk_sky_lut_compute_uv,
+        chunk_calculate_multiscattering,
+    ]
+)
+
+export const shader_volumetrics_build_scattering_lut = ComputeShader.from({
+    label: "Volumetrics / build scattering lut",
+    resources,
+    body
 });

package/src/shade/renderer/volumetrics/shader_volumetrics_build_sun_shadow_volume.d.ts

@@ -1,8 +1,58 @@
 /**
- * One build shader per cascade, innermost first.
+ * Q-04. Builds one cascade of the sun's optical-depth volume so the lighting pass can read a
+ * froxel's media self-shadowing in one fetch instead of marching 16 steps toward the sun for it.
  *
- * @type {ComputeShader[]}
+ * The structure is a light-aligned voxel grid holding a prefix sum of extinction along the sun
+ * axis — in the shadow-map taxonomy an opacity shadow map (Kim & Neumann 2001) with enough slices
+ * and hardware trilinear reconstruction that the slice artefacts it is remembered for do not
+ * appear, and exact rather than approximate for the piecewise-constant field a voxel grid is.
+ * Enshrouded (GPC 2024) ships the same thing, cascaded: 3D volumes with their z axis on the primary
+ * light, initialised from the participating media and then integrated by a 2D dispatch per column,
+ * each cascade seeded from the one outside it. Frostbite (SIGGRAPH 2015) cascades its extinction
+ * volume the same way, three clip-map levels of it, for the same reason.
+ *
+ * Fourier Opacity Mapping is the better-known answer and is the wrong one here. It exists because
+ * the medium usually arrives as unordered rasterized particles, where the only thing you can do is
+ * accumulate a fixed-size, order-independent, additively-blendable summary — and it pays for that
+ * with ringing at sharp density transitions. This engine's medium is already a 3D texture with a
+ * defined order along any axis, so the scan is available, exact, and has nothing to ring.
+ *
+ * Two shaders, written out: the outermost cascade, whose scan starts at zero, and every cascade
+ * inside it, whose scan starts from the cascade outside. That is a difference in *bindings* — the
+ * second reads a texture the first does not have — so it cannot be data. Which cascade is being
+ * built can be, and is: it arrives as immediate data, so the inner cascades share one pipeline.
+ *
+ * @see chunk_volumetrics_sun_optical_depth for the read side
+ * @see build_volumetrics_sun_shadow_transform for where each box is placed, and why it is stable
+ */
+/**
+ * Which cascade a dispatch is building.
+ *
+ * Per-dispatch, uniform, read-only and eight bytes, which is the shape immediate data exists for:
+ * no pooled buffer, no staging copy, no bind group.
+ *
+ * `sub_steps` travels with it rather than being derived in the shader because it is a property of
+ * the cascade ladder rather than of the box: {@link volumetrics_sun_shadow_sub_steps} is where the
+ * rule that it is even and at least two lives, and nothing in the metadata lets the shader
+ * re-derive it.
+ *
+ * @type {WebGPUStruct}
+ */
+export const VOLUMETRICS_SUN_SHADOW_BUILD_SETTINGS: WebGPUStruct;
+/**
+ * The outermost cascade. Nothing is outside it, so its scan starts from zero and it binds no outer
+ * volume.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_build_sun_shadow_volume_outermost: ComputeShader;
+/**
+ * Every cascade but the outermost, seeded from the one outside it. Which one that is arrives as
+ * immediate data, so the whole inner ladder shares this pipeline.
+ *
+ * @type {ComputeShader}
  */
-export const shader_volumetrics_build_sun_shadow_volume: ComputeShader[];
+export const shader_volumetrics_build_sun_shadow_volume_seeded: ComputeShader;
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../shader/ComputeShader.js";
 //# sourceMappingURL=shader_volumetrics_build_sun_shadow_volume.d.ts.map

package/src/shade/renderer/volumetrics/shader_volumetrics_build_sun_shadow_volume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_volumetrics_build_sun_shadow_volume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_sun_shadow_volume.js"],"names":[],"mappings":"AAuKA;;;;GAIG;AACH,yDAFU,aAAa,EAAE,CAG0E;8BA3KrE,4BAA4B"}
+{"version":3,"file":"shader_volumetrics_build_sun_shadow_volume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_sun_shadow_volume.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;GAYG;AACH,oDAFU,YAAY,CAKkB;AAaxC;;;;;GAKG;AACH,mEAFU,aAAa,CA8FpB;AAcH;;;;;GAKG;AACH,gEAFU,aAAa,CAwGpB;6BA3R0B,gCAAgC;8BAH/B,4BAA4B"}