@woosh/meep-engine 3.69.0 → 3.70.0

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

@@ -13,7 +13,11 @@
  *   {@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)`;
- * - {@link previous_uniform}: the table as the frame before read it, over the same atlas.
+ * - {@link previous_uniform}: the table as the frame before read it, over the same atlas;
+ * - {@link turbulence}: the far field's turbulence tile, `rgba16float`, which every reader of the field
+ *   samples where the far field has turbulence. One texel of zeros until the far field first has any,
+ *   then the engine's tile and its band-limited levels as mips (`fluid_turbulence_tile_levels`), uploaded
+ *   once and kept.
  *
  * **The producer's frame**, before any consumer encodes (at `FrameStart`, ahead of the scene's own
  * update):
@@ -21,7 +25,8 @@
  *     set_cascades(count, resolution)                    the stack's shape; allocates tiles
  *     set_cascade_window(c, corner, cell_size)           where each cascade's window is
  *     set_cascade_decay(c, decay)                        k_c, each cascade's read record
- *     set_far_velocity(velocity)                         v_far(t)
+ *     set_far_velocity(velocity)                         u(t), the far field's mean
+ *     set_turbulence(sigma, offset, length)              its turbulence
  *
  * 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.
@@ -84,6 +89,18 @@ export class GPUSceneWind {
      * @returns {number}
      */
     get cascade_count(): number;
+    /**
+     * Whether the field is the far field's mean at every point, this frame and the frame before: no
+     * cascades and no turbulence in either. What `WIND_FIELD_UNIFORM` is set from.
+     * @returns {boolean}
+     */
+    get is_uniform(): boolean;
+    /**
+     * A view of the far field's turbulence tile, as the readers bind it, `fluid_turbulence`: replaced
+     * once, the first time the far field has turbulence, so a consumer takes it per frame ({@link bind}).
+     * @returns {GPUTextureView}
+     */
+    get turbulence(): GPUTextureView;
     /**
      * The atlas slot of a cascade's tile: the one this frame's readers take.
      *
@@ -138,11 +155,26 @@ export class GPUSceneWind {
      */
     set_cascade_decay(index: number, decay: number): void;
     /**
-     * `v_far(t)`: the wind wherever no cascade holds, now.
+     * `u(t)`: the far field's mean now, which is the wind wherever no cascade holds when the far field has
+     * no turbulence.
      *
      * @param {ArrayLike<number>} velocity m/s, x, y, z
      */
     set_far_velocity(velocity: ArrayLike<number>): void;
+    /**
+     * The far field's turbulence now: `σ`, its rms on each axis, m/s, 0 for none; `offset`, how far the
+     * mean has carried it, m; `length`, its length scale `L`, m. The far field at a world point `p` is then
+     * `u + σ·T((p − offset) ⊙ S⁻¹)`, `S` the tile's size for `L`. The first `σ` that is not 0 uploads the
+     * engine's tile, once.
+     *
+     * The offset is folded into one tile here, in f64, so the table holds a coordinate in `[0, 1)` however
+     * far the air has carried the turbulence.
+     *
+     * @param {number} sigma
+     * @param {ArrayLike<number>} offset
+     * @param {number} length > 0 when `sigma` is not 0
+     */
+    set_turbulence(sigma: number, offset: ArrayLike<number>, length: number): void;
     /**
      * 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,
@@ -151,7 +183,7 @@ export class GPUSceneWind {
     update(): void;
     /**
      * Put the field into a dispatch's bindings, under the names `wind_field_add_resources` declares:
-     * `wind_field` and `wind_field_atlas`; `wind_field_sampler` is the declaration's default.
+     * `wind_field`, `wind_field_atlas` and `fluid_turbulence`; the samplers are the declaration's defaults.
      *
      * @param {Object} bindings
      */

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"GPUSceneWind.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/GPUSceneWind.js"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IAsHI;;;;;OAKG;IACH,wDAJW,UAAU,MAAM,CAAC,YACjB,MAAM,GACJ,cAAc,CAoB1B;IAzDD;;OAEG;IACH,+BA4BC;IA4BD;;;;OAIG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;OAIG;IACH,kCAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;OAIG;IACH,0BAKC;IAED;;;;OAIG;IACH,iCAEC;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;;;;;OAKG;IACH,2BAFW,UAAU,MAAM,CAAC,QAY3B;IAED;;;;;;;;;;;;OAYG;IACH,sBAJW,MAAM,UACN,UAAU,MAAM,CAAC,UACjB,MAAM,QA+BhB;IAwCD;;;;OAIG;IACH,eAmBC;IAiED;;;;;OAKG;IACH,0BAIC;IAED;;;;;;OAMG;IACH,kCAIC;IAED;;OAEG;IACH,gBAWC;;CACJ;+BAjsB8B,oCAAoC"}

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

@@ -1,4 +1,8 @@
 import { assert } from "../../../core/assert.js";
+import { FLUID_TURBULENCE_TEXELS_PER_LENGTH, FLUID_TURBULENCE_TILE_RESOLUTION } from "../../../engine/physics/fluid/turbulence/FLUID_TURBULENCE_TILE.js";
+import { fluid_turbulence_tile_level_size } from "../../../engine/physics/fluid/turbulence/fluid_turbulence_tile_generate.js";
+import { fluid_turbulence_inverse_tile_size } from "../../../engine/physics/fluid/turbulence/fluid_turbulence_inverse_tile_size.js";
+import { fluid_turbulence_tile_data_rgba16 } from "../../../engine/physics/fluid/turbulence/fluid_turbulence_tile_data.js";
 import { CLIPMAP_LEVEL_STRUCT } from "../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
 import { GPUTileAtlas3D } from "../texture/atlas/GPUTileAtlas3D.js";
 import { WIND_FIELD_CASCADE_LIMIT, WIND_FIELD_TILE_BORDER, WIND_FIELD_TILE_FORMAT } from "./WIND_FIELD.js";
@@ -17,6 +21,10 @@ const CASCADE_DECAY = WIND_CASCADE_STRUCT.get('decay').offset >>> 2;
 const FAR_VELOCITY = WIND_FIELD_STRUCT.get('far_velocity').offset >>> 2;
 const CASCADE_COUNT = WIND_FIELD_STRUCT.get('cascade_count').offset >>> 2;
 const INVERSE_ATLAS_SIZE = WIND_FIELD_STRUCT.get('inverse_atlas_size').offset >>> 2;
+const TURBULENCE_SIGMA = WIND_FIELD_STRUCT.get('turbulence_sigma').offset >>> 2;
+const TURBULENCE_SCALE = WIND_FIELD_STRUCT.get('turbulence_scale').offset >>> 2;
+const TURBULENCE_ORIGIN = WIND_FIELD_STRUCT.get('turbulence_origin').offset >>> 2;
+const TURBULENCE_INVERSE_TEXEL = WIND_FIELD_STRUCT.get('turbulence_inverse_texel').offset >>> 2;
 
 /**
  * Content of the atlas before any cascade has a resolution: one texel and its skirt, so there is a
@@ -40,7 +48,11 @@ const PLACEHOLDER_CONTENT = [1, 1, 1];
  *   {@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)`;
