@woosh/meep-engine 3.68.0 → 3.70.0

package/src/shade/renderer/dynamic/shader_dynamic_mesh_avboit_splat.js

@@ -1,18 +1,8 @@
-import { PipelineLayoutDescriptor } from "../../descriptor/pipeline/PipelineLayoutDescriptor.js";
-import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { AVBOIT_WARP_STRUCT } from "../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
-import { chunk_avboit_coverage } from "../rasterize/native/avboit/chunk_avboit_coverage.js";
-import { chunk_avboit_splat_slice } from "../rasterize/native/avboit/chunk_avboit_splat_slice.js";
-import {
-    chunk_avboit_transmittance_to_extinction
-} from "../rasterize/native/avboit/chunk_avboit_transmittance_to_extinction.js";
-import { chunk_avboit_view_depth_to_physical } from "../rasterize/native/avboit/chunk_avboit_view_depth_to_physical.js";
-import { AVBOIT_SPLAT_DUMMY_FORMAT } from "../rasterize/native/avboit/shader_avboit_splat.js";
+import { avboit_unlit_splat_pipeline, AVBOIT_UNLIT_SPLAT_PASS_GROUP, chunk_avboit_unlit_splat_fragment } from "../rasterize/native/avboit/avboit_unlit_splat.js";
+import { AVBOIT_SPLAT_VOLUME_GROUP } from "../rasterize/native/avboit/shader_avboit_splat.js";
 import { CodeChunk } from "../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
 import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
