@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -1,6 +1,36 @@
+import { assert } from "../../../core/assert.js";
 import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { generate_record_writer } from "../buffer/table/serde/generate_record_writer.js";
+import { GPUTileAtlas3D } from "../texture/atlas/GPUTileAtlas3D.js";
+import {
+    bake_volumetrics_noise_tile,
+    enquire_bake_volumetrics_noise_tile_pipelines
+} from "./noise/bake_volumetrics_noise_tile.js";
+import {
+    PARTICIPATING_MEDIA_NOISE_ATLAS_CAPACITY,
+    PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_X,
+    PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_Y,
+    PARTICIPATING_MEDIA_NOISE_DEFAULT_FEATURES,
+    PARTICIPATING_MEDIA_NOISE_DEFAULT_OCTAVES,
+    PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT,
+    PARTICIPATING_MEDIA_NOISE_TILE_BORDER,
+    PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE,
+    PARTICIPATING_MEDIA_NOISE_TILE_FORMAT
+} from "./noise/PARTICIPATING_MEDIA_NOISE.js";
+import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
 
 /**
+ * A row's noise phases, the only words of it a scrolling field changes from frame to frame.
+ * @type {import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter}
+ */
+const NOISE_PHASE_WRITER = generate_record_writer(PARTICIPATING_MEDIA_VOLUME_STRUCT, ['noise_flow_phase', 'noise_offset', 'noise_warp_offset']);
+
+/** `noise_offset` and `noise_warp_offset`, three floats each, and `noise_flow_phase`. */
+const NOISE_PHASE_WORDS = 7;
+
+/**
+ * @typedef {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
  * @typedef {import("./SceneVolumetrics.js").SceneVolumetrics} SceneVolumetrics
  * @typedef {import("../buffer/table/GPUTypedTable.js").GPUTypedTable} GPUTypedTable
@@ -13,13 +43,32 @@ import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
  * of their own.
  *
  * The table is written whole whenever {@link SceneVolumetrics#version} moves — cleared and refilled
- * in the scene's volume order — and not at all otherwise; the scene database's own update, later in
- * the same frame, takes the rows to the GPU. The rows are dense from 0, which the passes' walk over
- * `[0, participating_media_volumes_count)` relies on. A volume whose transform has no inverse —
- * scaled to nothing on an axis — gets no row.
+ * in the scene's volume order. While only {@link SceneVolumetrics#noise_version} moves, each row whose
+ * noise phases differ from what was last written gets those seven words and nothing else, through the
+ * table's partial stream (`set_fields`): a scrolling field costs a few words a volume a frame, not a
+ * table rebuild with an inversion a volume. Otherwise nothing is written. The scene database's own
+ * update, later in the same frame, takes the rows to the GPU. The rows are dense from 0, which the
+ * passes' walk over `[0, participating_media_volumes_count)` relies on. A volume whose transform has
+ * no inverse — scaled to nothing on an axis — gets no row.
+ *
+ * **The noise atlas lives here too.** Every volume's noise is a tile of one 3-D atlas the passes
+ * bind beside the scene database, and the atlas is this scene's: slot 0 is the engine's own tile,
+ * baked on the device the first time this updates, and the rest are whoever asked
+ * {@link noise_atlas} for them. Per scene rather than per device because a volume names its tile
+ * by slot, and the volumes are the scene's.
  */
 export class GPUSceneVolumetrics {
 
+    /**
+     * Offer the pipeline every scene's first {@link update} bakes its default noise tile with — see
+     * {@link PipelineEnquiry}. Fog itself is drawn by passes of the view, for a scene that has volumes.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquire_bake_volumetrics_noise_tile_pipelines(enquiry);
+    }
+
     /**
      * @type {SceneVolumetrics}
      */
@@ -27,27 +76,100 @@ export class GPUSceneVolumetrics {
 
     #version = -1;
 
+    /** The {@link SceneVolumetrics#noise_version} the rows' phases were last brought up to. */
+    #noise_version = -1;
+
+    /**
+     * Each volume's row as {@link #repack} placed it, by the volume's index, -1 for one with no row.
+     * Grown by the repack, never shrunk.
+     * @type {Int32Array}
+     */
+    #rows = new Int32Array(16);
+
+    /**
+     * The phases each volume's row holds, as f32, {@link NOISE_PHASE_WORDS} a volume by its index:
+     * `noise_offset`, `noise_warp_offset`, then `noise_flow_phase`.
+     * @type {Float32Array}
+     */
+    #written_phases = new Float32Array(16 * NOISE_PHASE_WORDS);
+
+    /** What {@link NOISE_PHASE_WRITER} is handed, reused for every row. */
+    #phase_record = {
+        noise_flow_phase: 0,
+        noise_offset: new Float32Array(3),
+        noise_warp_offset: new Float32Array(3),
+    };
+
+    /** The repack's scratch for each volume's inverse transform. */
+    #transform_inverse = new Float32Array(16);
+
     /**
      * The scene database's `participating_media_volumes` table; owned by the database.
      * @type {GPUTypedTable}
      */
     #table;
 
+    /**
+     * @type {GPUTileAtlas3D}
+     */
+    #noise_atlas;
+
+    /**
+     * Whether slot 0 holds the engine's tile yet. Baked on the first update, since a bake needs a
+     * command stream and the constructor has none.
+     * @type {boolean}
+     */
+    #default_baked = false;
+
     /**
      *
+     * @param {GPUDevice} device
      * @param {GPUTypedTable} table the scene database's `participating_media_volumes` table
      * @param {SceneVolumetrics} volumetrics
      */
-    constructor(table, volumetrics) {
-        this.#table = table;
+    constructor(device, table, volumetrics) {
+        assert.defined(device, 'device');
+        assert.defined(table, 'table');
+        assert.defined(volumetrics, 'volumetrics');
 
+        this.#table = table;
         this.source = volumetrics;
+
+        this.#noise_atlas = new GPUTileAtlas3D({
+            device,
+            format: PARTICIPATING_MEDIA_NOISE_TILE_FORMAT,
+            // a cube: the bake makes the same number of features along every edge
+            content_size: [PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE, PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE, PARTICIPATING_MEDIA_NOISE_TILE_CONTENT_SIZE],
+            border: PARTICIPATING_MEDIA_NOISE_TILE_BORDER,
+            slots_x: PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_X,
+            slots_y: PARTICIPATING_MEDIA_NOISE_ATLAS_SLOTS_Y,
+            capacity: PARTICIPATING_MEDIA_NOISE_ATLAS_CAPACITY,
+            // sampled by the density pass; the bake lands by copy, which the atlas provides for
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+            label: "GPUSceneVolumetrics/noise atlas",
+        });
+
+        // the first slot of a fresh atlas, which is what makes 0 the engine's by convention
+        const slot = this.#noise_atlas.allocate();
+
+        assert.equal(slot, PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT, 'the engine\'s tile takes the first slot');
     }
 
     /**
-     * Nothing to release: the rows belong to the scene database.
+     * The tiles a volume's `noise_slot` names. Slot {@link PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT}
+     * is the engine's; `allocate` one and `write` it for a tile of your own.
+     *
+     * @returns {GPUTileAtlas3D}
+     */
+    get noise_atlas() {
+        return this.#noise_atlas;
+    }
+
+    /**
+     * The rows belong to the scene database; the atlas is ours.
      */
     destroy() {
+        this.#noise_atlas.destroy();
     }
 
     /**
@@ -59,29 +181,185 @@ export class GPUSceneVolumetrics {
         gfx,
         time_delta_s
     ) {
-        if (this.#version === this.source.version) {
-            // no change
+        if (!this.#default_baked) {
+            const command = ShadeGPUCommandContext.create(gfx, 'GPUSceneVolumetrics/noise bake');
+
+            bake_volumetrics_noise_tile({
+                command,
+                atlas: this.#noise_atlas,
+                slot: PARTICIPATING_MEDIA_NOISE_DEFAULT_SLOT,
+                features: PARTICIPATING_MEDIA_NOISE_DEFAULT_FEATURES,
+                octaves: PARTICIPATING_MEDIA_NOISE_DEFAULT_OCTAVES,
+            });
+
+            command.finish();
+
+            this.#default_baked = true;
+        }
+
+        const source = this.source;
+
+        if (this.#version !== source.version) {
+            this.#repack();
+
+            this.#version = source.version;
+            // the repack wrote the phases as they stand
+            this.#noise_version = source.noise_version;
+
             return;
         }
 
+        if (this.#noise_version !== source.noise_version) {
+            this.#write_phases();
+
+            this.#noise_version = source.noise_version;
+        }
+    }
+
+    /**
+     * Every row's noise phases that differ from what this last wrote for it, and nothing else:
+     * {@link NOISE_PHASE_WRITER}'s words per changed row, through the table's partial stream.
+     *
+     * Compared while assigned, as f32 — the precision the row holds — against
+     * {@link #written_phases}, so a noisy volume that is not scrolling writes nothing. The volumes
+     * are the ones {@link #repack} packed, in the same order: adding or removing one moves the
+     * version, which repacks instead.
+     */
+    #write_phases() {
+        const table = this.#table;
+        const volumes = this.source.volumes;
+        const rows = this.#rows;
+        const written = this.#written_phases;
+        const record = this.#phase_record;
+        const offset_out = record.noise_offset;
+        const warp_out = record.noise_warp_offset;
+
+        const count = volumes.length;
+
+        for (let i = 0; i < count; i++) {
+            const row = rows[i];
+
+            if (row < 0) {
+                // no row: scaled to nothing on an axis
+                continue;
+            }
+
+            const v = volumes[i];
+            const offset = v.noise_offset;
+            const warp = v.noise_warp_offset;
+            const base = i * NOISE_PHASE_WORDS;
+
+            let changed = false;
+
+            const o0 = Math.fround(offset[0]);
+            const o1 = Math.fround(offset[1]);
+            const o2 = Math.fround(offset[2]);
+            const w0 = Math.fround(warp[0]);
+            const w1 = Math.fround(warp[1]);
+            const w2 = Math.fround(warp[2]);
+            const flow = Math.fround(v.noise_flow_phase);
+
+            if (written[base] !== o0) {
+                written[base] = o0;
+                changed = true;
+            }
+
+            if (written[base + 1] !== o1) {
+                written[base + 1] = o1;
+                changed = true;
+            }
+
+            if (written[base + 2] !== o2) {
+                written[base + 2] = o2;
+                changed = true;
+            }
+
+            if (written[base + 3] !== w0) {
+                written[base + 3] = w0;
+                changed = true;
+            }
+
+            if (written[base + 4] !== w1) {
+                written[base + 4] = w1;
+                changed = true;
+            }
+
+            if (written[base + 5] !== w2) {
+                written[base + 5] = w2;
+                changed = true;
+            }
+
+            if (written[base + 6] !== flow) {
+                written[base + 6] = flow;
+                changed = true;
+            }
+
+            if (!changed) {
+                continue;
+            }
+
+            offset_out[0] = o0;
+            offset_out[1] = o1;
+            offset_out[2] = o2;
+            warp_out[0] = w0;
+            warp_out[1] = w1;
+            warp_out[2] = w2;
+            record.noise_flow_phase = flow;
+
+            table.set_fields(row, record, NOISE_PHASE_WRITER);
+        }
+    }
+
+    /**
+     * The whole table, cleared and refilled in the scene's volume order, dense from row 0; each
+     * volume's row and phases remembered for {@link #write_phases}.
+     */
+    #repack() {
         const table = this.#table;
 
         table.clear();
 
