@woosh/meep-engine 3.11.0 → 3.11.1

package/src/shade/renderer/volumetrics/NOTES.md

@@ -6,4 +6,45 @@
 
 
 Check out "A Novel Sampling Algorithm for Fast and Stable Real-Time Volume Rendering" SIGGRAPH 2015
- * https://github.com/huwb/volsample/blob/master/src/shadertoy/clouds.shader
+ * https://github.com/huwb/volsample/blob/master/src/shadertoy/clouds.shader
+## Blue noise for the froxel column jitter — measured, 2026-08-29
+
+Considered as a fix for C-05 (adjacent columns carry independent jitter, so a trilinear XY fetch
+mixes slabs at different depths) and as groundwork for cutting `SAMPLE_COUNT`. Measured against the
+shipped `stbn_vec*.bin` volumes rather than argued. Three findings, one of which kills the original
+rationale.
+
+**Reusing `stbn_vec3` is not an option — it biases, and the bias does not converge away.**
+The aerial pass already reads `stbn_sample_vec3(vec3(voxel_coord.xy, view.frame_index))` and
+consumes all three channels (`.xy` for the tile UV, `.z` for the slice dither). A column jitter
+indexed the same way is *the same number* — correlation 1.0000, not merely "the same set". Two
+nuisance variables locked together stop exploring the unit square and only ever visit its diagonal,
+so the estimator converges to the wrong integral:
+
+| integrand over (j, d) | truth | naive `stbn_vec3.x` converges to | error |
+|---|---|---|---|
+| `j*d`          | 0.250 | 0.334 | +34% |
+| `exp(-3(j+d))` | 0.100 | 0.167 | +67% |
+| `step(j > d)`  | 0.500 | 0.000 | −100% |
+
+RMSE is flat from N=32 to N=128 in every case. That is bias, not noise — no TAA window fixes it.
+
+**An independent source is fine, and converges faster than the hash.** `stbn_vec1` is a separate
+scalar 128×128×64 volume, already loaded by `STATIC_GRAPHICS_ENGINE_ASSETS`, uniform to 0.75%, and
+decorrelated from all three `stbn_vec3` channels (|r| ≤ 0.0018). RMSE on `j*d`: 0.0478 vs the
+murmur hash's 0.0632 at N=8, 0.0149 vs 0.0219 at N=64 — roughly 1.3–1.5× better across the window
+the 0.95 TAA blend actually spans (~39 effective samples). Bias ≤ 0.0025.
+
+Caveat: STBN stops improving past N=64, the volume's temporal depth, while white noise keeps going —
+at N=128 the hash wins. The TAA never reaches that regime, but anything accumulating longer would.
+
+**It does not fix C-05, it makes it slightly worse.** Blue noise is built to make neighbours
+*maximally different*; C-05 wants them *similar*. Measured adjacent-column jitter difference:
+hash 0.3331 (neighbour r = 0.0005, i.e. independent), `stbn_vec1` 0.3656 (neighbour r = −0.112,
+anti-correlated). So it widens the cross-column depth mixing by ~10%.
+
+Conclusion: C-05 stays closed as a documented non-issue — it is zero-mean, the TAA integrates it
+away, and the obvious fix aggravates the stated mechanism. Genuinely removing it means dropping the
+XY jitter (the TAA's 3×3×3 Blackman–Harris resample already does spatial reconstruction), not
+changing the noise source. Adopt `stbn_vec1` when cutting `SAMPLE_COUNT` (P-01), where better
+per-pixel temporal distribution is the actual goal — and never `stbn_vec3`, for the reason above.

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

@@ -0,0 +1,21 @@
+/**
+ * Converts a planar view-space depth into a distance along a unit-length view ray.
+ *
+ * The froxel depth curve is planar. `cluster_depth_from_z_slice` and its inverse are built in
+ * `-position_vs.z` — that is what `build_light_cluster_parameters` is derived from, what
+ * `volumetrics_position_world_to_froxel_uvw` reads back, and what the deferred composite feeds in
+ * (`get_view_space_depth` is a function of the depth buffer alone, with no screen-position term, so
+ * it cannot be anything else). `camera_ray_from_uv` returns a *unit* direction. A ray therefore
+ * reaches the depth plane at `depth` only after travelling `depth / cos(theta)`, where theta is the
+ * angle off the camera forward axis.
+ *
+ * Multiplying a planar depth by a unit direction stops on the arc of constant distance instead —
+ * exact on the centre axis, and short by cos(theta) everywhere else, which reads as a radial error
+ * rather than an offset and is why it survives casual inspection.
+ *
+ * @see shader_volumetrics_build_lighting, shader_volumetrics_build_scattering_lut
+ * @type {CodeChunk}
+ */
+export const chunk_camera_ray_planar_depth_scale: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_camera_ray_planar_depth_scale.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_camera_ray_planar_depth_scale.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_camera_ray_planar_depth_scale.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAFU,SAAS,CA2BjB;0BA7CwB,iCAAiC"}

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

@@ -0,0 +1,47 @@
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * Converts a planar view-space depth into a distance along a unit-length view ray.
+ *
+ * The froxel depth curve is planar. `cluster_depth_from_z_slice` and its inverse are built in
+ * `-position_vs.z` — that is what `build_light_cluster_parameters` is derived from, what
+ * `volumetrics_position_world_to_froxel_uvw` reads back, and what the deferred composite feeds in
+ * (`get_view_space_depth` is a function of the depth buffer alone, with no screen-position term, so
+ * it cannot be anything else). `camera_ray_from_uv` returns a *unit* direction. A ray therefore
+ * reaches the depth plane at `depth` only after travelling `depth / cos(theta)`, where theta is the
+ * angle off the camera forward axis.
+ *
+ * Multiplying a planar depth by a unit direction stops on the arc of constant distance instead —
+ * exact on the centre axis, and short by cos(theta) everywhere else, which reads as a radial error
+ * rather than an offset and is why it survives casual inspection.
+ *
+ * @see shader_volumetrics_build_lighting, shader_volumetrics_build_scattering_lut
+ * @type {CodeChunk}
+ */
+export const chunk_camera_ray_planar_depth_scale = CodeChunk.from(
+    //language=WGSL
+    `
+fn camera_ray_planar_depth_scale(
+    direction_ws: vec3<f32>,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref}
+) -> f32 {
+
+    // The z row of the view matrix dotted with the direction — i.e. (V * vec4(dir, 0)).z without
+    // the rest of the multiply. WGSL indexes a matrix by column, so m[c][2] walks that row.
+    // View space looks down -Z, so negate to get a positive cosine for a forward-going ray.
+    let cos_theta = -(
+        camera.view_matrix[0][2] * direction_ws.x
+        + camera.view_matrix[1][2] * direction_ws.y
+        + camera.view_matrix[2][2] * direction_ws.z
+    );
+
+    // A ray at or past 90 degrees off-axis never reaches the plane at all. Clamping rather than
+    // dividing by ~0 keeps the caller finite; no froxel ray is anywhere near this, since every one
+    // of them lies inside the frustum.
+    return 1.0 / max(cos_theta, 1e-4);
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+    ]
+);

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_integrate_optical_depth.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_integrate_optical_depth.js"],"names":[],"mappings":"AAKA,sDA2DC;0BA9DyB,iCAAiC"}
+{"version":3,"file":"chunk_integrate_optical_depth.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_integrate_optical_depth.js"],"names":[],"mappings":"AAKA,sDAsEC;0BAzEyB,iCAAiC"}

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

@@ -6,14 +6,25 @@ import { volumetrics_position_world_to_froxel_uvw } from "./volumetrics_position
 export const chunk_integrate_optical_depth = CodeChunk.from(
     //language=WGSL
     `
-fn integrate_optical_depth(ray_ws: ${RAY_STRUCT.wgsl_ref}) -> vec3<f32>{ 
-    
-    var frustum_tmax = min(ray_ws.tmax, frustum_clip_ray(
-        ray_ws.origin,
-        ray_ws.direction,
-        camera.frustum
-    ));
-            
+fn integrate_optical_depth(ray_ws: ${RAY_STRUCT.wgsl_ref}) -> vec3<f32>{
+
+    // volumetrics_metadata.frustum, NOT camera.frustum. The camera's frustum has no usable far
+    // plane: an infinite reverse-Z projection puts (0,0,0,near) in row 2 of the VP, a normal that
+    // cannot be normalized, so PerspectiveCamera.update_frustum zeroes the entry outright.
+    // frustum_clip_ray then discards it — correctly — which leaves the frustum OPEN at the far end,
+    // and a ray whose direction lies inside the view cone crosses no plane outward at all. t_exit
+    // stays at its 1e20 sentinel; capped by a directional light's tmax of 1.496e11 that gives a
+    // step of ~9.35e9, so the first sample lands far outside the grid, the loop below breaks on
+    // iteration one, and this returns zero — no media self-shadowing at all whenever the sun is in
+    // front of the camera, which is exactly when shafts are wanted.
+    //
+    // The metadata frustum is the same one rebuilt with a FINITE far plane
+    // (update_frustum_far_plane), which the participating-media pass already slices against.
+    var frustum_tmax = min(
+        ray_ws.tmax,
+        frustum_clip_ray(ray_ws.origin, ray_ws.direction, volumetrics_metadata.frustum)
+    );
+
     if(frustum_tmax <= 0.0){
         return vec3<f32>(0.0);
     }

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

@@ -0,0 +1,37 @@
+/**
+ * Where a froxel's stored value actually sits inside its slab, in slices from the slab's near face.
+ *
+ * The froxel grid is *cell-averaged*: texel `k` holds an average over the slab spanning slice
+ * coordinates `[k + j, k + 1 + j]`, where `j` is the shared column jitter. Reading it back by depth
+ * therefore needs the inverse of that, and the centroid is not the midpoint — the lighting pass
+ * importance-samples uniformly in `z^3` (a froxel's volume grows as `z^2`), and the depth curve is
+ * exponential, so the mean lands slightly past halfway.
+ *
+ * With `r` the per-slice depth ratio — constant on a log curve, which is what makes the answer the
+ * same for every slice and every jitter:
+ *
+ *     z(u)      = z0 * (1 + u (r^3 - 1))^(1/3),   u ~ U(0,1)
+ *     offset(u) = ln(1 + u (r^3 - 1)) / (3 ln r)
+ *     E[offset] = r^3 / (r^3 - 1) - 1 / (3 ln r)
+ *
+ * That runs ~0.525 to ~0.543 across the depth ranges this engine uses, and tends to exactly 0.5 as
+ * the curve flattens toward linear. Treating it as 0.5 — or, as the shipping code did, addressing
+ * texel `k` as if it held slice `k` — leaves a systematic bias of about half a froxel, which on a
+ * 64-slice log grid is a ~7% depth error at every distance.
+ *
+ * The jitter `j` is deliberately NOT corrected for here. It is zero-mean, so the temporal filter
+ * integrates it away, and a sample lands between two columns carrying *different* jitters anyway
+ * (see C-05) — so there is no single `j` to subtract. What is left after this is the part that does
+ * not average out.
+ *
+ * Contrast the aerial LUT, which is *boundary-sampled*: it stores at texel `k` the integral
+ * accumulated up to `from_z_slice(k)`, so texel `k` really is slice `k` and the plain `+0.5`
+ * texel-centre convention is correct there. Two grids, two conventions; the bug was applying the
+ * boundary one to the cell-averaged textures.
+ *
+ * @see volumetrics_position_world_to_froxel_uvw, shader_volumetrics_build_lighting
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_froxel_content_offset: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_froxel_content_offset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_froxel_content_offset.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_froxel_content_offset.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,sDAFU,SAAS,CAqBjB;0BAvDwB,iCAAiC"}

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

@@ -0,0 +1,56 @@
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * Where a froxel's stored value actually sits inside its slab, in slices from the slab's near face.
+ *
+ * The froxel grid is *cell-averaged*: texel `k` holds an average over the slab spanning slice
+ * coordinates `[k + j, k + 1 + j]`, where `j` is the shared column jitter. Reading it back by depth
+ * therefore needs the inverse of that, and the centroid is not the midpoint — the lighting pass
+ * importance-samples uniformly in `z^3` (a froxel's volume grows as `z^2`), and the depth curve is
+ * exponential, so the mean lands slightly past halfway.
+ *
+ * With `r` the per-slice depth ratio — constant on a log curve, which is what makes the answer the
+ * same for every slice and every jitter:
+ *
+ *     z(u)      = z0 * (1 + u (r^3 - 1))^(1/3),   u ~ U(0,1)
+ *     offset(u) = ln(1 + u (r^3 - 1)) / (3 ln r)
+ *     E[offset] = r^3 / (r^3 - 1) - 1 / (3 ln r)
+ *
+ * That runs ~0.525 to ~0.543 across the depth ranges this engine uses, and tends to exactly 0.5 as
+ * the curve flattens toward linear. Treating it as 0.5 — or, as the shipping code did, addressing
+ * texel `k` as if it held slice `k` — leaves a systematic bias of about half a froxel, which on a
+ * 64-slice log grid is a ~7% depth error at every distance.
+ *
+ * The jitter `j` is deliberately NOT corrected for here. It is zero-mean, so the temporal filter
+ * integrates it away, and a sample lands between two columns carrying *different* jitters anyway
+ * (see C-05) — so there is no single `j` to subtract. What is left after this is the part that does
+ * not average out.
+ *
+ * Contrast the aerial LUT, which is *boundary-sampled*: it stores at texel `k` the integral
+ * accumulated up to `from_z_slice(k)`, so texel `k` really is slice `k` and the plain `+0.5`
+ * texel-centre convention is correct there. Two grids, two conventions; the bug was applying the
+ * boundary one to the cell-averaged textures.
+ *
+ * @see volumetrics_position_world_to_froxel_uvw, shader_volumetrics_build_lighting
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_froxel_content_offset = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_froxel_content_offset(cluster_scale: f32) -> f32 {
+
+    // r = 2^(1/scale) is the depth ratio across one slice, so ln(r) = ln(2) / scale
+    let ln_r = 0.69314718 / max(cluster_scale, 1e-6);
+
+    // As the curve flattens both terms below diverge while their difference tends to 1/2. Bail out
+    // before the subtraction loses its significant digits rather than after.
+    if (ln_r < 1e-3) {
+        return 0.5;
+    }
+
+    let r3 = exp(3.0 * ln_r);
+
+    return r3 / (r3 - 1.0) - 1.0 / (3.0 * ln_r);
+}
+    `
+);

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

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

@@ -239,6 +239,11 @@ function graph_integrate_light_scattering({
             magFilter: "linear",
         }));
 
+        // Spatiotemporal blue noise for the per-froxel sample offset. The pass takes one sample and
+        // leans on the volumetric TAA to integrate, which only works if each froxel's sequence over
+        // frames is well distributed — the property a per-froxel hash does not have.
+        const tSTBN_vec3 = context.graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
+
         const encoder = context.encoder;
 
         shader_volumetrics_build_lighting.dispatch({
@@ -253,6 +258,7 @@ function graph_integrate_light_scattering({
                 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),

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":"AA+TA,8DAIE;8BA9S4B,4BAA4B"}
+{"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"}