@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/renderer/volumetrics/taa/chunk_volumetrics_taa_reproject.js

@@ -0,0 +1,168 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_cluster_depth_from_z_slice } from "../../light/cluster/chunk_cluster_depth_from_z_slice.js";
+import { chunk_cluster_depth_to_z_slice } from "../../light/cluster/chunk_cluster_depth_to_z_slice.js";
+import { chunk_frustum_sample_point } from "../../shader/chunk/geometry/frustum/chunk_frustum_sample_point.js";
+import { chunk_ndc_to_uv } from "../../shader/chunk/texture/chunk_ndc_to_uv.js";
+import { chunk_texel_coordinate_to_uv } from "../../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Froxel coordinate -> a sample point for `frustum_sample_point`, NOT a froxel texture coordinate.
+ *
+ * That distinction is the whole reason this is not `volumetrics_position_world_to_froxel_uvw`
+ * turned around. There `w` is slice space -- `log2(fma(depth, x, y)) * z`, corrected by the
+ * cell-averaged content offset -- because it addresses the 3D texture. Here `w` is a LINEAR
+ * fraction of the near..far range, because its only consumer is `frustum_sample_point`, which
+ * mixes the near and far planes linearly. The two agree at the endpoints and nowhere between, so
+ * feeding this `w` to a froxel textureSample reads the wrong slab.
+ *
+ * @see volumetrics_position_world_to_froxel_uvw
+ * @type {CodeChunk}
+ */
+const chunk_volumetrics_froxel_coord_to_frustum_uvw = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_froxel_coord_to_frustum_uvw(
+    coord: vec3<u32>,
+    res: vec3<u32>,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+    cluster_params: vec3f
+) -> vec3f {
+    let uv = texel_coordinate_to_uv(vec2f(coord.xy), res.xy);
+
+    // Logical near/far (clip_near_far), NOT the projection-derived range: the projection is
+    // infinite-far reverse-Z so its far resolves to ~3.4e38, which collapses z0_norm below to ~0
+    // (every slice maps to the near plane). This was the core reason TAA reprojection produced
+    // garbage. Matches the participating-media build shader.
+    let near_far = camera.clip_near_far;
+
+    // centre of the froxel along the depth curve
+    let depth_raw = cluster_depth_from_z_slice(
+        f32(coord.z) + 0.5,
+        cluster_params,
+        f32(res.z)
+    );
+
+    let view_depth = clamp(
+        depth_raw,
+        near_far.x,
+        near_far.y
+    );
+
+    let z0_norm = (view_depth - near_far.x) / (near_far.y - near_far.x);
+
+    return vec3f(uv, z0_norm);
+}
+    `, [
+        chunk_texel_coordinate_to_uv,
+        chunk_cluster_depth_from_z_slice,
+    ]
+);
+
+const chunk_world_pos_from_froxel = CodeChunk.from(
+    //language=WGSL
+    `
+// Helper to get world position from voxel index
+fn world_pos_from_froxel(
+    coord: vec3<u32>,
+    res: vec3<u32>,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+    cluster_params: vec3f,
+    frustum: array<vec4<f32>, 6>
+) -> vec3f {
+    let uvw = volumetrics_froxel_coord_to_frustum_uvw(coord, res, camera, cluster_params);
+
+    // Reconstruct the froxel-centre world position. frustum_sample_point intersects the
+    // interpolated L/R, B/T, N/F planes; X maps left->left and Z maps near->far directly, so only
+    // screen-Y is flipped vs world-Y (1.0 - uvw.y). The caller passes the metadata frustum, which
+    // carries a FINITE far plane — the camera's own projection is infinite-far reverse-Z (far plane
+    // zeroed), which frustum_sample_point cannot intersect. Mirrors the participating-media build
+    // shader's Y-only flip; replaces the old vec3(1.0) - uvw inside-out hack that mirrored X and Z.
+    return frustum_sample_point(frustum, vec3f(uvw.x, 1.0 - uvw.y, uvw.z));
+}
+`, [
+        chunk_volumetrics_froxel_coord_to_frustum_uvw,
+        chunk_frustum_sample_point,
+    ]);
+
+/**
+ * Where this frame's froxel was in last frame's froxel grid, for the volumetric TAA.
+ *
+ * Reconstructs the froxel centre in world space through the current camera's metadata frustum,
+ * then projects it through the previous camera. Returns `(prev_uvw, prev_depth)`: the first three
+ * are the history texture coordinate, the last is planar view depth in the previous camera, which
+ * `volumetrics_taa_history_valid` needs because a point behind that camera still projects to a uv
+ * in range -- the divide by a negative `w` mirrors it into the frame.
+ *
+ * A pure function of its arguments so `chunk_volumetrics_taa_reproject.spec.js` can drive it in
+ * the WGSL emulator against geometry-derived expectations; it was inline in the TAA body before.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_taa_reproject = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_taa_reproject(
+    coord: vec3<u32>,
+    res: vec3<u32>,
+    camera_current: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+    camera_previous: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+    cluster_params: vec3f,
+    frustum: array<vec4<f32>, 6>
+) -> vec4f {
+    let position_ws = world_pos_from_froxel(coord, res, camera_current, cluster_params, frustum);
+
+    // Planar view depth in the previous camera: the metric the cluster curve is built in.
+    let prev_view = camera_previous.view_matrix * vec4f(position_ws, 1.0);
+    let prev_depth = -prev_view.z;
+
+    // NDC through the UN-jittered projection. GPUCameraContext bakes the TAA sub-pixel jitter into
+    // the projection it uploads as a shear in m[8]/m[9] and nowhere else, while the metadata
+    // frustum the reconstruction above went through comes from the CPU camera and carries none.
+    // Reprojecting through view_projection_matrix therefore moved a static camera by last frame's
+    // jitter, up to 0.03 froxel, every frame. projection_infinite_reverse_z has no other
+    // off-diagonal terms, so the un-jittered clip.xy is the diagonal times view xy, and clip.w is
+    // -view.z, which is prev_depth. WGSL indexes a matrix by column: P[0][0] is m[0], P[1][1] m[5].
+    let P = camera_previous.projection_matrix;
+    let prev_ndc = vec2f(P[0][0] * prev_view.x, P[1][1] * prev_view.y) / prev_depth;
+
+    let prev_uv = ndc_to_uv(prev_ndc);
+
+    let prev_slice = cluster_depth_to_z_slice(
+        prev_depth,
+        cluster_params,
+        f32(res.z)
+    );
+
+    // prev_slice already lands at the reconstructed froxel's CENTRE — the reconstruction sampled
+    // cluster_depth_from_z_slice(voxel.z + 0.5), so for a static camera prev_slice == voxel.z + 0.5,
+    // whose texel-centre normalized coord is exactly prev_slice / res.z. Adding a further +0.5 here
+    // double-counted the texel-centre offset and sampled half a froxel too far in Z every frame: the
+    // history blurred slice z into z+1 and the 0.95 blend fed that error back (the visible noise).
+    let prev_w = prev_slice / f32(res.z);
+
+    return vec4f(prev_uv, prev_w, prev_depth);
+}
+
+// Reprojection must land inside the volume, and history must not be flagged for reset (first
+// frame / resize / teleport); otherwise the TAA falls back to the fresh sample.
+fn volumetrics_taa_history_valid(reprojection: vec4f, history_reset: u32) -> bool {
+    let prev_uvw = reprojection.xyz;
+    let prev_depth = reprojection.w;
+
+    // A froxel behind the previous camera has a negative depth there, and the divide by that
+    // negative w mirrored its NDC, so the uv alone can land inside the frame and lie. The Z half
+    // of the range test cannot fail, cluster_depth_to_z_slice clamps to [0, limit]; it is the xy
+    // that the range test is for.
+    return prev_depth > 0.0
+        && all(prev_uvw >= vec3f(0.0))
+        && all(prev_uvw <= vec3f(1.0))
+        && history_reset == 0u;
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+        chunk_world_pos_from_froxel,
+        chunk_cluster_depth_to_z_slice,
+        chunk_ndc_to_uv,
+    ]
+);

package/src/shade/renderer/volumetrics/taa/chunk_volumetrics_taa_resolve.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The volumetric TAA's resolve: clip the reprojected history to the neighbourhood box, then blend
+ * it with the current sample. Everything is in the encoded space the body works in, YCoCg for the
+ * scattering and the extinction as is.
+ *
+ * A pure function of the four vectors so `chunk_volumetrics_taa_resolve.spec.js` can drive it in
+ * the WGSL emulator; it was inline in the TAA body before.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_taa_resolve: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_taa_resolve.d.ts.map

package/src/shade/renderer/volumetrics/taa/chunk_volumetrics_taa_resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_taa_resolve.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/taa/chunk_volumetrics_taa_resolve.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,4CAFU,SAAS,CA2CjB;0BArDwB,oCAAoC"}

package/src/shade/renderer/volumetrics/taa/chunk_volumetrics_taa_resolve.js

@@ -0,0 +1,56 @@
+import { chunk_color_clip_to_aabb4 } from "../../postprocess/taa/chunk_color_clip_to_aabb3.js";
+import { chunk_aabb4_normalized_dist } from "../../shader/chunk/geometry/aabb3/chunk_aabb4_normalized_dist.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * The volumetric TAA's resolve: clip the reprojected history to the neighbourhood box, then blend
+ * it with the current sample. Everything is in the encoded space the body works in, YCoCg for the
+ * scattering and the extinction as is.
+ *
+ * A pure function of the four vectors so `chunk_volumetrics_taa_resolve.spec.js` can drive it in
+ * the WGSL emulator; it was inline in the TAA body before.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_taa_resolve = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_taa_resolve(
+    center: vec4f,
+    history: vec4f,
+    aabb_min: vec4f,
+    aabb_max: vec4f
+) -> vec4f {
+    // The box contains the centre by construction (volumetric_history_bounding_box), which is what
+    // makes this a clip: the history moves toward the centre until it enters the box.
+    let history_clamped = color_clip_to_aabb4(history, center, aabb_min, aabb_max);
+
+    // Karis, "High Quality Temporal Supersampling", SIGGRAPH 2014: detect when a clamp would occur
+    // and dampen the INCOMING sample's contribution to counteract it. The current sample is a 1-spp
+    // point sample of the froxel, so a jitter landing on a thin lit feature is an ordinary frame;
+    // without the damping that impulse moves the resolve by its full weight and the next frame's
+    // clip takes it back, which reads as flicker. t_clamp is 1 whenever the clip moved the
+    // history, and falls toward 0 as the history sits nearer the centre.
+    let t_clamp = saturate(aabb4_normalized_dist_from_center(
+        center,
+        history_clamped,
+        aabb_min,
+        aabb_max,
+    ));
+
+    // The 0.95 feedback the rest of the subsystem is tuned around (~39 effective samples). This
+    // used to damp the HISTORY by (1 - t^3), which is the rule backwards: any clipped voxel then
+    // output the raw sample, and under motion that was most of them. The quarter is a tuning
+    // value; what is fixed is the direction -- the damping can only lower the sample's pull.
+    const W_CURRENT = 0.05;
+    const W_CURRENT_CLAMPED = W_CURRENT * 0.25;
+
+    let w_current = mix(W_CURRENT, W_CURRENT_CLAMPED, t_clamp * t_clamp);
+
+    return mix(history_clamped, center, w_current);
+}
+    `, [
+        chunk_color_clip_to_aabb4,
+        chunk_aabb4_normalized_dist,
+    ]
+);

package/src/shade/renderer/volumetrics/taa/shader_volumetrics_taa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_volumetrics_taa.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/taa/shader_volumetrics_taa.js"],"names":[],"mappings":"AA0UA,mDAIG;8BApU2B,+BAA+B"}
+{"version":3,"file":"shader_volumetrics_taa.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/taa/shader_volumetrics_taa.js"],"names":[],"mappings":"AAkIA,mDAIG;8BAlI2B,+BAA+B"}