@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -1,4 +1,5 @@
 /**
+ * @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
@@ -14,20 +15,41 @@
  * 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: PipelineEnquiry): void;
     /**
      *
+     * @param {GPUDevice} device
      * @param {GPUTypedTable} table the scene database's `participating_media_volumes` table
      * @param {SceneVolumetrics} volumetrics
      */
-    constructor(table: import("../buffer/table/GPUTypedTable.js").GPUTypedTable<any>, volumetrics: SceneVolumetrics);
+    constructor(device: GPUDevice, table: import("../buffer/table/GPUTypedTable.js").GPUTypedTable<any>, volumetrics: SceneVolumetrics);
     /**
      * @type {SceneVolumetrics}
      */
     source: SceneVolumetrics;
     /**
-     * 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(): GPUTileAtlas3D;
+    /**
+     * The rows belong to the scene database; the atlas is ours.
      */
     destroy(): void;
     /**
@@ -38,7 +60,9 @@ export class GPUSceneVolumetrics {
     update(gfx: GraphicsContext, time_delta_s: number): void;
     #private;
 }
+export type PipelineEnquiry = import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
 export type GraphicsContext = import("../GraphicsContext.js").GraphicsContext;
 export type SceneVolumetrics = import("./SceneVolumetrics.js").SceneVolumetrics;
 export type GPUTypedTable = import("../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
+import { GPUTileAtlas3D } from "../texture/atlas/GPUTileAtlas3D.js";
 //# sourceMappingURL=GPUSceneVolumetrics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUSceneVolumetrics.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH;IAeI;;;;OAIG;IACH,+FAFW,gBAAgB,EAM1B;IAtBD;;OAEG;IACH,QAFU,gBAAgB,CAEpB;IAqBN;;OAEG;IACH,gBACC;IAED;;;;OAIG;IACH,YAHW,eAAe,gBACf,MAAM,QA4ChB;;CAEJ;8BAlGY,OAAO,uBAAuB,EAAE,eAAe;+BAC/C,OAAO,uBAAuB,EAAE,gBAAgB"}
+{"version":3,"file":"GPUSceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUSceneVolumetrics.js"],"names":[],"mappings":"AAoBA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH;IAEI;;;;;OAKG;IACH,iCAFW,eAAe,QAIzB;IA2BD;;;;;OAKG;IACH,kHAFW,gBAAgB,EA2B1B;IAxDD;;OAEG;IACH,QAFU,gBAAgB,CAEpB;IAuDN;;;;;OAKG;IACH,kCAEC;IAED;;OAEG;IACH,gBAEC;IAED;;;;OAIG;IACH,YAHW,eAAe,gBACf,MAAM,QAqEhB;;CACJ;8BAxLY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;+BAC/C,OAAO,uBAAuB,EAAE,gBAAgB;;+BApB9B,oCAAoC"}

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

@@ -1,6 +1,25 @@
+import { assert } from "../../../core/assert.js";
 import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.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";
 
 /**
+ * @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
@@ -17,9 +36,25 @@ import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
  * 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}
      */
