@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -1,3 +1,27 @@
+/**
+ * Move a volume's noise along by a frame: the base tap's field 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
+ * phase wrapped back into [0, 1) in f64 — the fold the GPU is spared. The field is carried
+ * downwind: the shader looks up `position / scale + offset`, so the offset runs against the
+ * velocity, and what was at `p` is at `p + velocity · dt` after.
+ *
+ * A volume that feels the wind (`noise_wind_factor` not 0) also has its flow clock,
+ * `noise_flow_phase`, moved on by `dt / PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD`, wrapped, whatever the
+ * velocity: the shader carries the noise along the wind field's departure from the far field with
+ * it, and the departure is the GPU's to know.
+ *
+ * The caller owns the clock and the velocity: `ParticipatingMediaSystem` folds the scene's far field
+ * 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 `dt` moves nothing, nor does a zero velocity on
+ *   a volume out of the wind, 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 +73,67 @@ export const VOLUMETRIC_PARTICLE_SPEC_FOG: Readonly<VolumetricsParticleSpec>;
 export class ParticipatingMediaVolume {
     get id(): number;
     /**
-     * Gives us 3 octaves of perlin noise.
+     * 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_strength: 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_scale: 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_warp: number;
+    /**
+     * Which tile of the atlas: a slot. 0 is the one the engine bakes at start-up.
+     * @type {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_scale: number[];
-    noise_amplitude: number[];
     noise_offset: number[];
     /**
-     * Direction and speed of noise scrolling
+     * The scroll of the warp tap, in its own tile units, kept in [0, 1). State, like
+     * {@link noise_offset}.
      * @type {number[]}
      */
-    noise_velocity: number[];
+    noise_warp_offset: number[];
     /**
-     * Scaling factor wrt. time, for scrolling noise in 4th dimension
-     * @type {number[]}
+     * How much of the scene's wind the noise feels, 1 all of it and 0 none: a setting. The caller of
+     * {@link participating_media_volume_advance_noise} folds the far field by it into the scroll; the
+     * shaders scale the wind field's departure from the far field by it where they evaluate the
+     * noise, and a volume at 0 never samples the wind field.
+     *
+     * @type {number}
      */
-    noise_evolution_speed: number[];
+    noise_wind_factor: number;
     /**
-     * Current simulation time
+     * The flow map's clock, `t / PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD`, kept in [0, 1). State, like
+     * {@link noise_offset}: advanced by {@link participating_media_volume_advance_noise} while the
+     * volume feels the wind, and read by the shader to carry the noise along the wind field's
+     * departure from the far field.
+     *
      * @type {number}
      */
-    time: number;
+    noise_flow_phase: 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":"AAsPA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iEAPW,wBAAwB,YACxB,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,GACJ,OAAO,CAgDnB;AA/SD;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;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,gBAAc;IAEd;;;;;;;;;OASG;IACH,qCAEC;IAED,uCAA+E;IAE/E;;;;;;OAMG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;;;;;;;;OAWG;IACH,WAFU,WAAW,CAES;;CAEjC;4BAjP2B,8CAA8C"}

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

