@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/water/surface/shader_water_cull.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_water_cull.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_cull.js"],"names":[],"mappings":"AAoCA,2EAA2E;AAC3E,2CAA4C;AAE5C,0CAA0C;AAC1C;IACI,uDAAuD;;IAEvD,sEAAsE;;GAEvE;AAEH,qDAAqD;AACrD,6CAOuB;AAEvB,+CAA+C;AAC/C,oDAGE;AAEF,8EAA8E;AAC9E,yCAA0C;AA6C1C;;;;;;;GAOG;AACH,8CAsGiG;AAEjG,mEAAmE;AACnE;;;;;GAKG;AACH,8CAA+C;AAC/C,4CAA6C;AAW7C;;;;GAIG;AACH,uDAuBM;6BA9PuB,mCAAmC;8BAVlC,+BAA+B"}
+{"version":3,"file":"shader_water_cull.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_cull.js"],"names":[],"mappings":"AAsCA,2EAA2E;AAC3E,2CAA4C;AAE5C,0CAA0C;AAC1C;IACI,uDAAuD;;IAEvD,sEAAsE;;GAEvE;AAEH,qDAAqD;AACrD,6CAOuB;AAEvB,+CAA+C;AAC/C,oDAGE;AAEF,8EAA8E;AAC9E,yCAA0C;AA+C1C;;;;;;;;;;;;;GAaG;AACH,8CAoHiG;AAEjG,mEAAmE;AACnE;;;;;GAKG;AACH,8CAA+C;AAC/C,4CAA6C;AAW7C;;;;GAIG;AACH,uDAuBM;6BAtRuB,mCAAmC;8BAVlC,+BAA+B"}

package/src/shade/renderer/water/surface/shader_water_cull.js

@@ -22,7 +22,7 @@ import { WATER_BODIES_TABLE, WATER_WAVES_TABLE } from "../medium/chunk_water_bod
 import { chunk_water_lod } from "./lod/chunk_water_lod.js";
 import { WATER_LOD_VIEW_STRUCT } from "./lod/WATER_LOD.js";
 import { WATER_PARTICLE_LEVELS } from "./particles/chunk_water_particle.js";
