@woosh/meep-engine 3.11.1 → 3.11.2

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":"AA6SA;;;;;;;;;;;;;;;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"}