@woosh/meep-engine 3.11.0 → 3.11.2

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

@@ -0,0 +1,145 @@
+import { LIGHT_DATABASE_SPEC } from "../light/LIGHT_DATABASE_SPEC.js";
+import { LIGHT_FLAGS } from "../light/model/io/LIGHT_FLAGS.js";
+import {
+    chunk_uv_octahedral_unit_encode
+} from "../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_encode.js";
+import { chunk_ndc_to_uv } from "../shader/chunk/texture/chunk_ndc_to_uv.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+const POINT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('light_point');
+const SPOT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('light_spot');
+const SHADOW_POINT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('shadow_point');
+const SHADOW_SPOT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('shadow_spot');
+
+/**
+ * Shadow visibility for clustered point and spot lights, sampled the way a *volume* wants rather
+ * than the way a surface does: one nearest texel out of the shadow atlas, no filter kernel, no
+ * receiver bias.
+ *
+ * This exists alongside {@link chunk_shadowmap_get_light_visibility} rather than replacing it. The
+ * deferred path needs its filtering — a hard shadow edge on a surface is a visible artefact — and
+ * its cost is paid once per pixel. Here the cost is paid once per light per froxel, with up to 255
+ * point and 255 spot lights in a cluster, and the playground scene alone carries 130 shadow-casting
+ * point lights. The two callers want genuinely different things out of the same atlas, so they get
+ * two functions over it; the atlas, its tile rects and its projections are untouched.
+ *
+ * Three reasons the cheap tap is not a compromise here:
+ *
+ *  - The value being sampled is already an average over a froxel slab several pixels across, it is
+ *    jittered in xy and in depth every frame, and it then goes through a 3x3x3 Blackman-Harris
+ *    temporal resample at a 0.95 blend. A PCF kernel would be filtering something about to be
+ *    filtered three more times. Frostbite takes exactly this route for its froxel pass and accepts
+ *    the aliasing; Wronski's alternative (a separate pre-filtered low-resolution ESM) needs its own
+ *    target and build pass, and cannot be a downsample of THIS atlas because blurring moments
+ *    bleeds across tile borders.
+ *
+ *  - There is no receiver bias because there is no receiver. Normal-offset and slope-scaled depth
+ *    bias exist to stop a surface shadowing itself; a medium cannot. Note that the deferred helpers
+ *    reach the same answer when a volumetric caller passes the light direction in place of a normal:
+ *    `get_shadow_offsets(N, L)` with `N == L` gives `cos_alpha = 1`, hence `sqrt(1 - 1) = 0` for the
+ *    normal scale and `0` for the depth scale, so both offsets vanish. Dropping them here therefore
+ *    does not change the sampled position relative to those helpers — only the tap count does.
+ *
+ *  - `textureLoad` rather than `textureGatherCompare`: the comparison is one instruction either way,
+ *    and the raw load carries no uniformity requirement, so it is legal in the middle of a
+ *    non-uniform light loop without the gather dance `shadowmap_sample_filtered` needs.
+ *
+ * Both functions early-out to 1.0 on a light with no `CASTS_SHADOW_BIT`, so a non-shadowing light in
+ * the cluster stays free.
+ *
+ * Requires `shadowmapAtlas` in the calling shader's scope.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_local_light_shadow = CodeChunk.from(
+    //language=WGSL
+    `
+/**
+ * Nearest texel of an atlas tile, given a uv over that tile. Clamped to the tile so a uv that lands
+ * exactly on the far edge (or drifts a hair past it) cannot read a neighbouring light's slot.
+ */
+fn volumetrics_shadow_atlas_texel(uv: vec2f, atlas_aabb: vec4f) -> vec2u {
+    let local = clamp(floor(uv * atlas_aabb.zw), vec2f(0.0), atlas_aabb.zw - 1.0);
+
+    return vec2u(local) + vec2u(atlas_aabb.xy);
+}
+
+fn volumetrics_point_light_shadow(
+    database: ptr<storage, array<u32>>,
+    point_index: u32,
+    position_ws: vec3f,
+) -> f32 {
+    let light = ${POINT_DESCRIPTOR.marshalling_method_read}(database, point_index);
+
+    if ((light.flags & ${LIGHT_FLAGS.CASTS_SHADOW_BIT}u) == 0u) {
+        return 1.0;
+    }
+
+    let atlas_aabb = ${SHADOW_POINT_DESCRIPTOR.marshalling_method_read}(database, light.shadow_id);
+
+    // the cube faces are captured FROM the light, so the octahedral encode takes light -> sample
+    let to_sample = position_ws - light.position;
+    let distance_to_center = length(to_sample);
+
+    let direction_light_to_sample = to_sample / max(distance_to_center, 1e-6);
+
+    // reverse-Z radial, matching what the point shadow pass stores: at the light -> 1, at or beyond
+    // the light's range -> 0.
+    let reference_depth = 1.0 - saturate(distance_to_center / max(light.distance, 1e-6));
+
+    let texel = volumetrics_shadow_atlas_texel(
+        uv_octahedral_unit_encode(direction_light_to_sample),
+        atlas_aabb
+    );
+
+    let stored = textureLoad(shadowmapAtlas, texel, 0);
+
+    // A larger stored value is NEARER the light, so an occluder in front of this froxel reads
+    // greater than the froxel's own radial depth. Cleared atlas regions hold 0 and therefore never
+    // occlude, which is the right default for a light whose map was not rendered this frame.
+    return select(1.0, 0.0, stored > reference_depth);
+}
+
+fn volumetrics_spot_light_shadow(
+    database: ptr<storage, array<u32>>,
+    spot_index: u32,
+    position_ws: vec3f,
+) -> f32 {
+    let light = ${SPOT_DESCRIPTOR.marshalling_method_read}(database, spot_index);
+
+    if ((light.flags & ${LIGHT_FLAGS.CASTS_SHADOW_BIT}u) == 0u) {
+        return 1.0;
+    }
+
+    let view_meta = ${SHADOW_SPOT_DESCRIPTOR.marshalling_method_read}(database, light.shadow_id);
+
+    // Spot shadows are a single perspective view, so the divide is load-bearing (unlike the ortho
+    // cascades, where w is always 1). No bias offset is added before the transform — see the header.
+    let clip_light = view_meta.projection * vec4(position_ws, 1.0);
+
+    if (clip_light.w <= 0.0) {
+        // behind the light's apex: outside the map entirely, and the cone attenuation has already
+        // zeroed this light's contribution, so the value is moot. Unshadowed is the safe answer.
+        return 1.0;
+    }
+
+    let pos_light = clip_light.xyz / clip_light.w;
+
+    let texel = volumetrics_shadow_atlas_texel(ndc_to_uv(pos_light.xy), view_meta.atlas);
+
+    let stored = textureLoad(shadowmapAtlas, texel, 0);
+
+    // SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR compares "greater" — visible where the receiver's depth
+    // exceeds the stored one, which under reverse-Z means nearer to the light. Reproduced here by
+    // hand because the raw load skips the comparison sampler.
+    return select(0.0, 1.0, pos_light.z > stored);
+}
+    `, [
+        POINT_DESCRIPTOR.chunk_read,
+        SPOT_DESCRIPTOR.chunk_read,
+        SHADOW_POINT_DESCRIPTOR.chunk_read,
+        SHADOW_SPOT_DESCRIPTOR.chunk_read,
+        chunk_ndc_to_uv,
+        chunk_uv_octahedral_unit_encode,
+    ]
+);

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

@@ -0,0 +1,20 @@
+/**
+ * Extinction of the participating medium at a world position, or zero where the froxel grid does
+ * not reach.
+ *
+ * The grid is camera-shaped, so "does not reach" means outside the view frustum or past its far
+ * face — which is the medium's real extent as far as any consumer here is concerned, and the reason
+ * the sun's optical depth still stops at the frustum (Q-05) after this change as it did before it.
+ *
+ * The depth guard is not redundant with the bounds test. Behind the camera `view_depth` goes
+ * negative, the depth curve takes `log2` of a negative and yields NaN, and every comparison against
+ * NaN is false — so `any(abs(uvw - 0.5) >= 0.5)` reports the sample as *inside* and the fetch reads
+ * whatever the clamp lands on. The optical-depth march never had to care because it starts inside
+ * the frustum and breaks at the first sample outside it; a pass that sweeps a box does.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_sample_froxel_extinction: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_sample_froxel_extinction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_sample_froxel_extinction.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_sample_froxel_extinction.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,yDAFU,SAAS,CA4BjB;0BA9CwB,iCAAiC"}

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

@@ -0,0 +1,48 @@
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { volumetrics_position_world_to_froxel_uvw } from "./volumetrics_position_world_to_froxel_uvw.js";
+
+/**
+ * Extinction of the participating medium at a world position, or zero where the froxel grid does
+ * not reach.
+ *
+ * The grid is camera-shaped, so "does not reach" means outside the view frustum or past its far
+ * face — which is the medium's real extent as far as any consumer here is concerned, and the reason
+ * the sun's optical depth still stops at the frustum (Q-05) after this change as it did before it.
+ *
+ * The depth guard is not redundant with the bounds test. Behind the camera `view_depth` goes
+ * negative, the depth curve takes `log2` of a negative and yields NaN, and every comparison against
+ * NaN is false — so `any(abs(uvw - 0.5) >= 0.5)` reports the sample as *inside* and the fetch reads
+ * whatever the clamp lands on. The optical-depth march never had to care because it starts inside
+ * the frustum and breaks at the first sample outside it; a pass that sweeps a box does.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_sample_froxel_extinction = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_sample_froxel_extinction(position_ws: vec3<f32>) -> vec3<f32> {
+
+    let position_vs = camera.view_matrix * vec4<f32>(position_ws, 1.0);
+
+    // view space looks down -Z
+    let view_depth = -position_vs.z;
+
+    if (view_depth <= 0.0) {
+        return vec3<f32>(0.0);
+    }
+
+    let uvw = volumetrics_position_world_to_froxel_uvw(position_ws);
+
+    if (any(abs(uvw - 0.5) >= vec3<f32>(0.5))) {
+        return vec3<f32>(0.0);
+    }
+
+    return textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0).rgb;
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+        volumetrics_position_world_to_froxel_uvw,
+    ]
+);

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;AAkDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,kDAFU,SAAS,CAkBjB;0BAzGwB,iCAAiC"}

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

@@ -0,0 +1,107 @@
+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;
+
+function cascade_lookup(index) {
+    return `
+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;
+}`;
+}
+
+function cascade_selection() {
+    const lines = [];
+
+    for (let index = 0; index < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1; index++) {
+        lines.push(`
+    {
+        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)
+            );
+        }
+    }`);
+    }
+
+    return lines.join("\n");
+}
+
+/**
+ * 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
+    `
+${Array.from({ length: VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT }, (_, index) => cascade_lookup(index)).join("\n")}
+
+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_${VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1}(position_ws);
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+    ]
+);

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

@@ -9,12 +9,15 @@
  * @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): {
+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: any;
     lut_multiple_scattering: any;
     lut_aerial: any;

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":"AAuSA;;;;;;;;;;;;;;;GAeG;AACH;;;;;EA0JC"}
+{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AAyYA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;EAqKC"}