@woosh/meep-engine 3.11.0 → 3.11.2

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

@@ -0,0 +1,252 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * How many voxels of empty margin the box keeps around the frustum's bounding sphere, per side.
+ *
+ * One is load-bearing, the rest is comfort. The sun-side face is where the optical-depth scan
+ * starts, so the slab it begins on must be guaranteed empty for the snap below to be free: the
+ * medium only exists inside the camera frustum, the sphere contains the frustum, so any slab
+ * outside the sphere integrates to zero and shifting the box by whole voxels cannot change the
+ * answer. Snapping moves the box by up to one voxel, which spends one of these.
+ *
+ * @type {number}
+ */
+const MARGIN_VOXELS = 2;
+
+/**
+ * Far distance of cascade `index`, i.e. the view depth its box has to cover.
+ *
+ * A logarithmic split, `far / ratio^(count - 1 - index)`. The choice is forced by what the cascades
+ * are for: every box is sized from the bounding sphere of the sub-frustum it covers, so its voxel is
+ * proportional to its far distance, and a constant ratio between far distances is a constant ratio
+ * between voxel sizes. Any other split leaves one cascade carrying a resolution jump the others do
+ * not.
+ *
+ * The innermost cascade still starts at the camera rather than at the previous cascade's far plane —
+ * cascades here nest rather than tile, because the box is sized from a *frustum's* bounding sphere
+ * and a shell would need a sphere around the shell, which is the outer sphere again.
+ *
+ * @param {number} far the full range the structure must cover
+ * @param {number} index
+ * @param {number} count
+ * @param {number} ratio
+ * @returns {number}
+ */
+export function volumetrics_sun_shadow_cascade_far(far, index, count, ratio) {
+    assert.isNumber(far, 'far');
+    assert.isNumber(index, 'index');
+
+    return far / Math.pow(ratio, count - 1 - index);
+}
+
+/**
+ * Radius of the smallest sphere containing a symmetric perspective frustum, and where its centre
+ * sits along the view axis.
+ *
+ * This is the quantity that makes the structure temporally stable, and the reason it is a sphere
+ * rather than a tight fit: it depends only on `fov`, `aspect`, `near` and `far`, so it does not
+ * change when the camera turns. A box sized from it therefore has a fixed extent, hence a fixed
+ * voxel size, hence a world-space voxel lattice that only ever translates.
+ *
+ * Both frustum corner rings are equidistant from the centre when
+ * `z = (far + near)(k^2 + 1) / 2` with `k^2 = tan^2(theta_x) + tan^2(theta_y)`. Past `z = far` that
+ * solution leaves the sphere behind the far plane, and the far ring alone bounds it.
+ *
+ * @param {number[]} out `[center_view_z, radius]`
+ * @param {number} fov_y vertical field of view, radians
+ * @param {number} aspect width / height
+ * @param {number} near
+ * @param {number} far
+ * @returns {number[]} out
+ */
+export function frustum_bounding_sphere(out, fov_y, aspect, near, far) {
+    const tan_y = Math.tan(fov_y * 0.5);
+    const tan_x = tan_y * aspect;
+
+    const k2 = tan_x * tan_x + tan_y * tan_y;
+
+    const center_z = (far + near) * (k2 + 1) * 0.5;
+
+    if (center_z >= far) {
+        out[0] = far;
+        out[1] = far * Math.sqrt(k2);
+    } else {
+        const d = center_z - far;
+        out[0] = center_z;
+        out[1] = Math.sqrt(k2 * far * far + d * d);
+    }
+
+    return out;
+}
+
+/**
+ * Orthonormal basis whose third axis is `direction`.
+ *
+ * A function of the direction alone, so a stationary sun produces a bit-identical basis every
+ * frame. The reference axis is the world axis least aligned with the direction, which keeps the
+ * cross product well conditioned; the frame necessarily has a seam somewhere (no continuous
+ * tangent frame exists on the sphere), and it sits where two components of `direction` tie.
+ *
+ * @param {Float32Array} out 9 floats, `[x_axis, y_axis, direction]`
+ * @param {ArrayLike<number>} direction unit length
+ */
+function orthonormal_basis(out, direction) {
+    const dx = direction[0], dy = direction[1], dz = direction[2];
+
+    const ax = Math.abs(dx), ay = Math.abs(dy), az = Math.abs(dz);
+
+    let rx = 0, ry = 0, rz = 0;
+
+    if (ax <= ay && ax <= az) {
+        rx = 1;
+    } else if (ay <= az) {
+        ry = 1;
+    } else {
+        rz = 1;
+    }
+
+    // x = normalize(cross(reference, direction))
+    let xx = ry * dz - rz * dy;
+    let xy = rz * dx - rx * dz;
+    let xz = rx * dy - ry * dx;
+
+    const x_length = Math.hypot(xx, xy, xz);
+    xx /= x_length;
+    xy /= x_length;
+    xz /= x_length;
+
+    // y = cross(direction, x)
+    const yx = dy * xz - dz * xy;
+    const yy = dz * xx - dx * xz;
+    const yz = dx * xy - dy * xx;
+
+    out[0] = xx;
+    out[1] = xy;
+    out[2] = xz;
+    out[3] = yx;
+    out[4] = yy;
+    out[5] = yz;
+    out[6] = dx;
+    out[7] = dy;
+    out[8] = dz;
+}
+
+const _sphere = [0, 0];
+const _basis = new Float32Array(9);
+
+/**
+ * Place the sun's optical-depth volume for this frame.
+ *
+ * The volume is a box aligned to the sun: its third axis is the direction light travels, so a
+ * column of voxels along that axis is a light ray, and the optical depth of every voxel in the
+ * column is one running sum away from its neighbour's. That is what
+ * `shader_volumetrics_build_sun_shadow_volume` computes and what
+ * `chunk_volumetrics_sun_optical_depth` reads back in a single fetch.
+ *
+ * Two properties matter and both are about time rather than space, because the froxel lighting this
+ * feeds goes through a 0.95-blend temporal filter that turns any instability into either ghosting
+ * or flicker:
+ *
+ *  - **The extent never changes with camera orientation.** It comes from the frustum's bounding
+ *    sphere, which is a function of the projection only. A tight fit of the frustum corners in sun
+ *    space — the obvious thing, and what this engine's CSM deliberately does for its cascades —
+ *    would breathe as the camera turned, moving every voxel centre continuously and making the
+ *    whole structure swim. The CSM can afford the tight fit because it is two orders of magnitude
+ *    denser and its consumer is a filtered depth comparison; this is neither.
+ *
+ *  - **The origin is snapped to a whole voxel.** With a fixed extent that makes the world-space
+ *    voxel lattice identical from frame to frame no matter how the camera moves: voxel centres land
+ *    on the same world positions, so the sampled medium is the same and the reconstruction is the
+ *    same function of world position. Only the indexing changes. The box shifts by whole voxels,
+ *    and the slab it gains or loses lies outside the frustum where the medium is zero, so even the
+ *    scan's starting value is unaffected.
+ *
+ * @param {Float32Array} ws_to_uvw 16 floats, column-major. World position -> [0,1]^3 volume coords.
+ * @param {Float32Array} uvw_to_ws 16 floats, column-major. Its inverse, for the build pass.
+ * @param {ArrayLike<number>} light_direction unit vector along which light TRAVELS (the
+ * `light_directional` table's `direction`, i.e. NOT the direction toward the light).
+ * @param {ArrayLike<number>} camera_position world space
+ * @param {ArrayLike<number>} camera_forward unit, world space
+ * @param {number} fov_y vertical field of view, radians
+ * @param {number} aspect width / height
+ * @param {number} near
+ * @param {number} far the depth the medium actually extends to — `min(froxel_far, camera.far)`,
+ * since the froxel grid is where the extinction is read from and it ends there.
+ * @param {ArrayLike<number>} resolution `[x, y, z]` voxel counts
+ * @returns {number} world-space length of one voxel along the sun axis, i.e. the scan's `dz`
+ */
+export function build_volumetrics_sun_shadow_transform({
+                                                           ws_to_uvw,
+                                                           uvw_to_ws,
+                                                           light_direction,
+                                                           camera_position,
+                                                           camera_forward,
+                                                           fov_y,
+                                                           aspect,
+                                                           near,
+                                                           far,
+                                                           resolution,
+                                                       }) {
+
+    assert.greaterThanOrEqual(ws_to_uvw.length, 16, 'ws_to_uvw must hold 16 floats');
+    assert.greaterThanOrEqual(uvw_to_ws.length, 16, 'uvw_to_ws must hold 16 floats');
+
+    frustum_bounding_sphere(_sphere, fov_y, aspect, near, far);
+
+    const center_distance = _sphere[0];
+    const radius = _sphere[1];
+
+    orthonormal_basis(_basis, light_direction);
+
+    const center_x = camera_position[0] + camera_forward[0] * center_distance;
+    const center_y = camera_position[1] + camera_forward[1] * center_distance;
+    const center_z = camera_position[2] + camera_forward[2] * center_distance;
+
+    uvw_to_ws[12] = 0;
+    uvw_to_ws[13] = 0;
+    uvw_to_ws[14] = 0;
+
+    for (let axis = 0; axis < 3; axis++) {
+        const ax = _basis[axis * 3];
+        const ay = _basis[axis * 3 + 1];
+        const az = _basis[axis * 3 + 2];
+
+        const count = resolution[axis];
+
+        // The sphere spans 2r; the box is MARGIN_VOXELS wider on each side, so solving
+        // `step * (count - 2 * MARGIN_VOXELS) == 2r` gives a step that leaves that margin exactly.
+        const step = (2 * radius) / (count - 2 * MARGIN_VOXELS);
+        const extent = step * count;
+
+        // where the box's centre sits on this axis, in sun space
+        const center = center_x * ax + center_y * ay + center_z * az;
+
+        const origin = Math.floor((center - extent * 0.5) / step) * step;
+
+        // ws_to_uvw row `axis`: dot(position, axis) / extent - origin / extent
+        ws_to_uvw[axis] = ax / extent;
+        ws_to_uvw[4 + axis] = ay / extent;
+        ws_to_uvw[8 + axis] = az / extent;
+        ws_to_uvw[12 + axis] = -origin / extent;
+
+        // uvw_to_ws column `axis`: the axis scaled to the full extent
+        uvw_to_ws[axis * 4] = ax * extent;
+        uvw_to_ws[axis * 4 + 1] = ay * extent;
+        uvw_to_ws[axis * 4 + 2] = az * extent;
+        uvw_to_ws[axis * 4 + 3] = 0;
+
+        // and accumulate the box origin into its translation column
+        uvw_to_ws[12] += ax * origin;
+        uvw_to_ws[13] += ay * origin;
+        uvw_to_ws[14] += az * origin;
+    }
+
+    ws_to_uvw[3] = 0;
+    ws_to_uvw[7] = 0;
+    ws_to_uvw[11] = 0;
+    ws_to_uvw[15] = 1;
+
+    uvw_to_ws[15] = 1;
+
+    return (2 * radius) / (resolution[2] - 2 * MARGIN_VOXELS);
+}

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