@@ -2,6 +2,11 @@ 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_FLOW_PERIOD,
+    PARTICIPATING_MEDIA_NOISE_WARP_SCALE,
+    PARTICIPATING_MEDIA_NOISE_WARP_SCROLL
+} from "./noise/PARTICIPATING_MEDIA_NOISE.js";
 
 export class VolumetricsParticleSpec {
     /**
@@ -123,30 +128,74 @@ export class ParticipatingMediaVolume {
     }
 
     /**
-     * Gives us 3 octaves of perlin noise.
+     * 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_strength = 0;
+
+    /**
+     * 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_scale = 32;
+
+    /**
+     * 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_warp = 0.1;
+
+    /**
+     * Which tile of the atlas: a slot. 0 is the one the engine bakes at start-up.
+     * @type {number}
+     */
+    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_scale = [0, 0, 0];
-    noise_amplitude = [1, 1, 1];
     noise_offset = [0, 0, 0];
 
     /**
-     * Direction and speed of noise scrolling
+     * The scroll of the warp tap, in its own tile units, kept in [0, 1). State, like
+     * {@link noise_offset}.
      * @type {number[]}
      */
-    noise_velocity = [0, 0, 0];
+    noise_warp_offset = [0, 0, 0];
 
     /**
-     * Scaling factor wrt. time, for scrolling noise in 4th dimension
-     * @type {number[]}
+     * How much of the scene's wind the noise feels, 1 all of it and 0 none: a setting. The caller of
+     * {@link participating_media_volume_advance_noise} folds the far field by it into the scroll; the
+     * shaders scale the wind field's departure from the far field by it where they evaluate the
+     * noise, and a volume at 0 never samples the wind field.
+     *
+     * @type {number}
      */
-    noise_evolution_speed = [0, 0, 0];
+    noise_wind_factor = 1;
 
     /**
-     * Current simulation time
+     * The flow map's clock, `t / PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD`, kept in [0, 1). State, like
+     * {@link noise_offset}: advanced by {@link participating_media_volume_advance_noise} while the
+     * volume feels the wind, and read by the shader to carry the noise along the wind field's
+     * departure from the far field.
+     *
      * @type {number}
      */
-    time = 0;
+    noise_flow_phase = 0;
 
     /**
      * Measured in particles per m3.
@@ -193,4 +242,81 @@ export class ParticipatingMediaVolume {
      */
     transform = new Transform64();
 
+}
+
+/**
+ * Move a volume's noise along by a frame: the base tap's field 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
+ * phase wrapped back into [0, 1) in f64 — the fold the GPU is spared. The field is carried
+ * downwind: the shader looks up `position / scale + offset`, so the offset runs against the
+ * velocity, and what was at `p` is at `p + velocity · dt` after.
+ *
+ * A volume that feels the wind (`noise_wind_factor` not 0) also has its flow clock,
+ * `noise_flow_phase`, moved on by `dt / PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD`, wrapped, whatever the
+ * velocity: the shader carries the noise along the wind field's departure from the far field with
+ * it, and the departure is the GPU's to know.
+ *
+ * The caller owns the clock and the velocity: `ParticipatingMediaSystem` folds the scene's far field
+ * 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 `dt` moves nothing, nor does a zero velocity on
+ *   a volume out of the wind, 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) {
+        return false;
+    }
+
+    let moved = false;
+
+    if (volume.noise_wind_factor !== 0) {
+        volume.noise_flow_phase = wrap_unit(volume.noise_flow_phase + dt / PARTICIPATING_MEDIA_NOISE_FLOW_PERIOD);
+        moved = true;
+    }
+
+    if (vx === 0 && vy === 0 && vz === 0) {
+        return moved;
+    }
+
+    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;
+
+    // the lookup is `position / scale + offset`, so the field moves along +v as the offset moves along -v
+    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);
 }

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"SceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/SceneVolumetrics.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH;IACI;;;OAGG;IACH,SAFU,wBAAwB,EAAE,CAEvB;IAEb,gBAAY;IAEZ;;;OAGG;IACH,YAFW,wBAAwB,QAQlC;IAED;;;;;OAKG;IACH,eAHW,wBAAwB,GACtB,OAAO,CAenB;IAED;;;;;OAKG;IACH,mBAEC;CACJ;uCAlEY,OAAO,+BAA+B,EAAE,wBAAwB"}
+{"version":3,"file":"SceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/SceneVolumetrics.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IACI;;;OAGG;IACH,SAFU,wBAAwB,EAAE,CAEvB;IAEb,gBAAY;IAEZ;;;;;;;;;;OAUG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,YAFW,wBAAwB,QAQlC;IAED;;;;;OAKG;IACH,eAHW,wBAAwB,GACtB,OAAO,CAenB;IAED;;;;;OAKG;IACH,mBAEC;IAED;;;;;;;;OAQG;IACH,yBAEC;CACJ;uCA/FY,OAAO,+BAA+B,EAAE,wBAAwB"}

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

@@ -1,68 +1,97 @@
-/**
- * @typedef {import("./ParticipatingMediaVolume.js").ParticipatingMediaVolume} ParticipatingMediaVolume
- */
-
-/**
- * Every participating medium in a scene, and a counter saying whether the GPU's copy is stale.
- *
- * **The version is the whole synchronisation protocol.** {@link GPUSceneVolumetrics} repacks the
- * entire table whenever the number moves and does nothing at all when it does not, so a volume
- * changed without moving the counter renders with the values it was last uploaded with — the CPU
- * object holds the new density, reads back correctly, and only the picture is stale. Anything that
- * writes into a volume in place therefore has to say so; see {@link invalidate}.
- *
- * **Volumes are packed by array index**, so removing one renumbers the rest. That is free here
- * because the upload is all-or-nothing, and it is the reason no volume carries a slot number.
- */
-export class SceneVolumetrics {
-    /**
-     *
-     * @type {ParticipatingMediaVolume[]}
-     */
-    volumes = [];
-
-    version = 0;
-
-    /**
-     *
-     * @param {ParticipatingMediaVolume} volume
-     */
-    add(volume) {
-
-        this.volumes.push(volume);
-
-        this.version++;
-
-    }
-
-    /**
-     * Take a volume back out.
-     *
-     * @param {ParticipatingMediaVolume} volume
-     * @returns {boolean} true if it was there to be removed
-     */
-    remove(volume) {
-
-        const index = this.volumes.indexOf(volume);
-
-        if (index === -1) {
-            return false;
-        }
-
-        this.volumes.splice(index, 1);
-
-        this.version++;
-
-        return true;
-    }
-
-    /**
-     * Say that a volume already in the scene has been written into.
-     *
-     * Adding and removing move the version by themselves; changing a volume in place is invisible
-     * from here, and this is how such a change reaches the GPU.
-     */
-    invalidate() {
-        this.version++;
-    }
-}
+/**
+ * @typedef {import("./ParticipatingMediaVolume.js").ParticipatingMediaVolume} ParticipatingMediaVolume
+ */
+
+/**
+ * Every participating medium in a scene, and a counter saying whether the GPU's copy is stale.
+ *
+ * **Two versions are the whole synchronisation protocol.** {@link GPUSceneVolumetrics} repacks the
+ * entire table whenever {@link version} moves; while only {@link noise_version} moves it writes the
+ * noise phases of the rows whose phases changed; when neither moves it does nothing at all. A volume
+ * changed without moving a counter renders with the values it was last uploaded with — the CPU
+ * object holds the new density, reads back correctly, and only the picture is stale. Anything that
+ * writes into a volume in place therefore has to say so; see {@link invalidate} and
+ * {@link invalidate_noise}.
+ *
+ * **Volumes are packed by array index**, so removing one renumbers the rest. That is free here
+ * because adding or removing repacks the whole table, and it is the reason no volume carries a slot
+ * number.
+ */
+export class SceneVolumetrics {
+    /**
+     *
+     * @type {ParticipatingMediaVolume[]}
+     */
+    volumes = [];
+
+    version = 0;
+
+    /**
+     * A second counter, for the one change that happens every frame: a volume's noise phases
+     * (`noise_offset`, `noise_warp_offset`) moved and nothing else about any volume did. While only
+     * this one moves, {@link GPUSceneVolumetrics} writes each row's phase words where they differ
+     * from what it last wrote, and nothing else of the table; see {@link invalidate_noise}.
+     *
+     * A move of {@link version} covers the phases too: the whole table is repacked from the volumes
+     * as they stand.
+     *
+     * @type {number}
+     */
+    noise_version = 0;
+
+    /**
+     *
+     * @param {ParticipatingMediaVolume} volume
+     */
+    add(volume) {
+
+        this.volumes.push(volume);
+
+        this.version++;
+
+    }
+
+    /**
+     * Take a volume back out.
+     *
+     * @param {ParticipatingMediaVolume} volume
+     * @returns {boolean} true if it was there to be removed
+     */
+    remove(volume) {
+
+        const index = this.volumes.indexOf(volume);
+
+        if (index === -1) {
+            return false;
+        }
+
+        this.volumes.splice(index, 1);
+
+        this.version++;
+
+        return true;
+    }
+
+    /**
+     * Say that a volume already in the scene has been written into.
+     *
+     * Adding and removing move the version by themselves; changing a volume in place is invisible
+     * from here, and this is how such a change reaches the GPU.
+     */
+    invalidate() {
+        this.version++;
+    }
+
+    /**
+     * Say that volumes already in the scene had their noise phases advanced in place, and nothing
+     * else about them changed.
+     *
+     * The cheap path: a scrolling field moves its phases every frame, and they are six words of a
+     * row, so a frame that only scrolls writes those words per row instead of repacking the table
+     * (re-inverting every transform). Anything else written into a volume still owes an
+     * {@link invalidate}.
+     */
+    invalidate_noise() {
+        this.noise_version++;
+    }
+}

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

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

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

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

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

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