@woosh/meep-engine 3.49.0 → 3.51.0

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

@@ -5,14 +5,17 @@
 /**
  * Every participating medium in a scene, and a counter saying whether the GPU's copy is stale.
  *
- * **The version is the whole synchronisation protocol.** {@link GPUSceneVolumetrics} repacks the
- * entire table whenever the number moves and does nothing at all when it does not, so a volume
- * changed without moving the counter renders with the values it was last uploaded with — the CPU
+ * **Two versions are the whole synchronisation protocol.** {@link GPUSceneVolumetrics} repacks the
+ * entire table whenever {@link version} moves; while only {@link noise_version} moves it writes the
+ * noise phases of the rows whose phases changed; when neither moves it does nothing at all. A volume
+ * changed without moving a counter renders with the values it was last uploaded with — the CPU
  * object holds the new density, reads back correctly, and only the picture is stale. Anything that
- * writes into a volume in place therefore has to say so; see {@link invalidate}.
+ * writes into a volume in place therefore has to say so; see {@link invalidate} and
+ * {@link invalidate_noise}.
  *
  * **Volumes are packed by array index**, so removing one renumbers the rest. That is free here
- * because the upload is all-or-nothing, and it is the reason no volume carries a slot number.
+ * because adding or removing repacks the whole table, and it is the reason no volume carries a slot
+ * number.
  */
 export class SceneVolumetrics {
     /**
@@ -24,14 +27,17 @@ export class SceneVolumetrics {
     version = 0;
 
     /**
-     * The wind every volume's noise scrolls with, metres a second along the world axes. Each
-     * volume feels it through its own `noise_wind_factor` and adds its own velocity; the fold is
-     * `ParticipatingMediaSystem`'s, once a frame, and the result is a scroll phase on the volume —
-     * this number itself never reaches the GPU.
+     * A second counter, for the one change that happens every frame: a volume's noise phases
+     * (`noise_offset`, `noise_warp_offset`) moved and nothing else about any volume did. While only
+     * this one moves, {@link GPUSceneVolumetrics} writes each row's phase words where they differ
+     * from what it last wrote, and nothing else of the table; see {@link invalidate_noise}.
      *
-     * @type {number[]}
+     * A move of {@link version} covers the phases too: the whole table is repacked from the volumes
+     * as they stand.
+     *
+     * @type {number}
      */
-    wind = [0, 0, 0];
+    noise_version = 0;
 
     /**
      *
@@ -75,4 +81,17 @@ export class SceneVolumetrics {
     invalidate() {
         this.version++;
     }
+
+    /**
+     * Say that volumes already in the scene had their noise phases advanced in place, and nothing
+     * else about them changed.
+     *
+     * The cheap path: a scrolling field moves its phases every frame, and they are six words of a
+     * row, so a frame that only scrolls writes those words per row instead of repacking the table
+     * (re-inverting every transform). Anything else written into a volume still owes an
+     * {@link invalidate}.
+     */
+    invalidate_noise() {
+        this.noise_version++;
+    }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"VOLUMETRICS_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/VOLUMETRICS_METADATA_STRUCT.js"],"names":[],"mappings":"AAKA,uDA+EG;6BAlF0B,gCAAgC"}
+{"version":3,"file":"VOLUMETRICS_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/VOLUMETRICS_METADATA_STRUCT.js"],"names":[],"mappings":"AAKA,uDA+EU;6BAlFmB,gCAAgC"}

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

@@ -82,4 +82,4 @@ export const VOLUMETRICS_METADATA_STRUCT = WebGPUStruct.from({
      * are short and local and there is far less to amortize.
      */
     sun_shadow_light_index: u32,
-});
+}).pack();

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