@@ -1,65 +1,76 @@
-import { chunk_frustum_clip_ray } from "../shader/chunk/geometry/frustum/chunk_frustum_clip_ray.js";
-import { RAY_STRUCT } from "../shader/chunk/geometry/ray/RAY_STRUCT.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { volumetrics_position_world_to_froxel_uvw } from "./volumetrics_position_world_to_froxel_uvw.js";
-
-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
-    ));
-            
-    if(frustum_tmax <= 0.0){
-        return vec3<f32>(0.0);
-    }
-    
-    // go as far as we can in frustum space
-    const STEP_COUNT = 16;
-    
-    let step_size = frustum_tmax / STEP_COUNT;
-    
-    var optical_depth = vec3<f32>(0.0);
-    
-    // offset ray forward a tiny mount to avoid aliasing
-    var t_previous = step_size * 0.1; 
-    var t_current = step_size;
-    
-    for(var i = 0; i < STEP_COUNT; i++){
-        
-        let position_ws = ray_ws.origin + ray_ws.direction * t_current;
-        
-        let uvw = volumetrics_position_world_to_froxel_uvw(position_ws);
-        
-        if(any(abs(uvw.xyz - 0.5) >= vec3(0.5))){
-            // out of bounds, stop integration
-            break;
-        }
-        
-        let t_delta = t_current - t_previous;
-        
-        let sample_extinction = textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0).rgb;
-        
-        optical_depth += sample_extinction * t_delta;
-        
-        // update
-        t_previous = t_current;
-        t_current += step_size;
-    }
-    
-    // if ray goes outside of the frustum, integrate over fog volumes
-    // TODO implement
-    
-    return optical_depth;
-}
-    `,
-    [
-        RAY_STRUCT.declaration_chunk,
-        volumetrics_position_world_to_froxel_uvw,
-        chunk_frustum_clip_ray,
-    ]
+import { chunk_frustum_clip_ray } from "../shader/chunk/geometry/frustum/chunk_frustum_clip_ray.js";
+import { RAY_STRUCT } from "../shader/chunk/geometry/ray/RAY_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { volumetrics_position_world_to_froxel_uvw } from "./volumetrics_position_world_to_froxel_uvw.js";
+
+export const chunk_integrate_optical_depth = CodeChunk.from(
+    //language=WGSL
+    `
+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);
+    }
+    
+    // go as far as we can in frustum space
+    const STEP_COUNT = 16;
+    
+    let step_size = frustum_tmax / STEP_COUNT;
+    
+    var optical_depth = vec3<f32>(0.0);
+    
+    // offset ray forward a tiny mount to avoid aliasing
+    var t_previous = step_size * 0.1; 
+    var t_current = step_size;
+    
+    for(var i = 0; i < STEP_COUNT; i++){
+        
+        let position_ws = ray_ws.origin + ray_ws.direction * t_current;
+        
+        let uvw = volumetrics_position_world_to_froxel_uvw(position_ws);
+        
+        if(any(abs(uvw.xyz - 0.5) >= vec3(0.5))){
+            // out of bounds, stop integration
+            break;
+        }
+        
+        let t_delta = t_current - t_previous;
+        
+        let sample_extinction = textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0).rgb;
+        
+        optical_depth += sample_extinction * t_delta;
+        
+        // update
+        t_previous = t_current;
+        t_current += step_size;
+    }
+    
+    // if ray goes outside of the frustum, integrate over fog volumes
+    // TODO implement
+    
+    return optical_depth;
+}
+    `,
+    [
+        RAY_STRUCT.declaration_chunk,
+        volumetrics_position_world_to_froxel_uvw,
+        chunk_frustum_clip_ray,
+    ]
 )

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/chunk_volumetrics_local_light_shadow.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_local_light_shadow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_local_light_shadow.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_local_light_shadow.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,mDAFU,SAAS,CA6FjB;0BA1IwB,iCAAiC"}