- * - {@link previous_uniform}: the table as the frame before read it, over the same atlas.
+ * - {@link previous_uniform}: the table as the frame before read it, over the same atlas;
+ * - {@link turbulence}: the far field's turbulence tile, `rgba16float`, which every reader of the field
+ *   samples where the far field has turbulence. One texel of zeros until the far field first has any,
+ *   then the engine's tile and its band-limited levels as mips (`fluid_turbulence_tile_levels`), uploaded
+ *   once and kept.
  *
  * **The producer's frame**, before any consumer encodes (at `FrameStart`, ahead of the scene's own
  * update):
@@ -48,7 +60,8 @@ const PLACEHOLDER_CONTENT = [1, 1, 1];
  *     set_cascades(count, resolution)                    the stack's shape; allocates tiles
  *     set_cascade_window(c, corner, cell_size)           where each cascade's window is
  *     set_cascade_decay(c, decay)                        k_c, each cascade's read record
- *     set_far_velocity(velocity)                         v_far(t)
+ *     set_far_velocity(velocity)                         u(t), the far field's mean
+ *     set_turbulence(sigma, offset, length)              its turbulence
  *
  * 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.
@@ -86,6 +99,21 @@ export class GPUSceneWind {
     /** @type {GPUBuffer} */
     #previous_uniform;
 
+    /**
+     * The turbulence tile: one texel until {@link set_turbulence} first has a σ, the engine's tile after.
+     * @type {GPUTexture}
+     */
+    #turbulence;
+
+    /** {@link #turbulence}'s view, as readers bind it. @type {GPUTextureView} */
+    #turbulence_view;
+
+    /** Whether {@link #turbulence} is the engine's tile yet. */
+    #turbulence_tiled = false;
+
+    /** Scratch for the tile's inverse size. */
+    #inverse_tile_size = new Float64Array(3);
+
     /**
      * The table as the shader reads it, written in place by the setters.
      * @type {ArrayBuffer}
@@ -101,6 +129,7 @@ export class GPUSceneWind {
      */
     #previous_bytes = new ArrayBuffer(WIND_FIELD_STRUCT.size);
     #previous_u32 = new Uint32Array(this.#previous_bytes);
+    #previous_f32 = new Float32Array(this.#previous_bytes);
 
     #count = 0;
 
@@ -162,6 +191,17 @@ export class GPUSceneWind {
             size: WIND_FIELD_STRUCT.size,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
+
+        // a new texture is 0: no turbulence, and never read while σ is 0
+        this.#turbulence = device.createTexture({
+            label: 'GPUSceneWind/turbulence placeholder',
+            size: [1, 1, 1],
+            dimension: '3d',
+            format: 'rgba16float',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+
+        this.#turbulence_view = this.#turbulence.createView();
     }
 
     /**
@@ -231,6 +271,27 @@ export class GPUSceneWind {
         return this.#count;
     }
 
+    /**
+     * Whether the field is the far field's mean at every point, this frame and the frame before: no
+     * cascades and no turbulence in either. What `WIND_FIELD_UNIFORM` is set from.
+     * @returns {boolean}
+     */
+    get is_uniform() {
+        return this.#count === 0
+            && this.#previous_u32[CASCADE_COUNT] === 0
+            && this.#f32[TURBULENCE_SIGMA] === 0
+            && this.#previous_f32[TURBULENCE_SIGMA] === 0;
+    }
+
+    /**
+     * A view of the far field's turbulence tile, as the readers bind it, `fluid_turbulence`: replaced
+     * once, the first time the far field has turbulence, so a consumer takes it per frame ({@link bind}).
+     * @returns {GPUTextureView}
+     */
+    get turbulence() {
+        return this.#turbulence_view;
+    }
+
     /**
      * The atlas slot of a cascade's tile: the one this frame's readers take.
      *
@@ -420,7 +481,8 @@ export class GPUSceneWind {
     }
 
     /**
-     * `v_far(t)`: the wind wherever no cascade holds, now.
+     * `u(t)`: the far field's mean now, which is the wind wherever no cascade holds when the far field has
+     * no turbulence.
      *
      * @param {ArrayLike<number>} velocity m/s, x, y, z
      */
@@ -436,6 +498,88 @@ export class GPUSceneWind {
         this.#dirty = true;
     }
 
+    /**
+     * The far field's turbulence now: `σ`, its rms on each axis, m/s, 0 for none; `offset`, how far the
+     * mean has carried it, m; `length`, its length scale `L`, m. The far field at a world point `p` is then
+     * `u + σ·T((p − offset) ⊙ S⁻¹)`, `S` the tile's size for `L`. The first `σ` that is not 0 uploads the
+     * engine's tile, once.
+     *
+     * The offset is folded into one tile here, in f64, so the table holds a coordinate in `[0, 1)` however
+     * far the air has carried the turbulence.
+     *
+     * @param {number} sigma
+     * @param {ArrayLike<number>} offset
+     * @param {number} length > 0 when `sigma` is not 0
+     */
+    set_turbulence(sigma, offset, length) {
+        assert.isFinite(sigma, 'sigma');
+        assert.greaterThanOrEqual(sigma, 0, 'sigma');
+
+        const f32 = this.#f32;
+
+        f32[TURBULENCE_SIGMA] = sigma;
+
+        if (sigma !== 0) {
+            assert.isFinite(length, 'length');
+            assert.greaterThan(length, 0, 'length');
+
+            this.#ensure_turbulence_tile();
+
+            const inverse = fluid_turbulence_inverse_tile_size(this.#inverse_tile_size, length);
+
+            f32[TURBULENCE_INVERSE_TEXEL] = FLUID_TURBULENCE_TEXELS_PER_LENGTH / length;
+
+            for (let axis = 0; axis < 3; axis++) {
+                assert.isFinite(offset[axis], 'offset');
+
+                const origin = -offset[axis] * inverse[axis];
+
+                f32[TURBULENCE_SCALE + axis] = inverse[axis];
+                f32[TURBULENCE_ORIGIN + axis] = origin - Math.floor(origin);
+            }
+        }
+
+        this.#dirty = true;
+    }
+
+    /**
+     * Replace the placeholder with the engine's tile, once.
+     */
+    #ensure_turbulence_tile() {
+        if (this.#turbulence_tiled) {
+            return;
+        }
+
+        const levels = fluid_turbulence_tile_data_rgba16();
+
+        const texture = this.#device.createTexture({
+            label: 'GPUSceneWind/turbulence',
+            size: Array.from(FLUID_TURBULENCE_TILE_RESOLUTION),
+            dimension: '3d',
+            format: 'rgba16float',
+            mipLevelCount: levels.length,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+
+        const size = [0, 0, 0];
+
+        for (let level = 0; level < levels.length; level++) {
+            fluid_turbulence_tile_level_size(size, FLUID_TURBULENCE_TILE_RESOLUTION, level);
+
+            this.#device.queue.writeTexture(
+                { texture, mipLevel: level },
+                levels[level],
+                { bytesPerRow: 8 * size[0], rowsPerImage: size[1] },
+                size
+            );
+        }
+
+        this.#turbulence.destroy();
+        this.#turbulence = texture;
+        this.#turbulence_view = texture.createView();
+        this.#turbulence_tiled = true;
+    }
+
     /**
      * 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,
@@ -527,13 +671,14 @@ export class GPUSceneWind {
 
     /**
      * Put the field into a dispatch's bindings, under the names `wind_field_add_resources` declares:
-     * `wind_field` and `wind_field_atlas`; `wind_field_sampler` is the declaration's default.
+     * `wind_field`, `wind_field_atlas` and `fluid_turbulence`; the samplers are the declaration's defaults.
      *
      * @param {Object} bindings
      */
     bind(bindings) {
         bindings.wind_field = this.#uniform;
         bindings.wind_field_atlas = this.#atlas.texture;
+        bindings.fluid_turbulence = this.#turbulence_view;
     }
 
     /**
@@ -562,5 +707,6 @@ export class GPUSceneWind {
         this.#atlas.destroy();
         this.#uniform.destroy();
         this.#previous_uniform.destroy();
+        this.#turbulence.destroy();
     }
 }

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

@@ -18,7 +18,7 @@ export const WIND_LEVEL_ARRAY: WebGPUArray;
 export const WIND_CASCADE_ARRAY: WebGPUArray;
 /**
  * The published wind field as a shader reads it: the uniform `wind_field`
- * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §11). 800 bytes.
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §11). 832 bytes.
  *
  * Cascade `c` (finest first, below `cascade_count`) is two rows at index `c`:
  * - `levels[c]`: its window as a clipmap level (`CLIPMAP_LEVEL_STRUCT`) — the world cell at
@@ -29,10 +29,16 @@ export const WIND_CASCADE_ARRAY: WebGPUArray;
  *
  * Rows at and past `cascade_count` are never read.
  *
- * - `far_velocity`: `v_far(t)`, m/s, the far field now: the wind everywhere no cascade holds, and
- *   what every cascade's deviation decays toward.
+ * - `far_velocity`: `u(t)`, m/s, the far field's mean now.
  * - `inverse_atlas_size`: one over the atlas texture's texels along x, y and z, so a texel coordinate
  *   times it is the normalised one a sample takes.
+ * - `turbulence_sigma`, `turbulence_scale`, `turbulence_origin`: the far field's turbulence now, so
+ *   the far field at a world point `p` is `v_far(t, p) = far_velocity + σ·T(p ⊙ scale + origin)`
+ *   (`chunk_fluid_turbulence`): `σ` in m/s, 0 for none; `scale` one over the tile's size in the
+ *   world; `origin` the tile coordinate of the world's origin, the turbulence's offset folded into one
+ *   tile; `inverse_texel` one over the tile's texel in the world, `8 / L`, from which a read inside a
+ *   cascade takes the tile's level for the cascade's cell (`fluid_turbulence_lod`). `v_far(t, p)` is the wind everywhere no cascade holds, and what every cascade's deviation
+ *   decays toward.
  *
  * @type {WebGPUStruct}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"WIND_FIELD_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/WIND_FIELD_STRUCT.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,kCAFU,YAAY,CAgBJ;AAElB;;;;GAIG;AACH,+BAFU,WAAW,CAE4E;AAEjG;;;GAGG;AACH,iCAFU,WAAW,CAE6E;AAElG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gCAFU,YAAY,CAQN;6BAhEa,gCAAgC;4BADjC,+BAA+B"}
+{"version":3,"file":"WIND_FIELD_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/WIND_FIELD_STRUCT.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,kCAFU,YAAY,CAgBJ;AAElB;;;;GAIG;AACH,+BAFU,WAAW,CAE4E;AAEjG;;;GAGG;AACH,iCAFU,WAAW,CAE6E;AAElG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,gCAFU,YAAY,CAYN;6BA1Ea,gCAAgC;4BADjC,+BAA+B"}

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

@@ -41,7 +41,7 @@ export const WIND_CASCADE_ARRAY = WebGPUArray.from(WIND_CASCADE_STRUCT, WIND_FIE
 
 /**
  * The published wind field as a shader reads it: the uniform `wind_field`
- * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §11). 800 bytes.
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §11). 832 bytes.
  *
  * Cascade `c` (finest first, below `cascade_count`) is two rows at index `c`:
  * - `levels[c]`: its window as a clipmap level (`CLIPMAP_LEVEL_STRUCT`) — the world cell at
@@ -52,10 +52,16 @@ export const WIND_CASCADE_ARRAY = WebGPUArray.from(WIND_CASCADE_STRUCT, WIND_FIE
  *
  * Rows at and past `cascade_count` are never read.
  *
- * - `far_velocity`: `v_far(t)`, m/s, the far field now: the wind everywhere no cascade holds, and
- *   what every cascade's deviation decays toward.
+ * - `far_velocity`: `u(t)`, m/s, the far field's mean now.
  * - `inverse_atlas_size`: one over the atlas texture's texels along x, y and z, so a texel coordinate
  *   times it is the normalised one a sample takes.
+ * - `turbulence_sigma`, `turbulence_scale`, `turbulence_origin`: the far field's turbulence now, so
+ *   the far field at a world point `p` is `v_far(t, p) = far_velocity + σ·T(p ⊙ scale + origin)`
+ *   (`chunk_fluid_turbulence`): `σ` in m/s, 0 for none; `scale` one over the tile's size in the
+ *   world; `origin` the tile coordinate of the world's origin, the turbulence's offset folded into one
+ *   tile; `inverse_texel` one over the tile's texel in the world, `8 / L`, from which a read inside a
+ *   cascade takes the tile's level for the cascade's cell (`fluid_turbulence_lod`). `v_far(t, p)` is the wind everywhere no cascade holds, and what every cascade's deviation
+ *   decays toward.
  *
  * @type {WebGPUStruct}
  */
