@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -0,0 +1,53 @@
+import { chunk_ndc_to_uv } from "../shader/chunk/texture/chunk_ndc_to_uv.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * Froxel-grid texture coordinates of a point given as its clip position and its planar view depth.
+ *
+ * The second half of {@link volumetrics_position_world_to_froxel_uvw}, for a caller that already
+ * has those two: a march along a straight line, where both are affine in the line parameter and
+ * cost two `fma` per sample, a vec4 and a scalar, instead of two matrix products (see
+ * {@link chunk_volumetrics_sample_froxel_extinction}).
+ *
+ * `content_offset` is {@link chunk_volumetrics_froxel_content_offset} of the grid's slice scale. It
+ * depends on nothing but the grid, so a march evaluates it once and passes it in. Evaluated per
+ * sample, it is an `exp` and three divides that the compiler leaves inside the loop.
+ *
+ * NOTE: we don't clamp final slice coordinate, this is intentional, we let the linear texture sampler take care of that.
+ * See {@link build_light_cluster_parameters}
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_froxel_uvw_from_clip = CodeChunk.from(
+    //language=WGSL
+    `
+fn volumetrics_froxel_uvw_from_clip(
+    position_clip: vec4<f32>,
+    view_depth: f32,
+    content_offset: f32
+) -> vec3<f32>{
+
+    let uv = ndc_to_uv(position_clip.xy / position_clip.w);
+
+    // froxel_cluster_parameters, NOT cluster_parameters: this addresses the FROXEL grid, which the
+    // participating-media pass builds on that curve. cluster_parameters is the aerial LUT's. The
+    // two are identical while froxel_far is unset — which is why the mix-up went unnoticed — and
+    // diverge as soon as the grid is packed into a shorter range.
+    let cluster_parameters = volumetrics_metadata.froxel_cluster_parameters;
+
+    // see 'cluster_depth_to_z_slice' for explanation
+    let slice_position:f32 = log2(fma(view_depth, cluster_parameters.x, cluster_parameters.y)) * cluster_parameters.z;
+
+    // A cell-averaged grid: texel k holds the slab [k+j, k+1+j], not the point at slice k, so the
+    // texel-centre convention alone reads about half a froxel too far out. See
+    // chunk_volumetrics_froxel_content_offset for where the ~0.53 comes from.
+    let w = (slice_position + 0.5 - content_offset) / f32(volumetrics_metadata.resolution.z);
+
+    return vec3(
+        uv,
+        w
+    );
+}
+    `, [
+        chunk_ndc_to_uv,
+    ]
+);

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

@@ -1,6 +1,6 @@
 /**
- * Extinction of the participating medium at a world position, or zero where the froxel grid does
- * not reach.
+ * Extinction of the participating medium along a straight world-space line, 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
@@ -12,7 +12,16 @@
  * 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
+ * **Why a line rather than a point.** The view and the projection are linear maps, so along
+ * `origin + t * direction` the view depth and the clip position are affine in `t`: set up once,
+ * each sample costs two `fma`, a vec4 and a scalar, where a world position costs a view and a
+ * projection product. The content offset is constant along the line and is set up with it, because
+ * left in the per-sample lookup it stays in the loop. Measured 2026-10-16 in the sun-shadow-volume
+ * build, RTX 4090, p10 against the per-point form: hoisting the content offset alone (bit-identical
+ * output) made the pass 0.89-0.91 of it, the line with the offset on it 0.81-0.85. See
+ * {@link shader_volumetrics_build_sun_shadow_volume_outermost} for the numbers by part.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume_outermost
  * @type {CodeChunk}
  */
 export const chunk_volumetrics_sample_froxel_extinction: CodeChunk;

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

@@ -1 +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"}
+{"version":3,"file":"chunk_volumetrics_sample_froxel_extinction.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_volumetrics_sample_froxel_extinction.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,yDAFU,SAAS,CAuDjB;0BAnFwB,iCAAiC"}

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

