@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -1,290 +1,311 @@
-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);
-
-    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;
-
-            let position_ws = (uvw_to_ws * vec4<f32>(column_uv, w, 1.0)).xyz;
-
-            optical_depth += volumetrics_sample_froxel_extinction(position_ws) * 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;
-
-    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;
-
-            let position_ws = (uvw_to_ws * vec4<f32>(column_uv, w, 1.0)).xyz;
-
-            optical_depth += volumetrics_sample_froxel_extinction(position_ws) * sub_step_ws;
-        }
-    }
-}
-    `, [
-            CAMERA_UNIFORM_STRUCT.declaration_chunk,
-            chunk_texel_coordinate_to_uv,
-            chunk_volumetrics_sample_froxel_extinction,
-        ]
-    )
-});
+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,
+        ]
+    )
+});

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

@@ -1 +1 @@
-{"version":3,"file":"volumetrics_position_world_to_froxel_uvw.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/volumetrics_position_world_to_froxel_uvw.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,uDAFU,SAAS,CAyClB;0BA/CyB,iCAAiC"}
+{"version":3,"file":"volumetrics_position_world_to_froxel_uvw.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/volumetrics_position_world_to_froxel_uvw.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,uDAFU,SAAS,CAoBlB;0BA3ByB,iCAAiC"}