@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -1,145 +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,
-    ]
-);
+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_sun_optical_depth.d.ts.map

@@ -1 +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"}
+{"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

@@ -29,21 +29,48 @@ export function volumetrics_sun_shadow_texture_name(index) {
  */
 const CASCADE_BLEND_START = 0.9;
 
-function cascade_lookup(index) {
-    return `
+/**
+ * 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 = "";
 
-function cascade_selection() {
-    const lines = [];
+for (let index = 0; index < LAST_CASCADE; index++) {
 
-    for (let index = 0; index < VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1; index++) {
-        lines.push(`
+    //language=WGSL
+    cascade_selection += `
     {
         let far = volumetrics_metadata.sun_shadow_cascade_far[${index}];
         let blend_start = far * ${CASCADE_BLEND_START};
@@ -59,10 +86,8 @@ function cascade_selection() {
                 (view_depth - blend_start) / (far - blend_start)
             );
         }
-    }`);
     }
-
-    return lines.join("\n");
+`;
 }
 
 /**
@@ -91,15 +116,13 @@ function cascade_selection() {
 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")}
-
+${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_${VOLUMETRICS_SUN_SHADOW_CASCADE_COUNT - 1}(position_ws);
+${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
@@ -18,8 +30,8 @@
  * @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, sun_shadow_resolution, volumetrics_metadata, taa_history, taa_output, camera_previous, }: FrameGraph): {
-    lut_transmittance: any;
-    lut_multiple_scattering: any;
+    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":"AAyYA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;EAqKC"}
+{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AAyBA;;;;;;;GAOG;AACH,4DAFa;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAC,CAgEjE;AAqTD;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;EAwKC"}