@@ -1,48 +1,85 @@
-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,
-    ]
-);
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { chunk_volumetrics_froxel_content_offset } from "./chunk_volumetrics_froxel_content_offset.js";
+import { chunk_volumetrics_froxel_uvw_from_clip } from "./chunk_volumetrics_froxel_uvw_from_clip.js";
+
+/**
+ * Extinction of the participating medium along a straight world-space line, 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.
+ *
+ * **Why a line rather than a point.** The view and the projection are linear maps, so along
+ * `origin + t * direction` the view depth and the clip position are affine in `t`: set up once,
+ * each sample costs two `fma`, a vec4 and a scalar, where a world position costs a view and a
+ * projection product. The content offset is constant along the line and is set up with it, because
+ * left in the per-sample lookup it stays in the loop. Measured 2026-10-16 in the sun-shadow-volume
+ * build, RTX 4090, p10 against the per-point form: hoisting the content offset alone (bit-identical
+ * output) made the pass 0.89-0.91 of it, the line with the offset on it 0.81-0.85. See
+ * {@link shader_volumetrics_build_sun_shadow_volume_outermost} for the numbers by part.
+ *
+ * @see shader_volumetrics_build_sun_shadow_volume_outermost
+ * @type {CodeChunk}
+ */
+export const chunk_volumetrics_sample_froxel_extinction = CodeChunk.from(
+    //language=WGSL
+    `
+struct VolumetricsFroxelLine {
+    clip_origin: vec4<f32>,
+    clip_direction: vec4<f32>,
+    // planar view depth, positive in front of the camera
+    depth_origin: f32,
+    depth_direction: f32,
+    // depends only on the grid, carried here so a march evaluates it once
+    content_offset: f32,
+}
+
+fn volumetrics_froxel_line(origin_ws: vec3<f32>, direction_ws: vec3<f32>) -> VolumetricsFroxelLine {
+
+    let origin_vs = camera.view_matrix * vec4<f32>(origin_ws, 1.0);
+
+    // a direction, so w = 0: the view's translation moves the line, it does not tilt it
+    let direction_vs = camera.view_matrix * vec4<f32>(direction_ws, 0.0);
+
+    return VolumetricsFroxelLine(
+        camera.projection_matrix * origin_vs,
+        camera.projection_matrix * direction_vs,
+        // view space looks down -Z
+        -origin_vs.z,
+        -direction_vs.z,
+        volumetrics_froxel_content_offset(volumetrics_metadata.froxel_cluster_parameters.z),
+    );
+}
+
+fn volumetrics_sample_froxel_extinction(froxel_line: VolumetricsFroxelLine, t: f32) -> vec3<f32> {
+
+    let view_depth = fma(t, froxel_line.depth_direction, froxel_line.depth_origin);
+
+    if (view_depth <= 0.0) {
+        return vec3<f32>(0.0);
+    }
+
+    let position_clip = fma(vec4<f32>(t), froxel_line.clip_direction, froxel_line.clip_origin);
+
+    let uvw = volumetrics_froxel_uvw_from_clip(position_clip, view_depth, froxel_line.content_offset);
+
+    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,
+        chunk_volumetrics_froxel_content_offset,
+        chunk_volumetrics_froxel_uvw_from_clip,
+    ]
+);

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

@@ -20,9 +20,10 @@
  * @param {number[]} options.resolution the froxel grid
  * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode which froxel GI
  *   module starts the volume
+ * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the lights' pass is built for them
  * @returns {{Y: number, CoCg: number}} handles of the volume: luma SH2, and chroma in `.rg`
  */
-export function graph_build_froxel_irradiance({ graph, camera, view, lights, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetrics_metadata, resolution, indirect_lighting_mode, }: {
+export function graph_build_froxel_irradiance({ graph, camera, view, lights, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetrics_metadata, resolution, indirect_lighting_mode, shader_switches, }: {
     graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     camera: import("../camera/GPUCameraContext.js").GPUCameraContext;
     view: import("../view/GPUViewContext.js").GPUViewContext;
@@ -34,8 +35,10 @@ export function graph_build_froxel_irradiance({ graph, camera, view, lights, lig
     volumetrics_metadata: number;
     resolution: number[];
     indirect_lighting_mode: import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode;
+    shader_switches?: ShaderSwitchSet;
 }): {
     Y: number;
     CoCg: number;
 };
+import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
 //# sourceMappingURL=graph_build_froxel_irradiance.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"graph_build_froxel_irradiance.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_froxel_irradiance.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAdmG,KAAK,EAA7F,OAAO,2DAA2D,EAAE,UAAU;IACZ,MAAM,EAAxE,OAAO,+BAA+B,EAAE,gBAAgB;IACI,IAAI,EAAhE,OAAO,2BAA2B,EAAE,cAAc;IACmB,MAAM,EAA3E,OAAO,gCAAgC,EAAE,kBAAkB;IAC3C,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,oBAAoB,EAApC,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACqE,sBAAsB,EAAnG,OAAO,iCAAiC,EAAE,yBAAyB;IAEjE;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAkFrC"}
+{"version":3,"file":"graph_build_froxel_irradiance.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_froxel_irradiance.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAfmG,KAAK,EAA7F,OAAO,2DAA2D,EAAE,UAAU;IACZ,MAAM,EAAxE,OAAO,+BAA+B,EAAE,gBAAgB;IACI,IAAI,EAAhE,OAAO,2BAA2B,EAAE,cAAc;IACmB,MAAM,EAA3E,OAAO,gCAAgC,EAAE,kBAAkB;IAC3C,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACU,oBAAoB,EAApC,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACqE,sBAAsB,EAAnG,OAAO,iCAAiC,EAAE,yBAAyB;IAEzC,eAAe,GAAzC,eAAe;IACb;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAmFrC;gCAjH+B,uCAAuC"}

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

@@ -1,4 +1,5 @@
 import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
+import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
 import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR.js";
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR } from "../texture/DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR.js";
@@ -27,6 +28,7 @@ import { shader_volumetrics_build_irradiance } from "./shader_volumetrics_build_
  * @param {number[]} options.resolution the froxel grid
  * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode which froxel GI
  *   module starts the volume
+ * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the lights' pass is built for them
  * @returns {{Y: number, CoCg: number}} handles of the volume: luma SH2, and chroma in `.rg`
  */
 export function graph_build_froxel_irradiance({
@@ -41,6 +43,7 @@ export function graph_build_froxel_irradiance({
                                                   volumetrics_metadata,
                                                   resolution,
                                                   indirect_lighting_mode,
+                                                  shader_switches = ShaderSwitchSet.EMPTY,
                                               }) {
 
     const gi = graph_build_froxel_gi({
@@ -62,7 +65,7 @@ export function graph_build_froxel_irradiance({
         // recorded: the engine's assets arrive at startup, and this is when the pass needs them.
         const tSTBN_vec3 = context.graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
 
-        shader_volumetrics_build_irradiance.dispatchThreads({
+        shader_volumetrics_build_irradiance.variant(shader_switches).dispatchThreads({
             encoder: context.encoder,
             thread_count_x: output_Y.width,
             thread_count_y: output_Y.height,

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

@@ -24,8 +24,9 @@
  * @param {number} [options.taa_history] imported previous-frame accumulated scattering volume
  * @param {number} [options.taa_output] imported destination for this frame's accumulated scattering volume
  * @param {GPUCameraContext} [options.camera_previous] previous-frame camera, for temporal reprojection
+ * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the lighting pass is built for them
  */
-export function graph_build_volumetrics({ graph, camera, lights, view, sky, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetric_resolution, sun_shadow_resolution, volumetrics_metadata, taa_history, taa_output, camera_previous, }: {
+export function graph_build_volumetrics({ graph, camera, lights, view, sky, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, volumetric_resolution, sun_shadow_resolution, volumetrics_metadata, taa_history, taa_output, camera_previous, shader_switches, }: {
     graph: FrameGraph;
     camera: GPUCameraContext;
     lights: GPULightCollection;
@@ -41,10 +42,12 @@ export function graph_build_volumetrics({ graph, camera, lights, view, sky, ligh
     taa_history?: number;
     taa_output?: number;
     camera_previous?: GPUCameraContext;
+    shader_switches?: ShaderSwitchSet;
 }): {
     lut_transmittance: number;
     lut_multiple_scattering: number;
     lut_aerial: any;
     volumetrics_metadata: number;
 };
+import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
 //# sourceMappingURL=graph_build_volumetrics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AA2UA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IArB+B,KAAK;IACC,MAAM;IACJ,MAAM;IACV,IAAI;IACZ,GAAG;IAIH,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACY,qBAAqB,EAAvC,MAAM,EAAE;IACU,qBAAqB,EAAvC,MAAM,EAAE;IAGQ,oBAAoB,EAApC,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,UAAU,GAA3B,MAAM;IACqB,eAAe;;;;;;EA+KpD"}
+{"version":3,"file":"graph_build_volumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/graph_build_volumetrics.js"],"names":[],"mappings":"AA4VA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB+B,KAAK;IACC,MAAM;IACJ,MAAM;IACV,IAAI;IACZ,GAAG;IAIH,kBAAkB,EAAlC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACU,wBAAwB,EAAxC,MAAM;IACU,eAAe,EAA/B,MAAM;IACY,qBAAqB,EAAvC,MAAM,EAAE;IACU,qBAAqB,EAAvC,MAAM,EAAE;IAGQ,oBAAoB,EAApC,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,UAAU,GAA3B,MAAM;IACqB,eAAe;IAChB,eAAe,GAAzC,eAAe;;;;;;EAiLzB;gCApiB+B,uCAAuC"}

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

@@ -1,6 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.js";
 import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
+import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
 import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
 import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
 import { graph_import_texture } from "../shader/graph/graph_import_texture.js";
@@ -8,6 +9,7 @@ import { SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR } from "../shadow/map/SHADOWMAP_CO
 import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../STATIC_GRAPHICS_ENGINE_ASSETS.js";
 import { DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR } from "../texture/DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR.js";
 import { volumetrics_sun_shadow_texture_name } from "./chunk_volumetrics_sun_optical_depth.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "./noise/PARTICIPATING_MEDIA_NOISE.js";
 import { shader_volumetrics_build_lighting } from "./shader_volumetrics_build_lighting.js";
 import { shader_volumetrics_build_participating_media } from "./shader_volumetrics_build_participating_media.js";
 import { shader_volumetrics_build_scattering_lut } from "./shader_volumetrics_build_scattering_lut.js";
@@ -68,6 +70,15 @@ function graph_integrate_participating_media({
 
             const volumetrics_metadata = resources.get(data.volumetrics_metadata);
 
+            /**
+             * The scene's noise atlas, imported this frame so a grow between frames is seen.
+             * @type {GPUTextureContext}
+             */
+            const noise_atlas = resources.get(data.noise_atlas);
+
+            // the per-froxel point the noise is read at moves by this volume every frame
+            const tSTBN_vec3 = context.graphics.textures.obtain(STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3);
+
             shader_volumetrics_build_participating_media.dispatchThreads({
                 encoder,
                 thread_count_x: output0.width,
@@ -78,6 +89,9 @@ function graph_integrate_participating_media({
                     view: view.uniform_buffer.buffer,
                     volumetrics_metadata,
                     scene_database: scene.scene_database_buffer,
+                    tSTBN_vec3: tSTBN_vec3.obtainView(),
+                    tParticipatingMediaNoise: noise_atlas.obtainView(),
+                    sParticipatingMediaNoise: context.graphics.samplers.obtain(PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR),
                     tOutput0: output0.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
                     tOutput1: output1.obtainView(DEFAULT_RENDER_TARGET_VIEW_DESCRIPTOR),
                 }
@@ -87,6 +101,7 @@ function graph_integrate_participating_media({
         });
 
     data.volumetrics_metadata = pass.read(volumetrics_metadata);
+    data.noise_atlas = pass.read(graph_import_texture(graph, scene.volumetrics.noise_atlas.texture, "volumetrics noise atlas"));
 
     data.output0 = pass.create("Participating Media 0", TextureResourceDescriptor.from({
         resolution,
@@ -217,6 +232,7 @@ function graph_build_sun_shadow_volume({
  * @param view
  * @param camera
  * @param resolution
+ * @param {ShaderSwitchSet} shader_switches the renderer's; the lighting pass is built for them
  * @returns {number} the lit scattering volume
  */
 function graph_integrate_light_scattering({
@@ -235,6 +251,7 @@ function graph_integrate_light_scattering({
                                               view,
                                               camera,
                                               resolution,
+                                              shader_switches,
                                           }) {
 
     const data = {};
@@ -296,7 +313,7 @@ function graph_integrate_light_scattering({
             bindings[volumetrics_sun_shadow_texture_name(cascade)] = sun_shadow_cascades[cascade].obtainView();
         }
 
-        shader_volumetrics_build_lighting.dispatchThreads({
+        shader_volumetrics_build_lighting.variant(shader_switches).dispatchThreads({
             encoder,
             thread_count_x: output.width,
             thread_count_y: output.height,
@@ -355,6 +372,7 @@ function graph_integrate_light_scattering({
  * @param {number} [options.taa_history] imported previous-frame accumulated scattering volume
  * @param {number} [options.taa_output] imported destination for this frame's accumulated scattering volume
  * @param {GPUCameraContext} [options.camera_previous] previous-frame camera, for temporal reprojection
+ * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the lighting pass is built for them
  */
 export function graph_build_volumetrics({
                                             graph,
@@ -372,6 +390,7 @@ export function graph_build_volumetrics({
                                             taa_history,
                                             taa_output,
                                             camera_previous,
+                                            shader_switches = ShaderSwitchSet.EMPTY,
                                         }) {
 
     assert.defined(view, 'view');
@@ -423,6 +442,7 @@ export function graph_build_volumetrics({
         light_cluster_parameters,
         shadowmap_atlas,
         lights,
+        shader_switches,
     })
 
     // Temporal reprojection of the per-froxel lit scattering volume, applied BEFORE aerial

package/src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The volumetrics noise atlas, as the shaders and the host both know it.
+ *
+ * A participating-media volume's noise is a tile of this atlas sampled in world space, wrapping
+ * every `noise_scale` metres, scrolled by the wind and warped by a second, slower tap of the same
+ * tile. The tile sizes are compile-time facts of the shader (`chunk_participating_media_noise`
+ * derives a slot's texel origin from them and the atlas texture's own dimensions), so they are
+ * constants here and the atlas instance is built from the same numbers.
+ *
+ * Why 128³ with a one-texel skirt: the engine's default tile holds four base features along each
+ * edge with the finest of three octaves at eight texels a wavelength; Enshrouded's detail noise is
+ * 128³, Godot advises 64³ or under, and one texel of skirt is what a trilinear tap needs to wrap.
+ * A tile is 2.2 MB in `r8unorm` — uncompressed because WebGPU admits no compressed 3-D texture.
+ *
+ * See `VOLUMETRIC_NOISE_PLAN_2026_10_15.md`.
+ */
+/**
+ * Texels of content along each axis of a tile.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE: number;
+/**
+ * Texels of skirt on each side: what a linear filter reads past the content.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_BORDER: number;
+/**
+ * Texels along each axis of a whole tile, skirt included.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_SIZE: number;
+/**
+ * One byte a texel: the tile is a [0, 1] multiplier on density and nothing else.
+ * @type {GPUTextureFormat}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_FORMAT: GPUTextureFormat;
+/**
+ * The atlas's x/y footprint in tiles — fixed for its life, since it grows along z.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_X: number;
+/**
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_Y: number;
+/**
+ * Slots allocated up front: the engine's own tile and one spare. The atlas grows by a layer of
+ * `SLOTS_X × SLOTS_Y` whenever that runs out.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_CAPACITY: number;
+/**
+ * The slot the engine bakes its own tile into at start-up, and the slot a volume samples unless
+ * told otherwise.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT: number;
+/**
+ * Base features along each edge of the engine's default tile: four 32-texel wavelengths, so the
+ * tile repeats every four features in the world.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_FEATURES: number;
+/**
+ * Octaves baked into the engine's default tile, lacunarity 2, gain 0.5 — the finest at 8 texels a
+ * wavelength. AC4 shipped one octave and found more "rather subtle for added cost"; here the cost
+ * is paid once at bake time, so three is the budget, and a fourth would alias at 4 texels.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_OCTAVES: number;
+/**
+ * The warp tap samples the same tile at this fraction of the base frequency: a coarser field, so the
+ * displacement it drives is a smooth undulation of the base rather than a shimmer.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCALE: number;
+/**
+ * How fast the warp tap scrolls, as a fraction of the base tap's scroll in its own tile units. Not
+ * 1: the two fields have to slide against each other for the base to keep changing shape rather
+ * than ride along unchanged.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCROLL: number;
+/**
+ * The fixed direction the warp displaces along, a unit vector off every axis so the shear is
+ * oblique rather than a slide along x. A scalar tap can only displace along one direction; which
+ * one matters little for an isotropic field, and a constant keeps the tap count at two.
+ * @type {readonly number[]}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION: readonly number[];
+/**
+ * How the atlas is sampled: trilinear, and clamped — the wrap is done by the skirt and by `fract`
+ * on the tile coordinate, never by the sampler, which would wrap the whole atlas.
+ * @type {SamplerDescriptor}
+ */
+export const PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR: SamplerDescriptor;
+import { SamplerDescriptor } from "../../../descriptor/texture/SamplerDescriptor.js";
+//# sourceMappingURL=PARTICIPATING_MEDIA_NOISE.d.ts.map

package/src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PARTICIPATING_MEDIA_NOISE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH,0DAFU,MAAM,CAE+C;AAE/D;;;GAGG;AACH,oDAFU,MAAM,CAEuC;AAEvD;;;GAGG;AACH,kDAFU,MAAM,CAE2H;AAE3I;;;GAGG;AACH,qEAA+D;AAE/D;;;GAGG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;GAEG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;;;GAIG;AACH,uDAFU,MAAM,CAE0C;AAE1D;;;;GAIG;AACH,qDAFU,MAAM,CAEwC;AAExD;;;;GAIG;AACH,yDAFU,MAAM,CAE4C;AAE5D;;;;;GAKG;AACH,wDAFU,MAAM,CAE2C;AAE3D;;;;GAIG;AACH,mDAFU,MAAM,CAEwC;AAExD;;;;;GAKG;AACH,oDAFU,MAAM,CAE0C;AAE1D;;;;;GAKG;AACH,uDAFU,SAAS,MAAM,EAAE,CAE+D;AAE1F;;;;GAIG;AACH,2DAFU,iBAAiB,CAKxB;kCAlH+B,kDAAkD"}

package/src/shade/renderer/volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js

@@ -0,0 +1,115 @@
+import { SamplerDescriptor } from "../../../descriptor/texture/SamplerDescriptor.js";
+
+/**
+ * The volumetrics noise atlas, as the shaders and the host both know it.
+ *
+ * A participating-media volume's noise is a tile of this atlas sampled in world space, wrapping
+ * every `noise_scale` metres, scrolled by the wind and warped by a second, slower tap of the same
+ * tile. The tile sizes are compile-time facts of the shader (`chunk_participating_media_noise`
+ * derives a slot's texel origin from them and the atlas texture's own dimensions), so they are
+ * constants here and the atlas instance is built from the same numbers.
+ *
+ * Why 128³ with a one-texel skirt: the engine's default tile holds four base features along each
+ * edge with the finest of three octaves at eight texels a wavelength; Enshrouded's detail noise is
+ * 128³, Godot advises 64³ or under, and one texel of skirt is what a trilinear tap needs to wrap.
+ * A tile is 2.2 MB in `r8unorm` — uncompressed because WebGPU admits no compressed 3-D texture.
+ *
+ * See `VOLUMETRIC_NOISE_PLAN_2026_10_15.md`.
+ */
+
+/**
+ * Texels of content along each axis of a tile.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE = 128;
+
+/**
+ * Texels of skirt on each side: what a linear filter reads past the content.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_BORDER = 1;
+
+/**
+ * Texels along each axis of a whole tile, skirt included.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_SIZE = PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE + 2 * PARTICIPATING_MEDIA_NOISE_TILE_BORDER;
+
+/**
+ * One byte a texel: the tile is a [0, 1] multiplier on density and nothing else.
+ * @type {GPUTextureFormat}
+ */
+export const PARTICIPATING_MEDIA_NOISE_TILE_FORMAT = "r8unorm";
+
+/**
+ * The atlas's x/y footprint in tiles — fixed for its life, since it grows along z.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_X = 2;
+
+/**
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_Y = 1;
+
+/**
+ * Slots allocated up front: the engine's own tile and one spare. The atlas grows by a layer of
+ * `SLOTS_X × SLOTS_Y` whenever that runs out.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_ATLAS_CAPACITY = 2;
+
+/**
+ * The slot the engine bakes its own tile into at start-up, and the slot a volume samples unless
+ * told otherwise.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT = 0;
+
+/**
+ * Base features along each edge of the engine's default tile: four 32-texel wavelengths, so the
+ * tile repeats every four features in the world.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_FEATURES = 4;
+
+/**
+ * Octaves baked into the engine's default tile, lacunarity 2, gain 0.5 — the finest at 8 texels a
+ * wavelength. AC4 shipped one octave and found more "rather subtle for added cost"; here the cost
+ * is paid once at bake time, so three is the budget, and a fourth would alias at 4 texels.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_DEFAULT_OCTAVES = 3;
+
+/**
+ * The warp tap samples the same tile at this fraction of the base frequency: a coarser field, so the
+ * displacement it drives is a smooth undulation of the base rather than a shimmer.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCALE = 0.5;
+
+/**
+ * How fast the warp tap scrolls, as a fraction of the base tap's scroll in its own tile units. Not
+ * 1: the two fields have to slide against each other for the base to keep changing shape rather
+ * than ride along unchanged.
+ * @type {number}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_SCROLL = 0.37;
+
+/**
+ * The fixed direction the warp displaces along, a unit vector off every axis so the shear is
+ * oblique rather than a slide along x. A scalar tap can only displace along one direction; which
+ * one matters little for an isotropic field, and a constant keeps the tap count at two.
+ * @type {readonly number[]}
+ */
+export const PARTICIPATING_MEDIA_NOISE_WARP_DIRECTION = Object.freeze([0.6, 0.48, -0.64]);
+
+/**
+ * How the atlas is sampled: trilinear, and clamped — the wrap is done by the skirt and by `fract`
+ * on the tile coordinate, never by the sampler, which would wrap the whole atlas.
+ * @type {SamplerDescriptor}
+ */
+export const PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR = SamplerDescriptor.from({
+    magFilter: "linear",
+    minFilter: "linear",
+});

package/src/shade/renderer/volumetrics/noise/VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What one bake of a noise tile is told: the tile's geometry, the row stride of the block it writes,
+ * and the field to bake.
+ *
+ * @see shader_volumetrics_noise_tile_bake
+ */
+export const VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.d.ts.map

package/src/shade/renderer/volumetrics/noise/VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/volumetrics/noise/VOLUMETRICS_NOISE_TILE_BAKE_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,uEAcuC;6BAtBV,mCAAmC"}