@woosh/meep-engine 3.64.1 → 3.67.0

package/src/shade/renderer/wind/GPUSceneWind.d.ts

@@ -12,7 +12,8 @@
  *   cascade's resolution of content with a one-texel skirt. A producer writes a cascade's tile at
  *   {@link slot}, from the device; nothing here writes texels;
  * - {@link uniform}: the table a reader takes, {@link WIND_FIELD_STRUCT}: every cascade's window and
- *   read record, finest first, and `v_far(t)`.
+ *   read record, finest first, and `v_far(t)`;
+ * - {@link previous_uniform}: the table as the frame before read it, over the same atlas.
  *
  * **The producer's frame**, before any consumer encodes (at `FrameStart`, ahead of the scene's own
  * update):
@@ -25,12 +26,22 @@
  * and the scene's update ({@link update}) uploads the table once, if anything changed. Nothing here
  * allocates once the count is fixed: the setters write a retained copy of the table in place.
  *
+ * **One frame of history.** The field as the frame before read it stays readable beside this frame's:
+ * its table is {@link previous_uniform}, and its tiles are still in the atlas, because a cascade has
+ * two tiles and a producer writes this frame's into the one last frame's readers did not take
+ * ({@link publish_slot}). The scene context turns the frame over ({@link advance_frame}), once, before
+ * any producer writes. A reader that wants what the wind was a frame ago, a motion vector's, samples
+ * through the previous table (`chunk_wind_field_sample_previous`). In a frame where nothing was
+ * published and no setter ran, the two tables are equal, bit for bit. The history starts over, as a
+ * copy of this frame's field, whenever the cascades' count or resolution changes, which is also every
+ * time the atlas changes size: the previous table is always over the atlas as it is.
+ *
  * **A cascade reads as the far field until it has a record.** One that {@link set_cascades} adds
  * starts with a decay of 0, so whatever its tile holds — a freed slot's old texels, or nothing yet —
  * contributes nothing until the producer gives it a decay; a cascade created at the far field (as the
  * fluid creates them) is that exactly.
  *
- * **The atlas grows with the count and never shrinks**: more cascades allocate slots, which add
+ * **The atlas grows with the count and never shrinks**: more cascades allocate slots, two each, which add
  * layers to the texture (or widen it, past `maxTextureDimension3D`); fewer free them and keep the
  * texture. A new resolution is a new atlas. Either replaces the texture, so a consumer takes it per
  * frame ({@link bind}), as the frame graph does.