-import { chunk_water_waves_derive } from "./shader_water_waves_derive.js";
+import { chunk_water_waves_derive, WATER_WIND_REFERENCE_HEIGHT } from "./shader_water_waves_derive.js";
 import { WATER_PARTICLE_BODY_BOUNDS_STRIDE } from "./shader_water_waves_combine.js";
 import {
     WATER_BAND_REQUESTS_STRUCT,
@@ -33,6 +33,8 @@ import {
 import { chunk_water_spectrum } from "./spectrum/chunk_water_spectrum.js";
 import { WATER_SPECTRUM_COLUMN_GROUPS_PER_BAND, WATER_SPECTRUM_ROW_GROUPS_PER_BAND } from "./spectrum/shader_water_spectrum.js";
 import { WATER_WAVE_IMPULSE_LIMIT } from "./WATER_WAVE_RECORD_STRUCT.js";
+import { chunk_wind_field_sample } from "../../wind/chunk_wind_field_sample.js";
+import { wind_field_add_resources } from "../../wind/wind_field_add_resources.js";
 
 /** Workgroup size of the culling pass and of the passes over its lists. */
 export const WATER_CULL_WORKGROUP_SIZE = 64;
@@ -85,8 +87,10 @@ fn water_cull_ambient(weights: array<f32, WATER_SPECTRUM_BANDS>, blend: f32) ->
 }
 `);
 
+// the scene's wind field adds a uniform, a texture and a sampler, and no storage buffer: the pass is at the 10 a
+// device is asked for
 const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
+wind_field_add_resources(resources.createGroup()
     .addUniform('cull', WATER_CULL_STRUCT)
     .addUniform('lod', WATER_LOD_VIEW_STRUCT)
     .addUniform('camera', CAMERA_UNIFORM_STRUCT)
@@ -99,7 +103,7 @@ resources.createGroup()
     .addStorageBuffer('activity', WebGPUArray.u32, true)
     .addStorageBuffer('visible_rows', WATER_LIST_APPEND_STRUCT, true)
     .addStorageBuffer('active_rows', WATER_LIST_APPEND_STRUCT, true)
-    .addStorageBuffer('emit_rows', WATER_LIST_APPEND_STRUCT, true);
+    .addStorageBuffer('emit_rows', WATER_LIST_APPEND_STRUCT, true));
 
 const bodies = WATER_BODIES_TABLE, waves = WATER_WAVES_TABLE;
 const pg = bodies.page_iterator_symbol_prefix(64, true);
@@ -111,9 +115,15 @@ const STRIDE = WATER_PARTICLE_BODY_BOUNDS_STRIDE;
  * The frame's culling pass (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3.1), one thread a water body, before
  * anything simulates. Against the frustum of the view the frame is recorded for, with a prior bound on the body's
  * displacement, it decides whether the body is visible and whether it is simulated this frame, and lists it for the
- * passes that follow. On the way it does the per-body work that used to be passes of its own over every row: weights
- * when the wind or the fetch changed, the wind's turn for a body that is simulated, optics when they were edited.
- * A visible body ORs the bands it can draw into the frame's band mask.
+ * passes that follow. On the way it does the per-body work that used to be passes of its own over every row: the
+ * body's wind, weights when the wind left its deadband or the fetch changed, the wind's turn for a body that is
+ * simulated, optics when they were edited. A visible body ORs the bands it can draw into the frame's band mask.
+ *
+ * **The wind** (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, the Water row) is the scene's wind field,
+ * `wind_field_sample`, 10 m above the body's origin, low-passed per body on the frames
+ * that step and seeded from the first sample (`chunk_water_waves_derive`). Every body's is kept, hidden ones
+ * too, since their weights bound what they can reach. The pass reads the field as the frame's producer left it
+ * before it: a field published later in the same frame is read the frame after, which the low-pass does not see.
  */
 export const shader_water_cull = ComputeShader.from({ label: 'Water / cull', resources,
     body: CodeChunk.from(/* language=WGSL */ `
@@ -141,18 +151,33 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
     let scale = max(vec3<f32>(length(global[0].xyz), length(global[1].xyz), length(global[2].xyz)), vec3<f32>(1e-20));
     let box = geometries[${body('geometry')}].bounding_box;
 
-    // weights, when the wind or the fetch they were derived for changed; none without wind
-    let wind = ${read('wind')};
-    let direction = wind.xy / max(length(wind.xy), 1e-20);
-    let fetch = water_waves_fetch(box, scale, direction, ${read('upwind_fetch')});
+    // the body's wind: the field's at U10, low-passed over the frames that step; the first sample seeds it
+    let dt = select(0.0, cull.dt, cull.stepping != 0u);
+    let sample = wind_field_sample(global[3].xyz + vec3<f32>(0.0, ${WATER_WIND_REFERENCE_HEIGHT}.0, 0.0));
+    let seeded = ${read('wind_seeded')} != 0u;
+    let wind = water_wind_low_pass(${read('wind')}, seeded, sample, dt);
+    if (!seeded || dt > 0.0) { ${waves.marshalling_method_write_field('wind')}(&scene_database, row, wind); }
+    if (!seeded) { ${waves.marshalling_method_write_field('wind_seeded')}(&scene_database, row, 1u); }
+    let local = water_wind_local(wind, global, scale);
+    let speed = length(local);
+    var direction = vec2<f32>(0.0);
+    if (speed > 0.0) { direction = local / speed; }
+
+    // weights, when the wind left the deadband about the one they were derived for, or the fetch along its direction
+    // changed; none without wind
+    let reference = ${read('derived_for')};
+    let leaves = water_wind_speed_leaves(reference.x, speed) || (speed > 0.0 && water_wind_direction_leaves(reference.zw, direction));
+    let derived_speed = select(reference.x, speed, leaves);
+    let derived_direction = select(reference.zw, direction, leaves);
+    let fetch = water_waves_fetch(box, scale, derived_direction, ${read('upwind_fetch')});
     var weights: array<f32, WATER_SPECTRUM_BANDS>;
-    if (any(${read('derived_for')} != vec2<f32>(wind.z, fetch))) {
-        let derived = water_waves_derive(wind.z, fetch);
+    if (leaves || fetch != reference.y) {
+        let derived = water_waves_derive(derived_speed, fetch);
         weights = derived.weights;
         ${waves.marshalling_method_write_field('weights')}(&scene_database, row, weights);
         ${waves.marshalling_method_write_field('slope_variance')}(&scene_database, row, derived.slope_variance);
-        ${waves.marshalling_method_write_field('derived_for')}(&scene_database, row, vec2<f32>(wind.z, fetch));
-    } else if (wind.z > 0.0) {
+        ${waves.marshalling_method_write_field('derived_for')}(&scene_database, row, vec4<f32>(derived_speed, fetch, derived_direction));
+    } else if (derived_speed > 0.0) {
         weights = ${read('weights')};
     }
 
@@ -171,7 +196,7 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
             for (var j = 0u; j < queued; j++) { particles += WATER_RING_BOUND * clamp(impulses[j].z, 1e-3, 16.0); }
         }
         var ambient = vec2<f32>(0.0);
-        if (wind.z > 0.0) { ambient = water_cull_ambient(weights, ${read('wind_blend')}); }
+        if (derived_speed > 0.0) { ambient = water_cull_ambient(weights, ${read('wind_blend')}); }
         vertical = 2.0 * ambient.x + particles;
         horizontal = 2.0 * ambient.y + particles;
     }
