@woosh/meep-engine 3.11.1 → 3.11.3

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_integrate_optical_depth.js

@@ -1,76 +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>{
-
-    // 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,
-    ]
+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_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"}

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

@@ -0,0 +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,
+    ]
+);

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

@@ -0,0 +1,20 @@
+/**
+ * Extinction of the participating medium at a world position, or zero where the froxel grid does
+ * not reach.
+ *
+ * The grid is camera-shaped, so "does not reach" means outside the view frustum or past its far
+ * face — which is the medium's real extent as far as any consumer here is concerned, and the reason
+ * the sun's optical depth still stops at the frustum (Q-05) after this change as it did before it.
+ *
+ * The depth guard is not redundant with the bounds test. Behind the camera `view_depth` goes
+ * negative, the depth curve takes `log2` of a negative and yields NaN, and every comparison against
+ * NaN is false — so `any(abs(uvw - 0.5) >= 0.5)` reports the sample as *inside* and the fetch reads
+ * whatever the clamp lands on. The optical-depth march never had to care because it starts inside
+ * the frustum and breaks at the first sample outside it; a pass that sweeps a box does.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_sample_froxel_extinction: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_sample_froxel_extinction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_sample_froxel_extinction.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_sample_froxel_extinction.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,yDAFU,SAAS,CA4BjB;0BA9CwB,iCAAiC"}

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

@@ -0,0 +1,48 @@
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { volumetrics_position_world_to_froxel_uvw } from "./volumetrics_position_world_to_froxel_uvw.js";
+
+/**
+ * Extinction of the participating medium at a world position, or zero where the froxel grid does
+ * not reach.
+ *
+ * The grid is camera-shaped, so "does not reach" means outside the view frustum or past its far
+ * face — which is the medium's real extent as far as any consumer here is concerned, and the reason
+ * the sun's optical depth still stops at the frustum (Q-05) after this change as it did before it.
+ *
+ * The depth guard is not redundant with the bounds test. Behind the camera `view_depth` goes
+ * negative, the depth curve takes `log2` of a negative and yields NaN, and every comparison against
+ * NaN is false — so `any(abs(uvw - 0.5) >= 0.5)` reports the sample as *inside* and the fetch reads
+ * whatever the clamp lands on. The optical-depth march never had to care because it starts inside
+ * the frustum and breaks at the first sample outside it; a pass that sweeps a box does.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_sample_froxel_extinction = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_sample_froxel_extinction(position_ws: vec3<f32>) -> vec3<f32> {
+
+    let position_vs = camera.view_matrix * vec4<f32>(position_ws, 1.0);
+
+    // view space looks down -Z
+    let view_depth = -position_vs.z;
+
+    if (view_depth <= 0.0) {
+        return vec3<f32>(0.0);
+    }
+
+    let uvw = volumetrics_position_world_to_froxel_uvw(position_ws);
+
+    if (any(abs(uvw - 0.5) >= vec3<f32>(0.5))) {
+        return vec3<f32>(0.0);
+    }
+
+    return textureSampleLevel(tParticipatingMedia1, sLinear, uvw, 0.0).rgb;
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+        volumetrics_position_world_to_froxel_uvw,
+    ]
+);