@@ -48,7 +59,8 @@ export class GPUSceneWind {
      */
     constructor(device: GPUDevice);
     /**
-     * One tile per cascade, at {@link slot}. Replaced by a new resolution, and its texture by a grow.
+     * Two tiles per cascade: this frame's at {@link slot}, and the one a producer writes next. Replaced
+     * by a new resolution, and its texture by a grow.
      * @returns {GPUTileAtlas3D}
      */
     get atlas(): GPUTileAtlas3D;
@@ -57,17 +69,44 @@ export class GPUSceneWind {
      * @returns {GPUBuffer}
      */
     get uniform(): GPUBuffer;
+    /**
+     * The table as the frame before read it, {@link WIND_FIELD_STRUCT}, as the uniform
+     * `wind_field_previous`: it names tiles of {@link atlas}.
+     * @returns {GPUBuffer}
+     */
+    get previous_uniform(): GPUBuffer;
+    /**
+     * How many cascades the frame before read.
+     * @returns {number}
+     */
+    get previous_cascade_count(): number;
     /**
      * @returns {number}
      */
     get cascade_count(): number;
     /**
-     * The atlas slot of a cascade's tile.
+     * The atlas slot of a cascade's tile: the one this frame's readers take.
      *
      * @param {number} index a cascade, finest first
      * @returns {number}
      */
     slot(index: number): number;
+    /**
+     * The atlas slot a producer writes a cascade's tile into this frame, which becomes the cascade's
+     * {@link slot}: the tile the frame before did not read, so that one stays as it was read. Asked
+     * again before the frame turns over ({@link advance_frame}), it is the same slot. A producer calls
+     * it for each cascade it publishes, before the table is uploaded; a cascade it does not publish
+     * keeps its tile, which both frames then read.
+     *
+     * @param {number} index a cascade, finest first
+     * @returns {number}
+     */
+    publish_slot(index: number): number;
+    /**
+     * Turn the frame over: the field as it stands, which is what the frame now ending read, becomes
+     * the previous one. Once a frame, before any producer writes.
+     */
+    advance_frame(): void;
     /**
      * The stack's shape: how many cascades, and the cells of each one's window, which is its tile's
      * content. Cascades past `count` are dropped and their slots freed; cascades it adds start with
@@ -105,7 +144,7 @@ export class GPUSceneWind {
      */
     set_far_velocity(velocity: ArrayLike<number>): void;
     /**
-     * Upload the table when anything changed since the last upload; once a frame, after the producer
+     * Upload the tables that changed since their last upload; once a frame, after the producer
      * and before any consumer encodes. The tiles' texel origins and the atlas's size are taken here,
      * after every slot the frame allocated.
      */
@@ -117,6 +156,14 @@ export class GPUSceneWind {
      * @param {Object} bindings
      */
     bind(bindings: any): void;
+    /**
+     * Put the field and its history into a dispatch's bindings, under the names
+     * `wind_field_add_history_resources` declares: what {@link bind} puts, and
+     * `wind_field_previous`.
+     *
+     * @param {Object} bindings
+     */
+    bind_history(bindings: any): void;
     /**
      * Release the atlas and the table. Safe to call twice.
      */

package/src/shade/renderer/wind/GPUSceneWind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneWind.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/GPUSceneWind.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IAqDI;;;;;OAKG;IACH,wDAJW,UAAU,MAAM,CAAC,YACjB,MAAM,GACJ,cAAc,CAoB1B;IAxCD;;OAEG;IACH,+BAWC;IA4BD;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;;;;;OASG;IACH,oBAHW,MAAM,cACN,UAAU,MAAM,CAAC,QA4D3B;IAED;;;;;;;;OAQG;IACH,0BAJW,MAAM,UACN,UAAU,MAAM,CAAC,aACjB,MAAM,QAmBhB;IAED;;;;;;;OAOG;IACH,yBAHW,MAAM,SACN,MAAM,QAYhB;IAED;;;;OAIG;IACH,2BAFW,UAAU,MAAM,CAAC,QAY3B;IAED;;;;OAIG;IACH,eAiCC;IAiCD;;;;;OAKG;IACH,0BAGC;IAED;;OAEG;IACH,gBASC;;CACJ;+BAvZ8B,oCAAoC"}
+{"version":3,"file":"GPUSceneWind.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/GPUSceneWind.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IA2FI;;;;;OAKG;IACH,wDAJW,UAAU,MAAM,CAAC,YACjB,MAAM,GACJ,cAAc,CAoB1B;IA9CD;;OAEG;IACH,+BAiBC;IA4BD;;;;OAIG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;OAIG;IACH,kCAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;;;;;OASG;IACH,oBAHW,MAAM,GACJ,MAAM,CAkBlB;IAED;;;OAGG;IACH,sBAgBC;IAED;;;;;;;;;OASG;IACH,oBAHW,MAAM,cACN,UAAU,MAAM,CAAC,QAmE3B;IAED;;;;;;;;OAQG;IACH,0BAJW,MAAM,UACN,UAAU,MAAM,CAAC,aACjB,MAAM,QAmBhB;IAED;;;;;;;OAOG;IACH,yBAHW,MAAM,SACN,MAAM,QAYhB;IAED;;;;OAIG;IACH,2BAFW,UAAU,MAAM,CAAC,QAY3B;IAED;;;;OAIG;IACH,eAmBC;IAiED;;;;;OAKG;IACH,0BAGC;IAED;;;;;;OAMG;IACH,kCAIC;IAED;;OAEG;IACH,gBAUC;;CACJ;+BAnjB8B,oCAAoC"}

package/src/shade/renderer/wind/GPUSceneWind.js

@@ -39,7 +39,8 @@ const PLACEHOLDER_CONTENT = [1, 1, 1];
  *   cascade's resolution of content with a one-texel skirt. A producer writes a cascade's tile at
  *   {@link slot}, from the device; nothing here writes texels;
  * - {@link uniform}: the table a reader takes, {@link WIND_FIELD_STRUCT}: every cascade's window and
- *   read record, finest first, and `v_far(t)`.
+ *   read record, finest first, and `v_far(t)`;
+ * - {@link previous_uniform}: the table as the frame before read it, over the same atlas.
  *
  * **The producer's frame**, before any consumer encodes (at `FrameStart`, ahead of the scene's own
  * update):
@@ -52,12 +53,22 @@ const PLACEHOLDER_CONTENT = [1, 1, 1];
  * and the scene's update ({@link update}) uploads the table once, if anything changed. Nothing here
  * allocates once the count is fixed: the setters write a retained copy of the table in place.
  *
+ * **One frame of history.** The field as the frame before read it stays readable beside this frame's:
+ * its table is {@link previous_uniform}, and its tiles are still in the atlas, because a cascade has
+ * two tiles and a producer writes this frame's into the one last frame's readers did not take
+ * ({@link publish_slot}). The scene context turns the frame over ({@link advance_frame}), once, before
+ * any producer writes. A reader that wants what the wind was a frame ago, a motion vector's, samples
+ * through the previous table (`chunk_wind_field_sample_previous`). In a frame where nothing was
+ * published and no setter ran, the two tables are equal, bit for bit. The history starts over, as a
+ * copy of this frame's field, whenever the cascades' count or resolution changes, which is also every
+ * time the atlas changes size: the previous table is always over the atlas as it is.
+ *
  * **A cascade reads as the far field until it has a record.** One that {@link set_cascades} adds
  * starts with a decay of 0, so whatever its tile holds — a freed slot's old texels, or nothing yet —
  * contributes nothing until the producer gives it a decay; a cascade created at the far field (as the
  * fluid creates them) is that exactly.
  *
- * **The atlas grows with the count and never shrinks**: more cascades allocate slots, which add
+ * **The atlas grows with the count and never shrinks**: more cascades allocate slots, two each, which add
  * layers to the texture (or widen it, past `maxTextureDimension3D`); fewer free them and keep the
  * texture. A new resolution is a new atlas. Either replaces the texture, so a consumer takes it per
  * frame ({@link bind}), as the frame graph does.
@@ -72,6 +83,9 @@ export class GPUSceneWind {
     /** @type {GPUBuffer} */
     #uniform;
 
+    /** @type {GPUBuffer} */
+    #previous_uniform;
+
     /**
      * The table as the shader reads it, written in place by the setters.
      * @type {ArrayBuffer}
@@ -81,6 +95,13 @@ export class GPUSceneWind {
     #i32 = new Int32Array(this.#bytes);
     #u32 = new Uint32Array(this.#bytes);
 
+    /**
+     * The table as the frame before read it.
+     * @type {ArrayBuffer}
+     */
+    #previous_bytes = new ArrayBuffer(WIND_FIELD_STRUCT.size);
+    #previous_u32 = new Uint32Array(this.#previous_bytes);
+
     #count = 0;
 
     /**
@@ -89,6 +110,18 @@ export class GPUSceneWind {
      */
     #slots = new Uint32Array(WIND_FIELD_CASCADE_LIMIT);
 
+    /**
+     * The atlas slot of each cascade's other tile: the one a producer writes next.
+     * @type {Uint32Array}
+     */
+    #spare_slots = new Uint32Array(WIND_FIELD_CASCADE_LIMIT);
+
+    /**
+     * Whether each cascade's tile has changed places since the frame turned over.
+     * @type {Uint8Array}
+     */
+    #published = new Uint8Array(WIND_FIELD_CASCADE_LIMIT);
+
     /** @type {number[]} */
     #origin = [0, 0, 0];
 
@@ -97,6 +130,16 @@ export class GPUSceneWind {
      */
     #dirty = true;
 
+    /**
+     * Whether the previous table changed since it was last uploaded.
+     */
+    #previous_dirty = true;
+
+    /**
+     * Whether the history is to start over at the next upload, as a copy of the field then.
+     */
+    #history_lost = false;
+
     #destroyed = false;
 
     /**
@@ -113,6 +156,12 @@ export class GPUSceneWind {
             size: WIND_FIELD_STRUCT.size,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
+
+        this.#previous_uniform = device.createBuffer({
+            label: 'GPUSceneWind/previous table',
+            size: WIND_FIELD_STRUCT.size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
     }
 
     /**
@@ -142,7 +191,8 @@ export class GPUSceneWind {
     }
 
     /**
-     * One tile per cascade, at {@link slot}. Replaced by a new resolution, and its texture by a grow.
+     * Two tiles per cascade: this frame's at {@link slot}, and the one a producer writes next. Replaced
+     * by a new resolution, and its texture by a grow.
      * @returns {GPUTileAtlas3D}
      */
     get atlas() {
@@ -157,6 +207,23 @@ export class GPUSceneWind {
         return this.#uniform;
     }
 
+    /**
+     * The table as the frame before read it, {@link WIND_FIELD_STRUCT}, as the uniform
+     * `wind_field_previous`: it names tiles of {@link atlas}.
+     * @returns {GPUBuffer}
+     */
+    get previous_uniform() {
+        return this.#previous_uniform;
+    }
+
+    /**
+     * How many cascades the frame before read.
+     * @returns {number}
+     */
+    get previous_cascade_count() {
+        return this.#previous_u32[CASCADE_COUNT];
+    }
+
     /**
      * @returns {number}
      */
@@ -165,7 +232,7 @@ export class GPUSceneWind {
     }
 
     /**
-     * The atlas slot of a cascade's tile.
+     * The atlas slot of a cascade's tile: the one this frame's readers take.
      *
      * @param {number} index a cascade, finest first
      * @returns {number}
@@ -177,6 +244,56 @@ export class GPUSceneWind {
         return this.#slots[index];
     }
 
+    /**
+     * The atlas slot a producer writes a cascade's tile into this frame, which becomes the cascade's
+     * {@link slot}: the tile the frame before did not read, so that one stays as it was read. Asked
+     * again before the frame turns over ({@link advance_frame}), it is the same slot. A producer calls
+     * it for each cascade it publishes, before the table is uploaded; a cascade it does not publish
+     * keeps its tile, which both frames then read.
+     *
+     * @param {number} index a cascade, finest first
+     * @returns {number}
+     */
+    publish_slot(index) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.isNonNegativeInteger(index, 'index');
+        assert.lessThan(index, this.#count, 'index');
+
+        if (this.#published[index] === 0) {
+            const slot = this.#spare_slots[index];
+
+            this.#spare_slots[index] = this.#slots[index];
+            this.#slots[index] = slot;
+
+            this.#published[index] = 1;
+            this.#dirty = true;
+        }
+
+        return this.#slots[index];
+    }
+
+    /**
+     * Turn the frame over: the field as it stands, which is what the frame now ending read, becomes
+     * the previous one. Once a frame, before any producer writes.
+     */
+    advance_frame() {
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        this.#published.fill(0);
+
+        const from = this.#u32;
+        const to = this.#previous_u32;
+
+        for (let i = 0; i < from.length; i++) {
+            if (to[i] !== from[i]) {
+                to.set(from);
+                this.#previous_dirty = true;
+
+                break;
+            }
+        }
+    }
+
     /**
      * The stack's shape: how many cascades, and the cells of each one's window, which is its tile's
      * content. Cascades past `count` are dropped and their slots freed; cascades it adds start with
@@ -204,16 +321,22 @@ export class GPUSceneWind {
         if (count > 0 && (content[0] !== resolution[0] || content[1] !== resolution[1] || content[2] !== resolution[2])) {
             // a new tile shape: nothing of the old atlas carries over
             this.#atlas.destroy();
-            this.#atlas = GPUSceneWind.#make_atlas(this.#device, resolution, count);
+            this.#atlas = GPUSceneWind.#make_atlas(this.#device, resolution, 2 * count);
             this.#count = 0;
         }
 
+        if (count !== this.#count) {
+            // the previous table would name tiles that are gone, or not yet written
+            this.#history_lost = true;
+        }
+
         const atlas = this.#atlas;
 
         while (this.#count < count) {
             const c = this.#count;
 
             this.#slots[c] = atlas.allocate();
+            this.#spare_slots[c] = atlas.allocate();
 
             const level = LEVELS + c * LEVEL_STRIDE;
 
@@ -231,6 +354,7 @@ export class GPUSceneWind {
             this.#count--;
 
             atlas.free(this.#slots[this.#count]);
+            atlas.free(this.#spare_slots[this.#count]);
         }
 
         const size = atlas.content_size;
@@ -313,17 +437,35 @@ export class GPUSceneWind {
     }
 
     /**
-     * Upload the table when anything changed since the last upload; once a frame, after the producer
+     * Upload the tables that changed since their last upload; once a frame, after the producer
      * and before any consumer encodes. The tiles' texel origins and the atlas's size are taken here,
      * after every slot the frame allocated.
      */
     update() {
         assert.notOk(this.#destroyed, 'destroyed');
 
-        if (!this.#dirty) {
-            return;
+        if (this.#dirty) {
+            this.#upload();
+        }
+
+        if (this.#history_lost) {
+            this.#previous_u32.set(this.#u32);
+
+            this.#history_lost = false;
+            this.#previous_dirty = true;
+        }
+
+        if (this.#previous_dirty) {
+            this.#device.queue.writeBuffer(this.#previous_uniform, 0, this.#previous_bytes);
+
+            this.#previous_dirty = false;
         }
+    }
 
+    /**
+     * Finish the table and send it to the device.
+     */
+    #upload() {
         const atlas = this.#atlas;
         const origin = this.#origin;
         const f32 = this.#f32;
@@ -394,6 +536,19 @@ export class GPUSceneWind {
         bindings.wind_field_atlas = this.#atlas.texture;
     }
 
+    /**
+     * Put the field and its history into a dispatch's bindings, under the names
+     * `wind_field_add_history_resources` declares: what {@link bind} puts, and
+     * `wind_field_previous`.
+     *
+     * @param {Object} bindings
+     */
+    bind_history(bindings) {
+        this.bind(bindings);
+
+        bindings.wind_field_previous = this.#previous_uniform;
+    }
+
     /**
      * Release the atlas and the table. Safe to call twice.
      */
@@ -406,5 +561,6 @@ export class GPUSceneWind {
 
         this.#atlas.destroy();
         this.#uniform.destroy();
+        this.#previous_uniform.destroy();
     }
 }

package/src/shade/renderer/wind/WIND_FIELD_UNIFORM.d.ts

@@ -6,7 +6,9 @@
  * uniform alternative is the scroll alone: with no departure from the far field anywhere, the flow
  * map has nothing to carry.
  *
- * A pass sets it from the field it binds, `scene.wind.cascade_count === 0`, the frame it binds it.
+ * A pass sets it from the field it binds, `scene.wind.cascade_count === 0`, the frame it binds it; a
+ * pass that also reads the field's history (`chunk_wind_field_sample_previous`) sets it only when
+ * `scene.wind.previous_cascade_count` is 0 too, since both reads are the one alternative.
  * `false`, the default, is the field read as it is, cascades or none, so a pass that never sets it
  * reads the wind exactly as it always did.
  *

package/src/shade/renderer/wind/WIND_FIELD_UNIFORM.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WIND_FIELD_UNIFORM.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/WIND_FIELD_UNIFORM.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,iCAFU,YAAY,CAEoD;6BAhB7C,oCAAoC"}
+{"version":3,"file":"WIND_FIELD_UNIFORM.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/WIND_FIELD_UNIFORM.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,iCAFU,YAAY,CAEoD;6BAlB7C,oCAAoC"}

package/src/shade/renderer/wind/WIND_FIELD_UNIFORM.js

@@ -8,7 +8,9 @@ import { ShaderSwitch } from "../shader/compiler/ShaderSwitch.js";
  * uniform alternative is the scroll alone: with no departure from the far field anywhere, the flow
  * map has nothing to carry.
  *
- * A pass sets it from the field it binds, `scene.wind.cascade_count === 0`, the frame it binds it.
+ * A pass sets it from the field it binds, `scene.wind.cascade_count === 0`, the frame it binds it; a
+ * pass that also reads the field's history (`chunk_wind_field_sample_previous`) sets it only when
+ * `scene.wind.previous_cascade_count` is 0 too, since both reads are the one alternative.
  * `false`, the default, is the field read as it is, cascades or none, so a pass that never sets it
  * reads the wind exactly as it always did.
  *

package/src/shade/renderer/wind/chunk_wind_field_sample_cascades.d.ts

@@ -4,7 +4,8 @@
  * number of cascades, none included.
  *
  * Reads `wind_field` ({@link WIND_FIELD_STRUCT}), `wind_field_atlas` and `wind_field_sampler`, as
- * {@link wind_field_add_resources} declares them.
+ * {@link wind_field_add_resources} declares them. `wind_field_sample_in(field, position_ws)` is the
+ * same read through any table over that atlas, the previous frame's for one.
  *
  * **The read:**
  * - the cascades' windows are walked finest first, each by `clipmap_level_select`, and the first holding

package/src/shade/renderer/wind/chunk_wind_field_sample_cascades.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_wind_field_sample_cascades.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/chunk_wind_field_sample_cascades.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,+CAFU,SAAS,CA4DjB;0BAnGwB,iCAAiC"}
+{"version":3,"file":"chunk_wind_field_sample_cascades.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/chunk_wind_field_sample_cascades.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,+CAFU,SAAS,CAgEjB;0BAxGwB,iCAAiC"}

package/src/shade/renderer/wind/chunk_wind_field_sample_cascades.js

@@ -9,7 +9,8 @@ import { WIND_FIELD_STRUCT } from "./WIND_FIELD_STRUCT.js";
  * number of cascades, none included.
  *
  * Reads `wind_field` ({@link WIND_FIELD_STRUCT}), `wind_field_atlas` and `wind_field_sampler`, as
- * {@link wind_field_add_resources} declares them.
+ * {@link wind_field_add_resources} declares them. `wind_field_sample_in(field, position_ws)` is the
+ * same read through any table over that atlas, the previous frame's for one.
  *
  * **The read:**
  * - the cascades' windows are walked finest first, each by `clipmap_level_select`, and the first holding
@@ -46,26 +47,26 @@ export const chunk_wind_field_sample_cascades = CodeChunk.from(
 const WIND_FIELD_BAND_WIDTH: f32 = ${WIND_FIELD_BAND_WIDTH}.0;
 
 // cascade c's identity read at a world point its window holds
-fn wind_field_cascade_read(c: u32, position_ws: vec3<f32>) -> vec3<f32> {
-    let level = wind_field.levels[c];
-    let cascade = wind_field.cascades[c];
+fn wind_field_cascade_read(field: ptr<uniform, ${WIND_FIELD_STRUCT.wgsl_ref}>, c: u32, position_ws: vec3<f32>) -> vec3<f32> {
+    let level = (*field).levels[c];
+    let cascade = (*field).cascades[c];
 
     // window-local position in the cascade's cells, which is a texel offset from the tile's content
     let local = position_ws / level.cell_size - vec3<f32>(level.corner);
-    let uvw = (cascade.content_origin + local) * wind_field.inverse_atlas_size;
+    let uvw = (cascade.content_origin + local) * (*field).inverse_atlas_size;
 
     let deviation = textureSampleLevel(wind_field_atlas, wind_field_sampler, uvw, 0.0).xyz;
 
-    return wind_field.far_velocity + deviation * cascade.decay;
+    return (*field).far_velocity + deviation * cascade.decay;
 }
 
-fn wind_field_sample(position_ws: vec3<f32>) -> vec3<f32> {
-    let count = wind_field.cascade_count;
+fn wind_field_sample_in(field: ptr<uniform, ${WIND_FIELD_STRUCT.wgsl_ref}>, position_ws: vec3<f32>) -> vec3<f32> {
+    let count = (*field).cascade_count;
 
     var selection = ClipmapSelection(CLIPMAP_LEVEL_NONE, 0.0);
 
     for (var i = 0u; i < min(count, ${WIND_FIELD_CASCADE_LIMIT}u); i++) {
-        let weight = clipmap_level_select(wind_field.levels[i], position_ws, WIND_FIELD_BAND_WIDTH);
+        let weight = clipmap_level_select((*field).levels[i], position_ws, WIND_FIELD_BAND_WIDTH);
 
         if (weight >= 0.0) {
             selection = ClipmapSelection(i, weight);
@@ -74,10 +75,10 @@ fn wind_field_sample(position_ws: vec3<f32>) -> vec3<f32> {
     }
 
     if (selection.level == CLIPMAP_LEVEL_NONE) {
-        return wind_field.far_velocity;
+        return (*field).far_velocity;
     }
 
-    let inner = wind_field_cascade_read(selection.level, position_ws);
+    let inner = wind_field_cascade_read(field, selection.level, position_ws);
 
     if (selection.edge_weight <= 0.0) {
         return inner;
@@ -85,15 +86,19 @@ fn wind_field_sample(position_ws: vec3<f32>) -> vec3<f32> {
 
     let parent = selection.level + 1u;
 
-    var outer = wind_field.far_velocity;
+    var outer = (*field).far_velocity;
 
     if (parent < count) {
-        outer = wind_field_cascade_read(parent, position_ws);
+        outer = wind_field_cascade_read(field, parent, position_ws);
     }
 
     // mix's form, written so that equal reads blend to themselves exactly
     return inner + (outer - inner) * selection.edge_weight;
 }
+
+fn wind_field_sample(position_ws: vec3<f32>) -> vec3<f32> {
+    return wind_field_sample_in(&wind_field, position_ws);
+}
 `, [
         WIND_FIELD_STRUCT.declaration_chunk,
         chunk_clipmap_select_finest,

package/src/shade/renderer/wind/chunk_wind_field_sample_previous.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The wind at a world point as the frame before read it, m/s: `wind_field_sample_previous(position_ws)`.
+ * It is `chunk_wind_field_sample`'s read through the previous table, so a consumer that samples the
+ * same point with both has what the wind there changed by over the frame: a motion vector's share of it.
+ *
+ * Reads `wind_field_previous` beside the bindings of `chunk_wind_field_sample`, as
+ * `wind_field_add_history_resources` declares them and `GPUSceneWind.bind_history` fills them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_wind_field_sample_previous: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_wind_field_sample_previous.d.ts.map

package/src/shade/renderer/wind/chunk_wind_field_sample_previous.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_wind_field_sample_previous.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/chunk_wind_field_sample_previous.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,+CAFU,SAAS,CAWjB;0BAtBwB,iCAAiC"}

package/src/shade/renderer/wind/chunk_wind_field_sample_previous.js

@@ -0,0 +1,23 @@
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { chunk_wind_field_sample } from "./chunk_wind_field_sample.js";
+
+/**
+ * The wind at a world point as the frame before read it, m/s: `wind_field_sample_previous(position_ws)`.
+ * It is `chunk_wind_field_sample`'s read through the previous table, so a consumer that samples the
+ * same point with both has what the wind there changed by over the frame: a motion vector's share of it.
+ *
+ * Reads `wind_field_previous` beside the bindings of `chunk_wind_field_sample`, as
+ * `wind_field_add_history_resources` declares them and `GPUSceneWind.bind_history` fills them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_wind_field_sample_previous = CodeChunk.from(
+    //language=WGSL
+    `
+fn wind_field_sample_previous(position_ws: vec3<f32>) -> vec3<f32> {
+    return wind_field_sample_in(&wind_field_previous, position_ws);
+}
+`, [
+        chunk_wind_field_sample,
+    ]
+);

package/src/shade/renderer/wind/chunk_wind_field_sample_uniform.d.ts

@@ -4,6 +4,7 @@
  * exactly, having found no window that holds the point.
  *
  * Reads `wind_field.far_velocity` and nothing else; the atlas and its sampler stay bound and unread.
+ * `wind_field_sample_in(field, position_ws)` is the same read of any table with no cascades.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/wind/chunk_wind_field_sample_uniform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_wind_field_sample_uniform.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/chunk_wind_field_sample_uniform.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,8CAFU,SAAS,CAWjB;0BArBwB,iCAAiC"}
+{"version":3,"file":"chunk_wind_field_sample_uniform.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/chunk_wind_field_sample_uniform.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,8CAFU,SAAS,CAejB;0BA1BwB,iCAAiC"}

package/src/shade/renderer/wind/chunk_wind_field_sample_uniform.js

@@ -7,14 +7,19 @@ import { WIND_FIELD_STRUCT } from "./WIND_FIELD_STRUCT.js";
  * exactly, having found no window that holds the point.
  *
  * Reads `wind_field.far_velocity` and nothing else; the atlas and its sampler stay bound and unread.
+ * `wind_field_sample_in(field, position_ws)` is the same read of any table with no cascades.
  *
  * @type {CodeChunk}
  */
 export const chunk_wind_field_sample_uniform = CodeChunk.from(
     //language=WGSL
     `
+fn wind_field_sample_in(field: ptr<uniform, ${WIND_FIELD_STRUCT.wgsl_ref}>, position_ws: vec3<f32>) -> vec3<f32> {
+    return (*field).far_velocity;
+}
+
 fn wind_field_sample(position_ws: vec3<f32>) -> vec3<f32> {
-    return wind_field.far_velocity;
+    return wind_field_sample_in(&wind_field, position_ws);
 }
 `, [
         WIND_FIELD_STRUCT.declaration_chunk,

package/src/shade/renderer/wind/wind_field_add_resources.d.ts

@@ -12,4 +12,15 @@
  * @returns {import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
  */
 export function wind_field_add_resources(group: import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor): import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor;
+/**
+ * {@link wind_field_add_resources}, and the field as the frame before read it, for a consumer that
+ * samples both (`chunk_wind_field_sample_previous`): `wind_field_previous`, a second uniform
+ * {@link WIND_FIELD_STRUCT} over the same atlas. `GPUSceneWind.bind_history` fills them.
+ *
+ * Two uniforms, one texture, one sampler, and no storage buffer.
+ *
+ * @param {import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ * @returns {import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ */
+export function wind_field_add_history_resources(group: import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor): import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor;
 //# sourceMappingURL=wind_field_add_resources.d.ts.map

package/src/shade/renderer/wind/wind_field_add_resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wind_field_add_resources.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/wind_field_add_resources.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,gDAHW,OAAO,qDAAqD,EAAE,6BAA6B,GACzF,OAAO,qDAAqD,EAAE,6BAA6B,CAOvG"}
+{"version":3,"file":"wind_field_add_resources.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/wind_field_add_resources.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,gDAHW,OAAO,qDAAqD,EAAE,6BAA6B,GACzF,OAAO,qDAAqD,EAAE,6BAA6B,CAOvG;AAED;;;;;;;;;GASG;AACH,wDAHW,OAAO,qDAAqD,EAAE,6BAA6B,GACzF,OAAO,qDAAqD,EAAE,6BAA6B,CAKvG"}