@woosh/meep-engine 3.68.0 → 3.70.0

package/src/shade/renderer/fluid/GPUFluidCascadeStack.js

@@ -6,6 +6,7 @@ import { GPUFluidCascade } from "./GPUFluidCascade.js";
 import { FluidAtmosphere } from "../../../engine/physics/fluid/FluidAtmosphere.js";
 import { fluid_cascade_parent_value } from "./coupling/FLUID_CASCADE_PARENT_STRUCT.js";
 import { FluidWindPublish } from "./publish/FluidWindPublish.js";
+import { fluid_far_field_value } from "./FLUID_FAR_FIELD_STRUCT.js";
 
 /**
  * @typedef {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
@@ -59,7 +60,9 @@ export const GPU_FLUID_CASCADE_STACK_LIMIT = 8;
  * `read_keep` (`k`). All retained: nothing is allocated to read them.
  *
  * Created placed around `anchor` and filled from the far field of `atmosphere` (velocity `v_far`,
- * pressure 0); after that nothing is allocated per tick.
+ * pressure 0): its mean at creation, and with turbulence, at the first tick that has any, every
+ * cascade's whole window filled from its parent, coarsest first, so the coarsest takes the far field's
+ * eddies exactly and every finer one its parent's. After that nothing is allocated per tick.
  */
 export class GPUFluidCascadeStack {
     /**
@@ -105,6 +108,12 @@ export class GPUFluidCascadeStack {
 
     #destroyed = false;
 
+    /** Whether the windows hold the far field's turbulence yet: filled whole at the first tick with any. */
+    #seeded = false;
+
+    /** One box, a whole window, as `GPUFluidCascade#record_fill` takes it. */
+    #whole = new Int32Array(6);
+
     /**
      * Whether rows 2..5 of every cascade relax toward its parent (§9). On by design; off for the seam
      * probes' A/B.
@@ -159,7 +168,7 @@ export class GPUFluidCascadeStack {
 
             this.#publish_records.push({
                 corner: new Int32Array(3),
-                far_velocity: new Float32Array(3),
+                far: fluid_far_field_value(),
                 parent: fluid_cascade_parent_value(),
                 parent_faces: { u: null, v: null, w: null, pressure: null },
             });
@@ -248,8 +257,11 @@ export class GPUFluidCascadeStack {
      * @param {number} [options.vorticity_confinement] its strength ε, per second, ≥ 0, for both of the
      *   tick's steps, each with its own cell and step (`GPUFluidCascade#record_step`); 0, the default,
      *   records no curl pass
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile
+     *   (`GPUSceneWind#turbulence`), which every pass that reads the far field binds; `null`, the default,
+     *   only for a far field with none
      */
-    record_tick({ graph, tick, dt, anchor, atmosphere, atmosphere_offset, forcing = null, vorticity_confinement = 0 }) {
+    record_tick({ graph, tick, dt, anchor, atmosphere, atmosphere_offset, forcing = null, vorticity_confinement = 0, turbulence = null }) {
         assert.notOk(this.#destroyed, 'the stack is destroyed');
         assert.defined(graph, 'graph');
         assert.isNonNegativeInteger(tick, 'tick');
@@ -288,10 +300,30 @@ export class GPUFluidCascadeStack {
             const box_count = window_scroll_regions(this.#old_corner, this.#new_corner, this.#resolution, 3, this.#boxes);
 
             cascade.place(this.#new_corner);
-            cascade.record_fill({ graph, boxes: this.#boxes, box_count, parent: c + 1 < count ? cascades[c + 1] : null });
+            cascade.record_fill({ graph, boxes: this.#boxes, box_count, parent: c + 1 < count ? cascades[c + 1] : null, turbulence });
             this.#unpublished[c] = 1;
         }
 
+        // the far field's eddies into every window, once: the windows were made at its mean
+        if (!this.#seeded && atmosphere[atmosphere_offset + FluidAtmosphere.TURBULENCE_SIGMA] !== 0) {
+            const whole = this.#whole;
+
+            for (let c = count - 1; c >= 0; c--) {
+                const cascade = cascades[c];
+                const corner = cascade.corner;
+
+                for (let axis = 0; axis < 3; axis++) {
+                    whole[axis] = corner[axis];
+                    whole[3 + axis] = corner[axis] + this.#resolution[axis];
+                }
+
+                cascade.record_fill({ graph, boxes: whole, box_count: 1, parent: c + 1 < count ? cascades[c + 1] : null, turbulence });
+                this.#unpublished[c] = 1;
+            }
+
+            this.#seeded = true;
+        }
+
         const band = this.relaxation_band;
 
         // the brick queries of both stepping cascades, against the windows they step in
@@ -306,7 +338,7 @@ export class GPUFluidCascadeStack {
             this.#unpublished[coarse] = 1;
 
             if (this.feedback) {
-                cascade.record_restrict({ graph, child: cascades[coarse - 1] });
+                cascade.record_restrict({ graph, child: cascades[coarse - 1], turbulence });
             }
 
             // after the restriction, which would overwrite the walls it pins
@@ -321,6 +353,7 @@ export class GPUFluidCascadeStack {
                 relaxation_band: band,
                 forcing: coarse_forcing,
                 vorticity_confinement,
+                turbulence,
             });
         }
 
@@ -335,6 +368,7 @@ export class GPUFluidCascadeStack {
             relaxation_band: band,
             forcing: fine_forcing,
             vorticity_confinement,
+            turbulence,
         });
 
         this.#unpublished[0] = 1;
@@ -349,7 +383,8 @@ export class GPUFluidCascadeStack {
      *     wind.set_cascades(count, resolution)
      *     wind.set_cascade_window(c, corner, cell_size)       every cascade
      *     wind.set_cascade_decay(c, k)                        k = e^(−(Λ(t) − Λ(t_s,c))), read_keep
-     *     wind.set_far_velocity(v_far(t))
+     *     wind.set_far_velocity(u(t))                         the far field's mean
+     *     wind.set_turbulence(σ, offset, L)                   its turbulence
      *
      * A tile holds `v − v_far(t_s,c)` and `k` is taken for `t`, so a cascade that did not step reads
      * from its old tile through its new decay. A cascade that is published takes the field's
@@ -393,7 +428,7 @@ export class GPUFluidCascadeStack {
             const record = this.#publish_records[c];
 
             record.corner.set(cascade.corner);
-            record.far_velocity.set(cascade.read_far_velocity);
+            cascade.describe_far(record.far);
             cascade.describe_parent(record.parent, record.parent_faces, c + 1 < count ? cascades[c + 1] : null);
 
             // its tile is written beside the one the frame before read
@@ -409,6 +444,11 @@ export class GPUFluidCascadeStack {
         far[2] = atmosphere[atmosphere_offset + FluidAtmosphere.VELOCITY_Z];
 
         wind.set_far_velocity(far);
+        wind.set_turbulence(
+            atmosphere[atmosphere_offset + FluidAtmosphere.TURBULENCE_SIGMA],
+            this.#turbulence_offset_of(atmosphere, atmosphere_offset),
+            atmosphere[atmosphere_offset + FluidAtmosphere.TURBULENCE_LENGTH]
+        );
 
         if (pending === 0) {
             return;
@@ -421,7 +461,25 @@ export class GPUFluidCascadeStack {
     }
 
     /** The options {@link FluidWindPublish#record} takes, rewritten for every cascade. */
-    #publish_options = { encoder: null, velocity: null, corner: null, far_velocity: null, parent: null, parent_faces: null, atlas: null, slot: 0 };
+    #publish_options = { encoder: null, velocity: null, corner: null, far: null, turbulence: null, parent: null, parent_faces: null, atlas: null, slot: 0 };
+
+    /** Scratch for an atmosphere's turbulence offset. */
+    #turbulence_offset = new Float64Array(3);
+
+    /**
+     * @param {Float64Array|number[]} atmosphere
+     * @param {number} offset
+     * @returns {Float64Array}
+     */
+    #turbulence_offset_of(atmosphere, offset) {
+        const out = this.#turbulence_offset;
+
+        out[0] = atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_X];
+        out[1] = atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_Y];
+        out[2] = atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_Z];
+
+        return out;
+    }
 
     /**
      * @param {object} pass
@@ -440,6 +498,7 @@ export class GPUFluidCascadeStack {
 
         options.encoder = context.encoder;
         options.atlas = wind.atlas;
+        options.turbulence = wind.turbulence;
 
         try {
             for (let i = 0; i < pass.count; i++) {
@@ -448,7 +507,7 @@ export class GPUFluidCascadeStack {
 
                 options.velocity = stack.#cascades[c].velocity;
                 options.corner = record.corner;
-                options.far_velocity = record.far_velocity;
+                options.far = record.far;
                 options.parent = record.parent;
                 options.parent_faces = record.parent_faces;
                 options.slot = wind.slot(c);
@@ -456,7 +515,7 @@ export class GPUFluidCascadeStack {
                 stack.#publish.record(options);
             }
         } finally {
-            options.encoder = options.atlas = options.velocity = options.corner = options.far_velocity = null;
+            options.encoder = options.atlas = options.velocity = options.corner = options.far = options.turbulence = null;
             options.parent = options.parent_faces = null;
             pass.wind = null;
         }

package/src/shade/renderer/fluid/chunk_fluid_far_field.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The far field laid over a lattice ({@link FLUID_FAR_FIELD_STRUCT}), at the lattice's cell coordinate
+ * `c` (cell centres at integers; a u face `(i, j, k)` at `(i − ½, j, k)`):
+ *
+ * - `fluid_far_unit(far, c)`: `T(origin + c ⊙ scale)` at level `far.lod`, the unit-rms turbulence there,
+ *   one tap of the tile; `vec3(0)` with no turbulence, and then no tap;
+ * - `fluid_far_field(far, c)`: `mean + sigma · T`, the far field there; `mean` exactly with no
+ *   turbulence.
+ *
+ * Every lattice point of every pass branches on `sigma` from a uniform, so the branch is uniform too:
+ * a far field with no turbulence costs a compare.
+ *
+ * Binds the tile and its sampler (`fluid_turbulence_add_resources`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_far_field: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_far_field.d.ts.map

package/src/shade/renderer/fluid/chunk_fluid_far_field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_fluid_far_field.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/chunk_fluid_far_field.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CAwBjB;0BA1CwB,iCAAiC"}

package/src/shade/renderer/fluid/chunk_fluid_far_field.js

@@ -0,0 +1,43 @@
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { chunk_fluid_turbulence } from "../wind/chunk_fluid_turbulence.js";
+import { FLUID_FAR_FIELD_STRUCT } from "./FLUID_FAR_FIELD_STRUCT.js";
+
+/**
+ * The far field laid over a lattice ({@link FLUID_FAR_FIELD_STRUCT}), at the lattice's cell coordinate
+ * `c` (cell centres at integers; a u face `(i, j, k)` at `(i − ½, j, k)`):
+ *
+ * - `fluid_far_unit(far, c)`: `T(origin + c ⊙ scale)` at level `far.lod`, the unit-rms turbulence there,
+ *   one tap of the tile; `vec3(0)` with no turbulence, and then no tap;
+ * - `fluid_far_field(far, c)`: `mean + sigma · T`, the far field there; `mean` exactly with no
+ *   turbulence.
+ *
+ * Every lattice point of every pass branches on `sigma` from a uniform, so the branch is uniform too:
+ * a far field with no turbulence costs a compare.
+ *
+ * Binds the tile and its sampler (`fluid_turbulence_add_resources`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_far_field = CodeChunk.from(
+    //language=WGSL
+    `
+fn fluid_far_unit(far: ${FLUID_FAR_FIELD_STRUCT.wgsl_ref}, c: vec3<f32>) -> vec3<f32> {
+    if (far.sigma == 0.0) {
+        return vec3<f32>(0.0);
+    }
+
+    return fluid_turbulence_at(far.origin + c * far.scale, far.lod);
+}
+
+fn fluid_far_field(far: ${FLUID_FAR_FIELD_STRUCT.wgsl_ref}, c: vec3<f32>) -> vec3<f32> {
+    if (far.sigma == 0.0) {
+        return far.mean;
+    }
+
+    return far.mean + far.sigma * fluid_turbulence_at(far.origin + c * far.scale, far.lod);
+}
+`, [
+        FLUID_FAR_FIELD_STRUCT.declaration_chunk,
+        chunk_fluid_turbulence,
+    ]
+);

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_PARENT_STRUCT.d.ts

@@ -1,7 +1,7 @@
 /**
  * A {@link FLUID_CASCADE_PARENT_STRUCT} value, to be filled in place (`GPUFluidCascade#describe_parent`).
  *
- * @returns {{origin: Int32Array, keep: number, cells: object, faces_u: object, faces_v: object, faces_w: object, far_velocity: Float32Array, read_far_velocity: Float32Array}}
+ * @returns {{origin: Int32Array, keep: number, cells: object, faces_u: object, faces_v: object, faces_w: object, far: object, read: object}}
  */
 export function fluid_cascade_parent_value(): {
     origin: Int32Array;
@@ -10,8 +10,8 @@ export function fluid_cascade_parent_value(): {
     faces_u: object;
     faces_v: object;
     faces_w: object;
-    far_velocity: Float32Array;
-    read_far_velocity: Float32Array;
+    far: object;
+    read: object;
 };
 /**
  * A cascade's parent as the cascade reads it beyond its own window, the uniform `parent`
@@ -27,16 +27,17 @@ export function fluid_cascade_parent_value(): {
  * - `cells`: where the parent's pressure is stored ({@link GRID_TILE_WINDOW_STRUCT}, in the parent's
  *   cells).
  * - `faces_u`, `faces_v`, `faces_w`: where the parent's faces are stored.
- * - `far_velocity`: `v_far(t_s,p)`, m/s, the far field at the parent's last step: what its faces are
- *   a deviation from.
- * - `read_far_velocity`: `v_far` at the instant the child reads at, m/s.
+ * - `far`: `v_far(t_s,p)`, the far field at the parent's last step: what its faces are a deviation
+ *   from ({@link FLUID_FAR_FIELD_STRUCT}, over the child's lattice, cell coordinate 0 at the child-lattice
+ *   cell `origin`).
+ * - `read`: `v_far` at the instant the child reads at, over the same lattice.
  * - `keep`: `e^(−(Λ(t_read) − Λ(t_s,p)))`, how much of the parent's deviation the read keeps.
  *
- * So the parent's identity read of a face value `v` is `read_far_velocity + (v − far_velocity)·keep`
- * (§6), and a read beyond the parent's window is `read_far_velocity`.
+ * So the parent's identity read of a face value `v` at `x` is `read(x) + (v − far(x))·keep` (§6), and a
+ * read beyond the parent's window is `read(x)`.
  *
  * **The far field is a parent with no window**: every window's size is 0, so every read lands
- * beyond it, velocity reads `read_far_velocity` and pressure 0. The coarsest cascade, and a cascade
+ * beyond it, velocity reads `read(x)` and pressure 0. The coarsest cascade, and a cascade
  * stepped on its own, read that.
  *
  * @type {WebGPUStruct}

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_PARENT_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FLUID_CASCADE_PARENT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_PARENT_STRUCT.js"],"names":[],"mappings":"AA4CA;;;;GAIG;AACH,8CAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,iBAAiB,EAAE,YAAY,CAAA;CAAC,CAa7K;AAvDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,0CAFU,YAAY,CAWG;6BAxCI,mCAAmC"}
+{"version":3,"file":"FLUID_CASCADE_PARENT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_PARENT_STRUCT.js"],"names":[],"mappings":"AA8CA;;;;GAIG;AACH,8CAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAa3I;AAxDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,0CAFU,YAAY,CAWG;6BA1CI,mCAAmC"}

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_PARENT_STRUCT.js

@@ -1,7 +1,8 @@
 import { GRID_TILE_WINDOW_STRUCT } from "../../shader/chunk/grid/GRID_TILE_WINDOW_STRUCT.js";
-import { f32, vec3f, vec3i } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { f32, vec3i } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { fluid_cascade_window_value } from "../fluid_cascade_window.js";
+import { FLUID_FAR_FIELD_STRUCT, fluid_far_field_value } from "../FLUID_FAR_FIELD_STRUCT.js";
 
 /**
  * A cascade's parent as the cascade reads it beyond its own window, the uniform `parent`
@@ -17,16 +18,17 @@ import { fluid_cascade_window_value } from "../fluid_cascade_window.js";
  * - `cells`: where the parent's pressure is stored ({@link GRID_TILE_WINDOW_STRUCT}, in the parent's
  *   cells).
  * - `faces_u`, `faces_v`, `faces_w`: where the parent's faces are stored.
- * - `far_velocity`: `v_far(t_s,p)`, m/s, the far field at the parent's last step: what its faces are
- *   a deviation from.
- * - `read_far_velocity`: `v_far` at the instant the child reads at, m/s.
+ * - `far`: `v_far(t_s,p)`, the far field at the parent's last step: what its faces are a deviation
+ *   from ({@link FLUID_FAR_FIELD_STRUCT}, over the child's lattice, cell coordinate 0 at the child-lattice
+ *   cell `origin`).
+ * - `read`: `v_far` at the instant the child reads at, over the same lattice.
  * - `keep`: `e^(−(Λ(t_read) − Λ(t_s,p)))`, how much of the parent's deviation the read keeps.
  *
- * So the parent's identity read of a face value `v` is `read_far_velocity + (v − far_velocity)·keep`
- * (§6), and a read beyond the parent's window is `read_far_velocity`.
+ * So the parent's identity read of a face value `v` at `x` is `read(x) + (v − far(x))·keep` (§6), and a
+ * read beyond the parent's window is `read(x)`.
  *
  * **The far field is a parent with no window**: every window's size is 0, so every read lands
- * beyond it, velocity reads `read_far_velocity` and pressure 0. The coarsest cascade, and a cascade
+ * beyond it, velocity reads `read(x)` and pressure 0. The coarsest cascade, and a cascade
  * stepped on its own, read that.
  *
  * @type {WebGPUStruct}
@@ -38,14 +40,14 @@ export const FLUID_CASCADE_PARENT_STRUCT = WebGPUStruct.from({
     faces_u: GRID_TILE_WINDOW_STRUCT,
     faces_v: GRID_TILE_WINDOW_STRUCT,
     faces_w: GRID_TILE_WINDOW_STRUCT,
-    far_velocity: vec3f,
-    read_far_velocity: vec3f,
+    far: FLUID_FAR_FIELD_STRUCT,
+    read: FLUID_FAR_FIELD_STRUCT,
 }, 'FluidCascadeParent');
 
 /**
  * A {@link FLUID_CASCADE_PARENT_STRUCT} value, to be filled in place (`GPUFluidCascade#describe_parent`).
  *
- * @returns {{origin: Int32Array, keep: number, cells: object, faces_u: object, faces_v: object, faces_w: object, far_velocity: Float32Array, read_far_velocity: Float32Array}}
+ * @returns {{origin: Int32Array, keep: number, cells: object, faces_u: object, faces_v: object, faces_w: object, far: object, read: object}}
  */
 export function fluid_cascade_parent_value() {
     return {
@@ -55,7 +57,7 @@ export function fluid_cascade_parent_value() {
         faces_u: fluid_cascade_window_value(),
         faces_v: fluid_cascade_window_value(),
         faces_w: fluid_cascade_window_value(),
-        far_velocity: new Float32Array(3),
-        read_far_velocity: new Float32Array(3),
+        far: fluid_far_field_value(),
+        read: fluid_far_field_value(),
     };
 }

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_RESTRICT_STRUCT.d.ts

@@ -14,8 +14,9 @@ export const FLUID_CASCADE_FEEDBACK_MARGIN: number;
  * - `box`, `box_size`: the parent window-local cells restricted, whose six faces all take the child's;
  * - `child_offset`: the child window-local cell of the parent's window-local cell 0, so parent cell
  *   `P` holds child cells `2P + child_offset` to `2P + child_offset + 1`;
- * - `child_far_velocity`: `v_far` at the child's record, what its faces deviate from;
- * - `far_velocity`: `v_far` at the parent's record;
+ * - `child_far`: `v_far` at the child's record, what its faces deviate from, laid over the parent's
+ *   cells ({@link FLUID_FAR_FIELD_STRUCT}, cell coordinate 0 at the parent's window-local cell 0);
+ * - `far`: `v_far` at the parent's record, over the same lattice;
  * - `keep`: `e^(−(Λ(t_s,parent) − Λ(t_s,child)))`, the child's deviation as of the parent's record.
  *
  * @type {WebGPUStruct}

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_RESTRICT_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FLUID_CASCADE_RESTRICT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_RESTRICT_STRUCT.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;GAaG;AACH,4CAFU,YAAY,CAeK;6BAtCE,mCAAmC"}
+{"version":3,"file":"FLUID_CASCADE_RESTRICT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_RESTRICT_STRUCT.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;GAcG;AACH,4CAFU,YAAY,CAeK;6BAxCE,mCAAmC"}

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_RESTRICT_STRUCT.js

@@ -1,6 +1,7 @@
 import { GRID_TILE_WINDOW_STRUCT } from "../../shader/chunk/grid/GRID_TILE_WINDOW_STRUCT.js";
-import { f32, vec3f, vec3i, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { f32, vec3i, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { FLUID_FAR_FIELD_STRUCT } from "../FLUID_FAR_FIELD_STRUCT.js";
 
 /**
  * Child cells from each face of a child's window that its feedback leaves out: the edge row and the
@@ -19,8 +20,9 @@ export const FLUID_CASCADE_FEEDBACK_MARGIN = 6;
  * - `box`, `box_size`: the parent window-local cells restricted, whose six faces all take the child's;
  * - `child_offset`: the child window-local cell of the parent's window-local cell 0, so parent cell
  *   `P` holds child cells `2P + child_offset` to `2P + child_offset + 1`;
- * - `child_far_velocity`: `v_far` at the child's record, what its faces deviate from;
- * - `far_velocity`: `v_far` at the parent's record;
+ * - `child_far`: `v_far` at the child's record, what its faces deviate from, laid over the parent's
+ *   cells ({@link FLUID_FAR_FIELD_STRUCT}, cell coordinate 0 at the parent's window-local cell 0);
+ * - `far`: `v_far` at the parent's record, over the same lattice;
  * - `keep`: `e^(−(Λ(t_s,parent) − Λ(t_s,child)))`, the child's deviation as of the parent's record.
  *
  * @type {WebGPUStruct}
@@ -36,6 +38,6 @@ export const FLUID_CASCADE_RESTRICT_STRUCT = WebGPUStruct.from({
     keep: f32,
     box_size: vec3u,
     child_offset: vec3i,
-    child_far_velocity: vec3f,
-    far_velocity: vec3f,
+    child_far: FLUID_FAR_FIELD_STRUCT,
+    far: FLUID_FAR_FIELD_STRUCT,
 }, 'FluidCascadeRestrict');

package/src/shade/renderer/fluid/coupling/chunk_fluid_cascade_epilogue.d.ts

@@ -33,17 +33,25 @@ export const FLUID_CASCADE_DEVIATION_CELLS: number;
  *   faces are row 1.
  * - `fluid_mac_epilogue_u(face, value, push)`, `_v`, `_w`: the identity, plus `push`, the face's
  *   vorticity confinement over the step (0 without it); then, with `step.band`, the band toward the
- *   parent's identity read at the face carried through the same identity, then the clamp about
- *   `v_far` at the step's end. The order is §8's pass 3: the atmosphere, confinement, the band, the
- *   clamp, so the band relaxes and the clamp bounds the confined face like any other.
+ *   parent carried through the same identity, `v_far(t₁)` plus what the step keeps of the parent's
+ *   deviation at the face, then the clamp about `v_far(t₁)`. The order is §8's pass 3: the atmosphere,
+ *   confinement, the band, the clamp, so the band relaxes and the clamp bounds the confined face like
+ *   any other.
  *
- * Reads the uniforms `step` (`FLUID_MAC_STEP_STRUCT`) and `parent`, and the parent's faces
- * (`chunk_fluid_cascade_parent_velocity`), whose read is at the step's start; the band reads 8 parent
- * texels a face on its rows, nothing elsewhere.
+ * The far field at a face is `step.far` and `step.far_end` there (`FLUID_MAC_STEP_STRUCT`): with
+ * turbulence, the eddies the mean carries to the face by `t₁`, one tap of the tile a face shared by
+ * the step's start and end, so air the far field alone moves, advected to the face, is `v_far(t₀)`
+ * there and goes to `v_far(t₁)`. Turbulence carried by the mean and advection by the whole field part
+ * by the eddies' own speed over the step, a deviation the atmosphere relaxes like any other.
  *
- * Air the far field alone moves is exact through all of it: the identity maps `v_far(t₀)` to
- * `v_far(t₁)`, the parent reads `v_far(t₀)` there so the band's target is `v_far(t₁)` too, and the
- * clamp holds what is already at its centre.
+ * Reads the uniforms `step` (`FLUID_MAC_STEP_STRUCT`) and `parent`, the parent's faces
+ * (`chunk_fluid_cascade_parent_velocity`), whose read is at the step's start, and the turbulence tile:
+ * one tap a face with turbulence, none without; the band reads 8 parent texels a face on its rows, and
+ * a tap more with turbulence, nothing elsewhere.
+ *
+ * Air the far field alone moves is exact through all of it with no turbulence: the identity maps
+ * `v_far(t₀)` to `v_far(t₁)`, the parent's deviation there is 0 so the band's target is `v_far(t₁)` too,
+ * and the clamp holds what is already at its centre.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/fluid/coupling/chunk_fluid_cascade_epilogue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_fluid_cascade_epilogue.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/chunk_fluid_cascade_epilogue.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,2CAFU,MAAM,CAE8B;AAE9C,qBAAqB;AACrB,0CADW,MAAM,CAC4B;AAE7C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,2CAFU,SAAS,CA4FjB;0BAjJwB,oCAAoC"}
+{"version":3,"file":"chunk_fluid_cascade_epilogue.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/chunk_fluid_cascade_epilogue.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,2CAFU,MAAM,CAE8B;AAE9C,qBAAqB;AACrB,0CADW,MAAM,CAC4B;AAE7C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,2CAFU,SAAS,CA0HjB;0BAzLwB,oCAAoC"}

package/src/shade/renderer/fluid/coupling/chunk_fluid_cascade_epilogue.js

@@ -1,5 +1,7 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { chunk_fluid_cascade_parent_velocity } from "./chunk_fluid_cascade_parent.js";
+import { chunk_fluid_turbulence } from "../../wind/chunk_fluid_turbulence.js";
+import { FLUID_FAR_FIELD_STRUCT } from "../FLUID_FAR_FIELD_STRUCT.js";
 
 /**
  * Rows of a cascade's relaxation band (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §9, WRF's Davies
@@ -39,17 +41,25 @@ export const FLUID_CASCADE_DEVIATION_CELLS = 4;
  *   faces are row 1.
  * - `fluid_mac_epilogue_u(face, value, push)`, `_v`, `_w`: the identity, plus `push`, the face's
  *   vorticity confinement over the step (0 without it); then, with `step.band`, the band toward the
- *   parent's identity read at the face carried through the same identity, then the clamp about
- *   `v_far` at the step's end. The order is §8's pass 3: the atmosphere, confinement, the band, the
- *   clamp, so the band relaxes and the clamp bounds the confined face like any other.
+ *   parent carried through the same identity, `v_far(t₁)` plus what the step keeps of the parent's
+ *   deviation at the face, then the clamp about `v_far(t₁)`. The order is §8's pass 3: the atmosphere,
+ *   confinement, the band, the clamp, so the band relaxes and the clamp bounds the confined face like
+ *   any other.
  *
- * Reads the uniforms `step` (`FLUID_MAC_STEP_STRUCT`) and `parent`, and the parent's faces
- * (`chunk_fluid_cascade_parent_velocity`), whose read is at the step's start; the band reads 8 parent
- * texels a face on its rows, nothing elsewhere.
+ * The far field at a face is `step.far` and `step.far_end` there (`FLUID_MAC_STEP_STRUCT`): with
+ * turbulence, the eddies the mean carries to the face by `t₁`, one tap of the tile a face shared by
+ * the step's start and end, so air the far field alone moves, advected to the face, is `v_far(t₀)`
+ * there and goes to `v_far(t₁)`. Turbulence carried by the mean and advection by the whole field part
+ * by the eddies' own speed over the step, a deviation the atmosphere relaxes like any other.
  *
- * Air the far field alone moves is exact through all of it: the identity maps `v_far(t₀)` to
- * `v_far(t₁)`, the parent reads `v_far(t₀)` there so the band's target is `v_far(t₁)` too, and the
- * clamp holds what is already at its centre.
+ * Reads the uniforms `step` (`FLUID_MAC_STEP_STRUCT`) and `parent`, the parent's faces
+ * (`chunk_fluid_cascade_parent_velocity`), whose read is at the step's start, and the turbulence tile:
+ * one tap a face with turbulence, none without; the band reads 8 parent texels a face on its rows, and
+ * a tap more with turbulence, nothing elsewhere.
+ *
+ * Air the far field alone moves is exact through all of it with no turbulence: the identity maps
+ * `v_far(t₀)` to `v_far(t₁)`, the parent's deviation there is 0 so the band's target is `v_far(t₁)` too,
+ * and the clamp holds what is already at its centre.
  *
  * @type {CodeChunk}
  */
@@ -99,48 +109,78 @@ fn fluid_mac_face_row_w(face: vec3<i32>) -> i32 {
     return 1 + min(along, across);
 }
 
+// the eddies the far field alone brings to window-local cell coordinate c by t₁: one tap, which the
+// start's far field and the end's share; 0 with no turbulence at either end
+fn fluid_mac_step_eddies(c: vec3<f32>) -> vec3<f32> {
+    if (step.far.sigma == 0.0 && step.far_end.sigma == 0.0) {
+        return vec3<f32>(0.0);
+    }
+
+    // whichever end has turbulence lays it; both do alike when both have it
+    let end = step.far_end.sigma != 0.0;
+    let origin = select(step.far.origin, step.far_end.origin, end);
+    let scale = select(step.far.scale, step.far_end.scale, end);
+    let lod = select(step.far.lod, step.far_end.lod, end);
+
+    return fluid_turbulence_at(origin + c * scale, lod);
+}
+
 fn fluid_mac_epilogue_u(face: vec3<i32>, value: f32, push: f32) -> f32 {
-    var v = fluid_atmosphere_identity(value, step.far_velocity.x, step.far_velocity_end.x, step.keep) + push;
+    let eddy = fluid_mac_step_eddies(vec3<f32>(face) - vec3<f32>(0.5, 0.0, 0.0)).x;
+    let far_start = step.far.mean.x + step.far.sigma * eddy;
+    let far_end = step.far_end.mean.x + step.far_end.sigma * eddy;
+
+    var v = fluid_atmosphere_identity(value, far_start, far_end, step.keep) + push;
 
     let weight = select(0.0, fluid_relaxation_weight(fluid_mac_face_row_u(face)), step.band != 0u);
 
     if (weight > 0.0) {
-        let toward = fluid_atmosphere_identity(fluid_parent_face_u(face, step.cells.corner - parent.origin), step.far_velocity.x, step.far_velocity_end.x, step.keep);
+        let toward = far_end + step.keep * fluid_parent_face_deviation_u(face, step.cells.corner - parent.origin);
 
         v += weight * (toward - v);
     }
 
-    return fluid_deviation_clamp(v, step.far_velocity_end.x, step.deviation_limit);
+    return fluid_deviation_clamp(v, far_end, step.deviation_limit);
 }
 
 fn fluid_mac_epilogue_v(face: vec3<i32>, value: f32, push: f32) -> f32 {
-    var v = fluid_atmosphere_identity(value, step.far_velocity.y, step.far_velocity_end.y, step.keep) + push;
+    let eddy = fluid_mac_step_eddies(vec3<f32>(face) - vec3<f32>(0.0, 0.5, 0.0)).y;
+    let far_start = step.far.mean.y + step.far.sigma * eddy;
+    let far_end = step.far_end.mean.y + step.far_end.sigma * eddy;
+
+    var v = fluid_atmosphere_identity(value, far_start, far_end, step.keep) + push;
 
     let weight = select(0.0, fluid_relaxation_weight(fluid_mac_face_row_v(face)), step.band != 0u);
 
     if (weight > 0.0) {
-        let toward = fluid_atmosphere_identity(fluid_parent_face_v(face, step.cells.corner - parent.origin), step.far_velocity.y, step.far_velocity_end.y, step.keep);
+        let toward = far_end + step.keep * fluid_parent_face_deviation_v(face, step.cells.corner - parent.origin);
 
         v += weight * (toward - v);
     }
 
-    return fluid_deviation_clamp(v, step.far_velocity_end.y, step.deviation_limit);
+    return fluid_deviation_clamp(v, far_end, step.deviation_limit);
 }
 
 fn fluid_mac_epilogue_w(face: vec3<i32>, value: f32, push: f32) -> f32 {
-    var v = fluid_atmosphere_identity(value, step.far_velocity.z, step.far_velocity_end.z, step.keep) + push;
+    let eddy = fluid_mac_step_eddies(vec3<f32>(face) - vec3<f32>(0.0, 0.0, 0.5)).z;
+    let far_start = step.far.mean.z + step.far.sigma * eddy;
+    let far_end = step.far_end.mean.z + step.far_end.sigma * eddy;
+
+    var v = fluid_atmosphere_identity(value, far_start, far_end, step.keep) + push;
 
     let weight = select(0.0, fluid_relaxation_weight(fluid_mac_face_row_w(face)), step.band != 0u);
 
     if (weight > 0.0) {
-        let toward = fluid_atmosphere_identity(fluid_parent_face_w(face, step.cells.corner - parent.origin), step.far_velocity.z, step.far_velocity_end.z, step.keep);
+        let toward = far_end + step.keep * fluid_parent_face_deviation_w(face, step.cells.corner - parent.origin);
 
         v += weight * (toward - v);
     }
 
-    return fluid_deviation_clamp(v, step.far_velocity_end.z, step.deviation_limit);
+    return fluid_deviation_clamp(v, far_end, step.deviation_limit);
 }
 `, [
         chunk_fluid_cascade_parent_velocity,
+        chunk_fluid_turbulence,
+        FLUID_FAR_FIELD_STRUCT.declaration_chunk,
     ]
 );