@@ -0,0 +1,17 @@
+/**
+ * The froxel grid's parameters (`VOLUMETRICS_METADATA_STRUCT`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_METADATA_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The integrated froxel volume.
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The participating media's extinction, per froxel.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PARTICIPATING_MEDIA_1_RESOURCE: ShaderResourceDescriptor;
+import { ShaderResourceDescriptor } from "../shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=VOLUMETRICS_RESOURCES.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VOLUMETRICS_RESOURCES.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/VOLUMETRICS_RESOURCES.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,4CAFU,wBAAwB,CAEiG;AAEnI;;;GAGG;AACH,mCAFU,wBAAwB,CAEkE;AAEpG;;;GAGG;AACH,6CAFU,wBAAwB,CAEoF;yCAnB7E,gDAAgD"}

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

@@ -0,0 +1,20 @@
+import { ShaderResourceDescriptor } from "../shader/resource/ShaderResourceDescriptor.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "./VOLUMETRICS_METADATA_STRUCT.js";
+
+/**
+ * The froxel grid's parameters (`VOLUMETRICS_METADATA_STRUCT`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_METADATA_RESOURCE = ShaderResourceDescriptor.uniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT);
+
+/**
+ * The integrated froxel volume.
+ * @type {ShaderResourceDescriptor}
+ */
+export const VOLUMETRICS_RESOURCE = ShaderResourceDescriptor.texture("tVolumetrics", "float", "3d");
+
+/**
+ * The participating media's extinction, per froxel.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PARTICIPATING_MEDIA_1_RESOURCE = ShaderResourceDescriptor.texture("tParticipatingMedia1", "float", "3d");

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

@@ -161,7 +161,15 @@ of the volume, identical for every thread, so a uniform branch and not a variant
 
 **Global wind — `SceneVolumetrics.wind`, felt per medium.** Per Alex's F7: effective velocity
 `= wind × noise_wind_factor + noise_velocity`, two explicit fields on the component, folded by the
-system into the phase. The row carries phases only.
+system into the phase. The row carries phases only. *Superseded 2026-10-16 (GPU fluid S3,
+`GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md` §6): `SceneVolumetrics.wind` is removed, and a scroll
+writes each row's phase words through `SceneVolumetrics.invalidate_noise()` instead of repacking the
+table. The phases fold the scene's far field (`GPUFluidSystem.far_field`, still air without one);
+the fluid's departure from it is sampled on the GPU wherever the noise is evaluated and carries the
+noise as a flow map, on a flow clock the host folds into the row (`noise_flow_phase`, period 2.5 s),
+scaled by `noise_wind_factor`, which the row now carries too. A per-volume read-back of the wind was
+built first and withdrawn on Alex's word: the data is on the GPU. The scroll also changed sign: it
+had carried the noise upwind.*
 
 **Where the froxel pass evaluates it.** Once per froxel, before the volume loop, a world point
 inside the slab at an STBN jitter with a **third** decorrelation offset `(53, 97)` — the aerial pass
@@ -248,7 +256,7 @@ ECS, flat on `ParticipatingMedia`:
     noise_wind_factor = 1        // how much of the scene wind it feels
     noise_texture     = 0        // atlas slot; 0 = the engine's
 
-Scene: `SceneVolumetrics.wind` (m/s). Tiles: `GPUSceneVolumetrics.noise_atlas` —
+Scene: `SceneVolumetrics.wind` (m/s) — removed 2026-10-16, see above. Tiles: `GPUSceneVolumetrics.noise_atlas` —
 `allocate()`, `write(slot, Uint8Array(128³))`, `free(slot)`.
 
 Renderer-side `ParticipatingMediaVolume`: `noise_strength`, `noise_scale`, `noise_warp`,
@@ -259,7 +267,9 @@ anything moved.
 GPU row, appended to `PARTICIPATING_MEDIA_VOLUME_STRUCT`: `noise_offset: vec3f`,
 `noise_warp_offset: vec3f`, `noise_slot: u32`, `noise_strength: f32`, `noise_inverse_scale: f32`,
 `noise_warp: f32`. Packed by `GPUSceneVolumetrics` whenever the version moves — which, while any
-volume's phase moves, is every frame (tens of rows).
+volume's phase moves, is every frame (tens of rows). *Since 2026-10-16 a scroll moves
+`SceneVolumetrics.noise_version` instead, and only the moved rows' phase words go up: seven, with
+`noise_flow_phase`; `noise_wind_factor` and `noise_flow_phase` sit in the padding after `density`.*
 
 Serialization: `ParticipatingMediaSerializationAdapter` version 1 (eighteen doubles),
 `ParticipatingMediaSerializationUpgrader_0_1` fills a version-0 save with the defaults.

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,sDAsEC;0BAzEyB,iCAAiC"}
+{"version":3,"file":"chunk_integrate_optical_depth.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_integrate_optical_depth.js"],"names":[],"mappings":"AAOA,sDAsEC;0BA3EyB,iCAAiC"}

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

@@ -1,76 +1,82 @@
-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";
+import { SAMPLER_LINEAR_RESOURCE } from "../texture/SAMPLER_LINEAR_RESOURCE.js";
+import { PARTICIPATING_MEDIA_1_RESOURCE, VOLUMETRICS_METADATA_RESOURCE } from "./VOLUMETRICS_RESOURCES.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,
+    ]
+)
+
+chunk_integrate_optical_depth.requireResource(SAMPLER_LINEAR_RESOURCE);
+chunk_integrate_optical_depth.requireResource(PARTICIPATING_MEDIA_1_RESOURCE);
+chunk_integrate_optical_depth.requireResource(VOLUMETRICS_METADATA_RESOURCE);

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

@@ -7,9 +7,10 @@
  *   smoothstep over `fade_distance` (in world units, unaffected by scale) that
  *   `compute_volume_fade_factor` evaluates at a froxel's midpoint; here it is the field itself. The
  *   noise is `chunk_participating_media_noise`'s [0, 1] multiplier from the volumetrics noise
- *   atlas, which an importing shader therefore binds as `tParticipatingMediaNoise` with
- *   `sParticipatingMediaNoise`. Bounded above by `density`, so `density * extinction` majorizes
- *   the volume anywhere in it.
+ *   atlas, carried by the scene's wind at the point, which an importing shader therefore binds as
+ *   `tParticipatingMediaNoise` with `sParticipatingMediaNoise`, and the wind field as
+ *   `wind_field_add_resources` declares it. Bounded above by `density`, so `density * extinction`
+ *   majorizes the volume anywhere in it.
  * - `participating_media_volume_span` is where a ray is inside the box, as distances along it,
  *   clipped to `[0, t_max]`; empty (`y <= x`) when it misses. The direction need not be unit
  *   length, and the distances are in its units: the local direction is not renormalized.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_participating_media_volume_sample.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sDAFU,SAAS,CAwDjB;0BA/EwB,iCAAiC"}
+{"version":3,"file":"chunk_participating_media_volume_sample.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,sDAFU,SAAS,CAwDjB;0BAhFwB,iCAAiC"}

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

@@ -13,9 +13,10 @@ import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_
  *   smoothstep over `fade_distance` (in world units, unaffected by scale) that
  *   `compute_volume_fade_factor` evaluates at a froxel's midpoint; here it is the field itself. The
  *   noise is `chunk_participating_media_noise`'s [0, 1] multiplier from the volumetrics noise
- *   atlas, which an importing shader therefore binds as `tParticipatingMediaNoise` with
- *   `sParticipatingMediaNoise`. Bounded above by `density`, so `density * extinction` majorizes
- *   the volume anywhere in it.
+ *   atlas, carried by the scene's wind at the point, which an importing shader therefore binds as
+ *   `tParticipatingMediaNoise` with `sParticipatingMediaNoise`, and the wind field as
+ *   `wind_field_add_resources` declares it. Bounded above by `density`, so `density * extinction`
+ *   majorizes the volume anywhere in it.
  * - `participating_media_volume_span` is where a ray is inside the box, as distances along it,
  *   clipped to `[0, t_max]`; empty (`y <= x`) when it misses. The direction need not be unit
  *   length, and the distances are in its units: the local direction is not renormalized.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_volumetrics_froxel_uvw_from_clip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_froxel_uvw_from_clip.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,qDAFU,SAAS,CAmCjB;0BAnDwB,iCAAiC"}
+{"version":3,"file":"chunk_volumetrics_froxel_uvw_from_clip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_froxel_uvw_from_clip.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,qDAFU,SAAS,CAmCjB;0BApDwB,iCAAiC"}

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

@@ -1,5 +1,6 @@
 import { chunk_ndc_to_uv } from "../shader/chunk/texture/chunk_ndc_to_uv.js";
 import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { VOLUMETRICS_METADATA_RESOURCE } from "./VOLUMETRICS_RESOURCES.js";
 
 /**
  * Froxel-grid texture coordinates of a point given as its clip position and its planar view depth.
@@ -51,3 +52,5 @@ fn volumetrics_froxel_uvw_from_clip(
         chunk_ndc_to_uv,
     ]
 );
+
+chunk_volumetrics_froxel_uvw_from_clip.requireResource(VOLUMETRICS_METADATA_RESOURCE);

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

@@ -1 +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"}
+{"version":3,"file":"chunk_volumetrics_local_light_shadow.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_local_light_shadow.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,mDAFU,SAAS,CA6FjB;0BA3IwB,iCAAiC"}

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

@@ -5,6 +5,7 @@ import {
 } 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";
+import { SHADOWMAP_ATLAS_RESOURCE } from "../shadow/map/SHADOWMAP_RESOURCES.js";
 
 const POINT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('light_point');
 const SPOT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('light_spot');
@@ -143,3 +144,5 @@ fn volumetrics_spot_light_shadow(
         chunk_uv_octahedral_unit_encode,
     ]
 );
+
+chunk_volumetrics_local_light_shadow.requireResource(SHADOWMAP_ATLAS_RESOURCE);

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

@@ -0,0 +1,36 @@
+/**
+ * The participating-media build's workgroup, in froxels: flat in z, one slice a group. Read by its
+ * `@workgroup_size`, by the bin that pre-culls the volumes for each of those groups, and by the
+ * dispatches of both.
+ * @type {number[]}
+ */
+export const VOLUMETRICS_MEDIA_WORKGROUP_RESOLUTION: number[];
+/**
+ * The most volumes of its group's list a froxel of the participating-media build walks. Chosen, not
+ * derived. Past it the build drops the group's highest-indexed volumes, whatever each froxel would
+ * have made of them.
+ * @type {number}
+ */
+export const VOLUMETRICS_MEDIA_GROUP_VOLUME_BUDGET: number;
+/**
+ * The volumes each workgroup of the participating-media build may see, as one list per group: a
+ * bitmask over the volumes' rows, `list_words` words a group, the groups in `grid3d_to_index` order.
+ * The bin writes it, and the build walks its own group's list in row order instead of every volume.
+ *
+ * - `volumetrics_media_groups` is the build's workgroup grid over a froxel grid.
+ * - `volumetrics_media_list_words` is the words of one group's list: as many as the volumes need, and
+ *   never more than the buffer holds for each group, so a list sized from a count the host had
+ *   before a volume arrived drops that volume for a frame rather than overrun.
+ * - `volumetrics_froxel_planes` is the metadata frustum with its Y pair turned to the froxel grid's
+ *   rows (screen Y runs down, world Y up).
+ * - `volumetrics_froxel_slab` is the frustum of a box of froxels: `uv` over the grid's columns and
+ *   rows, `slice` over its depth curve, clamped to the camera's logical near and far.
+ *   `volumetrics_froxel_slab_between` is the same with the depths given, inside `[near, far]`.
+ * - `volumetrics_volume_in_slab` is the build's own rejection of a volume by a slab: its unit box
+ *   against the slab's planes taken into the volume's frame.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_media_group_list: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_volumetrics_media_group_list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_volumetrics_media_group_list.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_media_group_list.js"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,qDAFU,MAAM,EAAE,CAEgD;AAElE;;;;;GAKG;AACH,oDAFU,MAAM,CAEwC;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,iDAFU,SAAS,CAoFjB;0BAzHwB,iCAAiC"}

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

@@ -0,0 +1,129 @@
+import { AABB3_STRUCT } from "../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import { chunk_aabb3_intersects_frustum } from "../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
+import { chunk_frustum_slice } from "../shader/chunk/geometry/frustum/chunk_frustum_slice.js";
+import {
+    chunk_frustum_transform_plane_matrix
+} from "../shader/chunk/geometry/frustum/chunk_frustum_transform_plane_matrix.js";
+import { chunk_grid3d_to_index } from "../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { chunk_cluster_depth_from_z_slice } from "../light/cluster/chunk_cluster_depth_from_z_slice.js";
+import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
+
+/**
+ * The participating-media build's workgroup, in froxels: flat in z, one slice a group. Read by its
+ * `@workgroup_size`, by the bin that pre-culls the volumes for each of those groups, and by the
+ * dispatches of both.
+ * @type {number[]}
+ */
+export const VOLUMETRICS_MEDIA_WORKGROUP_RESOLUTION = [16, 16, 1];
+
+/**
+ * The most volumes of its group's list a froxel of the participating-media build walks. Chosen, not
+ * derived. Past it the build drops the group's highest-indexed volumes, whatever each froxel would
+ * have made of them.
+ * @type {number}
+ */
+export const VOLUMETRICS_MEDIA_GROUP_VOLUME_BUDGET = 32;
+
+/**
+ * The volumes each workgroup of the participating-media build may see, as one list per group: a
+ * bitmask over the volumes' rows, `list_words` words a group, the groups in `grid3d_to_index` order.
+ * The bin writes it, and the build walks its own group's list in row order instead of every volume.
+ *
+ * - `volumetrics_media_groups` is the build's workgroup grid over a froxel grid.
+ * - `volumetrics_media_list_words` is the words of one group's list: as many as the volumes need, and
+ *   never more than the buffer holds for each group, so a list sized from a count the host had
+ *   before a volume arrived drops that volume for a frame rather than overrun.
+ * - `volumetrics_froxel_planes` is the metadata frustum with its Y pair turned to the froxel grid's
+ *   rows (screen Y runs down, world Y up).
+ * - `volumetrics_froxel_slab` is the frustum of a box of froxels: `uv` over the grid's columns and
+ *   rows, `slice` over its depth curve, clamped to the camera's logical near and far.
+ *   `volumetrics_froxel_slab_between` is the same with the depths given, inside `[near, far]`.
+ * - `volumetrics_volume_in_slab` is the build's own rejection of a volume by a slab: its unit box
+ *   against the slab's planes taken into the volume's frame.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_media_group_list = CodeChunk.from(
+    //language=WGSL
+    `
+const VOLUMETRICS_MEDIA_GROUP_XY = vec2<u32>(${VOLUMETRICS_MEDIA_WORKGROUP_RESOLUTION[0]}u, ${VOLUMETRICS_MEDIA_WORKGROUP_RESOLUTION[1]}u);
+const VOLUMETRICS_MEDIA_GROUP_VOLUME_BUDGET: u32 = ${VOLUMETRICS_MEDIA_GROUP_VOLUME_BUDGET}u;
+
+fn volumetrics_media_groups(resolution: vec3<u32>) -> vec3<u32> {
+    return vec3<u32>((resolution.xy + VOLUMETRICS_MEDIA_GROUP_XY - vec2<u32>(1u)) / VOLUMETRICS_MEDIA_GROUP_XY, resolution.z);
+}
+
+fn volumetrics_media_list_words(volume_count: u32, buffer_words: u32, groups: vec3<u32>) -> u32 {
+    return min((volume_count + 31u) / 32u, buffer_words / (groups.x * groups.y * groups.z));
+}
+
+fn volumetrics_media_list_offset(group: vec3<u32>, groups: vec3<u32>, list_words: u32) -> u32 {
+    return grid3d_to_index(group, groups.xy) * list_words;
+}
+
+fn volumetrics_froxel_planes(frustum: array<vec4<f32>, 6>) -> array<vec4<f32>, 6> {
+    // Frustum planes are [LEFT, RIGHT, BOTTOM, TOP, NEAR, FAR] (see Camera.construct_frustum_planes),
+    // every one facing in. The grid's rows run down the screen while world Y runs up, so the Y pair
+    // trades places, and stays facing in: frustum_slice takes the plane at uv 0 as it is and the one
+    // at uv 1 as it is, so swapped and kept they bound the slab from the inside, as X and Z do.
+    var planes = frustum;
+    let t = planes[2];
+    planes[2] = planes[3];
+    planes[3] = t;
+    return planes;
+}
+
+fn volumetrics_froxel_slab(
+    planes: array<vec4<f32>, 6>,
+    uv_min: vec2<f32>,
+    uv_max: vec2<f32>,
+    slice_0: f32,
+    slice_1: f32,
+    near_far: vec2<f32>,
+    curve: vec3<f32>,
+    slices: f32,
+) -> array<vec4<f32>, 6> {
+    let z0 = max(near_far.x, cluster_depth_from_z_slice(slice_0, curve, slices));
+    let z1 = min(near_far.y, cluster_depth_from_z_slice(slice_1, curve, slices));
+
+    return volumetrics_froxel_slab_between(planes, uv_min, uv_max, z0, z1, near_far);
+}
+
+fn volumetrics_froxel_slab_between(
+    planes: array<vec4<f32>, 6>,
+    uv_min: vec2<f32>,
+    uv_max: vec2<f32>,
+    z0: f32,
+    z1: f32,
+    near_far: vec2<f32>,
+) -> array<vec4<f32>, 6> {
+    let z0_norm = (z0 - near_far.x) / (near_far.y - near_far.x);
+    let z1_norm = (z1 - near_far.x) / (near_far.y - near_far.x);
+
+    return frustum_slice(planes, vec3(uv_min, z0_norm), vec3(uv_max, z1_norm));
+}
+
+fn volumetrics_volume_in_slab(slab: array<vec4<f32>, 6>, volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref}) -> bool {
+    // Points go world -> local through transform_inverse, so planes go by the transpose of *its*
+    // inverse, which is just transpose(transform) — already resident.
+    let local = frustum_transform_plane_matrix(slab, transpose(volume.transform));
+
+    const unit_bounds = ${AABB3_STRUCT.make({
+        min: "vec3(-0.5)",
+        max: "vec3(0.5)",
+    })};
+
+    return aabb3_intersects_frustum(unit_bounds, local);
+}
+    `,
+    [
+        PARTICIPATING_MEDIA_VOLUME_STRUCT.declaration_chunk,
+        AABB3_STRUCT.declaration_chunk,
+        chunk_aabb3_intersects_frustum,
+        chunk_frustum_slice,
+        chunk_frustum_transform_plane_matrix,
+        chunk_cluster_depth_from_z_slice,
+        chunk_grid3d_to_index,
+    ]
+);

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

@@ -10,6 +10,12 @@
  * @returns {string}
  */
 export function volumetrics_sun_shadow_texture_name(index: number): string;
+/**
+ * The cascades' textures, innermost first, as {@link chunk_volumetrics_sun_optical_depth} reads them.
+ *
+ * @type {ShaderResourceDescriptor[]}
+ */
+export const VOLUMETRICS_SUN_SHADOW_CASCADE_RESOURCES: ShaderResourceDescriptor[];
 /**
  * Optical depth of the participating medium between a world position and the sun, in one fetch.
  *
@@ -34,5 +40,6 @@ export function volumetrics_sun_shadow_texture_name(index: number): string;
  * @type {CodeChunk}
  */
 export const chunk_volumetrics_sun_optical_depth: CodeChunk;
+import { ShaderResourceDescriptor } from "../shader/resource/ShaderResourceDescriptor.js";
 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

@@ -1 +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;AA2ED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,kDAFU,SAAS,CAgBjB;0BAhIwB,iCAAiC"}
+{"version":3,"file":"chunk_volumetrics_sun_optical_depth.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_sun_optical_depth.js"],"names":[],"mappings":"AAQA;;;;;;;;;;GAUG;AACH,2DAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,uDAFU,wBAAwB,EAAE,CAKlC;AA2EF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,kDAFU,SAAS,CAgBjB;yCA5IuC,gDAAgD;0BAD/D,iCAAiC"}