@@ -65,4 +71,8 @@ export const WIND_FIELD_STRUCT = WebGPUStruct.from({
     far_velocity: vec3f,
     cascade_count: u32,
     inverse_atlas_size: vec3f,
+    turbulence_sigma: f32,
+    turbulence_scale: vec3f,
+    turbulence_inverse_texel: f32,
+    turbulence_origin: vec3f,
 }, "WindField");

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

@@ -1,14 +1,14 @@
 /**
- * Whether the published wind field is uniform: it holds no cascades, so the wind is
- * `wind_field.far_velocity` at every point — `GPUSceneWind.cascade_count` is 0, which is every scene
- * no producer fills (one without a GPU fluid). Decided by `chunk_wind_field_sample`, whose uniform
+ * Whether the published wind field is uniform: it holds no cascades and its far field no turbulence,
+ * so the wind is `wind_field.far_velocity` at every point — `GPUSceneWind.is_uniform`, which is every
+ * scene no producer fills (one without a GPU fluid). Decided by `chunk_wind_field_sample`, whose uniform
  * alternative is the far field and nothing else, and by `chunk_participating_media_noise`, whose
  * 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 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.
+ * A pass sets it from the field it binds, `scene.wind.is_uniform`, the frame it binds it; that holds
+ * only when the field as the frame before read it was uniform too, so a pass that also reads the
+ * history (`chunk_wind_field_sample_previous`) takes the same rule.
  * `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.js

@@ -1,16 +1,16 @@
 import { ShaderSwitch } from "../shader/compiler/ShaderSwitch.js";
 
 /**
- * Whether the published wind field is uniform: it holds no cascades, so the wind is
- * `wind_field.far_velocity` at every point — `GPUSceneWind.cascade_count` is 0, which is every scene
- * no producer fills (one without a GPU fluid). Decided by `chunk_wind_field_sample`, whose uniform
+ * Whether the published wind field is uniform: it holds no cascades and its far field no turbulence,
+ * so the wind is `wind_field.far_velocity` at every point — `GPUSceneWind.is_uniform`, which is every
+ * scene no producer fills (one without a GPU fluid). Decided by `chunk_wind_field_sample`, whose uniform
  * alternative is the far field and nothing else, and by `chunk_participating_media_noise`, whose
  * 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 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.
+ * A pass sets it from the field it binds, `scene.wind.is_uniform`, the frame it binds it; that holds
+ * only when the field as the frame before read it was uniform too, so a pass that also reads the
+ * history (`chunk_wind_field_sample_previous`) takes the same rule.
  * `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_fluid_turbulence.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Declare the turbulence tile's bindings in a resource group, under the names
+ * {@link chunk_fluid_turbulence} reads:
+ * - `fluid_turbulence`: the tile, `texture_3d<f32>`, filterable, `rgba16float`, the engine's tile
+ *   (`fluid_turbulence_tile_data`) as `GPUSceneWind#turbulence` holds it;
+ * - `fluid_turbulence_sampler`: {@link FLUID_TURBULENCE_SAMPLER_DESCRIPTOR}, the declaration's default,
+ *   so a host binds only the texture.
+ *
+ * @param {import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ * @returns {import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ */
+export function fluid_turbulence_add_resources(group: import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor): import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor;
+/**
+ * The sampler the far field's turbulence tile is read with: trilinear and repeating on every axis,
+ * the tile being one period of an infinite field, and linear between its levels.
+ *
+ * @type {SamplerDescriptor}
+ */
+export const FLUID_TURBULENCE_SAMPLER_DESCRIPTOR: SamplerDescriptor;
+/**
+ * `fluid_turbulence_at(q, lod)`: the far field's unit-rms turbulence at tile coordinate `q` (one tile
+ * is 1 on each axis, repeating), band-limited to level `lod`: one trilinear tap of `fluid_turbulence`
+ * between two of its levels. A caller scales it by `σ` and places `q` from a world point by the far
+ * field's offset and length scale.
+ *
+ * `fluid_turbulence_lod(cell, inverse_texel)`: the level a lattice of cell `cell` reads, the tile's
+ * texel being `1 / inverse_texel`: `log2(cell / texel)`, and 0 for a cell no larger than a texel. Level
+ * `ℓ` holds the wavelengths of two of its texels and longer (`fluid_turbulence_tile_generate_levels`), so
+ * a lattice reads what its cells can hold: nothing aliased into it, and a footprint of about a texel a
+ * cell, which is what a tap's cache wants.
+ *
+ * Bindings as {@link fluid_turbulence_add_resources} declares them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_turbulence: CodeChunk;
+import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_turbulence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_fluid_turbulence.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/wind/chunk_fluid_turbulence.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;GAUG;AACH,sDAHW,OAAO,qDAAqD,EAAE,6BAA6B,GACzF,OAAO,qDAAqD,EAAE,6BAA6B,CAMvG;AA9BD;;;;;GAKG;AACH,kDAFU,iBAAiB,CASvB;AAmBJ;;;;;;;;;;;;;;;GAeG;AACH,qCAFU,SAAS,CAajB;kCA9DgC,+CAA+C;0BACvD,iCAAiC"}

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

@@ -0,0 +1,63 @@
+import { SamplerDescriptor } from "../../descriptor/texture/SamplerDescriptor.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * The sampler the far field's turbulence tile is read with: trilinear and repeating on every axis,
+ * the tile being one period of an infinite field, and linear between its levels.
+ *
+ * @type {SamplerDescriptor}
+ */
+export const FLUID_TURBULENCE_SAMPLER_DESCRIPTOR = Object.freeze(SamplerDescriptor.from({
+    magFilter: "linear",
+    minFilter: "linear",
+    mipmapFilter: "linear",
+    addressModeU: "repeat",
+    addressModeV: "repeat",
+    addressModeW: "repeat",
+}));
+
+/**
+ * Declare the turbulence tile's bindings in a resource group, under the names
+ * {@link chunk_fluid_turbulence} reads:
+ * - `fluid_turbulence`: the tile, `texture_3d<f32>`, filterable, `rgba16float`, the engine's tile
+ *   (`fluid_turbulence_tile_data`) as `GPUSceneWind#turbulence` holds it;
+ * - `fluid_turbulence_sampler`: {@link FLUID_TURBULENCE_SAMPLER_DESCRIPTOR}, the declaration's default,
+ *   so a host binds only the texture.
+ *
+ * @param {import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ * @returns {import("../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} group
+ */
+export function fluid_turbulence_add_resources(group) {
+    return group
+        .addTexture("fluid_turbulence", "float", "3d")
+        .addSampler("fluid_turbulence_sampler", "filtering", FLUID_TURBULENCE_SAMPLER_DESCRIPTOR);
+}
+
+/**
+ * `fluid_turbulence_at(q, lod)`: the far field's unit-rms turbulence at tile coordinate `q` (one tile
+ * is 1 on each axis, repeating), band-limited to level `lod`: one trilinear tap of `fluid_turbulence`
+ * between two of its levels. A caller scales it by `σ` and places `q` from a world point by the far
+ * field's offset and length scale.
+ *
+ * `fluid_turbulence_lod(cell, inverse_texel)`: the level a lattice of cell `cell` reads, the tile's
+ * texel being `1 / inverse_texel`: `log2(cell / texel)`, and 0 for a cell no larger than a texel. Level
+ * `ℓ` holds the wavelengths of two of its texels and longer (`fluid_turbulence_tile_generate_levels`), so
+ * a lattice reads what its cells can hold: nothing aliased into it, and a footprint of about a texel a
+ * cell, which is what a tap's cache wants.
+ *
+ * Bindings as {@link fluid_turbulence_add_resources} declares them.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_turbulence = CodeChunk.from(
+    //language=WGSL
+    `
+fn fluid_turbulence_at(q: vec3<f32>, lod: f32) -> vec3<f32> {
+    return textureSampleLevel(fluid_turbulence, fluid_turbulence_sampler, q, lod).xyz;
+}
+
+fn fluid_turbulence_lod(cell: f32, inverse_texel: f32) -> f32 {
+    return max(0.0, log2(cell * inverse_texel));
+}
+`
+);

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

@@ -3,21 +3,24 @@
  * `chunk_wind_field_sample` links for a field as it is ({@link WIND_FIELD_UNIFORM} `false`), any
  * 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. `wind_field_sample_in(field, position_ws)` is the
+ * Reads `wind_field` ({@link WIND_FIELD_STRUCT}), `wind_field_atlas`, `wind_field_sampler` and the
+ * turbulence tile, as {@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
  *   the point answers, with how far into its edge band of {@link WIND_FIELD_BAND_WIDTH} cells the point is;
- * - a cascade's read is the atmosphere identity, `v_far(t) + tap · k_c`: one trilinear tap of its tile,
- *   which holds `v − v_far(t_s,c)` at cell centres, times its decay;
+ * - the far field at the point, `v_far(t, p)`: its mean, plus its turbulence's one tap when it has any
+ *   (`wind_field_far`), band-limited inside a cascade to the cascade's cell, as the cascade's own far
+ *   field is, and whole beyond every cascade;
+ * - a cascade's read is the atmosphere identity, `v_far(t, p) + tap · k_c`: one trilinear tap of its
+ *   tile, which holds `v − v_far(t_s,c)` at cell centres, times its decay;
  * - in the band, a second read blends in linearly, all of it on the window's face: the parent's
- *   identity read, or `v_far(t)` for the coarsest; deeper than the band, one read;
- * - outside every cascade, `v_far(t)`.
+ *   identity read, or `v_far(t, p)` for the coarsest; deeper than the band, one read;
+ * - outside every cascade, `v_far(t, p)`.
  *
  * The blend and the decay are taken now, at the sample, so a cascade that last stepped ticks ago reads
- * the far field's current gust and drag. Air at the far field publishes a deviation of 0 and reads
+ * the far field's current mean, turbulence and drag. Air at the far field publishes a deviation of 0 and reads
  * back `v_far(t)` exactly, on every cascade, in every band, at every instant: the blend is written as
  * `inner + (outer − inner)·w`, which leaves equal reads as they are.
  *

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,+CAFU,SAAS,CAgEjB;0BAxGwB,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":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,+CAFU,SAAS,CAmFjB;0BA/HwB,iCAAiC"}