-import { atomic_u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
 import { chunk_dynamic_mesh_avboit_vertex } from "./chunk_dynamic_mesh_avboit_vertex.js";
 import {
     DYNAMIC_MESH_BIND_GROUP_DRAWS,
@@ -21,53 +11,22 @@ import {
 } from "./shader_dynamic_mesh.js";
 
 /**
- * Bind group of the warp, set once per pass. Groups 0 and 1 are the dynamic-mesh groups: the draw
- * constants per chunk, the geometry per mesh.
+ * Bind group of the warp (`AVBOIT_UNLIT_SPLAT_PASS_GROUP`), set once per pass. Groups 0 and 1 are the
+ * dynamic-mesh groups: the draw constants per chunk, the geometry per mesh.
  * @type {number}
  */
 export const DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_PASS = 2;
 
 /**
- * Bind group of the volume atomics, set once per pass.
+ * Bind group of the volume atomics (`AVBOIT_SPLAT_VOLUME_GROUP`), set once per pass.
  * @type {number}
  */
 export const DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_VOLUME = 3;
 
 /**
- * Samples per pixel of the splat's raster, which is what a fragment's extinction is weighted by the
- * share of. Four, being the only count above one that WebGPU guarantees.
- * @type {number}
- */
-export const DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES = 4;
-
-/**
- * The dynamic meshes' AVBOIT splat: every mesh's triangles rasterized at the volume's resolution,
- * each fragment's extinction added into the voxel volume through `avboit_splat_slice` — the same
- * write path as the meshlet and particle splats, so a trail, a particle and a surface at one depth
- * pile up in one field.
- *
- * Coverage is the vertex colour's alpha times the mesh's, through `avboit_coverage` — the function
- * the draw weights the same fragment by — and `T_self = 1 - coverage`, untinted. A fragment that
- * has faded to nothing covers nothing and writes nothing, which on a trail is its whole aged-out
- * tail.
- *
- * **Weighted by the share of the voxel the triangle covers.** A voxel is eight pixels across, and a
- * trail is often narrower than that. Sampled at the voxel's centre alone, a thin trail either
- * crosses the centre and writes its full extinction there or misses it and writes nothing, so its
- * occlusion of what lies behind it came and went as it moved by a fraction of a voxel — beaded along
- * a curve, flickering in motion. Here the raster has {@link DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES}
- * samples per pixel, the fragment runs wherever any of them is covered, and its extinction is scaled
- * by the covered fraction: the voxel gets the triangle's extinction averaged over its footprint, as
- * a volume that coarse can hold it. The triangles of one mesh cover disjoint samples, so the
- * fractions of the triangles sharing a voxel add up to at most one layer; a fully covered voxel is
- * written exactly as before. What remains is the average's own bias — a trail a fraction of a voxel
- * wide occludes what is behind it by that fraction of its extinction — which holds still as the
- * trail moves.
- *
- * Depth is the fragment's own view depth from the shared vertex stage, through curve → warp →
- * physical and the two-slice linear split the other splats make. No depth attachment, for the
- * reason the meshlet splat has none: a splat behind an opaque surface lies deeper than anything the
- * draw will look it up for.
+ * The dynamic meshes' AVBOIT splat: every mesh's triangles rasterized at the volume's resolution by the
+ * dynamic-mesh vertex stage, into the unlit splat's fragment stage (`chunk_avboit_unlit_splat_fragment`,
+ * which says what a fragment writes). Coverage is the vertex colour's alpha times the mesh's.
  *
  * Groups 0 and 1 are `DYNAMIC_MESH_RESOURCES`' own groups, the same objects, so their layouts are
  * the ones every dynamic-mesh pipeline declares and a geometry's one group serves them all. The AVBOIT
@@ -78,93 +37,34 @@ const resources = new ShaderResourceSetDescriptor();
 
 resources.addGroup(DYNAMIC_MESH_RESOURCES.groups[DYNAMIC_MESH_BIND_GROUP_DRAWS]);
 resources.addGroup(DYNAMIC_MESH_RESOURCES.groups[DYNAMIC_MESH_BIND_GROUP_GEOMETRY]);
-
-resources.createGroup()
-    .addStorageBuffer("warp", AVBOIT_WARP_STRUCT);
-
-resources.createGroup()
-    .addStorageBuffer("extinction_volume", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("overflow_slice", WebGPUArray.from(atomic_u32), true);
+resources.addGroup(AVBOIT_UNLIT_SPLAT_PASS_GROUP);
+resources.addGroup(AVBOIT_SPLAT_VOLUME_GROUP);
 
 const body = CodeChunk.from(
     //language=WGSL
     `
 @vertex
-fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) draw_index : u32) -> DynamicMeshAVBOITVertexOut {
+fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) draw_index : u32) -> AVBOITUnlitVaryings {
     return dynamic_mesh_avboit_vertex(vi, draw_index);
 }
-
-@fragment
-fn fs_main(in : DynamicMeshAVBOITVertexOut, @builtin(sample_mask) sample_mask : u32) {
-    // the coverage the draw weights this fragment by, through the same function
-    let coverage = avboit_coverage(in.color.a);
-
-    if (coverage <= 0.0) {
-        // faded out: occludes nothing
-        return;
-    }
-
-    // the share of the voxel's samples this triangle covers
-    let footprint = f32(countOneBits(sample_mask)) / ${DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES}.0;
-
-    let extinction = avboit_transmittance_to_extinction(vec3<f32>(1.0 - coverage)) * footprint;
-
-    let p = avboit_view_depth_to_physical(&warp, in.view_depth);
-
-    // in.clip is @builtin(position): .xy the low-resolution pixel
-    let texel = vec2<u32>(in.clip.xy);
-    let column = texel.y * warp.voxel_width + texel.x;
-
-    // linear splat between the two slices around the fragment
-    let c = p - 0.5;
-    let slice = i32(floor(c));
-    let fraction = c - floor(c);
-
-    avboit_splat_slice(column, slice, extinction * (1.0 - fraction), texel);
-    avboit_splat_slice(column, slice + 1, extinction * fraction, texel);
-}
 `, [
     chunk_dynamic_mesh_avboit_vertex,
-    chunk_avboit_coverage,
-    chunk_avboit_transmittance_to_extinction,
-    chunk_avboit_view_depth_to_physical,
-    chunk_avboit_splat_slice,
+    chunk_avboit_unlit_splat_fragment,
 ]);
 
 const descriptor = ShaderDescriptor.from({ label: "Dynamic Mesh AVBOIT Splat", body, resources });
 
-// Built group by group: the atomics are fragment-only, and WebGPU refuses a read-write storage
-// buffer that is visible to the vertex stage. The dynamic-mesh groups keep the visibility they have
-// in the pass over the scene, so the layouts agree and one geometry group serves every pipeline.
-const groups = resources.groups;
-const layout = PipelineLayoutDescriptor.from([
-    groups[DYNAMIC_MESH_BIND_GROUP_DRAWS].generateBindGroupLayoutDescriptor(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-    groups[DYNAMIC_MESH_BIND_GROUP_GEOMETRY].generateBindGroupLayoutDescriptor(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-    groups[DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_PASS].generateBindGroupLayoutDescriptor(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-    groups[DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_VOLUME].generateBindGroupLayoutDescriptor(GPUShaderStage.FRAGMENT),
-], resources.immediateSize);
-
 /**
- * The splat pipeline: no depth, one never-written attachment to size the raster, multisampled so a
- * fragment knows how much of its voxel it covers, both faces — a trail is seen from inside and out.
- * The attachment is the splat's own ({@link DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES} samples), not the
- * volume's single-sampled one the meshlet and particle splats share.
- * @type {RenderPipelineDescriptor}
+ * The splat pipeline, as every unlit splat is built (`avboit_unlit_splat_pipeline`).
+ * @type {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor}
  */
-export const DYNAMIC_MESH_AVBOIT_SPLAT_PIPELINE = RenderPipelineDescriptor.from({
+export const DYNAMIC_MESH_AVBOIT_SPLAT_PIPELINE = avboit_unlit_splat_pipeline({
     label: "Dynamic Mesh AVBOIT Splat",
-    layout,
-    vertex: { module: { code: descriptor.source }, entryPoint: "vs_main" },
-    fragment: {
-        module: { code: descriptor.source },
-        entryPoint: "fs_main",
-        targets: [{ format: AVBOIT_SPLAT_DUMMY_FORMAT, writeMask: 0 }],
-    },
-    primitive: { topology: "triangle-list", cullMode: "none" },
-    multisample: { count: DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES },
+    resources,
+    source: descriptor.source,
 });
 
-/** The splat shader's resource set, for building its pass-level bind groups. */
+/** The splat shader's resource set. */
 export const DYNAMIC_MESH_AVBOIT_SPLAT_RESOURCES = resources;
 
 /** The assembled shader, for the validity tier. */

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

@@ -0,0 +1,111 @@
+/**
+ * A {@link FLUID_FAR_FIELD_STRUCT} value, filled in place: still air.
+ *
+ * @returns {{mean: Float32Array, sigma: number, origin: Float32Array, lod: number, scale: Float32Array}}
+ */
+export function fluid_far_field_value(): {
+    mean: Float32Array;
+    sigma: number;
+    origin: Float32Array;
+    lod: number;
+    scale: Float32Array;
+};
+/**
+ * The far field at one instant as a cascade keeps it on the CPU: what a {@link FluidAtmosphere}
+ * record says of it, the mean rounded to f32 as the device holds it.
+ *
+ * - `mean`: `u`, m/s, f32.
+ * - `sigma`: `σ`, m/s.
+ * - `offset`: `o`, m, f64: how far the mean has carried the turbulence.
+ * - `length`: `L`, m: the turbulence's length scale; anything when `sigma` is 0.
+ *
+ * @returns {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}}
+ */
+export function fluid_far_record(): {
+    mean: Float32Array;
+    sigma: number;
+    offset: Float64Array;
+    length: number;
+};
+/**
+ * Read a {@link fluid_far_record} from a {@link FluidAtmosphere} record.
+ *
+ * @param {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}} out
+ * @param {Float64Array|number[]} atmosphere
+ * @param {number} offset where the record starts
+ */
+export function fluid_far_record_read(out: {
+    mean: Float32Array;
+    sigma: number;
+    offset: Float64Array;
+    length: number;
+}, atmosphere: Float64Array | number[], offset: number): void;
+/**
+ * Copy one {@link fluid_far_record} into another.
+ *
+ * @param {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}} out
+ * @param {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}} from
+ */
+export function fluid_far_record_copy(out: {
+    mean: Float32Array;
+    sigma: number;
+    offset: Float64Array;
+    length: number;
+}, from: {
+    mean: Float32Array;
+    sigma: number;
+    offset: Float64Array;
+    length: number;
+}): void;
+/**
+ * Lay the far field `record` describes over a lattice of cell `h` whose cell coordinate 0 is the world
+ * cell `base` (its centre at `(base + ½)·h`), as a {@link FLUID_FAR_FIELD_STRUCT} value, band-limited to
+ * a cascade of cell `owner_h`, the one whose state it is the far field of. The turbulence is placed by
+ * `offset`, which may be another record's, and scaled by `length`: a step lays its start's mean and σ
+ * where the end's offset puts the eddies.
+ *
+ * @param {{mean: Float32Array, sigma: number, origin: Float32Array, scale: Float32Array}} out
+ * @param {{mean: Float32Array, sigma: number}} record the mean and σ
+ * @param {ArrayLike<number>} offset `o`, m
+ * @param {number} length `L`, m, > 0 when `record.sigma` is not 0
+ * @param {number} base_x
+ * @param {number} base_y
+ * @param {number} base_z
+ * @param {number} h the lattice's cell, m
+ * @param {number} owner_h the cell of the cascade whose far field this is, m
+ */
+export function fluid_far_field_place(out: {
+    mean: Float32Array;
+    sigma: number;
+    origin: Float32Array;
+    scale: Float32Array;
+}, record: {
+    mean: Float32Array;
+    sigma: number;
+}, offset: ArrayLike<number>, length: number, base_x: number, base_y: number, base_z: number, h: number, owner_h: number): void;
+/**
+ * The far field at one instant, laid over one lattice, as a pass reads it
+ * (`chunk_fluid_far_field`): at the lattice's cell coordinate `c` (cell centres at integers),
+ *
+ *     v_far(c) = mean + sigma · T(origin + c ⊙ scale)
+ *
+ * `T` the unit-rms turbulence tile, repeating (`fluid_turbulence_at`).
+ *
+ * - `mean`: `u`, m/s, the far field's mean.
+ * - `sigma`: `σ`, m/s, its turbulence's rms on each axis; 0 for none, and then a read never taps the
+ *   tile.
+ * - `origin`: the tile coordinate of the lattice's cell `c = 0`, folded into `[0, 1)`.
+ * - `lod`: the tile's level it is read at: that of the cell of the cascade whose state it is the far
+ *   field of (`fluid_turbulence_lod`), so a cascade and everything that reads it take its far field
+ *   band-limited to what its cells hold.
+ * - `scale`: tile coordinates per cell on each axis, `h / S`.
+ *
+ * {@link fluid_far_field_place} lays a {@link fluid_far_record} over a lattice; the offset and the
+ * fold are taken there in f64, so the device sees small numbers however far the window is from the
+ * world's origin and however far the air has carried the turbulence. 48 bytes.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_FAR_FIELD_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_FAR_FIELD_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_FAR_FIELD_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/FLUID_FAR_FIELD_STRUCT.js"],"names":[],"mappings":"AAsCA;;;;GAIG;AACH,yCAFa;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAC,CAUvG;AAED;;;;;;;;;;GAUG;AACH,oCAFa;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CASrF;AAED;;;;;;GAMG;AACH,2CAJW;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,cACzE,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAqBhB;AAED;;;;;GAKG;AACH,2CAHW;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,QACzE;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,QAOnF;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,2CAVW;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAC,UAC9E;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,UACnC,UAAU,MAAM,CAAC,UACjB,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,KACN,MAAM,WACN,MAAM,QA8BhB;AA1JD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qCAFU,YAAY,CAQF;6BA/BS,gCAAgC"}

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

@@ -0,0 +1,162 @@
+import { assert } from "../../../core/assert.js";
+import { FluidAtmosphere } from "../../../engine/physics/fluid/FluidAtmosphere.js";
+import { fluid_turbulence_inverse_tile_size } from "../../../engine/physics/fluid/turbulence/fluid_turbulence_inverse_tile_size.js";
+import { FLUID_TURBULENCE_TEXELS_PER_LENGTH } from "../../../engine/physics/fluid/turbulence/FLUID_TURBULENCE_TILE.js";
+import { f32, vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+
+/**
+ * The far field at one instant, laid over one lattice, as a pass reads it
+ * (`chunk_fluid_far_field`): at the lattice's cell coordinate `c` (cell centres at integers),
+ *
+ *     v_far(c) = mean + sigma · T(origin + c ⊙ scale)
+ *
+ * `T` the unit-rms turbulence tile, repeating (`fluid_turbulence_at`).
+ *
+ * - `mean`: `u`, m/s, the far field's mean.
+ * - `sigma`: `σ`, m/s, its turbulence's rms on each axis; 0 for none, and then a read never taps the
+ *   tile.
+ * - `origin`: the tile coordinate of the lattice's cell `c = 0`, folded into `[0, 1)`.
+ * - `lod`: the tile's level it is read at: that of the cell of the cascade whose state it is the far
+ *   field of (`fluid_turbulence_lod`), so a cascade and everything that reads it take its far field
+ *   band-limited to what its cells hold.
+ * - `scale`: tile coordinates per cell on each axis, `h / S`.
+ *
+ * {@link fluid_far_field_place} lays a {@link fluid_far_record} over a lattice; the offset and the
+ * fold are taken there in f64, so the device sees small numbers however far the window is from the
+ * world's origin and however far the air has carried the turbulence. 48 bytes.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_FAR_FIELD_STRUCT = WebGPUStruct.from({
+    mean: vec3f,
+    sigma: f32,
+    origin: vec3f,
+    lod: f32,
+    scale: vec3f,
+}, 'FluidFarField');
+
+/**
+ * A {@link FLUID_FAR_FIELD_STRUCT} value, filled in place: still air.
+ *
+ * @returns {{mean: Float32Array, sigma: number, origin: Float32Array, lod: number, scale: Float32Array}}
+ */
+export function fluid_far_field_value() {
+    return {
+        mean: new Float32Array(3),
+        sigma: 0,
+        origin: new Float32Array(3),
+        lod: 0,
+        scale: new Float32Array(3),
+    };
+}
+
+/**
+ * The far field at one instant as a cascade keeps it on the CPU: what a {@link FluidAtmosphere}
+ * record says of it, the mean rounded to f32 as the device holds it.
+ *
+ * - `mean`: `u`, m/s, f32.
+ * - `sigma`: `σ`, m/s.
+ * - `offset`: `o`, m, f64: how far the mean has carried the turbulence.
+ * - `length`: `L`, m: the turbulence's length scale; anything when `sigma` is 0.
+ *
+ * @returns {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}}
+ */
+export function fluid_far_record() {
+    return {
+        mean: new Float32Array(3),
+        sigma: 0,
+        offset: new Float64Array(3),
+        length: 0,
+    };
+}
+
+/**
+ * Read a {@link fluid_far_record} from a {@link FluidAtmosphere} record.
+ *
+ * @param {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}} out
+ * @param {Float64Array|number[]} atmosphere
+ * @param {number} offset where the record starts
+ */
+export function fluid_far_record_read(out, atmosphere, offset) {
+    out.mean[0] = atmosphere[offset + FluidAtmosphere.VELOCITY_X];
+    out.mean[1] = atmosphere[offset + FluidAtmosphere.VELOCITY_Y];
+    out.mean[2] = atmosphere[offset + FluidAtmosphere.VELOCITY_Z];
+
+    out.sigma = atmosphere[offset + FluidAtmosphere.TURBULENCE_SIGMA];
+    out.offset[0] = atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_X];
+    out.offset[1] = atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_Y];
+    out.offset[2] = atmosphere[offset + FluidAtmosphere.TURBULENCE_OFFSET_Z];
+    out.length = atmosphere[offset + FluidAtmosphere.TURBULENCE_LENGTH];
+
+    for (let axis = 0; axis < 3; axis++) {
+        assert.isFinite(out.mean[axis], 'v_far');
+        assert.isFinite(out.offset[axis], 'turbulence offset');
+    }
+
+    assert.isFinite(out.sigma, 'σ');
+    assert.greaterThanOrEqual(out.sigma, 0, 'σ');
+    assert.ok(out.sigma === 0 || out.length > 0, 'turbulence has a length scale');
+}
+
+/**
+ * Copy one {@link fluid_far_record} into another.
+ *
+ * @param {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}} out
+ * @param {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}} from
+ */
+export function fluid_far_record_copy(out, from) {
+    out.mean.set(from.mean);
+    out.sigma = from.sigma;
+    out.offset.set(from.offset);
+    out.length = from.length;
+}
+
+const inverse_size = new Float64Array(3);
+
+/**
+ * Lay the far field `record` describes over a lattice of cell `h` whose cell coordinate 0 is the world
+ * cell `base` (its centre at `(base + ½)·h`), as a {@link FLUID_FAR_FIELD_STRUCT} value, band-limited to
+ * a cascade of cell `owner_h`, the one whose state it is the far field of. The turbulence is placed by
+ * `offset`, which may be another record's, and scaled by `length`: a step lays its start's mean and σ
+ * where the end's offset puts the eddies.
+ *
+ * @param {{mean: Float32Array, sigma: number, origin: Float32Array, scale: Float32Array}} out
+ * @param {{mean: Float32Array, sigma: number}} record the mean and σ
+ * @param {ArrayLike<number>} offset `o`, m
+ * @param {number} length `L`, m, > 0 when `record.sigma` is not 0
+ * @param {number} base_x
+ * @param {number} base_y
+ * @param {number} base_z
+ * @param {number} h the lattice's cell, m
+ * @param {number} owner_h the cell of the cascade whose far field this is, m
+ */
+export function fluid_far_field_place(out, record, offset, length, base_x, base_y, base_z, h, owner_h) {
+    out.mean.set(record.mean);
+    out.sigma = record.sigma;
+
+    if (record.sigma === 0) {
+        out.origin.fill(0);
+        out.scale.fill(0);
+        out.lod = 0;
+
+        return;
+    }
+
+    // log2(cell / texel), the texel L / FLUID_TURBULENCE_TEXELS_PER_LENGTH, and level 0 for a finer cell
+    out.lod = Math.max(0, Math.log2(owner_h * FLUID_TURBULENCE_TEXELS_PER_LENGTH / length));
+
+    fluid_turbulence_inverse_tile_size(inverse_size, length);
+
+    const origin_x = ((base_x + 0.5) * h - offset[0]) * inverse_size[0];
+    const origin_y = ((base_y + 0.5) * h - offset[1]) * inverse_size[1];
+    const origin_z = ((base_z + 0.5) * h - offset[2]) * inverse_size[2];
+
+    out.origin[0] = origin_x - Math.floor(origin_x);
+    out.origin[1] = origin_y - Math.floor(origin_y);
+    out.origin[2] = origin_z - Math.floor(origin_z);
+
+    out.scale[0] = h * inverse_size[0];
+    out.scale[1] = h * inverse_size[1];
+    out.scale[2] = h * inverse_size[2];
+}

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

@@ -76,11 +76,13 @@ export const GPU_FLUID_CASCADE_GROWTH_EXPONENT_LIMIT: number;
  *   `FLUID_FORCED_FLAG` where the tick's forcing was written for the cell's faces. A step reads these
  *   unless it is handed another buffer. `GPUFluidForcing` writes them before each step of the
  *   cascade, with {@link solid_bricks} saying which bricks it last wrote;
- * - **its read record**: the instant its velocity was last brought to, `t_s`, with `v_far(t_s)`
- *   ({@link read_far_velocity}, rounded to f32 as the device holds it) and `Λ(t_s)`
- *   ({@link read_lambda}), on the CPU. The velocity is a deviation from `v_far(t_s)`, so every read of
- *   it at an instant `t` is `v_far(t) + (v − v_far(t_s))·e^(−(Λ(t) − Λ(t_s)))` (§6); {@link update_read}
- *   computes that factor, {@link read_keep}, on the CPU, and the device never sees `Λ`.
+ * - **its read record**: the instant its velocity was last brought to, `t_s`, with `v_far(t_s)` —
+ *   its mean ({@link read_far_velocity}, rounded to f32 as the device holds it) and its turbulence's
+ *   `σ`, offset and length scale — and `Λ(t_s)` ({@link read_lambda}), on the CPU. The velocity is a
+ *   deviation from `v_far(t_s)`, so every read of it at an instant `t` at a point `x` is
+ *   `v_far(t, x) + (v − v_far(t_s, x))·e^(−(Λ(t) − Λ(t_s)))` (§6); {@link update_read} computes that
+ *   factor, {@link read_keep}, on the CPU, and the device never sees `Λ`. Each pass lays the far field
+ *   over its own lattice (`FLUID_FAR_FIELD_STRUCT`), so the device never sees the offset either.
  *
  * It is created at the far field of a {@link FluidAtmosphere} record: velocity `v_far`, pressure 0,
  * the read record that instant.
@@ -240,6 +242,24 @@ export class GPUFluidCascade {
      * @returns {Readonly<Float32Array>}
      */
     get read_far_velocity(): Readonly<Float32Array>;
+    /**
+     * `v_far(t_s)` laid over this cascade's window as a {@link FLUID_FAR_FIELD_STRUCT} value: cell
+     * coordinate 0 at window-local cell 0. What its publish subtracts.
+     *
+     * @param {{mean: Float32Array, sigma: number, origin: Float32Array, scale: Float32Array}} out
+     * @returns {{mean: Float32Array, sigma: number, origin: Float32Array, scale: Float32Array}} `out`
+     */
+    describe_far(out: {
+        mean: Float32Array;
+        sigma: number;
+        origin: Float32Array;
+        scale: Float32Array;
+    }): {
+        mean: Float32Array;
+        sigma: number;
+        origin: Float32Array;
+        scale: Float32Array;
+    };
     /**
      * `k = e^(−(Λ(t) − Λ(t_s)))` for the instant of the last {@link update_read}, in [0, 1]: a read of
      * the stored velocity `v` at that instant is `v_far(t) + (v − v_far(t_s))·k`. 1 until the first.
@@ -326,8 +346,10 @@ export class GPUFluidCascade {
      * @param {GPUFluidCascadePressureArm} [options.arm]
      * @param {number} [options.count] V-cycles under {@link GPUFluidCascadePressureArm.VCycles}, red-black
      *   sweeps under {@link GPUFluidCascadePressureArm.SOR}
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile
+     *   (`GPUSceneWind#turbulence`); `null`, the default, only for a far field with none
      */
-    record_step({ graph, dt, atmosphere, atmosphere_offset, parent, relaxation_band, solid, forcing, vorticity_confinement, arm, count, }: {
+    record_step({ graph, dt, atmosphere, atmosphere_offset, parent, relaxation_band, solid, forcing, vorticity_confinement, arm, count, turbulence, }: {
         graph: FrameGraph;
         dt: number;
         atmosphere: Float64Array | number[];
@@ -339,6 +361,7 @@ export class GPUFluidCascade {
         vorticity_confinement?: number;
         arm?: GPUFluidCascadePressureArm;
         count?: number;
+        turbulence?: GPUTextureView | null;
     }): void;
     /**
      * Record a fill into `graph`: the cells a placement exposed take the parent's identity read as of
@@ -352,12 +375,15 @@ export class GPUFluidCascade {
      *   one inside the window and on the 4-cell lattice
      * @param {number} options.box_count 0 to 3
      * @param {GPUFluidCascade|null} options.parent the parent to fill from, or `null` for the far field
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile; `null`, the
+     *   default, only for a far field with none
      */
-    record_fill({ graph, boxes, box_count, parent }: {
+    record_fill({ graph, boxes, box_count, parent, turbulence }: {
         graph: FrameGraph;
         boxes: ArrayLike<number>;
         box_count: number;
         parent: GPUFluidCascade | null;
+        turbulence?: GPUTextureView | null;
     }): void;
     /**
      * Record the feedback of `child` into this cascade (§8 pass 7, §9), as it must run before this
@@ -371,10 +397,13 @@ export class GPUFluidCascade {
      * @param {object} options
      * @param {FrameGraph} options.graph
      * @param {GPUFluidCascade} options.child a cascade of half the cell and the same resolution
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile; `null`, the
+     *   default, only for a far field with none
      */
-    record_restrict({ graph, child }: {
+    record_restrict({ graph, child, turbulence }: {
         graph: FrameGraph;
         child: GPUFluidCascade;
+        turbulence?: GPUTextureView | null;
     }): void;
     /**
      * Release everything the cascade made. A step recorded into a graph that has not run yet encodes

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

@@ -1 +1 @@
-{"version":3,"file":"GPUFluidCascade.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/GPUFluidCascade.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUFluidCascade.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/GPUFluidCascade.js"],"names":[],"mappings":"AAyEA;;;;;;;GAOG;AACH,mDAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;;;;yCAvDS,MAAM;AARhB;;;GAGG;AAEH;;;;GAIG;AACH;IACI,4EAA4E;;IAE5E,+EAA+E;;GAEhF;AAEH;;;;;;;;;;;;;GAaG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,iDAFU,MAAM,CAEsC;AAEtD;;;;;;;;;;;GAWG;AACH,sDAFU,MAAM,CAE0C;AA8E1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH;IACI;;;;;OAKG;IACH,iCAFW,OAAO,0CAA0C,EAAE,eAAe,QAS5E;IAw1BD;;;;OAIG;IACH,0CAJW,MAAM,4BAEN;QAAC,OAAO,EAAE,sBAAsB,CAAA;KAAC,QAc3C;IAyCD;;;;OAIG;IACH,sCAJW,MAAM,4BAEN;QAAC,OAAO,EAAE,sBAAsB,CAAA;KAAC,QAe3C;IAkCD;;;;OAIG;IACH,iCAJW,MAAM,aACN,OAAO,mEAAmE,EAAE,kBAAkB,WAC9F;QAAC,OAAO,EAAE,sBAAsB,CAAA;KAAC,QAe3C;IA/1BD;;;;;;;;;OASG;IACH;QAR8B,MAAM;QACE,UAAU,EAArC,UAAU,MAAM,CAAC;QACD,SAAS,EAAzB,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;OAmIhB;IAED;;;OAGG;IACH,wCAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,oCAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,uBAEC;IAED;;;;;;OAMG;IACH,8BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,gDAEC;IAED;;;;;;OAMG;IACH,kBAHW;QAAC,IAAI,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAC,GAC5E;QAAC,IAAI,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAC,CAS1F;IAoBD;;;;OAIG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,wBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAQhB;IAED;;;;OAIG;IACH;gBAFsB,UAAU;wBAAkB,WAAW;cAAQ,WAAW;gBAAU,WAAW;MAMpG;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,cAAc,EAAE,WAAW,CAAC;QAAC,IAAI,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAC,CAUrG;IAED;;;;;;OAMG;IACH,cAFW,UAAU,MAAM,CAAC,QAU3B;IAED;;;;;;;;;OASG;IACH,qBAJW,MAAM,gBACN;QAAC,CAAC,EAAE,iBAAe,IAAI,CAAC;QAAC,CAAC,EAAE,iBAAe,IAAI,CAAC;QAAC,CAAC,EAAE,iBAAe,IAAI,CAAC;QAAC,QAAQ,EAAE,YAAU,IAAI,CAAA;KAAC,UAClG,eAAe,GAAC,IAAI,QA2D9B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH;QArB+B,KAAK,EAAzB,UAAU;QACM,EAAE,EAAlB,MAAM;QACyB,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;QACwB,MAAM,EAApC,eAAe,GAAC,IAAI;QAEH,eAAe,EAAhC,OAAO;QACa,KAAK;QACH,OAAO,GAA7B,MAAM,GAAC,IAAI;QAGM,qBAAqB,GAAtC,MAAM;QAG+B,GAAG,GAAxC,0BAA0B;QACT,KAAK,GAAtB,MAAM;QAEwB,UAAU,GAAxC,iBAAe,IAAI;aAwH7B;IAED;;;;;;;;;;;;;;OAcG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACiB,KAAK,EAAhC,UAAU,MAAM,CAAC;QAGD,SAAS,EAAzB,MAAM;QACwB,MAAM,EAApC,eAAe,GAAC,IAAI;QACU,UAAU,GAAxC,iBAAe,IAAI;aAiF7B;IAED;;;;;;;;;;;;;;OAcG;IACH;QAL+B,KAAK,EAAzB,UAAU;QACe,KAAK,EAA9B,eAAe;QACe,UAAU,GAAxC,iBAAe,IAAI;aAqE7B;IAgOD;;;;OAIG;IACH,gBAqBC;;CACJ;yBAnyCY,OAAO,2DAA2D,EAAE,UAAU;qCAC9E,OAAO,wCAAwC,EAAE,sBAAsB;oCAPhD,8BAA8B"}