@woosh/meep-engine 3.11.1 → 3.11.3

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

@@ -0,0 +1,38 @@
+/**
+ * Name of the texture holding cascade `index` of the sun's optical-depth volume.
+ *
+ * Generated rather than written out because the cascade count is a constant and everything that
+ * touches the structure — this chunk, the lighting pass's resource set, the frame graph — has to
+ * agree with it. A name spelled by hand in one of those places is the way a fourth cascade turns
+ * into a silent black frame.
+ *
+ * @param {number} index
+ * @returns {string}
+ */
+export function volumetrics_sun_shadow_texture_name(index: number): string;
+/**
+ * Optical depth of the participating medium between a world position and the sun, in one fetch.
+ *
+ * Same quantity `integrate_optical_depth` returns for a directional light, and deliberately the
+ * same signature shape, so the two are interchangeable at the call site. What it does not expose is
+ * how the answer was produced: the caller passes a world position and gets an integral back, and
+ * whether that came from a light-aligned prefix scan, a Fourier basis or a march is not its
+ * business. Swapping the representation should not touch `shader_volumetrics_build_lighting`.
+ *
+ * Cascades are selected on **view depth**, not on containment in each box. The two agree — every
+ * box is sized from the bounding sphere of the sub-frustum out to that depth, so a froxel at or
+ * inside it is inside the box — and only the first gives a scalar to blend along. It also makes the
+ * branch uniform across a workgroup: the lighting pass dispatches one froxel slice per workgroup in
+ * z, and a slice is a surface of constant depth.
+ *
+ * The `saturate` in each lookup is a statement about the domain rather than a clamp that fires.
+ * Selection has already established the position is inside the cascade it reads; outside, the
+ * sensible reading of a clamped fetch is still the right one, since the outermost box's faces sit
+ * in empty space and the value there is the column's total.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume, build_volumetrics_sun_shadow_transform
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_sun_optical_depth: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_sun_optical_depth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_sun_optical_depth.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_sun_optical_depth.js"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,2DAHW,MAAM,GACJ,MAAM,CAIlB;AA2ED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,kDAFU,SAAS,CAgBjB;0BAhIwB,iCAAiC"}

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

@@ -0,0 +1,130 @@
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT } from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
+
+/**
+ * Name of the texture holding cascade `index` of the sun's optical-depth volume.
+ *
+ * Generated rather than written out because the cascade count is a constant and everything that
+ * touches the structure — this chunk, the lighting pass's resource set, the frame graph — has to
+ * agree with it. A name spelled by hand in one of those places is the way a fourth cascade turns
+ * into a silent black frame.
+ *
+ * @param {number} index
+ * @returns {string}
+ */
+export function volumetrics_sun_shadow_texture_name(index) {
+    return `tSunShadowCascade${index}`;
+}
+
+/**
+ * Fraction of a cascade's range at which it starts handing over to the next one out.
+ *
+ * The two cascades do not agree where they meet — that is the entire point of having two, one is
+ * more accurate than the other — so a hard switch is a visible edge at a fixed view depth, which is
+ * to say a ring around the screen that the 0.95-blend froxel TAA would smear rather than remove.
+ * Cascaded shadow maps blend across a band for the same reason.
+ *
+ * @type {number}
+ */
+const CASCADE_BLEND_START = 0.9;
+
+/**
+ * Outermost cascade. It is where the selection ladder falls out to, so it is the one cascade with
+ * no successor to hand over to, and therefore the bound on the ladder rather than a step in it.
+ *
+ * @type {number}
+ */
+const LAST_CASCADE = VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1;
+
+/**
+ * One `volumetrics_sun_optical_depth_cascade_<index>` per cascade.
+ *
+ * @type {string}
+ */
+let cascade_lookups = "";
+
+for (let index = 0; index < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT; index++) {
+
+    //language=WGSL
+    cascade_lookups += `
+fn volumetrics_sun_optical_depth_cascade_${index}(position_ws: vec3<f32>) -> vec3<f32> {
+
+    let uvw = (volumetrics_metadata.sun_shadow_ws_to_uvw[${index}] * vec4<f32>(position_ws, 1.0)).xyz;
+
+    return textureSampleLevel(${volumetrics_sun_shadow_texture_name(index)}, sLinear, saturate(uvw), 0.0).rgb;
+}
+`;
+}
+
+/**
+ * The ladder that picks between those lookups, one block per hand-over, spliced into the body of
+ * `volumetrics_sun_optical_depth`. Indexed over the same cascades and one short, so a cascade
+ * declared above and never reached here is a function nothing samples, and a block here naming a
+ * cascade not declared above is a call to a function that does not exist.
+ *
+ * @type {string}
+ */
+let cascade_selection = "";
+
+for (let index = 0; index < LAST_CASCADE; index++) {
+
+    //language=WGSL
+    cascade_selection += `
+    {
+        let far = volumetrics_metadata.sun_shadow_cascade_far[${index}];
+        let blend_start = far * ${CASCADE_BLEND_START};
+
+        if (view_depth < blend_start) {
+            return volumetrics_sun_optical_depth_cascade_${index}(position_ws);
+        }
+
+        if (view_depth < far) {
+            return mix(
+                volumetrics_sun_optical_depth_cascade_${index}(position_ws),
+                volumetrics_sun_optical_depth_cascade_${index + 1}(position_ws),
+                (view_depth - blend_start) / (far - blend_start)
+            );
+        }
+    }
+`;
+}
+
+/**
+ * Optical depth of the participating medium between a world position and the sun, in one fetch.
+ *
+ * Same quantity `integrate_optical_depth` returns for a directional light, and deliberately the
+ * same signature shape, so the two are interchangeable at the call site. What it does not expose is
+ * how the answer was produced: the caller passes a world position and gets an integral back, and
+ * whether that came from a light-aligned prefix scan, a Fourier basis or a march is not its
+ * business. Swapping the representation should not touch `shader_volumetrics_build_lighting`.
+ *
+ * Cascades are selected on **view depth**, not on containment in each box. The two agree — every
+ * box is sized from the bounding sphere of the sub-frustum out to that depth, so a froxel at or
+ * inside it is inside the box — and only the first gives a scalar to blend along. It also makes the
+ * branch uniform across a workgroup: the lighting pass dispatches one froxel slice per workgroup in
+ * z, and a slice is a surface of constant depth.
+ *
+ * The `saturate` in each lookup is a statement about the domain rather than a clamp that fires.
+ * Selection has already established the position is inside the cascade it reads; outside, the
+ * sensible reading of a clamped fetch is still the right one, since the outermost box's faces sit
+ * in empty space and the value there is the column's total.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume, build_volumetrics_sun_shadow_transform
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_sun_optical_depth = CodeChunk.from(
+    //language=WGSL
+    `
+${cascade_lookups}
+fn volumetrics_sun_optical_depth(position_ws: vec3<f32>) -> vec3<f32> {
+
+    // view space looks down -Z
+    let view_depth = -(camera.view_matrix * vec4<f32>(position_ws, 1.0)).z;
+${cascade_selection}
+    return volumetrics_sun_optical_depth_cascade_${LAST_CASCADE}(position_ws);
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+    ]
+);

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

@@ -1,3 +1,15 @@
+/**
+ * Transmittance LUT, then the multiple-scattering LUT that reads it. Exported for
+ * `graph_integrate_sky.spec.js`, which pins the dispatch shape and the transient's usage
+ * flags -- neither of which the WGSL validity gate can see.
+ *
+ * @param {FrameGraph} graph
+ * @returns {{transmittance_lut: number, multiscatted_lut: number}} resource handles
+ */
+export function graph_integrate_sky({ graph }: FrameGraph): {
+    transmittance_lut: number;
+    multiscatted_lut: number;
+};
 /**
  *
  * @param {FrameGraph} graph
@@ -9,14 +21,17 @@
  * @param {number} light_cluster_parameters
  * @param {number} shadowmap_atlas
  * @param {number[]} volumetric_resolution
+ * @param {number[]} sun_shadow_resolution voxel counts of one Q-04 sun optical-depth cascade;
+ * `[1, 1, 1]` when the froxels are marching instead, which keeps the passes in the graph without
+ * doing any work
  * @param {number} volumetrics_metadata
  * @param {number} [taa_history] imported previous-frame accumulated scattering volume
  * @param {number} [taa_output] imported destination for this frame's accumulated scattering volume
  * @param {GPUCameraContext} [camera_previous] previous-frame camera, for temporal reprojection
  */