-        const m4_transform_inverse = new Float32Array(16);
+        const m4_transform_inverse = this.#transform_inverse;
 
         const volumes = this.source.volumes;
+        const count = volumes.length;
+
+        if (this.#rows.length < count) {
+            const capacity = Math.max(count, 2 * this.#rows.length);
+
+            this.#rows = new Int32Array(capacity);
+            this.#written_phases = new Float32Array(capacity * NOISE_PHASE_WORDS);
+        }
+
+        const rows = this.#rows;
+        const written = this.#written_phases;
 
-        for (let i = 0; i < volumes.length; i++) {
+        for (let i = 0; i < count; i++) {
             const v = volumes[i];
 
-            if (!m4_invert(m4_transform_inverse, v.transform.matrix)) {
+            rows[i] = -1;
+
+            // the transform itself: its matrix is its first sixteen elements
+            if (!m4_invert(m4_transform_inverse, v.transform)) {
                 // scaled to nothing on an axis: it encloses nothing, and without an inverse every
                 // pass would place it wrong — an all-zero matrix puts the whole world inside it
                 continue;
             }
 
-            table.add({
+            assert.greaterThan(v.noise_scale, 0, 'noise_scale must be positive');
+            assert.ok(this.#noise_atlas.is_live(v.noise_slot), `noise_slot ${v.noise_slot} is not an allocated tile of this scene's noise atlas`);
+
+            const base = i * NOISE_PHASE_WORDS;
+
+            written[base] = Math.fround(v.noise_offset[0]);
+            written[base + 1] = Math.fround(v.noise_offset[1]);
+            written[base + 2] = Math.fround(v.noise_offset[2]);
+            written[base + 3] = Math.fround(v.noise_warp_offset[0]);
+            written[base + 4] = Math.fround(v.noise_warp_offset[1]);
+            written[base + 5] = Math.fround(v.noise_warp_offset[2]);
+            written[base + 6] = Math.fround(v.noise_flow_phase);
+
+            rows[i] = table.add({
                 particle_spec: {
                     scattering: v.particle_spec.scattering,
                     extinction: v.particle_spec.extinction,
@@ -93,10 +371,15 @@ export class GPUSceneVolumetrics {
                 transform_inverse: m4_transform_inverse,
                 fade_distance: v.fade_distance,
                 density: v.density,
+                noise_wind_factor: v.noise_wind_factor,
+                noise_flow_phase: v.noise_flow_phase,
+                noise_offset: v.noise_offset,
+                noise_warp_offset: v.noise_warp_offset,
+                noise_slot: v.noise_slot,
+                noise_strength: v.noise_strength,
+                noise_inverse_scale: 1 / v.noise_scale,
+                noise_warp: v.noise_warp,
             });
         }
-
-        this.#version = this.source.version;
     }
-
 }

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

@@ -30,8 +30,12 @@ export class GPUViewVolumetrics {
      * @param {number} options.light_cluster_lookup
      * @param {number} options.light_cluster_parameters
      * @param {number} options.shadowmap_atlas
-     * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode the renderer's; picks the froxel GI
-     *   module that starts the froxel irradiance volume
+     * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the passes that light froxels are built
+     *   for them, the froxel GI that starts the froxel irradiance volume among them
+     * @param {import("../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap} [options.brick4] the scene's,
+     *   while Brick4 runs
+     * @param {import("../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume} [options.lpv] the
+     *   scene's, while LPV runs
      * @returns {{resolved: number, metadata: number, irradiance: {Y: number, CoCg: number}}} the
      *   integrated aerial LUT, the metadata buffer, and the froxel irradiance volume
      *   (chunk_volumetrics_irradiance_sh) that lit particles are lit by. The two do not depend on
@@ -39,13 +43,15 @@ export class GPUViewVolumetrics {
      *   with no participating-media volume records no fog at all, and `resolved` is then a constant:
      *   no in-scatter, full transmittance.
      */
-    graph_update({ graph, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, indirect_lighting_mode, }: {
+    graph_update({ graph, light_cluster_data, light_cluster_lookup, light_cluster_parameters, shadowmap_atlas, shader_switches, brick4, lpv, }: {
         graph: FrameGraph;
         light_cluster_data: number;
         light_cluster_lookup: number;
         light_cluster_parameters: number;
         shadowmap_atlas: number;
-        indirect_lighting_mode: import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode;
+        shader_switches?: ShaderSwitchSet;
+        brick4?: import("../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap;
+        lpv?: import("../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume;
     }): {
         resolved: number;
         metadata: number;
@@ -58,4 +64,5 @@ export class GPUViewVolumetrics {
 }
 export type FrameGraph = import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
 export type GPUViewContext = import("../view/GPUViewContext.js").GPUViewContext;
+import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
 //# sourceMappingURL=GPUViewVolumetrics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUViewVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUViewVolumetrics.js"],"names":[],"mappings":"AAkCA;IA2II;;;;OAIG;IACH,kBAHW,cAAc,qBAyCxB;IAlJD;;OAEG;IACH,4BAOC;IAjBD;;OAEG;IACH,2BAEC;IAsCD;;OAEG;IACH,0BAEC;IAZD;;OAEG;IACH,yBAEC;IAkHD,gBAaC;IA6ND;;;;;;;;;;;;;;;;OAgBG;IACH;QAd+B,KAAK,EAAzB,UAAU;QACM,kBAAkB,EAAlC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACU,wBAAwB,EAAxC,MAAM;QACU,eAAe,EAA/B,MAAM;QACuE,sBAAsB,EAAnG,OAAO,iCAAiC,EAAE,yBAAyB;QAEjE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAmIvF;;CAEJ;yBA1jBY,OAAO,2DAA2D,EAAE,UAAU;6BAC9E,OAAO,2BAA2B,EAAE,cAAc"}
+{"version":3,"file":"GPUViewVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUViewVolumetrics.js"],"names":[],"mappings":"AAmCA;IA2II;;;;OAIG;IACH,kBAHW,cAAc,qBAyCxB;IAlJD;;OAEG;IACH,4BAOC;IAjBD;;OAEG;IACH,2BAEC;IAsCD;;OAEG;IACH,0BAEC;IAZD;;OAEG;IACH,yBAEC;IAkHD,gBAaC;IA6ND;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;QAlB+B,KAAK,EAAzB,UAAU;QACM,kBAAkB,EAAlC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACU,wBAAwB,EAAxC,MAAM;QACU,eAAe,EAA/B,MAAM;QACoB,eAAe,GAAzC,eAAe;QAEoE,MAAM,GAAzF,OAAO,iDAAiD,EAAE,cAAc;QAEkB,GAAG,GAA7F,OAAO,mDAAmD,EAAE,mBAAmB;QAE7E;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAwIvF;;CAEJ;yBAnkBY,OAAO,2DAA2D,EAAE,UAAU;6BAC9E,OAAO,2BAA2B,EAAE,cAAc;gCAf/B,uCAAuC"}

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

@@ -10,6 +10,7 @@ import {
     build_volumetrics_sun_shadow_transform,
     volumetrics_sun_shadow_cascade_far
 } from "./build_volumetrics_sun_shadow_transform.js";
+import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
 import { graph_build_froxel_irradiance } from "./graph_build_froxel_irradiance.js";
 import { graph_build_volumetrics } from "./graph_build_volumetrics.js";
 import {
@@ -458,8 +459,12 @@ export class GPUViewVolumetrics {
      * @param {number} options.light_cluster_lookup
      * @param {number} options.light_cluster_parameters
      * @param {number} options.shadowmap_atlas
-     * @param {import("../ShadeIndirectLightingMode.js").ShadeIndirectLightingMode} options.indirect_lighting_mode the renderer's; picks the froxel GI
-     *   module that starts the froxel irradiance volume
+     * @param {ShaderSwitchSet} [options.shader_switches] the renderer's; the passes that light froxels are built
+     *   for them, the froxel GI that starts the froxel irradiance volume among them
+     * @param {import("../global_illumination/brick4/Brick4LightMap.js").Brick4LightMap} [options.brick4] the scene's,
+     *   while Brick4 runs
+     * @param {import("../global_illumination/lpv/GPULightProbeVolume.js").GPULightProbeVolume} [options.lpv] the
+     *   scene's, while LPV runs
      * @returns {{resolved: number, metadata: number, irradiance: {Y: number, CoCg: number}}} the
      *   integrated aerial LUT, the metadata buffer, and the froxel irradiance volume
      *   (chunk_volumetrics_irradiance_sh) that lit particles are lit by. The two do not depend on
@@ -473,7 +478,9 @@ export class GPUViewVolumetrics {
                      light_cluster_lookup,
                      light_cluster_parameters,
                      shadowmap_atlas,
-                     indirect_lighting_mode,
+                     shader_switches = ShaderSwitchSet.EMPTY,
+                     brick4,
+                     lpv,
                  }) {
 
         const view = this.#view;
@@ -524,7 +531,9 @@ export class GPUViewVolumetrics {
             shadowmap_atlas,
             volumetrics_metadata: gr_metadata,
             resolution,
-            indirect_lighting_mode,
+            shader_switches,
+            brick4,
+            lpv,
         });
 
         if (view.scene.volumetrics.source.volumes.length === 0) {
@@ -582,6 +591,7 @@ export class GPUViewVolumetrics {
             taa_history,
             taa_output,
             camera_previous: view.gpu_previous_camera_state,
+            shader_switches,
         });
 
         this.#reset_history = false;

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

@@ -1021,3 +1021,100 @@ Observed in that same set-up, and not changed here: with the light 0.25 m from t
 jittered irradiance shows as blotchy 16-pixel blocks around the light even after 420 frames of the
 main TAA, identically on the old build. Nothing filters the irradiance volume in time, and a whole
 froxel flickering together is coherent over more pixels than the TAA's neighbourhood clamp looks at.
+
+## Noise on the volumes — built and measured, 2026-10-15
+
+`VOLUMETRIC_NOISE_PLAN_2026_10_15.md` is the design and the record of how it got there (Smolder,
+Enshrouded 2025 and AC4 read; three revisions; Alex's answers). What landed: a general 3-D tile
+atlas (`texture/atlas/GPUTileAtlas3D`), the volumetrics instance of it on `GPUSceneVolumetrics`
+(`r8unorm`, 128³ content + a one-texel skirt, growing by a layer along z), slot 0 baked on the
+device from three octaves of `psrdnoise3` the first time the scene updates, and a per-volume
+`[0, 1]` multiplier on density — two trilinear taps at most (base, and a warp tap that displaces the
+base lookup), read at a per-froxel STBN-jittered point at a third decorrelation offset `(53, 97)`,
+scrolled by phases the host folds and wraps in f64. The path tracer reads the same function.
+
+**The tile is on the device.** Read back off the atlas through `download_region` in the froxel
+playground (RTX 4090, Chrome, headless): a z slice through the middle of slot 0 spans 0–255 with a
+mean of 125.5 and texels in all eight histogram bins; every skirt texel checked equals the content
+texel it wraps; a row reads 127, 167, 200, 220, …, 253, …, 14 — a continuous field, not a block.
+
+**The picture changes by the noise and nothing else.** `measure.js`'s image `ab` from the "Inside
+the fog" viewpoint at 1080p, the fog bank with `noise_strength` 0 against 1 (16-frame averages after
+45 frames of settling, the floor from a repeat of each side):
+
+| | mean |d| luminance |
+|---|---|
+| floor, off vs off / on vs on | 0.44 / 0.24 |
+| signal, off vs on, twice | 17.0 / 16.7 |
+
+Signed mean +14.9: the fog thins where the tile is below its mean, so more of the lit scene shows.
+
+**What it costs: the taps are below the density pass's timestamp quantum unless the camera is in
+the noisy volume.** Per-pass GPU medians (`profile`, 60 recorded frames an arm, six rounds, the
+two arms interleaved and their order alternated each round, 3796×1852):
+
+| view | `build participating media`, uniform | with noise | frame |
+|---|---|---|---|
+| Dead overview, 2 noisy volumes covering few froxels | 0.2355 (6/6 identical) | 0.2355 (6/6) | 5.062 vs 5.068 |
+| Inside the graveyard fog | 0.2427–0.2437 | 0.2468 (6/6) | 4.619 vs 4.624 |
+| Inside the fog bank, 3 noisy volumes | 0.2642 (6/6) | 0.2703–0.2714 | 5.456 vs 5.466 |
+
+So +0.003 to +0.007 ms on the pass at 2160p with every froxel in front of the camera paying two
+taps, spreads disjoint; the frame totals sit inside their own round-to-round spread (±0.01 ms).
+Lighting, TAA and the LUT read identically in both arms. The whole-frame readings are the usual
+reminder that the pass capture is the number to believe (the README's Q-04 story).
+
+**The uniform path is untouched by construction**, not by measurement: `noise_strength > 0` is a
+per-volume uniform branch around the taps. A zero-volume scene was not re-timed.
+
+Not done on the device: the froxel-versus-tracer parity check for a noisy volume (both paths read
+one function and `chunk_participating_media_noise.spec.js` pins it on the emulator), and the
+giant-particle seam check with a noisy volume (the point is jittered on all three axes exactly as
+the lighting pass's is). Driver and probes: `probe/` in session 2fe0ac92's scratchpad, a one-off.
+
+## The flow map is linked only where the wind field has cascades — measured, 2026-10-16
+
+The noise's flow map (the GPU fluid's volumetrics, `e54461d36`) cost the froxel build 16.4 → 18.3 µs
+in uniform air, a scene with no fluid, where it never runs: a reach of exactly zero takes the one
+tap. The GPU fluid session's breakdown (RTX 4090, 1280×720, camera inside the fog) put it on the code
+being linked, not on running it: without the flow map and the wind sample the shader read 0.1–0.2 µs
+off the old one, and an exact-compare skip, dropping the two taps, or dropping the wind sample, each
+on its own, still cost about 1.8 µs.
+
+So the field's shape is a shader switch, `WIND_FIELD_UNIFORM` (a bool; `false`, the default, is the
+field as it is), decided in two places from one value: `chunk_wind_field_sample` (uniform: return
+`far_velocity`, which the cascaded read returns at every point of a field with no cascades) and
+`chunk_participating_media_noise` (uniform: the one tap at the scrolled lookup, the flow map's value
+at a zero departure). The froxel build picks its variant from the field it binds,
+`scene.wind.cascade_count === 0`, the frame it binds it; the other readers are left at the default.
+`ShaderSwitchSet.with` now remembers the sets it hands out, so deriving the build's set every frame
+allocates nothing (it built two arrays, a key and an assert message a call: 595 B).
+
+**On the device**, the three froxel builds interleaved by blocks of four frames in one capture: the
+pass as built (`new`, the variant it picked), the shader before the flow map (`old`, `ec5f0c093`), and
+master's (`head`, the flow map always linked). Means of ~175 frames an arm a round, µs, three rounds
+each:
+
+| scene | order | new | old | head |
+|---|---|---|---|---|
+| uniform air | new, old, head | 15.89 / 15.71 / 16.28 | 15.80 / 15.65 / 16.27 | 17.32 / 17.17 / 17.80 |
+| uniform air | head, old, new | 14.24 / 14.68 / 14.97 | 14.23 / 14.75 / 15.09 | 15.66 / 16.02 / 16.46 |
+| a domain, a wake, a vortex | head, old, new | 20.13 / 17.05 / 17.05 | 16.76 / 13.98 / 13.87 | 20.18 / 17.17 / 16.79 |
+
+Uniform air is the old cost to within 0.1 µs; disturbed air (the `new` arm on the full variant)
+is master's to within ±0.3 µs either way. TAA, which no arm touches, read alike in every row. The
+labels in the capture confirm which variant the pass picked in each scene.
+
+Every touched shader compiles through Tint on the device and builds a pipeline: both variants of the
+build, the water cull, the fluid query, the accumulating tracer, the Brick4 bake, the LPV trace, both
+lightmap viz bakes. Linked for the default, the seven readers of the wind alone (five particle
+passes, the water cull, the fluid query) are byte-identical to master's WGSL; the six readers of the
+noise differ only by the scroll-and-warp lookup now being one function both alternatives call.
+
+Specs: on the emulator, linked for a uniform field, the multiplier, the multiplier in a wind, the
+density and the wind read what the full variant reads in a field with no cascades, bit for bit (96
+random volumes, three far fields; red against a scrolled alternative that drops the warp and a
+uniform wind of zero). On the software device, the froxel build dispatches the uniform variant in a
+scene with no fluid and the full one when the field has a cascade, judged by the module it was
+handed (red against a pass that never and one that always picks it). Driver: `wfu_*` in session
+f2a32857's scratchpad, a one-off, adapted from the GPU fluid session's `s3g_*`.

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICIPATING_MEDIA_VOLUME_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/PARTICIPATING_MEDIA_VOLUME_STRUCT.js"],"names":[],"mappings":"AAWA,6DAcE;6BAxB2B,gCAAgC"}
+{"version":3,"file":"PARTICIPATING_MEDIA_VOLUME_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/PARTICIPATING_MEDIA_VOLUME_STRUCT.js"],"names":[],"mappings":"AAWA,6DAuDE;6BAjE2B,gCAAgC"}

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

@@ -1,4 +1,4 @@
-import { f32, mat4x4f, vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { f32, mat4x4f, u32, vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
 
 const VOLUMETRICS_PARTICLE_SPEC_STRUCT = WebGPUStruct.from({
@@ -23,4 +23,45 @@ export const PARTICIPATING_MEDIA_VOLUME_STRUCT = WebGPUStruct.from({
      * Numeric density of particles. In physics this would be `N`.
      */
     density: f32,
+    /**
+     * How much of the scene's wind the noise feels: the shader scales the published wind field's
+     * departure from its far field by it, as the host scales the far field it folds into
+     * `noise_offset`. 0 reads no wind. Placed here, with the flow phase, in the eight bytes the
+     * vec3 below would otherwise pad.
+     */
+    noise_wind_factor: f32,
+    /**
+     * The flow map's clock, `t / PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD`, wrapped to [0, 1) on the
+     * host: the GPU has no clock of its own. See `chunk_participating_media_noise`.
+     */
+    noise_flow_phase: f32,
+    /**
+     * Noise: a tile of the volumetrics noise atlas, sampled in world space and multiplied into the
+     * density. See `chunk_participating_media_noise`.
+     *
+     * The scroll of the base tap, in tile units, wrapped to [0, 1) on the host — the GPU never
+     * multiplies a velocity by a time.
+     */
+    noise_offset: vec3f,
+    /**
+     * The scroll of the warp tap, in its own tile units, wrapped to [0, 1) on the host.
+     */
+    noise_warp_offset: vec3f,
+    /**
+     * Which tile: a slot of the atlas. 0 is the engine's own.
+     */
+    noise_slot: u32,
+    /**
+     * [0, 1]: how far the density goes from uniform toward the tile's multiplier. 0 means the
+     * noise is not evaluated at all.
+     */
+    noise_strength: f32,
+    /**
+     * 1 / the tile's world size in metres: world position times this is the tile coordinate.
+     */
+    noise_inverse_scale: f32,
+    /**
+     * How far, in tile units, the warp tap may displace the base lookup. 0 means one tap.
+     */
+    noise_warp: f32,
 })