@woosh/meep-engine 3.57.0 → 3.59.0

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

@@ -1,311 +1,558 @@
-import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_texel_coordinate_to_uv } from "../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
-import { chunk_volumetrics_sample_froxel_extinction } from "./chunk_volumetrics_sample_froxel_extinction.js";
-import { VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
-import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
-
-/**
- * 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.
- *
- * 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.from({
-    cascade: u32,
-    sub_steps: u32,
-}, 'VolumetricsSunShadowBuildSettings');
-
-const outermost_resources = new ShaderResourceSetDescriptor();
-
-outermost_resources.setImmediate("settings", VOLUMETRICS_SUN_SHADOW_BUILD_SETTINGS);
-
-outermost_resources.createGroup()
-    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
-    .addTexture("tParticipatingMedia1", "float", "3d")
-    .addStorageTexture("tSunShadowVolume", "rgba16float", "3d", "write-only");
-
-/**
- * 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.from({
-    label: 'Volumetrics / build sun shadow volume (outermost)',
-    resources: outermost_resources,
-    body: CodeChunk.from(
-        //language=WGSL
-        `
-@compute @workgroup_size(${VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION.join(",")})
-fn main(
-    @builtin(global_invocation_id) column : vec3<u32>
-){
-    let resolution = textureDimensions(tSunShadowVolume);
-
-    if(any(column.xy >= resolution.xy)){
-        // overflow
-        return;
-    }
-
-    // The volume's z axis is the direction light TRAVELS, so this column is one sun ray and slice 0
-    // is its end nearest the sun. Walking it in order turns the per-froxel integral into a running
-    // sum: every voxel's optical depth is its predecessor's plus one slab. That is the whole point
-    // of the pass — the same information the 16-step march produces, in O(voxels) instead of
-    // O(froxels * steps), and produced once rather than once per froxel that happens to lie on the
-    // ray.
-    //
-    // One invocation per column rather than a cooperative scan. The dependency chain is one
-    // cascade's depth long and each link is a texture fetch, so a Hillis-Steele or Blinn-Sengupta
-    // scan would trade this pass's perfectly coherent, register-resident accumulator for log(n)
-    // rounds of shared memory and barriers to speed up something that is already bandwidth-bound.
-    // The aerial pass has the same shape for the same reason.
-    //
-    // Immediate data, so this is uniform across the dispatch.
-    let cascade = settings.cascade;
-
-    let uvw_to_ws = volumetrics_metadata.sun_shadow_uvw_to_ws[cascade];
-
-    // What a voxel must hold is the medium's INTEGRAL across its slab, not the medium's value at
-    // its centre, and one point sample per voxel is not that. A fog volume three units thick
-    // crossed by a 2.3-unit lattice has its entire optical depth resting on one or two samples:
-    // whether they land inside it, on its fade, or just outside swings the answer by the whole
-    // shadow, and the per-frame column jitter under them turns that into a strobe.
-    //
-    // So sample the slab several times and store the storage-resolution result. The sampling rate
-    // and the resolution are separate knobs and only the first one has to beat the medium's
-    // features. The count is per cascade — see volumetrics_sun_shadow_sub_steps — so that every
-    // cascade samples at the same world-space spacing rather than at the same count per voxel.
-    let sub_steps = settings.sub_steps;
-
-    let sub_steps_half = sub_steps / 2u;
-
-    let sub_step_ws = volumetrics_metadata.sun_shadow_step_ws[cascade] / f32(sub_steps);
-
-    let w_per_slice = 1.0 / f32(resolution.z);
-    let w_per_sub_step = w_per_slice / f32(sub_steps);
-
-    let column_uv = texel_coordinate_to_uv(vec2<f32>(column.xy), resolution.xy);
-
-    // The outermost cascade's box contains the whole frustum, and the medium exists only inside
-    // the frustum, so the slab its scan starts on is empty and zero is the whole of the truth about
-    // what is between it and the sun.
-    var optical_depth = vec3<f32>(0.0);
-
-    // The column is a straight line: uvw (column_uv, w) for w in [0, 1], which in world space starts
-    // on the box's sun-side face and runs along the box's z axis. So its view depth and clip
-    // position are affine in w and are set up here, once, rather than projected per sub-step.
-    //
-    // Measured 2026-10-16, RTX 4090, headless Chrome, volumetrics_froxel playground at 1898x982,
-    // "Fog bank, wide" and "Inside the fog", p10 of each pass, arms interleaved in one capture.
-    // The old form projected every sub-step. Evaluating each of its parts a second time cost:
-    //   all of it              1.18-1.23x
-    //   the content offset     1.10-1.13x  (uniform, but the compiler left it in the loop)
-    //   the uvw_to_ws product  1.02-1.04x
-    //   the view product       1.02-1.05x  (dropping its repeat in the old sampler read 0.98-1.00x)
-    //   the projection         1.01-1.03x
-    //   the log2               0.99-1.01x
-    // This line, with the content offset carried on it, takes this pass from 84.7 to 68.6 us
-    // (0.81-0.82 of the old) and the seeded passes to 0.83-0.85. The output is not bit-identical:
-    // at most 0.12% of texels differ, mostly by one f16 step. The largest differences are one
-    // sample crossing a guard and the running sum staying stepped down the column. Reassociating
-    // only the old uvw_to_ws product moves a comparable number of texels and has outliers of the
-    // same kind: over the frames read, at most 591 steps for that against 180 for this form.
-    let column_line = volumetrics_froxel_line((uvw_to_ws * vec4<f32>(column_uv, 0.0, 1.0)).xyz, uvw_to_ws[2].xyz);
-
-    for(var slice = 0u; slice < resolution.z; slice++){
-
-        let voxel = vec3<u32>(column.xy, slice);
-
-        let w_slice = f32(slice) * w_per_slice;
-
-        for(var sub = 0u; sub < sub_steps; sub++){
-
-            // Halfway through the slab, so the value stored at slice k is the integral from the
-            // box's sun-side face to the voxel's CENTRE. Linear interpolation between two stored
-            // values then reproduces the true integral exactly wherever extinction is constant
-            // across the pair. Storing the integral to the far face instead — a right-endpoint sum,
-            // which is what the march this replaces does — biases every reading by half a slab.
-            if(sub == sub_steps_half){
-                textureStore(tSunShadowVolume, voxel, vec4<f32>(optical_depth, 0.0));
-            }
-
-            let w = w_slice + (f32(sub) + 0.5) * w_per_sub_step;
-
-            optical_depth += volumetrics_sample_froxel_extinction(column_line, w) * sub_step_ws;
-        }
-    }
-}
-    `, [
-            CAMERA_UNIFORM_STRUCT.declaration_chunk,
-            chunk_texel_coordinate_to_uv,
-            chunk_volumetrics_sample_froxel_extinction,
-        ]
-    )
-});
-
-const seeded_resources = new ShaderResourceSetDescriptor();
-
-seeded_resources.setImmediate("settings", VOLUMETRICS_SUN_SHADOW_BUILD_SETTINGS);
-
-seeded_resources.createGroup()
-    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
-    .addTexture("tParticipatingMedia1", "float", "3d")
-    .addTexture("tSunShadowOuter", "float", "3d")
-    .addStorageTexture("tSunShadowVolume", "rgba16float", "3d", "write-only");
-
-/**
- * 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_seeded = ComputeShader.from({
-    label: 'Volumetrics / build sun shadow volume (seeded)',
-    resources: seeded_resources,
-    body: CodeChunk.from(
-        //language=WGSL
-        `
-@compute @workgroup_size(${VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION.join(",")})
-fn main(
-    @builtin(global_invocation_id) column : vec3<u32>
-){
-    let resolution = textureDimensions(tSunShadowVolume);
-
-    if(any(column.xy >= resolution.xy)){
-        // overflow
-        return;
-    }
-
-    // The volume's z axis is the direction light TRAVELS, so this column is one sun ray and slice 0
-    // is its end nearest the sun. Walking it in order turns the per-froxel integral into a running
-    // sum: every voxel's optical depth is its predecessor's plus one slab. That is the whole point
-    // of the pass — the same information the 16-step march produces, in O(voxels) instead of
-    // O(froxels * steps), and produced once rather than once per froxel that happens to lie on the
-    // ray.
-    //
-    // One invocation per column rather than a cooperative scan. The dependency chain is one
-    // cascade's depth long and each link is a texture fetch, so a Hillis-Steele or Blinn-Sengupta
-    // scan would trade this pass's perfectly coherent, register-resident accumulator for log(n)
-    // rounds of shared memory and barriers to speed up something that is already bandwidth-bound.
-    // The aerial pass has the same shape for the same reason.
-    //
-    // Immediate data, so this is uniform across the dispatch.
-    let cascade = settings.cascade;
-
-    let uvw_to_ws = volumetrics_metadata.sun_shadow_uvw_to_ws[cascade];
-
-    // What a voxel must hold is the medium's INTEGRAL across its slab, not the medium's value at
-    // its centre, and one point sample per voxel is not that. A fog volume three units thick
-    // crossed by a 2.3-unit lattice has its entire optical depth resting on one or two samples:
-    // whether they land inside it, on its fade, or just outside swings the answer by the whole
-    // shadow, and the per-frame column jitter under them turns that into a strobe.
-    //
-    // So sample the slab several times and store the storage-resolution result. The sampling rate
-    // and the resolution are separate knobs and only the first one has to beat the medium's
-    // features. The count is per cascade — see volumetrics_sun_shadow_sub_steps — so that every
-    // cascade samples at the same world-space spacing rather than at the same count per voxel.
-    let sub_steps = settings.sub_steps;
-
-    let sub_steps_half = sub_steps / 2u;
-
-    let sub_step_ws = volumetrics_metadata.sun_shadow_step_ws[cascade] / f32(sub_steps);
-
-    let w_per_slice = 1.0 / f32(resolution.z);
-    let w_per_sub_step = w_per_slice / f32(sub_steps);
-
-    let column_uv = texel_coordinate_to_uv(vec2<f32>(column.xy), resolution.xy);
-
-    // Seeded from the cascade outside this one, at the world position where this column enters
-    // this box. Everything between the sun and that plane has already been integrated out there, at
-    // that cascade's resolution, so the scan here starts from it rather than from zero and an inner
-    // cascade is a refinement of the outer rather than a truncation of the medium. Enshrouded
-    // describes exactly this: "each cascade as an initial shadow value reads the upper cascade".
-    //
-    // The clamp is a statement about the domain rather than a guard that fires: the outer box
-    // contains the whole frustum and this box's entry plane is a face of a box sized from a
-    // sub-frustum of it.
-    let entry_ws = (uvw_to_ws * vec4<f32>(column_uv, 0.0, 1.0)).xyz;
-
-    let outer_uvw = (volumetrics_metadata.sun_shadow_ws_to_uvw[cascade + 1u] * vec4<f32>(entry_ws, 1.0)).xyz;
-
-    var optical_depth = textureSampleLevel(tSunShadowOuter, sLinear, saturate(outer_uvw), 0.0).rgb;
-
-    // The column is a straight line from where it enters the box, along the box's z axis, so it is
-    // set up once rather than projected per sub-step. The outermost shader has the measurements.
-    let column_line = volumetrics_froxel_line(entry_ws, uvw_to_ws[2].xyz);
-
-    for(var slice = 0u; slice < resolution.z; slice++){
-
-        let voxel = vec3<u32>(column.xy, slice);
-
-        let w_slice = f32(slice) * w_per_slice;
-
-        for(var sub = 0u; sub < sub_steps; sub++){
-
-            // Halfway through the slab, so the value stored at slice k is the integral from the
-            // box's sun-side face to the voxel's CENTRE. Linear interpolation between two stored
-            // values then reproduces the true integral exactly wherever extinction is constant
-            // across the pair. Storing the integral to the far face instead — a right-endpoint sum,
-            // which is what the march this replaces does — biases every reading by half a slab.
-            if(sub == sub_steps_half){
-                textureStore(tSunShadowVolume, voxel, vec4<f32>(optical_depth, 0.0));
-            }
-
-            let w = w_slice + (f32(sub) + 0.5) * w_per_sub_step;
-
-            optical_depth += volumetrics_sample_froxel_extinction(column_line, w) * sub_step_ws;
-        }
-    }
-}
-    `, [
-            CAMERA_UNIFORM_STRUCT.declaration_chunk,
-            chunk_texel_coordinate_to_uv,
-            chunk_volumetrics_sample_froxel_extinction,
-        ]
-    )
-});
+import { chunk_aabb3_slab_span } from "../shader/chunk/geometry/aabb3/chunk_aabb3_slab_span.js";
+import { chunk_mat4_extract_scale } from "../shader/chunk/geometry/mat4/chunk_mat4_extract_scale.js";
+import { F16_MAX_DEFINITION } from "../shader/chunk/math/F16_MAX_DEFINITION.js";
+import { F32_MAX_DEFINITION } from "../shader/chunk/math/F32_MAX_DEFINITION.js";
+import { chunk_texel_coordinate_to_uv } from "../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { chunk_wind_field_sample } from "../wind/chunk_wind_field_sample.js";
+import { wind_field_add_resources } from "../wind/wind_field_add_resources.js";
+import { chunk_participating_media_volumes_iterate } from "./chunk_participating_media_volumes_iterate.js";
+import {
+    chunk_volumetrics_sun_shadow_group_list,
+    VOLUMETRICS_SUN_SHADOW_BRICK_Z,
+    VOLUMETRICS_SUN_SHADOW_BUILD_SETTINGS,
+    VOLUMETRICS_SUN_SHADOW_UPWIND_LATTICE_SLICES,
+    VOLUMETRICS_SUN_SHADOW_UPWIND_TAIL_STEPS,
+} from "./chunk_volumetrics_sun_shadow_group_list.js";
+import { chunk_participating_media_noise } from "./noise/chunk_participating_media_noise.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "./noise/PARTICIPATING_MEDIA_NOISE.js";
+import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
+import { VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
+
+export { VOLUMETRICS_SUN_SHADOW_BUILD_SETTINGS };
+
+/**
+ * Q-04 / Q-05. Builds one cascade of the sun's optical-depth volume by integrating the scene's
+ * world-space participating-media volumes directly along each sun-aligned column.
+ *
+ * Integrating the scene's participating media in world space rather than resampling the camera's
+ * froxel grid (`tParticipatingMedia1`) removes the camera-frustum boundary from the shadow domain:
+ * a sun ray that enters the camera view through its top, side, near or far plane carries the full
+ * optical depth of every volume between the sun and that point, whether or not the volume lies
+ * inside the camera frustum.
+ *
+ * To scale to thousands of volumes, each cascade is preceded by a broad-phase volume cull
+ * ({@link shader_volumetrics_cull_sun_shadow_media}) and an `8x8x8` brick bin
+ * ({@link shader_volumetrics_bin_sun_shadow_media}). Here, each thread walks its column brick by
+ * brick: empty bricks advance eight slices in O(1), and populated bricks amortize each volume's
+ * `scene_database` load, local-space basis projection and 4-ray RGSS slab intersection across all
+ * eight slices of the brick.
+ *
+ * @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
+ */
+
+const chunk_volumetrics_sun_shadow_column_scan = CodeChunk.from(
+    //language=WGSL
+    `
+const VOLUMETRICS_SUN_SHADOW_UPWIND_LATTICE_SLICES: f32 = ${VOLUMETRICS_SUN_SHADOW_UPWIND_LATTICE_SLICES}.0;
+const VOLUMETRICS_SUN_SHADOW_UPWIND_TAIL_STEPS: u32 = ${VOLUMETRICS_SUN_SHADOW_UPWIND_TAIL_STEPS}u;
+
+// 4-rooks (rotated grid) stratified offsets across a voxel's [-0.5, +0.5]^2 lateral face.
+// Deterministic in world space so a stationary medium on the world-snapped sun lattice never strobes
+// from frame to frame, while still resolving sub-voxel lateral coverage across soft or sharp edges.
+const VOLUMETRICS_SUN_SHADOW_RGSS_U = vec4<f32>(-0.375,  0.125, -0.125,  0.375);
+const VOLUMETRICS_SUN_SHADOW_RGSS_V = vec4<f32>(-0.125, -0.375,  0.375,  0.125);
+
+// Entry and exit distances (near, far) of a ray origin + s * dir with the unit box [-0.5, +0.5]^3,
+// using aabb3_slab_span on each axis so a zero direction component on a box plane never forms NaN.
+fn volumetrics_unit_box_ray_span(origin: vec3<f32>, inv_dir: vec3<f32>) -> vec2<f32> {
+    let x = aabb3_slab_span(-0.5 - origin.x, 0.5 - origin.x, inv_dir.x);
+    let y = aabb3_slab_span(-0.5 - origin.y, 0.5 - origin.y, inv_dir.y);
+    let z = aabb3_slab_span(-0.5 - origin.z, 0.5 - origin.z, inv_dir.z);
+
+    let near = max(max(x.x, y.x), z.x);
+    let far = min(min(x.y, y.y), z.y);
+
+    return vec2<f32>(near, far);
+}
+
+struct VolumetricsSunColumnVolume {
+    valid: bool,
+    col_start_local: vec3<f32>,
+    local_e_z: vec3<f32>,
+    world_scale: vec3<f32>,
+    core_margin: vec3<f32>,
+    ray_s_enter: vec4<f32>,
+    ray_s_exit: vec4<f32>,
+    center_span: vec2<f32>,
+    union_span: vec2<f32>,
+}
+
+// Projects a column's origin and voxel steps into volume-local space, intersects the 4 RGSS
+// sub-rays and the centre ray with the unit box [-0.5, +0.5]^3, and computes the union span and
+// interior-core margin once per brick.
+fn volumetrics_sun_column_volume_setup(
+    volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref},
+    col_start_ws: vec3<f32>,
+    voxel_step_x_ws: vec3<f32>,
+    voxel_step_y_ws: vec3<f32>,
+    voxel_step_z_ws: vec3<f32>,
+) -> VolumetricsSunColumnVolume {
+    var result: VolumetricsSunColumnVolume;
+
+    let col_start_local = (volume.transform_inverse * vec4<f32>(col_start_ws, 1.0)).xyz;
+    let local_e_x = (volume.transform_inverse * vec4<f32>(voxel_step_x_ws, 0.0)).xyz;
+    let local_e_y = (volume.transform_inverse * vec4<f32>(voxel_step_y_ws, 0.0)).xyz;
+    let local_e_z = (volume.transform_inverse * vec4<f32>(voxel_step_z_ws, 0.0)).xyz;
+    let inv_e_z = 1.0 / local_e_z;
+
+    let span0 = volumetrics_unit_box_ray_span(
+        col_start_local + VOLUMETRICS_SUN_SHADOW_RGSS_U.x * local_e_x + VOLUMETRICS_SUN_SHADOW_RGSS_V.x * local_e_y,
+        inv_e_z,
+    );
+    let span1 = volumetrics_unit_box_ray_span(
+        col_start_local + VOLUMETRICS_SUN_SHADOW_RGSS_U.y * local_e_x + VOLUMETRICS_SUN_SHADOW_RGSS_V.y * local_e_y,
+        inv_e_z,
+    );
+    let span2 = volumetrics_unit_box_ray_span(
+        col_start_local + VOLUMETRICS_SUN_SHADOW_RGSS_U.z * local_e_x + VOLUMETRICS_SUN_SHADOW_RGSS_V.z * local_e_y,
+        inv_e_z,
+    );
+    let span3 = volumetrics_unit_box_ray_span(
+        col_start_local + VOLUMETRICS_SUN_SHADOW_RGSS_U.w * local_e_x + VOLUMETRICS_SUN_SHADOW_RGSS_V.w * local_e_y,
+        inv_e_z,
+    );
+
+    let ray_s_enter = vec4<f32>(span0.x, span1.x, span2.x, span3.x);
+    let ray_s_exit  = vec4<f32>(span0.y, span1.y, span2.y, span3.y);
+    let valid = ray_s_exit > ray_s_enter;
+
+    if (!any(valid)) {
+        return result;
+    }
+
+    let valid_enter = select(vec4<f32>(F32_MAX), ray_s_enter, valid);
+    let valid_exit  = select(vec4<f32>(-F32_MAX), ray_s_exit, valid);
+    let union_span = vec2<f32>(
+        min(min(valid_enter.x, valid_enter.y), min(valid_enter.z, valid_enter.w)),
+        max(max(valid_exit.x, valid_exit.y), max(valid_exit.z, valid_exit.w)),
+    );
+
+    let world_scale = mat4_extract_scale(volume.transform);
+    let fade_local = select(
+        vec3<f32>(0.0),
+        vec3<f32>(volume.fade_distance) / max(world_scale, vec3<f32>(1e-6)),
+        volume.fade_distance > 0.001,
+    );
+    let voxel_local_half = 0.5 * (abs(local_e_x) + abs(local_e_y) + abs(local_e_z));
+
+    result.valid = true;
+    result.col_start_local = col_start_local;
+    result.local_e_z = local_e_z;
+    result.world_scale = world_scale;
+    result.core_margin = fade_local + voxel_local_half;
+    result.ray_s_enter = ray_s_enter;
+    result.ray_s_exit = ray_s_exit;
+    result.center_span = volumetrics_unit_box_ray_span(col_start_local, inv_e_z);
+    result.union_span = union_span;
+
+    return result;
+}
+
+// Evaluates one volume's weight (coverage * soft-edge fade * wind-carried noise) over a slice
+// interval [s0, s1] (of length ds = s1 - s0 > 0) along a column whose 4 RGSS rays and center ray
+// have already been intersected with the unit box.
+//
+// Returns vec2(weight_to_center, weight_full), both normalized by ds:
+//   .x integrates [s0, (s0 + s1) * 0.5] (for storing the cumulative integral at the voxel centre)
+//   .y integrates [s0, s1]              (for advancing the column's running optical depth)
+fn volumetrics_sun_slice_volume_weight(
+    volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref},
+    setup: VolumetricsSunColumnVolume,
+    s0: f32,
+    s1: f32,
+    inv_ds: f32,
+    col_start_ws: vec3<f32>,
+    voxel_step_z_ws: vec3<f32>,
+) -> vec2<f32> {
+    let s_center = (s0 + s1) * 0.5;
+    let c_local = setup.col_start_local + s_center * setup.local_e_z;
+    let d_local = vec3<f32>(0.5) - abs(c_local);
+
+    var coverage = vec2<f32>(0.5, 1.0);
+    var fade = 1.0;
+    var s_mid = s_center;
+
+    // Interior core fast-path: when a unit-step voxel's entire local AABB sits inside the volume
+    // and past its fade_distance on all six faces, coverage is (0.5, 1.0) and smoothstep fade is
+    // 1.0 everywhere in the voxel, so both the 4-ray coverage and the smoothstep are skipped.
+    if (inv_ds != 1.0 || !all(d_local >= setup.core_margin)) {
+        let s0_v = max(vec4<f32>(s0), setup.ray_s_enter);
+        let cov4_full = max(vec4<f32>(0.0), min(vec4<f32>(s1), setup.ray_s_exit) - s0_v) * inv_ds;
+        let cov_full = (cov4_full.x + cov4_full.y + cov4_full.z + cov4_full.w) * 0.25;
+
+        if (cov_full <= 0.0) {
+            return vec2<f32>(0.0);
+        }
+
+        let cov4_half = max(vec4<f32>(0.0), min(vec4<f32>(s_center), setup.ray_s_exit) - s0_v) * inv_ds;
+        let cov_half = (cov4_half.x + cov4_half.y + cov4_half.z + cov4_half.w) * 0.25;
+        coverage = vec2<f32>(cov_half, cov_full);
+
+        let c_start = max(s0, setup.center_span.x);
+        let c_end = min(s1, setup.center_span.y);
+
+        if (c_end > c_start) {
+            s_mid = (c_start + c_end) * 0.5;
+        } else {
+            let u_start = max(s0, setup.union_span.x);
+            let u_end = min(s1, setup.union_span.y);
+            s_mid = select(s_center, (u_start + u_end) * 0.5, u_end > u_start);
+        }
+
+        if (volume.fade_distance > 0.001) {
+            let mid_local = clamp(setup.col_start_local + s_mid * setup.local_e_z, vec3<f32>(-0.5), vec3<f32>(0.5));
+            let dist_to_edge_world = (vec3<f32>(0.5) - abs(mid_local)) * setup.world_scale;
+            let alpha = smoothstep(vec3<f32>(0.0), vec3<f32>(volume.fade_distance), dist_to_edge_world);
+            fade = alpha.x * alpha.y * alpha.z;
+
+            if (fade <= 0.0) {
+                return vec2<f32>(0.0);
+            }
+        }
+    }
+
+    var noise = 1.0;
+
+    if (volume.noise_strength > 0.0) {
+        let sample_ws = col_start_ws + s_mid * voxel_step_z_ws;
+        noise = participating_media_noise_multiplier(volume, sample_ws);
+    }
+
+    return coverage * (fade * noise);
+}
+
+// Integrates any participating media upwind of the outermost cascade's w = 0 entry face
+// (brick layer z = interior_bricks_z). The 16 slices immediately ahead of w = 0 are integrated on
+// the exact integer voxel lattice [-16, 0) so whole-voxel origin snaps of the cascade move slices
+// across w = 0 without changing their coverage, fade or noise sample point.
+fn volumetrics_sun_shadow_upwind_seed(
+    column: vec2<u32>,
+    resolution: vec3<u32>,
+    cascade: u32,
+) -> vec3<f32> {
+    let uvw_to_ws = volumetrics_metadata.sun_shadow_uvw_to_ws[cascade];
+    let step_ws = volumetrics_metadata.sun_shadow_step_ws[cascade];
+    let res_f = vec3<f32>(resolution);
+
+    let column_uv = texel_coordinate_to_uv(vec2<f32>(column), resolution.xy);
+    let col_start_ws = (uvw_to_ws * vec4<f32>(column_uv, 0.0, 1.0)).xyz;
+    let voxel_step_x_ws = uvw_to_ws[0].xyz / res_f.x;
+    let voxel_step_y_ws = uvw_to_ws[1].xyz / res_f.y;
+    let voxel_step_z_ws = uvw_to_ws[2].xyz / res_f.z;
+
+    let group_xy = column / VOLUMETRICS_SUN_SHADOW_GROUP_XY;
+    let groups = volumetrics_sun_shadow_groups(resolution);
+    let interior_bricks_z = volumetrics_sun_shadow_interior_bricks_z(resolution.z);
+    let volume_count = participating_media_volumes_count(&scene_database);
+    let list_words = volumetrics_sun_shadow_list_words(volume_count, arrayLength(&group_lists), groups);
+    let list = volumetrics_sun_shadow_list_offset(vec3<u32>(group_xy, interior_bricks_z), groups, list_words);
+
+    var optical_depth = vec3<f32>(0.0);
+    var bits = 0u;
+    var word = 0u;
+
+    for (var listed = 0u; listed < VOLUMETRICS_SUN_SHADOW_VOLUME_BUDGET; listed++) {
+        while (bits == 0u && word < list_words) {
+            bits = group_lists[list + word];
+            word++;
+        }
+
+        if (bits == 0u) {
+            break;
+        }
+
+        let v = (word - 1u) * 32u + countTrailingZeros(bits);
+        bits &= bits - 1u;
+
+        let volume = participating_media_volume_read(&scene_database, v);
+        let setup = volumetrics_sun_column_volume_setup(
+            volume,
+            col_start_ws,
+            voxel_step_x_ws,
+            voxel_step_y_ws,
+            voxel_step_z_ws,
+        );
+
+        if (!setup.valid) {
+            continue;
+        }
+
+        let s_up_end = min(setup.union_span.y, 0.0);
+
+        if (s_up_end <= setup.union_span.x) {
+            continue;
+        }
+
+        var vol_weight = 0.0;
+
+        // 1. Deep upwind tail (s < -16): integrate in at most VOLUMETRICS_SUN_SHADOW_UPWIND_TAIL_STEPS steps
+        let tail_end = min(s_up_end, -VOLUMETRICS_SUN_SHADOW_UPWIND_LATTICE_SLICES);
+
+        if (tail_end > setup.union_span.x) {
+            let tail_span = tail_end - setup.union_span.x;
+            let tail_steps = u32(clamp(ceil(tail_span), 1.0, f32(VOLUMETRICS_SUN_SHADOW_UPWIND_TAIL_STEPS)));
+            let ds = tail_span / f32(tail_steps);
+            let inv_ds = 1.0 / ds;
+
+            for (var step = 0u; step < tail_steps; step++) {
+                let s0 = setup.union_span.x + f32(step) * ds;
+                let s1 = s0 + ds;
+                vol_weight += volumetrics_sun_slice_volume_weight(
+                    volume,
+                    setup,
+                    s0,
+                    s1,
+                    inv_ds,
+                    col_start_ws,
+                    voxel_step_z_ws,
+                ).y * ds;
+            }
+        }
+
+        // 2. Lattice-aligned upwind slices (s in [-16, 0)): exact unit-voxel steps on the cascade lattice
+        let lat_start = max(setup.union_span.x, -VOLUMETRICS_SUN_SHADOW_UPWIND_LATTICE_SLICES);
+
+        if (s_up_end > lat_start) {
+            let s_first = i32(floor(lat_start));
+            let s_last = min(0, i32(ceil(s_up_end)));
+
+            for (var s = s_first; s < s_last; s++) {
+                let s0 = f32(s);
+                let s1 = s0 + 1.0;
+                vol_weight += volumetrics_sun_slice_volume_weight(
+                    volume,
+                    setup,
+                    s0,
+                    s1,
+                    1.0,
+                    col_start_ws,
+                    voxel_step_z_ws,
+                ).y;
+            }
+        }
+
+        optical_depth += (volume.particle_spec.extinction * (volume.density * step_ws)) * vol_weight;
+    }
+
+    return optical_depth;
+}
+
+// Walks one sun-aligned column brick by brick from slice 0 to resolution.z - 1, starting from
+// initial_optical_depth and writing the cumulative optical depth to each voxel's centre into
+// tSunShadowVolume.
+fn volumetrics_sun_shadow_integrate_column(
+    column: vec2<u32>,
+    resolution: vec3<u32>,
+    cascade: u32,
+    initial_optical_depth: vec3<f32>,
+) {
+    let uvw_to_ws = volumetrics_metadata.sun_shadow_uvw_to_ws[cascade];
+    let step_ws = volumetrics_metadata.sun_shadow_step_ws[cascade];
+    let res_f = vec3<f32>(resolution);
+
+    let column_uv = texel_coordinate_to_uv(vec2<f32>(column), resolution.xy);
+    let col_start_ws = (uvw_to_ws * vec4<f32>(column_uv, 0.0, 1.0)).xyz;
+    let voxel_step_x_ws = uvw_to_ws[0].xyz / res_f.x;
+    let voxel_step_y_ws = uvw_to_ws[1].xyz / res_f.y;
+    let voxel_step_z_ws = uvw_to_ws[2].xyz / res_f.z;
+
+    let group_xy = column / VOLUMETRICS_SUN_SHADOW_GROUP_XY;
+    let groups = volumetrics_sun_shadow_groups(resolution);
+    let interior_bricks_z = volumetrics_sun_shadow_interior_bricks_z(resolution.z);
+    let volume_count = participating_media_volumes_count(&scene_database);
+    let list_words = volumetrics_sun_shadow_list_words(volume_count, arrayLength(&group_lists), groups);
+
+    var optical_depth = initial_optical_depth;
+
+    for (var bz = 0u; bz < interior_bricks_z; bz++) {
+        let brick_s0 = bz * VOLUMETRICS_SUN_SHADOW_BRICK_Z;
+        let brick_slices = min(VOLUMETRICS_SUN_SHADOW_BRICK_Z, resolution.z - brick_s0);
+        let brick_start_f = f32(brick_s0);
+        let brick_end_f = f32(brick_s0 + brick_slices);
+
+        let list = volumetrics_sun_shadow_list_offset(vec3<u32>(group_xy, bz), groups, list_words);
+
+        var slab_od_half: array<vec3<f32>, ${VOLUMETRICS_SUN_SHADOW_BRICK_Z}>;
+        var slab_od_full: array<vec3<f32>, ${VOLUMETRICS_SUN_SHADOW_BRICK_Z}>;
+
+        var bits = 0u;
+        var word = 0u;
+
+        for (var listed = 0u; listed < VOLUMETRICS_SUN_SHADOW_VOLUME_BUDGET; listed++) {
+            while (bits == 0u && word < list_words) {
+                bits = group_lists[list + word];
+                word++;
+            }
+
+            if (bits == 0u) {
+                break;
+            }
+
+            let v = (word - 1u) * 32u + countTrailingZeros(bits);
+            bits &= bits - 1u;
+
+            let volume = participating_media_volume_read(&scene_database, v);
+            let setup = volumetrics_sun_column_volume_setup(
+                volume,
+                col_start_ws,
+                voxel_step_x_ws,
+                voxel_step_y_ws,
+                voxel_step_z_ws,
+            );
+
+            if (!setup.valid) {
+                continue;
+            }
+
+            let s_start = max(brick_start_f, setup.union_span.x);
+            let s_end = min(brick_end_f, setup.union_span.y);
+
+            if (s_end <= s_start) {
+                continue;
+            }
+
+            let vol_ext_step = volume.particle_spec.extinction * (volume.density * step_ws);
+
+            let k_first = u32(max(0, i32(floor(s_start)) - i32(brick_s0)));
+            let k_last = min(brick_slices, u32(max(0, i32(ceil(s_end)) - i32(brick_s0))));
+
+            for (var k = k_first; k < k_last; k++) {
+                let s0 = f32(brick_s0 + k);
+                let s1 = s0 + 1.0;
+                let weights = volumetrics_sun_slice_volume_weight(
+                    volume,
+                    setup,
+                    s0,
+                    s1,
+                    1.0,
+                    col_start_ws,
+                    voxel_step_z_ws,
+                );
+                slab_od_half[k] += vol_ext_step * weights.x;
+                slab_od_full[k] += vol_ext_step * weights.y;
+            }
+        }
+
+        for (var k = 0u; k < brick_slices; k++) {
+            let mid_od = min(optical_depth + slab_od_half[k], vec3<f32>(F16_MAX));
+            textureStore(tSunShadowVolume, vec3<u32>(column, brick_s0 + k), vec4<f32>(mid_od, 0.0));
+            optical_depth += slab_od_full[k];
+        }
+    }
+}
+    `,
+    [
+        F16_MAX_DEFINITION,
+        F32_MAX_DEFINITION,
+        chunk_aabb3_slab_span,
+        chunk_mat4_extract_scale,
+        chunk_texel_coordinate_to_uv,
+        chunk_wind_field_sample,
+        chunk_participating_media_noise,
+        chunk_participating_media_volumes_iterate,
+        chunk_volumetrics_sun_shadow_group_list,
+    ]
+);
+
+const outermost_resources = new ShaderResourceSetDescriptor();
+
+outermost_resources.setImmediate("settings", VOLUMETRICS_SUN_SHADOW_BUILD_SETTINGS);
+
+wind_field_add_resources(outermost_resources.createGroup()
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addStorageBuffer("scene_database", WebGPUArray.u32)
+    .addStorageBuffer("group_lists", WebGPUArray.u32)
+    .addTexture("tParticipatingMediaNoise", "float", "3d")
+    .addSampler("sParticipatingMediaNoise", "filtering", PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR)
+    .addStorageTexture("tSunShadowVolume", "rgba16float", "3d", "write-only"));
+
+/**
+ * The outermost cascade. Nothing is outside it, so its scan seeds from any volumes in the upwind
+ * brick layer (`w <= 0`) and binds no outer cascade texture.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_volumetrics_build_sun_shadow_volume_outermost = ComputeShader.from({
+    label: 'Volumetrics / build sun shadow volume (outermost)',
+    resources: outermost_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION.join(",")})
+fn main(
+    @builtin(global_invocation_id) column : vec3<u32>
+){
+    let resolution = textureDimensions(tSunShadowVolume);
+
+    if(any(column.xy >= resolution.xy)){
+        return;
+    }
+
+    let cascade = settings.cascade;
+    let seed = volumetrics_sun_shadow_upwind_seed(column.xy, resolution, cascade);
+
+    volumetrics_sun_shadow_integrate_column(column.xy, resolution, cascade, seed);
+}
+    `, [
+            chunk_volumetrics_sun_shadow_column_scan,
+        ]
+    )
+});
+
+const seeded_resources = new ShaderResourceSetDescriptor();
+
+seeded_resources.setImmediate("settings", VOLUMETRICS_SUN_SHADOW_BUILD_SETTINGS);
+
+wind_field_add_resources(seeded_resources.createGroup()
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addStorageBuffer("scene_database", WebGPUArray.u32)
+    .addStorageBuffer("group_lists", WebGPUArray.u32)
+    .addTexture("tParticipatingMediaNoise", "float", "3d")
+    .addSampler("sParticipatingMediaNoise", "filtering", PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR)
+    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
+    .addTexture("tSunShadowOuter", "float", "3d")
+    .addStorageTexture("tSunShadowVolume", "rgba16float", "3d", "write-only"));
+
+/**
+ * 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_seeded = ComputeShader.from({
+    label: 'Volumetrics / build sun shadow volume (seeded)',
+    resources: seeded_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION.join(",")})
+fn main(
+    @builtin(global_invocation_id) column : vec3<u32>
+){
+    let resolution = textureDimensions(tSunShadowVolume);
+
+    if(any(column.xy >= resolution.xy)){
+        return;
+    }
+
+    let cascade = settings.cascade;
+    let uvw_to_ws = volumetrics_metadata.sun_shadow_uvw_to_ws[cascade];
+    let column_uv = texel_coordinate_to_uv(vec2<f32>(column.xy), resolution.xy);
+    let entry_ws = (uvw_to_ws * vec4<f32>(column_uv, 0.0, 1.0)).xyz;
+    let outer_uvw = (volumetrics_metadata.sun_shadow_ws_to_uvw[cascade + 1u] * vec4<f32>(entry_ws, 1.0)).xyz;
+    let seed = textureSampleLevel(tSunShadowOuter, sLinear, saturate(outer_uvw), 0.0).rgb;
+
+    volumetrics_sun_shadow_integrate_column(column.xy, resolution, cascade, seed);
+}
+    `, [
+            chunk_volumetrics_sun_shadow_column_scan,
+        ]
+    )
+});