-export function graph_build_volumetrics({ graph, camera, lights, view, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetric_resolution, volumetrics_metadata, taa_history, taa_output, camera_previous, }: FrameGraph): {
-    lut_transmittance: any;
-    lut_multiple_scattering: any;
+export function graph_build_volumetrics({ graph, camera, lights, view, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetric_resolution, sun_shadow_resolution, volumetrics_metadata, taa_history, taa_output, camera_previous, }: FrameGraph): {
+    lut_transmittance: number;
+    lut_multiple_scattering: number;
     lut_aerial: any;
     volumetrics_metadata: FrameGraph;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AA6SA;;;;;;;;;;;;;;;GAeG;AACH;;;;;EA0JC"}
+{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AA4BA;;;;;;;GAOG;AACH,4DAFa;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAC,CAgEjE;AAqTD;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;EAwKC"}

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

@@ -1,25 +1,43 @@
-
-
 import { assert } from "../../../core/assert.js";
 import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.js";
 import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
+import { shader_multiscatter_lut } from "../atmosphere/shader_multiscatter_lut.js";
+import { shader_transmittance_lut } from "../atmosphere/shader_transmittance_lut.js";
+import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
+import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
 import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR } from "../texture/DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR.js";
-import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
-import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
-import { shader_multiscatter_lut } from "../atmosphere/shader_multiscatter_lut.js";
-import { shader_transmittance_lut } from "../atmosphere/shader_transmittance_lut.js";
-import { shader_volumetrics_build_lighting } from "./shader_volumetrics_build_lighting.js";
+import { volumetrics_sun_shadow_texture_name } from "./chunk_volumetrics_sun_optical_depth.js";
+import {
+    shader_volumetrics_build_lighting,
+    VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION
+} from "./shader_volumetrics_build_lighting.js";
 import { shader_volumetrics_build_participating_media } from "./shader_volumetrics_build_participating_media.js";
 import { shader_volumetrics_build_scattering_lut } from "./shader_volumetrics_build_scattering_lut.js";
+import {
+    shader_volumetrics_build_sun_shadow_volume_outermost,
+    shader_volumetrics_build_sun_shadow_volume_seeded
+} from "./shader_volumetrics_build_sun_shadow_volume.js";
 import { shader_volumetrics_taa } from "./taa/shader_volumetrics_taa.js";
+import {
+    VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT,
+    VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION,
+    volumetrics_sun_shadow_sub_steps
+} from "./VOLUMETRICS_SUN_SHADOW_RESOLUTION.js";
 
 /**
+ * Transmittance LUT, then the multiple-scattering LUT that reads it. Exported for
+ * `graph_integrate_sky.spec.js`, which pins the dispatch shape and the transient's usage
+ * flags -- neither of which the WGSL validity gate can see.
  *
  * @param {FrameGraph} graph
+ * @returns {{transmittance_lut: number, multiscatted_lut: number}} resource handles
  */
-function graph_integrate_sky({ graph }) {
+export function graph_integrate_sky({ graph }) {
+
+    graph.push_scope("integrate sky");
+
     const t_data = {};
 
     const t_pass = graph.add("transmittance", t_data, (data, resources, context) => {
@@ -31,7 +49,10 @@ function graph_integrate_sky({ graph }) {
         const settings_type = shader_transmittance_lut.descriptor.resources.getResourceByName("settings").buffer_type;
 
         const settings = encoder.allocateTransientValueBuffer(settings_type, {
-            steps: 40
+            steps: 40,
+            // taken off the target being drawn into, so the generator cannot be told a size
+            // the texture does not have
+            resolution: [output.width, output.height],
         });
 
         shader_transmittance_lut.draw({
@@ -53,46 +74,28 @@ function graph_integrate_sky({ graph }) {
         usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
     }));
 
-    const m_data = {};
-
-    const m_pass = graph.add("multiscatter lut", m_data, (data, resources, context) => {
-        const output = resources.get(data.output);
-
-        const settings_type = shader_multiscatter_lut.descriptor.resources.getResourceByName("settings").buffer_type;
-
-        const encoder = context.encoder;
-
-        const settings = encoder.allocateTransientValueBuffer(settings_type, {
-            steps: 20,
-            sqrt_samples: 8,
-        });
+    // The transient does not exist yet at graph-build time, so the dispatch cannot be
+    // counted off it the way GPUSky does; one local value feeds both instead.
+    const multiscatter_resolution = [32, 32];
 
-        const tSkyLutTransmittance = resources.get(data.tSkyLutTransmittance);
-
-        shader_multiscatter_lut.draw({
-            encoder: encoder,
-            bindings: {
-                settings,
-                tSkyLutTransmittance
-            },
-            colorAttachments: [{
-                view: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                loadOp: "clear",
-                storeOp: "store",
-            }]
-        })
+    const multiscatter_outputs = graph_compute_pass({
+        graph,
+        shader: shader_multiscatter_lut,
+        // one workgroup per LUT texel, each thread integrating one direction
+        group_count: [multiscatter_resolution[0], multiscatter_resolution[1], 1],
+        bindings: {
+            tSkyLutTransmittance: t_data.output,
+            tSkyLutMultiscatterOut: TextureResourceDescriptor.from({
+                resolution: multiscatter_resolution,
+                format: "rgba16float",
+                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING
+            })
+        }
     });
 
-    m_data.output = m_pass.create("multiscatter lut", TextureResourceDescriptor.from({
-        resolution: [32, 32],
-        format: "rgba16float",
-        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
-    }))
-
-    m_data.tSkyLutTransmittance = m_pass.read(t_data.output);
+    graph.pop_scope();
 
-
-    return { transmittance_lut: t_data.output, multiscatted_lut: m_data.output };
+    return { transmittance_lut: t_data.output, multiscatted_lut: multiscatter_outputs.tSkyLutMultiscatterOut };
 }
 
 
@@ -182,6 +185,97 @@ function graph_integrate_participating_media({
     };
 }
 
+/**
+ * Q-04. The sun's optical depth, integrated once per frame into cascaded light-aligned volumes so
+ * the lighting pass can read it in a single fetch instead of marching toward the sun from every
+ * froxel.
+ *
+ * Sits between the participating-media build and the lighting pass because it reads the former and
+ * is read by the latter; the frame graph derives that ordering from the handles alone. The cascades
+ * are ordered among themselves for the same reason: each one is seeded from the value the cascade
+ * outside it already computed at its entry face, so the outermost is built first and the handle it
+ * returns is what makes the next pass wait for it.
+ *
+ * A texture per cascade rather than one texture with the cascades stacked along w. Stacking would
+ * put a pass's own output and its input in the same texture, which WebGPU rejects — a subresource
+ * cannot be bound as writable storage and as a sampled texture at once — and there is no
+ * subresource finer than the whole 3D texture to split it on.
+ *
+ * Always present, even with the mode off — the volumes are then dispatched at 1x1x1 (see
+ * `GPUViewVolumetrics`), which keeps the graph's topology identical on both sides of the A/B. A
+ * pass appearing and disappearing would change resource aliasing and pass scheduling along with the
+ * thing being measured, and this subsystem has already produced one confident wrong answer from a
+ * measurement where the two sides did not pay the same fixed costs.
+ *
+ * @param {FrameGraph} graph
+ * @param {GPUCameraContext} camera
+ * @param {number} participating_media1
+ * @param {number} volumetrics_metadata
+ * @param {number[]} resolution voxel counts of one cascade
+ * @returns {number[]} handles of the cascades, innermost first
+ */
+function graph_build_sun_shadow_volume({
+                                           graph,
+                                           camera,
+                                           participating_media1,
+                                           volumetrics_metadata,
+                                           resolution,
+                                       }) {
+
+    const camera_buffer = graph_import_buffer(graph, camera.buffer.buffer, "volumetrics sun shadow camera");
+
+    const group_count = [
+        // one invocation per COLUMN along the sun axis, so only x and y are dispatched
+        Math.ceil(resolution[0] / VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION[0]),
+        Math.ceil(resolution[1] / VOLUMETRICS_SUN_SHADOW_WORKGROUP_RESOLUTION[1]),
+        1,
+    ];
+
+    const cascades = [];
+
+    for (let cascade = VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1; cascade >= 0; cascade--) {
+
+        // Every cascade but the outermost starts its scan from the one outside it — which the
+        // descending loop has already added, and which is the one difference the two build shaders
+        // exist for.
+        const seeded = cascade < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1;
+
+        const bindings = {
+            // which cascade this dispatch is building; the shader is shared across all of them
+            settings: {
+                cascade,
+                sub_steps: volumetrics_sun_shadow_sub_steps(cascade),
+            },
+            camera: camera_buffer,
+            volumetrics_metadata,
+            tParticipatingMedia1: participating_media1,
+            tSunShadowVolume: TextureResourceDescriptor.from({
+                resolution,
+                dimension: "3d",
+                format: "rgba16float",
+                usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING
+            }),
+        };
+
+        if (seeded) {
+            bindings.tSunShadowOuter = cascades[cascade + 1];
+        }
+
+        const outputs = graph_compute_pass({
+            graph,
+            shader: seeded
+                ? shader_volumetrics_build_sun_shadow_volume_seeded
+                : shader_volumetrics_build_sun_shadow_volume_outermost,
+            group_count,
+            bindings,
+        });
+
+        cascades[cascade] = outputs.tSunShadowVolume;
+    }
+
+    return cascades;
+}
+
 /**
  *
  * @param {FrameGraph} graph
@@ -194,6 +288,7 @@ function graph_integrate_participating_media({
  * @param shadowmap_atlas
  * @param sun_transmittance_lut
  * @param sun_multiple_scattering_lut
+ * @param {number[]} sun_shadow_cascades handles of the Q-04 optical-depth cascades, innermost first
  * @param lights
  * @param view
  * @param camera
@@ -210,6 +305,7 @@ function graph_integrate_light_scattering({
                                               shadowmap_atlas,
                                               sun_transmittance_lut,
                                               sun_multiple_scattering_lut,
+                                              sun_shadow_cascades,
                                               lights,
                                               view,
                                               camera,
@@ -233,6 +329,7 @@ function graph_integrate_light_scattering({
 
         const sun_transmittance_lut = resources.get(data.sun_transmittance_lut);
         const sun_multiple_scattering_lut = resources.get(data.sun_multiple_scattering_lut);
+        const sun_shadow_cascades = data.sun_shadow_cascades.map(handle => resources.get(handle));
 
         const sampler_shadowmap = context.graphics.samplers.obtain(SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR);
         const sLinear = context.graphics.samplers.obtain(SamplerDescriptor.from({
@@ -246,32 +343,40 @@ function graph_integrate_light_scattering({
 
         const encoder = context.encoder;
 
+        const bindings = {
+            camera: camera.buffer.buffer,
+            view: view.uniform_buffer.buffer,
+            volumetrics_metadata,
+            sLinear,
+            tSunTransmittance: sun_transmittance_lut.obtainView(),
+            tMultiScattering: sun_multiple_scattering_lut.obtainView(),
+            tSTBN_vec3: tSTBN_vec3.obtainView(),
+            tParticipatingMedia0: participating_media0.obtainView(),
+            tParticipatingMedia1: participating_media1.obtainView(),
+            tLighting: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
+            //
+            light_data: lights.buffer_data,
+
+            cluster_data: light_cluster_data,
+            cluster_lookup: light_cluster_lookup,
+            cluster_parameters: light_cluster_parameters,
+
+            shadowmapAtlas: shadowmap_atlas.obtainView(),
+            sCompareLinear: sampler_shadowmap,
+        };
+
+        // One texture per cascade, under the names the read side declares. Bound here rather than
+        // above because the count is a constant of the structure, not of this pass.
+        for (let cascade = 0; cascade < sun_shadow_cascades.length; cascade++) {
+            bindings[volumetrics_sun_shadow_texture_name(cascade)] = sun_shadow_cascades[cascade].obtainView();
+        }
+
         shader_volumetrics_build_lighting.dispatch({
             encoder,
-            group_count_x: Math.ceil(output.width / 16),
-            group_count_y: Math.ceil(output.height / 16),
-            group_count_z: output.depth,
-            bindings: {
-                camera: camera.buffer.buffer,
-                view: view.uniform_buffer.buffer,
-                volumetrics_metadata,
-                sLinear,
-                tSunTransmittance: sun_transmittance_lut.obtainView(),
-                tMultiScattering: sun_multiple_scattering_lut.obtainView(),
-                tSTBN_vec3: tSTBN_vec3.obtainView(),
-                tParticipatingMedia0: participating_media0.obtainView(),
-                tParticipatingMedia1: participating_media1.obtainView(),
-                tLighting: output.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
-                //
-                light_data: lights.buffer_data,
-
-                cluster_data: light_cluster_data,
-                cluster_lookup: light_cluster_lookup,
-                cluster_parameters: light_cluster_parameters,
-
-                shadowmapAtlas: shadowmap_atlas.obtainView(),
-                sCompareLinear: sampler_shadowmap,
-            }
+            group_count_x: Math.ceil(output.width / VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION[0]),
+            group_count_y: Math.ceil(output.height / VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION[1]),
+            group_count_z: Math.ceil(output.depth / VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION[2]),
+            bindings
         })
     });
 
@@ -286,6 +391,7 @@ function graph_integrate_light_scattering({
 
     data.sun_transmittance_lut = pass.read(sun_transmittance_lut);
     data.sun_multiple_scattering_lut = pass.read(sun_multiple_scattering_lut);
+    data.sun_shadow_cascades = sun_shadow_cascades.map(handle => pass.read(handle));
 
     data.output = pass.create("Light Scattering LUT", TextureResourceDescriptor.from({
         resolution,
@@ -310,6 +416,9 @@ function graph_integrate_light_scattering({
  * @param {number} light_cluster_parameters
  * @param {number} shadowmap_atlas
  * @param {number[]} volumetric_resolution
+ * @param {number[]} sun_shadow_resolution voxel counts of one Q-04 sun optical-depth cascade;
+ * `[1, 1, 1]` when the froxels are marching instead, which keeps the passes in the graph without
+ * doing any work
  * @param {number} volumetrics_metadata
  * @param {number} [taa_history] imported previous-frame accumulated scattering volume
  * @param {number} [taa_output] imported destination for this frame's accumulated scattering volume
@@ -325,6 +434,7 @@ export function graph_build_volumetrics({
                                             light_cluster_parameters,
                                             shadowmap_atlas,
                                             volumetric_resolution,
+                                            sun_shadow_resolution,
                                             volumetrics_metadata,
                                             taa_history,
                                             taa_output,
@@ -333,6 +443,9 @@ export function graph_build_volumetrics({
 
     assert.defined(view, 'view');
     assert.defined(volumetric_resolution, 'volumetric_resolution');
+    assert.defined(sun_shadow_resolution, 'sun_shadow_resolution');
+
+    graph.push_scope("build volumetrics");
 
     const { transmittance_lut, multiscatted_lut } = graph_integrate_sky({ graph: graph });
 
@@ -348,6 +461,14 @@ export function graph_build_volumetrics({
         camera,
     });
 
+    const sun_shadow_cascades = graph_build_sun_shadow_volume({
+        graph,
+        camera,
+        participating_media1,
+        volumetrics_metadata,
+        resolution: sun_shadow_resolution,
+    });
+
     const light_scattering_lut = graph_integrate_light_scattering({
         graph,
         resolution: volumetric_resolution,
@@ -355,6 +476,7 @@ export function graph_build_volumetrics({
         view,
         sun_transmittance_lut: transmittance_lut,
         sun_multiple_scattering_lut: multiscatted_lut,
+        sun_shadow_cascades,
         participating_media0,
         participating_media1,
         volumetrics_metadata,
@@ -409,7 +531,6 @@ export function graph_build_volumetrics({
 
 
         const graphics = context.graphics;
-        const device = graphics.device;
 
         const sLinear = graphics.samplers.obtain(SamplerDescriptor.from({
             magFilter: "linear",
@@ -463,6 +584,8 @@ export function graph_build_volumetrics({
 
     // TODO add temporal reprojection
 
+    graph.pop_scope();
+
     return {
         lut_transmittance: transmittance_lut,
         lut_multiple_scattering: multiscatted_lut,

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

@@ -1,3 +1,19 @@
+/**
+ * Workgroup shape of this pass, `[x, y, z]` in froxels, read by both the `@workgroup_size` below
+ * and the dispatch in `graph_build_volumetrics` so the two cannot drift.
+ *
+ * Flat in z. Lights are binned into 3D clusters and the largest distance between neighbouring
+ * clusters is along depth, so a group spanning z is the one spanning the most unrelated light
+ * lists.
+ *
+ * 64 invocations — one wave64, two warps — is a deliberate trade: 16x16x1 measures faster on the
+ * RTX 4090 this was benchmarked on, and is kept off because that part's register file is unusually
+ * large and the result is not expected to generalize (AMD favours smaller groups). NOTES.md carries
+ * the numbers and the reasoning.
+ *
+ * @type {number[]}
+ */
+export const VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION: number[];
 export const shader_volumetrics_build_lighting: ComputeShader;
 import { ComputeShader } from "../shader/ComputeShader.js";
 //# sourceMappingURL=shader_volumetrics_build_lighting.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shader_volumetrics_build_lighting.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_lighting.js"],"names":[],"mappings":"AA0WA,8DAIE;8BA1V4B,4BAA4B"}
+{"version":3,"file":"shader_volumetrics_build_lighting.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/shader_volumetrics_build_lighting.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;GAcG;AACH,wDAFU,MAAM,EAAE,CAEiD;AAkXnE,8DAIE;8BA9Z4B,4BAA4B"}