@@ -33,21 +68,66 @@ export class GPUSceneVolumetrics {
      */
     #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,
+            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,6 +139,22 @@ export class GPUSceneVolumetrics {
         gfx,
         time_delta_s
     ) {
+        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;
+        }
+
         if (this.#version === this.source.version) {
             // no change
             return;
@@ -81,6 +177,9 @@ export class GPUSceneVolumetrics {
                 continue;
             }
 
+            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`);
+
             table.add({
                 particle_spec: {
                     scattering: v.particle_spec.scattering,
@@ -93,10 +192,15 @@ export class GPUSceneVolumetrics {
                 transform_inverse: m4_transform_inverse,
                 fade_distance: v.fade_distance,
                 density: v.density,
+                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

@@ -32,6 +32,8 @@ export class GPUViewVolumetrics {
      * @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
      * @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 +41,14 @@ 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, indirect_lighting_mode, shader_switches, }: {
         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;
     }): {
         resolved: number;
         metadata: number;
@@ -58,4 +61,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;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAhB+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;QAEzC,eAAe,GAAzC,eAAe;QAEb;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,CAsIvF;;CAEJ;yBA/jBY,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 {
@@ -460,6 +461,8 @@ export class GPUViewVolumetrics {
      * @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
      * @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
@@ -474,6 +477,7 @@ export class GPUViewVolumetrics {
                      light_cluster_parameters,
                      shadowmap_atlas,
                      indirect_lighting_mode,
+                     shader_switches = ShaderSwitchSet.EMPTY,
                  }) {
 
         const view = this.#view;
@@ -525,6 +529,7 @@ export class GPUViewVolumetrics {
             volumetrics_metadata: gr_metadata,
             resolution,
             indirect_lighting_mode,
+            shader_switches,
         });
 
         if (view.scene.volumetrics.source.volumes.length === 0) {
@@ -582,6 +587,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,53 @@ 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.

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,6DA2CE;6BArD2B,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,33 @@ export const PARTICIPATING_MEDIA_VOLUME_STRUCT = WebGPUStruct.from({
      * Numeric density of particles. In physics this would be `N`.
      */
     density: 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,
 })

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

@@ -1,3 +1,19 @@
+/**
+ * Move a volume's noise along by a frame: the base tap's scroll by `velocity` metres a second over
+ * `dt`, and the warp tap's by the fraction of that its scale and its scroll ratio give it, each
+ * wrapped back into [0, 1) in f64 — the fold the GPU is spared.
+ *
+ * The caller owns the clock and the velocity: `ParticipatingMediaSystem` folds the scene's wind
+ * and the entity's own motion into one and calls this once a frame; a playground calls it from its
+ * loop. Not called, the field stands still, which is what an accumulating reference wants.
+ *
+ * @param {ParticipatingMediaVolume} volume
+ * @param {number[]|Float64Array} velocity metres a second, world axes
+ * @param {number} dt seconds
+ * @returns {boolean} whether anything moved — a zero velocity or a zero `dt` moves nothing, and a
+ *   caller that tells the renderer about changes need not when nothing did
+ */
+export function participating_media_volume_advance_noise(volume: ParticipatingMediaVolume, velocity: number[] | Float64Array, dt: number): boolean;
 export class VolumetricsParticleSpec {
     /**
      *
@@ -49,27 +65,49 @@ export const VOLUMETRIC_PARTICLE_SPEC_FOG: Readonly<VolumetricsParticleSpec>;
 export class ParticipatingMediaVolume {
     get id(): number;
     /**
-     * Gives us 3 octaves of perlin noise.
-     * @type {number[]}
+     * Noise on the density: a tile of the volumetrics noise atlas, sampled in world space and
+     * multiplied in, [0, 1]. This is how far the density goes from uniform toward the tile's
+     * value — 0 is a uniform volume and costs nothing, 1 is the tile as it is.
+     *
+     * See `chunk_participating_media_noise` and `VOLUMETRIC_NOISE_PLAN_2026_10_15.md`.
+     *
+     * @type {number}
      */
-    noise_scale: number[];
-    noise_amplitude: number[];
-    noise_offset: number[];
+    noise_strength: number;
     /**
-     * Direction and speed of noise scrolling
-     * @type {number[]}
+     * World size of one repeat of the tile, in metres, along each axis. The engine's default tile
+     * holds four base features an edge, so the default puts features 8 m apart.
+     * @type {number}
      */
-    noise_velocity: number[];
+    noise_scale: number;
     /**
-     * Scaling factor wrt. time, for scrolling noise in 4th dimension
-     * @type {number[]}
+     * How far the warp tap may displace the base lookup, in tile units. The warp is what makes the
+     * field change shape in place rather than only slide; 0 is one tap and no change of shape.
+     * @type {number}
      */
-    noise_evolution_speed: number[];
+    noise_warp: number;
     /**
-     * Current simulation time
+     * Which tile of the atlas: a slot. 0 is the one the engine bakes at start-up.
      * @type {number}
      */
-    time: number;
+    noise_slot: number;
+    /**
+     * The scroll of the base tap, in tile units, kept in [0, 1).
+     *
+     * **State, not a setting.** It is advanced by {@link participating_media_volume_advance_noise}
+     * from a velocity and a frame's time, and wrapped there, so that a velocity may change without
+     * the field jumping and a session may run for days without the number growing. The GPU reads
+     * it as is and never multiplies a velocity by a time.
+     *
+     * @type {number[]}
+     */
+    noise_offset: number[];
+    /**
+     * The scroll of the warp tap, in its own tile units, kept in [0, 1). State, like
+     * {@link noise_offset}.
+     * @type {number[]}
+     */
+    noise_warp_offset: number[];
     /**
      * Measured in particles per m3.
      * Default is value for very dense fog.

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

@@ -1 +1 @@
-{"version":3,"file":"ParticipatingMediaVolume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/ParticipatingMediaVolume.js"],"names":[],"mappings":"AAKA;IA6EI;;;;OAIG;IACH,+BAHW;QAAC,wBAAwB,EAAE,MAAM,EAAE,CAAC;QAAC,wBAAwB,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,GAClG,uBAAuB,CAalC;IAED,oDAIC;IAlGD;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,UAAQ;IAER,iCAIC;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAOjC;IAED;;;;;aA0BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAOnB;CAyBJ;AAED,6EAKI;AAIJ;IAII,iBAEC;IAED;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEM;IACxB,0BAA4B;IAC5B,uBAAyB;IAEzB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;OAGG;IACH,uBAFU,MAAM,EAAE,CAEgB;IAElC;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,gBAAc;IAEd;;;;;;;;;OASG;IACH,qCAEC;IAED,uCAA+E;IAE/E;;;;;;OAMG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;;;;;;;;OAWG;IACH,WAFU,WAAW,CAES;;CAEjC;4BAhM2B,8CAA8C"}
+{"version":3,"file":"ParticipatingMediaVolume.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/ParticipatingMediaVolume.js"],"names":[],"mappings":"AAiOA;;;;;;;;;;;;;;GAcG;AACH,iEANW,wBAAwB,YACxB,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,GACJ,OAAO,CAmCnB;AAvQD;IA6EI;;;;OAIG;IACH,+BAHW;QAAC,wBAAwB,EAAE,MAAM,EAAE,CAAC;QAAC,wBAAwB,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,GAClG,uBAAuB,CAalC;IAED,oDAIC;IAlGD;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,UAAQ;IAER,iCAIC;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAOjC;IAED;;;;;aA0BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAOnB;CAyBJ;AAED,6EAKI;AAIJ;IAII,iBAEC;IAED;;;;;;;;OAQG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,aAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,YAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;OASG;IACH,cAFU,MAAM,EAAE,CAEO;IAEzB;;;;OAIG;IACH,mBAFU,MAAM,EAAE,CAEY;IAE9B;;;OAGG;IACH,gBAAc;IAEd;;;;;;;;;OASG;IACH,qCAEC;IAED,uCAA+E;IAE/E;;;;;;OAMG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;;;;;;;;OAWG;IACH,WAFU,WAAW,CAES;;CAEjC;4BA5N2B,8CAA8C"}

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

@@ -2,6 +2,10 @@ import { assert } from "../../../core/assert.js";
 import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
 import { rgb_to_luminance } from "../../../core/color/rgb_to_luminance.js";
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import {
+    PARTICIPATING_MEDIA_NOISE_WARP_SCALE,
+    PARTICIPATING_MEDIA_NOISE_WARP_SCROLL
+} from "./noise/PARTICIPATING_MEDIA_NOISE.js";
 
 export class VolumetricsParticleSpec {
     /**
@@ -123,30 +127,54 @@ export class ParticipatingMediaVolume {
     }
 
     /**
-     * Gives us 3 octaves of perlin noise.
-     * @type {number[]}
+     * Noise on the density: a tile of the volumetrics noise atlas, sampled in world space and
+     * multiplied in, [0, 1]. This is how far the density goes from uniform toward the tile's
+     * value — 0 is a uniform volume and costs nothing, 1 is the tile as it is.
+     *
+     * See `chunk_participating_media_noise` and `VOLUMETRIC_NOISE_PLAN_2026_10_15.md`.
+     *
+     * @type {number}
      */
-    noise_scale = [0, 0, 0];
-    noise_amplitude = [1, 1, 1];
-    noise_offset = [0, 0, 0];
+    noise_strength = 0;
 
     /**
-     * Direction and speed of noise scrolling
-     * @type {number[]}
+     * World size of one repeat of the tile, in metres, along each axis. The engine's default tile
+     * holds four base features an edge, so the default puts features 8 m apart.
+     * @type {number}
      */
-    noise_velocity = [0, 0, 0];
+    noise_scale = 32;
 
     /**
-     * Scaling factor wrt. time, for scrolling noise in 4th dimension
-     * @type {number[]}
+     * How far the warp tap may displace the base lookup, in tile units. The warp is what makes the
+     * field change shape in place rather than only slide; 0 is one tap and no change of shape.
+     * @type {number}
      */
-    noise_evolution_speed = [0, 0, 0];
+    noise_warp = 0.1;
 
     /**
-     * Current simulation time
+     * Which tile of the atlas: a slot. 0 is the one the engine bakes at start-up.
      * @type {number}
      */
-    time = 0;
+    noise_slot = 0;
+
+    /**
+     * The scroll of the base tap, in tile units, kept in [0, 1).
+     *
+     * **State, not a setting.** It is advanced by {@link participating_media_volume_advance_noise}
+     * from a velocity and a frame's time, and wrapped there, so that a velocity may change without
+     * the field jumping and a session may run for days without the number growing. The GPU reads
+     * it as is and never multiplies a velocity by a time.
+     *
+     * @type {number[]}
+     */
+    noise_offset = [0, 0, 0];
+
+    /**
+     * The scroll of the warp tap, in its own tile units, kept in [0, 1). State, like
+     * {@link noise_offset}.
+     * @type {number[]}
+     */
+    noise_warp_offset = [0, 0, 0];
 
     /**
      * Measured in particles per m3.
@@ -193,4 +221,61 @@ export class ParticipatingMediaVolume {
      */
     transform = new Transform64();
 
+}
+
+/**
+ * Move a volume's noise along by a frame: the base tap's scroll by `velocity` metres a second over
+ * `dt`, and the warp tap's by the fraction of that its scale and its scroll ratio give it, each
+ * wrapped back into [0, 1) in f64 — the fold the GPU is spared.
+ *
+ * The caller owns the clock and the velocity: `ParticipatingMediaSystem` folds the scene's wind
+ * and the entity's own motion into one and calls this once a frame; a playground calls it from its
+ * loop. Not called, the field stands still, which is what an accumulating reference wants.
+ *
+ * @param {ParticipatingMediaVolume} volume
+ * @param {number[]|Float64Array} velocity metres a second, world axes
+ * @param {number} dt seconds
+ * @returns {boolean} whether anything moved — a zero velocity or a zero `dt` moves nothing, and a
+ *   caller that tells the renderer about changes need not when nothing did
+ */
+export function participating_media_volume_advance_noise(volume, velocity, dt) {
+    assert.isInstanceOf(volume, ParticipatingMediaVolume, 'volume');
+    assert.defined(velocity, 'velocity');
+    assert.isNumber(dt, 'dt');
+    assert.isFinite(dt, 'dt');
+
+    const vx = velocity[0];
+    const vy = velocity[1];
+    const vz = velocity[2];
+
+    if (dt === 0 || (vx === 0 && vy === 0 && vz === 0)) {
+        return false;
+    }
+
+    assert.greaterThan(volume.noise_scale, 0, 'noise_scale must be positive to scroll');
+
+    // metres to tile units
+    const step = dt / volume.noise_scale;
+    const warp_step = step * PARTICIPATING_MEDIA_NOISE_WARP_SCALE * PARTICIPATING_MEDIA_NOISE_WARP_SCROLL;
+
+    const offset = volume.noise_offset;
+    const warp_offset = volume.noise_warp_offset;
+
+    offset[0] = wrap_unit(offset[0] + vx * step);
+    offset[1] = wrap_unit(offset[1] + vy * step);
+    offset[2] = wrap_unit(offset[2] + vz * step);
+
+    warp_offset[0] = wrap_unit(warp_offset[0] + vx * warp_step);
+    warp_offset[1] = wrap_unit(warp_offset[1] + vy * warp_step);
+    warp_offset[2] = wrap_unit(warp_offset[2] + vz * warp_step);
+
+    return true;
+}
+
+/**
+ * @param {number} x
+ * @returns {number} x wrapped into [0, 1)
+ */
+function wrap_unit(x) {
+    return x - Math.floor(x);
 }