@@ -183,7 +208,7 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
     let is_visible = aabb3_intersects_frustum(aabb3_project(array_to_aabb3(grown), global), camera.frustum);
     let is_active = is_visible || ${read('simulate_hidden')} != 0u;
 
-    if (is_visible && wind.z > 0.0) {
+    if (is_visible && derived_speed > 0.0) {
         // the bands this body can draw: waves longer than 8 of the finest cells it can be drawn with
         let rest = aabb3_project(array_to_aabb3(box), global);
         let eye = camera.view_matrix_inverse[3].xyz;
@@ -196,8 +221,7 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
         if (mask != 0u) { atomicOr(&band_requests.needed, mask); }
     }
     if (is_active) {
-        let turn = water_wind_turn(WaterWindTurn(${read('wind_from')}, ${read('wind_to')}, ${read('wind_blend')}),
-            direction, select(0.0, cull.dt, cull.stepping != 0u));
+        let turn = water_wind_turn(WaterWindTurn(${read('wind_from')}, ${read('wind_to')}, ${read('wind_blend')}), direction, dt);
         ${waves.marshalling_method_write_field('wind_from')}(&scene_database, row, turn.previous);
         ${waves.marshalling_method_write_field('wind_to')}(&scene_database, row, turn.current);
         ${waves.marshalling_method_write_field('wind_blend')}(&scene_database, row, turn.blend);
@@ -212,10 +236,10 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
     activity[row] = select(0u, ${WaterActivity.Visible}u, is_visible) | select(0u, ${WaterActivity.Active}u, is_active);
 }
 `, [bodies.chunk_iterate(64, true), bodies.chunk_write, bodies.chunk_read_rw,
-        ...['dirty', 'wave', 'node', 'geometry'].map(field => bodies.chunk_read_field(field, true)), ...['wind', 'upwind_fetch', 'weights', 'derived_for', 'wind_blend',
-        'impulses', 'impulse_count', 'simulate_hidden', 'wind_from', 'wind_to'].map(field => waves.chunk_read_field(field, true)),
-        ...['weights', 'slope_variance', 'derived_for', 'wind_from', 'wind_to', 'wind_blend'].map(field => waves.wgsl_gen_write_field_code(field)),
-        chunk_water_cull_bound, chunk_water_spectrum, chunk_water_waves_derive, chunk_water_lod, chunk_water_medium_derived,
+        ...['dirty', 'wave', 'node', 'geometry'].map(field => bodies.chunk_read_field(field, true)), ...['wind', 'wind_seeded', 'upwind_fetch', 'weights',
+        'derived_for', 'wind_blend', 'impulses', 'impulse_count', 'simulate_hidden', 'wind_from', 'wind_to'].map(field => waves.chunk_read_field(field, true)),
+        ...['wind', 'wind_seeded', 'weights', 'slope_variance', 'derived_for', 'wind_from', 'wind_to', 'wind_blend'].map(field => waves.wgsl_gen_write_field_code(field)),
+        chunk_wind_field_sample, chunk_water_cull_bound, chunk_water_spectrum, chunk_water_waves_derive, chunk_water_lod, chunk_water_medium_derived,
         chunk_water_medium_scattering, chunk_scene_database_access_rw, chunk_folded_workgroup_index, chunk_aabb3_project,
         chunk_array_to_aabb3, chunk_aabb3_intersects_frustum, chunk_mat4_linear_determinant]) });
 

package/src/shade/renderer/water/surface/shader_water_waves_derive.d.ts

@@ -1,8 +1,33 @@
 /** Seconds a change of wind direction takes to turn the waves. */
 export const WATER_WIND_TURN_SECONDS: 4;
+/**
+ * Metres above a body's origin its wind is sampled at: the 10 m wind, U10, which is what the JONSWAP growth laws
+ * are stated for.
+ */
+export const WATER_WIND_REFERENCE_HEIGHT: 10;
+/**
+ * The time constant of a body's low-pass of its wind sample, seconds: waves answer the wind over minutes, so gusts
+ * and eddies do not reach them, while a change of the weather does within a minute.
+ */
+export const WATER_WIND_LOW_PASS_SECONDS: 20;
+/**
+ * Fraction of the wind speed the weights were derived for that the low-passed speed must move by before they are
+ * derived again.
+ */
+export const WATER_WIND_SPEED_DEADBAND: 0.05;
+/** Degrees the low-passed wind must turn from the direction a derivation or a turn was made for to make another. */
+export const WATER_WIND_DIRECTION_DEADBAND_DEGREES: 3;
 /**
  * A body's ambient waves from its wind and its fetch, as weights on the shared spectral bands
- * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2).
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2), and the wind they follow
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, the Water row).
+ *
+ * **The wind.** One sample of the scene's wind field {@link WATER_WIND_REFERENCE_HEIGHT} m above the body's origin,
+ * low-passed per body with a time constant of {@link WATER_WIND_LOW_PASS_SECONDS} s and seeded from the first sample,
+ * feeds the fetch, the derivation and the turn. Neither fires on every wobble of it: a derivation is made again only
+ * when the low-passed wind leaves a deadband of {@link WATER_WIND_SPEED_DEADBAND} of the speed, or
+ * {@link WATER_WIND_DIRECTION_DEADBAND_DEGREES}° of the direction, it was made for; a turn starts only when the
+ * direction leaves the same angle of the one the waves turned to.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/water/surface/shader_water_waves_derive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_water_waves_derive.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_waves_derive.js"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,wCAAyC;AAEzC;;;;;GAKG;AACH,uCAFU,SAAS,CAmEO;0BA7EA,oCAAoC"}
+{"version":3,"file":"shader_water_waves_derive.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/shader_water_waves_derive.js"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,wCAAyC;AAEzC;;;GAGG;AACH,6CAA8C;AAE9C;;;GAGG;AACH,6CAA8C;AAE9C;;;GAGG;AACH,6CAA8C;AAE9C,oHAAoH;AACpH,sDAAuD;AAEvD;;;;;;;;;;;;;GAaG;AACH,uCAFU,SAAS,CAsGO;0BA7IA,oCAAoC"}

package/src/shade/renderer/water/surface/shader_water_waves_derive.js

@@ -4,13 +4,47 @@ import { chunk_water_jonswap } from "./spectrum/chunk_water_jonswap.js";
 /** Seconds a change of wind direction takes to turn the waves. */
 export const WATER_WIND_TURN_SECONDS = 4;
 
+/**
+ * Metres above a body's origin its wind is sampled at: the 10 m wind, U10, which is what the JONSWAP growth laws
+ * are stated for.
+ */
+export const WATER_WIND_REFERENCE_HEIGHT = 10;
+
+/**
+ * The time constant of a body's low-pass of its wind sample, seconds: waves answer the wind over minutes, so gusts
+ * and eddies do not reach them, while a change of the weather does within a minute.
+ */
+export const WATER_WIND_LOW_PASS_SECONDS = 20;
+
+/**
+ * Fraction of the wind speed the weights were derived for that the low-passed speed must move by before they are
+ * derived again.
+ */
+export const WATER_WIND_SPEED_DEADBAND = 0.05;
+
+/** Degrees the low-passed wind must turn from the direction a derivation or a turn was made for to make another. */
+export const WATER_WIND_DIRECTION_DEADBAND_DEGREES = 3;
+
 /**
  * A body's ambient waves from its wind and its fetch, as weights on the shared spectral bands
- * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2).
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §4.2), and the wind they follow
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, the Water row).
+ *
+ * **The wind.** One sample of the scene's wind field {@link WATER_WIND_REFERENCE_HEIGHT} m above the body's origin,
+ * low-passed per body with a time constant of {@link WATER_WIND_LOW_PASS_SECONDS} s and seeded from the first sample,
+ * feeds the fetch, the derivation and the turn. Neither fires on every wobble of it: a derivation is made again only
+ * when the low-passed wind leaves a deadband of {@link WATER_WIND_SPEED_DEADBAND} of the speed, or
+ * {@link WATER_WIND_DIRECTION_DEADBAND_DEGREES}° of the direction, it was made for; a turn starts only when the
+ * direction leaves the same angle of the one the waves turned to.
  *
  * @type {CodeChunk}
  */
 export const chunk_water_waves_derive = CodeChunk.from(/* language=WGSL */ `
+const WATER_WIND_LOW_PASS_SECONDS: f32 = ${WATER_WIND_LOW_PASS_SECONDS}.0;
+const WATER_WIND_SPEED_DEADBAND: f32 = ${WATER_WIND_SPEED_DEADBAND};
+// the cosine of WATER_WIND_DIRECTION_DEADBAND_DEGREES
+const WATER_WIND_DIRECTION_DEADBAND_COSINE: f32 = ${Math.cos(WATER_WIND_DIRECTION_DEADBAND_DEGREES * Math.PI / 180)};
+
 // How far the wind crosses the body along a unit direction of its metric local xz: the chord through the
 // centre of the ellipse inscribed in its box, so a square does not gain fetch at 45° and a long narrow lake
 // is long only along its length, plus the authored open water beyond it.
@@ -54,22 +88,52 @@ fn water_waves_derive(wind_speed: f32, fetch: f32) -> WaterWavesDerived {
     return derived;
 }
 
+// The body's wind after dt more seconds of its sample: the sample itself the first time (seeded), then an
+// exponential low-pass, exact for a sample held over the step. Written so that a wind equal to its sample stays
+// exactly that.
+fn water_wind_low_pass(last: vec3<f32>, seeded: bool, sample: vec3<f32>, dt: f32) -> vec3<f32> {
+    if (!seeded) { return sample; }
+    return sample + (last - sample) * exp(-max(dt, 0.0) / WATER_WIND_LOW_PASS_SECONDS);
+}
+
+// A world wind in the body's metric local xz: along the unit local x and z axes of its node's matrix, whatever
+// its scale.
+fn water_wind_local(wind: vec3<f32>, global: mat4x4<f32>, scale: vec3<f32>) -> vec2<f32> {
+    return vec2<f32>(dot(wind, global[0].xyz) / scale.x, dot(wind, global[2].xyz) / scale.z);
+}
+
+// Whether a wind speed has left the deadband about the one the weights were derived for. A row never derived for
+// (a negative speed) has left it whatever the wind; a calm row derived for calm has not.
+fn water_wind_speed_leaves(reference: f32, speed: f32) -> bool {
+    return abs(speed - reference) > WATER_WIND_SPEED_DEADBAND * reference;
+}
+
+// Whether a unit direction has left the deadband about a reference direction; every direction has left a zero one.
+fn water_wind_direction_leaves(reference: vec2<f32>, direction: vec2<f32>) -> bool {
+    return dot(reference, direction) < WATER_WIND_DIRECTION_DEADBAND_COSINE;
+}
+
 struct WaterWindTurn {
     previous: vec2<f32>,
     current: vec2<f32>,
     blend: f32,
 }
 
-// Follow the authored direction: a change starts a turn from the direction the waves show, which then advances
-// by dt / ${WATER_WIND_TURN_SECONDS} s. A change during a turn waits for it to finish, so a wind that keeps turning
-// is followed one turn behind, and an orientation only ever leaves the waves at no weight. A row seen for the
-// first time starts settled.
-fn water_wind_turn(last: WaterWindTurn, authored: vec2<f32>, dt: f32) -> WaterWindTurn {
+// Follow the wind's direction, 0 in calm: once the waves have turned, a direction that leaves the deadband about
+// the one they turned to starts a turn from it, which then advances by dt / ${WATER_WIND_TURN_SECONDS} s. A change
+// during a turn waits for it to finish, so a wind that keeps turning is followed one turn behind, and an
+// orientation only ever leaves the waves at no weight. A calm wind starts nothing. A row seen for the first time
+// starts settled at the first wind it has.
+fn water_wind_turn(last: WaterWindTurn, direction: vec2<f32>, dt: f32) -> WaterWindTurn {
     var turn = last;
-    if (all(turn.current == vec2<f32>(0.0))) { return WaterWindTurn(authored, authored, 1.0); }
-    if (turn.blend >= 1.0 && dot(turn.current, authored) < 0.99999) {
+    let calm = all(direction == vec2<f32>(0.0));
+    if (all(turn.current == vec2<f32>(0.0))) {
+        if (calm) { return turn; }
+        return WaterWindTurn(direction, direction, 1.0);
+    }
+    if (turn.blend >= 1.0 && !calm && water_wind_direction_leaves(turn.current, direction)) {
         turn.previous = turn.current;
-        turn.current = authored;
+        turn.current = direction;
         turn.blend = 0.0;
     }
     turn.blend = min(turn.blend + max(dt, 0.0) / ${WATER_WIND_TURN_SECONDS}.0, 1.0);

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

@@ -0,0 +1,127 @@
+/**
+ * A scene's published wind field (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §5, §11): what every GPU
+ * consumer samples the wind from, through `chunk_wind_field_sample`, and what the CPU read API
+ * gathers from.
+ *
+ * `GPUSceneContext` always makes one, with no cascades and a far field of 0, so a consumer binds it
+ * unconditionally and reads still air when nothing produces wind. A producer — the GPU fluid — fills
+ * it.
+ *
+ * **What it holds:**
+ * - {@link atlas}: a {@link GPUTileAtlas3D} of `rgba16float` tiles, one per cascade, each the
+ *   cascade's resolution of content with a one-texel skirt. A producer writes a cascade's tile at
+ *   {@link slot}, from the device; nothing here writes texels;
+ * - {@link uniform}: the table a reader takes, {@link WIND_FIELD_STRUCT}: every cascade's window and
+ *   read record, finest first, and `v_far(t)`.
+ *
+ * **The producer's frame**, before any consumer encodes (at `FrameStart`, ahead of the scene's own
+ * update):
+ *
+ *     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)
+ *
+ * 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.
+ *
+ * **A cascade reads as the far field until it has a record.** One that {@link set_cascades} adds
+ * starts with a decay of 0, so whatever its tile holds — a freed slot's old texels, or nothing yet —
+ * contributes nothing until the producer gives it a decay; a cascade created at the far field (as the
+ * fluid creates them) is that exactly.
+ *
+ * **The atlas grows with the count and never shrinks**: more cascades allocate slots, which add
+ * layers to the texture (or widen it, past `maxTextureDimension3D`); fewer free them and keep the
+ * texture. A new resolution is a new atlas. Either replaces the texture, so a consumer takes it per
+ * frame ({@link bind}), as the frame graph does.
+ */
+export class GPUSceneWind {
+    /**
+     * @param {GPUDevice} device
+     * @param {ArrayLike<number>} content
+     * @param {number} capacity
+     * @returns {GPUTileAtlas3D}
+     */
+    static "__#172@#make_atlas"(device: GPUDevice, content: ArrayLike<number>, capacity: number): GPUTileAtlas3D;
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * One tile per cascade, at {@link slot}. Replaced by a new resolution, and its texture by a grow.
+     * @returns {GPUTileAtlas3D}
+     */
+    get atlas(): GPUTileAtlas3D;
+    /**
+     * The table, {@link WIND_FIELD_STRUCT}, as the uniform `wind_field`.
+     * @returns {GPUBuffer}
+     */
+    get uniform(): GPUBuffer;
+    /**
+     * @returns {number}
+     */
+    get cascade_count(): number;
+    /**
+     * The atlas slot of a cascade's tile.
+     *
+     * @param {number} index a cascade, finest first
+     * @returns {number}
+     */
+    slot(index: number): number;
+    /**
+     * The stack's shape: how many cascades, and the cells of each one's window, which is its tile's
+     * content. Cascades past `count` are dropped and their slots freed; cascades it adds start with
+     * a decay of 0 and no window, and the producer sets both before the table is next uploaded.
+     *
+     * With cascades, a resolution other than the atlas's makes a new atlas, every cascade a new tile.
+     *
+     * @param {number} count 0 to {@link WIND_FIELD_CASCADE_LIMIT}
+     * @param {ArrayLike<number>} resolution cells along x, y and z of every cascade's window
+     */
+    set_cascades(count: number, resolution: ArrayLike<number>): void;
+    /**
+     * Where a cascade's window is: window-local cell 0 is world cell `corner`, of `cell_size` metres,
+     * so the window spans `[corner, corner + resolution) · cell_size` in the world. A cascade's window
+     * lies inside its parent's.
+     *
+     * @param {number} index a cascade, finest first
+     * @param {ArrayLike<number>} corner integers, in the cascade's cells
+     * @param {number} cell_size metres, positive
+     */
+    set_cascade_window(index: number, corner: ArrayLike<number>, cell_size: number): void;
+    /**
+     * A cascade's read record: `k_c = e^(−(Λ(t) − Λ(t_s,c)))`, what remains now of the deviation its
+     * last step published. A reader takes `v_far(t) + tap · k_c`, which is the atmosphere identity
+     * `v_far(t) + (v − v_far(t_s,c)) · k_c` because the tile holds `v − v_far(t_s,c)`.
+     *
+     * @param {number} index a cascade, finest first
+     * @param {number} decay in [0, 1]
+     */
+    set_cascade_decay(index: number, decay: number): void;
+    /**
+     * `v_far(t)`: the wind wherever no cascade holds, now.
+     *
+     * @param {ArrayLike<number>} velocity m/s, x, y, z
+     */
+    set_far_velocity(velocity: ArrayLike<number>): void;
+    /**
+     * Upload the table when anything changed since the last upload; once a frame, after the producer
+     * and before any consumer encodes. The tiles' texel origins and the atlas's size are taken here,
+     * after every slot the frame allocated.
+     */
+    update(): 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.
+     *
+     * @param {Object} bindings
+     */
+    bind(bindings: any): void;
+    /**
+     * Release the atlas and the table. Safe to call twice.
+     */
+    destroy(): void;
+    #private;
+}
+import { GPUTileAtlas3D } from "../texture/atlas/GPUTileAtlas3D.js";
+//# sourceMappingURL=GPUSceneWind.d.ts.map

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

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