@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/publish/chunk_fluid_wind_publish_cell.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a cascade publishes into the wind field at one cell (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md
+ * §11): `fluid_wind_publish_cell(cell, far_velocity)`, the velocity at window-local cell `cell`'s
+ * centre — on each axis the mean of the cell's two faces — less the far field the step ran under,
+ * `v_far(t_s,c)`, m/s.
+ *
+ * The deviation, not the velocity, is what a tile holds, and the read adds the far field back
+ * through the atmosphere identity (`chunk_wind_field_sample`): `v_far(t) + (v − v_far(t_s,c))·k_c` is
+ * the same sum whichever side of the tile the subtraction sits, since a trilinear tap's weights sum
+ * to one. Taken here, in f32, before the half-float store, it makes the store's rounding scale with
+ * the deviation instead of the wind, and air at the far field stores exactly 0.
+ *
+ * The faces come through `fluid_wind_publish_face_u(face)`, `_v` and `_w`, which the host defines:
+ * the step's end velocity at a window-local face, and beyond the window whatever the cascade's
+ * boundary holds there. A cell of the tile's skirt reaches one face past the window; the standalone
+ * publish answers it through the MAC seams (`chunk_fluid_mac_seam_source`), and a publish fused into
+ * the gradient pass (proposal §8 (3)) from its tile in workgroup memory — a change of host, not of
+ * this.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_wind_publish_cell: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_wind_publish_cell.d.ts.map

package/src/shade/renderer/fluid/publish/chunk_fluid_wind_publish_cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_fluid_wind_publish_cell.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/publish/chunk_fluid_wind_publish_cell.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4CAFU,SAAS,CAejB;0BApCwB,oCAAoC"}

package/src/shade/renderer/fluid/publish/chunk_fluid_wind_publish_cell.js

@@ -0,0 +1,37 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * What a cascade publishes into the wind field at one cell (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md
+ * §11): `fluid_wind_publish_cell(cell, far_velocity)`, the velocity at window-local cell `cell`'s
+ * centre — on each axis the mean of the cell's two faces — less the far field the step ran under,
+ * `v_far(t_s,c)`, m/s.
+ *
+ * The deviation, not the velocity, is what a tile holds, and the read adds the far field back
+ * through the atmosphere identity (`chunk_wind_field_sample`): `v_far(t) + (v − v_far(t_s,c))·k_c` is
+ * the same sum whichever side of the tile the subtraction sits, since a trilinear tap's weights sum
+ * to one. Taken here, in f32, before the half-float store, it makes the store's rounding scale with
+ * the deviation instead of the wind, and air at the far field stores exactly 0.
+ *
+ * The faces come through `fluid_wind_publish_face_u(face)`, `_v` and `_w`, which the host defines:
+ * the step's end velocity at a window-local face, and beyond the window whatever the cascade's
+ * boundary holds there. A cell of the tile's skirt reaches one face past the window; the standalone
+ * publish answers it through the MAC seams (`chunk_fluid_mac_seam_source`), and a publish fused into
+ * the gradient pass (proposal §8 (3)) from its tile in workgroup memory — a change of host, not of
+ * this.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_wind_publish_cell = CodeChunk.from(
+    //language=WGSL
+    `
+fn fluid_wind_publish_cell(cell: vec3<i32>, far_velocity: vec3<f32>) -> vec3<f32> {
+    let faces = vec3<f32>(
+        fluid_wind_publish_face_u(cell) + fluid_wind_publish_face_u(cell + vec3<i32>(1, 0, 0)),
+        fluid_wind_publish_face_v(cell) + fluid_wind_publish_face_v(cell + vec3<i32>(0, 1, 0)),
+        fluid_wind_publish_face_w(cell) + fluid_wind_publish_face_w(cell + vec3<i32>(0, 0, 1)),
+    );
+
+    return 0.5 * faces - far_velocity;
+}
+`
+);

package/src/shade/renderer/fluid/publish/shader_fluid_wind_publish.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Invocations along each axis of a workgroup: one per texel of the tile, whose sides are N + 2.
+ * @type {number[]}
+ */
+export const FLUID_WIND_PUBLISH_GROUP_SIZE: number[];
+/**
+ * A cascade's publish into the wind field (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §11, the publish
+ * half of pass 6): every texel of its atlas tile, the window's cells and the one-texel skirt around
+ * them, gets `chunk_fluid_wind_publish_cell` — the velocity at that cell's centre less the step's far
+ * field — as `rgba16float`, alpha 0.
+ *
+ * The skirt is the cells one past the window. Each takes the window's faces where it has them (along
+ * an axis, the boundary face plane) and, for the rest, what the MAC seams answer beyond the window:
+ * the parent's identity read as of the cascade's read record (`chunk_fluid_cascade_parent_velocity`),
+ * which for the coarsest is the far field. Beside the far field, a skirt cell beside a face of the
+ * window takes half that boundary face's deviation on the face's axis and none on the others, and one
+ * past an edge or a corner none at all.
+ *
+ * It writes its own tile and never samples the atlas: the atlas is bound as a write-only storage
+ * texture and nothing else.
+ *
+ * One invocation a texel, in 4 × 4 × 4 workgroups over the tile, dispatched
+ * `ceil((N + 2) / 4)` on each axis; each reads its cell's six faces (`textureLoad`) and stores one
+ * texel. Standalone until it is fused into the gradient pass (proposal §8 (3)), where the faces are in
+ * workgroup memory already.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT}: the cascade's windows and `far_velocity`, `v_far(t_s,c)`;
+ *   `cells.size` is the window, and the tile's content;
+ * - `publish`: {@link FLUID_WIND_PUBLISH_STRUCT}: the tile's texel origin in the atlas;
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, and `parent_u`, `parent_v`, `parent_w` the parent's
+ *   persistent faces, read for the skirt;
+ * - `source_u`, `source_v`, `source_w`: the cascade's persistent velocity after its step, `r32float`
+ *   3-D textures, toroidal through `step.faces_*`;
+ * - `tile`: written, the atlas, `rgba16float` 3-D storage texture.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_wind_publish: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_wind_publish.d.ts.map

package/src/shade/renderer/fluid/publish/shader_fluid_wind_publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_wind_publish.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/publish/shader_fluid_wind_publish.js"],"names":[],"mappings":"AAWA;;;GAGG;AACH,4CAFU,MAAM,EAAE,CAEoD;AAqEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wCAFU,aAAa,CAMpB;8BAzH2B,+BAA+B"}

package/src/shade/renderer/fluid/publish/shader_fluid_wind_publish.js

@@ -0,0 +1,122 @@
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WIND_FIELD_TILE_BORDER, WIND_FIELD_TILE_FORMAT } from "../../wind/WIND_FIELD.js";
+import { chunk_grid_tile_window } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { chunk_fluid_cascade_parent_velocity } from "../coupling/chunk_fluid_cascade_parent.js";
+import { FLUID_MAC_STEP_STRUCT } from "../mac/FLUID_MAC_STEP_STRUCT.js";
+import { FLUID_CASCADE_PARENT_STRUCT } from "../coupling/FLUID_CASCADE_PARENT_STRUCT.js";
+import { chunk_fluid_wind_publish_cell } from "./chunk_fluid_wind_publish_cell.js";
+import { FLUID_WIND_PUBLISH_STRUCT } from "./FLUID_WIND_PUBLISH_STRUCT.js";
+
+/**
+ * Invocations along each axis of a workgroup: one per texel of the tile, whose sides are N + 2.
+ * @type {number[]}
+ */
+export const FLUID_WIND_PUBLISH_GROUP_SIZE = Object.freeze([4, 4, 4]);
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("step", FLUID_MAC_STEP_STRUCT)
+    .addUniform("publish", FLUID_WIND_PUBLISH_STRUCT)
+    .addUniform("parent", FLUID_CASCADE_PARENT_STRUCT)
+    .addTexture("source_u", "unfilterable-float", "3d")
+    .addTexture("source_v", "unfilterable-float", "3d")
+    .addTexture("source_w", "unfilterable-float", "3d")
+    .addTexture("parent_u", "unfilterable-float", "3d")
+    .addTexture("parent_v", "unfilterable-float", "3d")
+    .addTexture("parent_w", "unfilterable-float", "3d")
+    .addStorageTexture("tile", WIND_FIELD_TILE_FORMAT, "3d", "write-only");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_WIND_PUBLISH_BORDER: u32 = ${WIND_FIELD_TILE_BORDER}u;
+
+// the step's end velocity, the persistent set, through its toroidal windows; beyond the window, the
+// cascade's boundary: its parent's identity read as of its record, as its seams read it (the skirt is
+// one face deep, so the read itself, not a step's ghosts)
+fn fluid_wind_publish_face_u(face: vec3<i32>) -> f32 {
+    if (grid_tile_window_contains(face, step.faces_u.size)) {
+        return textureLoad(source_u, grid_tile_window_storage(face, step.faces_u.corner_storage, step.faces_u.period), 0).r;
+    }
+
+    return fluid_parent_face_u(face, step.cells.corner - parent.origin);
+}
+
+fn fluid_wind_publish_face_v(face: vec3<i32>) -> f32 {
+    if (grid_tile_window_contains(face, step.faces_v.size)) {
+        return textureLoad(source_v, grid_tile_window_storage(face, step.faces_v.corner_storage, step.faces_v.period), 0).r;
+    }
+
+    return fluid_parent_face_v(face, step.cells.corner - parent.origin);
+}
+
+fn fluid_wind_publish_face_w(face: vec3<i32>) -> f32 {
+    if (grid_tile_window_contains(face, step.faces_w.size)) {
+        return textureLoad(source_w, grid_tile_window_storage(face, step.faces_w.corner_storage, step.faces_w.period), 0).r;
+    }
+
+    return fluid_parent_face_w(face, step.cells.corner - parent.origin);
+}
+
+@compute @workgroup_size(${FLUID_WIND_PUBLISH_GROUP_SIZE.join(', ')})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    // the window's cells and a skirt on every side
+    let tile_size = step.cells.size + vec3<u32>(2u * FLUID_WIND_PUBLISH_BORDER);
+
+    if (any(id >= tile_size)) {
+        return;
+    }
+
+    // tile texel t holds window-local cell t - border
+    let cell = vec3<i32>(id) - vec3<i32>(i32(FLUID_WIND_PUBLISH_BORDER));
+
+    textureStore(tile, publish.tile_origin + id, vec4<f32>(fluid_wind_publish_cell(cell, step.far_velocity), 0.0));
+}
+`, [
+        chunk_grid_tile_window,
+        chunk_fluid_cascade_parent_velocity,
+        chunk_fluid_wind_publish_cell,
+    ]
+);
+
+/**
+ * A cascade's publish into the wind field (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §11, the publish
+ * half of pass 6): every texel of its atlas tile, the window's cells and the one-texel skirt around
+ * them, gets `chunk_fluid_wind_publish_cell` — the velocity at that cell's centre less the step's far
+ * field — as `rgba16float`, alpha 0.
+ *
+ * The skirt is the cells one past the window. Each takes the window's faces where it has them (along
+ * an axis, the boundary face plane) and, for the rest, what the MAC seams answer beyond the window:
+ * the parent's identity read as of the cascade's read record (`chunk_fluid_cascade_parent_velocity`),
+ * which for the coarsest is the far field. Beside the far field, a skirt cell beside a face of the
+ * window takes half that boundary face's deviation on the face's axis and none on the others, and one
+ * past an edge or a corner none at all.
+ *
+ * It writes its own tile and never samples the atlas: the atlas is bound as a write-only storage
+ * texture and nothing else.
+ *
+ * One invocation a texel, in 4 × 4 × 4 workgroups over the tile, dispatched
+ * `ceil((N + 2) / 4)` on each axis; each reads its cell's six faces (`textureLoad`) and stores one
+ * texel. Standalone until it is fused into the gradient pass (proposal §8 (3)), where the faces are in
+ * workgroup memory already.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT}: the cascade's windows and `far_velocity`, `v_far(t_s,c)`;
+ *   `cells.size` is the window, and the tile's content;
+ * - `publish`: {@link FLUID_WIND_PUBLISH_STRUCT}: the tile's texel origin in the atlas;
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, and `parent_u`, `parent_v`, `parent_w` the parent's
+ *   persistent faces, read for the skirt;
+ * - `source_u`, `source_v`, `source_w`: the cascade's persistent velocity after its step, `r32float`
+ *   3-D textures, toroidal through `step.faces_*`;
+ * - `tile`: written, the atlas, `rgba16float` 3-D storage texture.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_wind_publish = ComputeShader.from({
+    label: "Fluid / wind publish",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/query/FLUID_QUERY_DATABASE_SPEC.d.ts

@@ -0,0 +1,66 @@
+/**
+ * One request of the GPU fluid's read API (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §12): a box and
+ * how many samples its lattice takes along each axis, and where the lattice's run of samples starts.
+ *
+ * Lattice point `(x, y, z)`, `x < count_x` and so on, lies at `mix(low, high, (x, y, z) / (count − 1))`
+ * per axis; an axis of one sample lies at `low`. Its sample is row `first_sample + x + count_x·(y +
+ * count_y·z)` of the sample table.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_QUERY_STRUCT: WebGPUStruct;
+/**
+ * One lattice sample: the wind there, m/s, `(x, y, z, 0)`. Written by the gather and read back
+ * whole, so a lattice lands as four floats a sample.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_QUERY_SAMPLE_STRUCT: WebGPUStruct;
+/** Name of the request table within {@link FLUID_QUERY_DATABASE_SPEC}. */
+export const FLUID_QUERY_TABLE: "fluid_query";
+/** Name of the sample table within {@link FLUID_QUERY_DATABASE_SPEC}. */
+export const FLUID_QUERY_SAMPLE_TABLE: "fluid_query_sample";
+/**
+ * A lattice is tens to thousands of samples and a frame asks for a few lattices, so a 16 KB page
+ * (1,015 samples or 340 requests) holds a frame's worth, and the tables grow a page at a time past
+ * it.
+ *
+ * @type {number}
+ */
+export const FLUID_QUERY_DATABASE_PAGE_SIZE: number;
+/**
+ * The page address table (two tables of `GPU_DATABASE_PAGE_LIMIT` u32 slots, 32 KB) and a page of
+ * each table, before the database grows itself.
+ *
+ * @type {number}
+ */
+export const FLUID_QUERY_DATABASE_INITIAL_SIZE: number;
+/**
+ * # The GPU fluid read API's database
+ *
+ * GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10, §12: the rows a request of the read API is, while
+ * it is in flight.
+ *
+ * | Table | Row | Lifecycle |
+ * |---|---|---|
+ * | `fluid_query` | one {@link FLUID_QUERY_STRUCT} per request: its box and lattice | added when the request is recorded; freed after its lattice is delivered or dropped |
+ * | `fluid_query_sample` | one {@link FLUID_QUERY_SAMPLE_STRUCT} per lattice sample, a run per request (`add_run_filled`) | written by the gather, read back as one run (`GPUDatabaseReadback#request_run`), freed with its request |
+ *
+ * A database of its own rather than tables in the forcing's (`FLUID_DATABASE_SPEC`): a request is
+ * answered with no `GPUFluidComponent` in the scene (the published field is then the far field
+ * alone), and the forcing and its database exist only while a domain does.
+ *
+ * @type {GPUDatabaseDefinition}
+ */
+export const FLUID_QUERY_DATABASE_SPEC: GPUDatabaseDefinition;
+/**
+ * @type {import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor}
+ */
+export const FLUID_QUERY_DESCRIPTOR: import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor;
+/**
+ * @type {import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor}
+ */
+export const FLUID_QUERY_SAMPLE_DESCRIPTOR: import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+//# sourceMappingURL=FLUID_QUERY_DATABASE_SPEC.d.ts.map

package/src/shade/renderer/fluid/query/FLUID_QUERY_DATABASE_SPEC.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_QUERY_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/query/FLUID_QUERY_DATABASE_SPEC.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,iCAFU,YAAY,CASL;AAEjB;;;;;GAKG;AACH,wCAFU,YAAY,CAIC;AAEvB,0EAA0E;AAC1E,8CAA+C;AAE/C,yEAAyE;AACzE,4DAA6D;AAE7D;;;;;;GAMG;AACH,6CAFU,MAAM,CAE4C;AAE5D;;;;;GAKG;AACH,gDAFU,MAAM,CAE+C;AAE/D;;;;;;;;;;;;;;;;GAgBG;AACH,wCAFU,qBAAqB,CAKI;AAEnC;;GAEG;AACH,qCAFU,OAAO,+CAA+C,EAAE,uBAAuB,CAEF;AAEvF;;GAEG;AACH,4CAFU,OAAO,+CAA+C,EAAE,uBAAuB,CAEY;6BApFxE,mCAAmC;sCAF1B,6CAA6C"}

package/src/shade/renderer/fluid/query/FLUID_QUERY_DATABASE_SPEC.js

@@ -0,0 +1,88 @@
+import { KILOBYTE } from "../../../../core/science/units/memory/KILOBYTE.js";
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+import { u32, vec3f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * One request of the GPU fluid's read API (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §12): a box and
+ * how many samples its lattice takes along each axis, and where the lattice's run of samples starts.
+ *
+ * Lattice point `(x, y, z)`, `x < count_x` and so on, lies at `mix(low, high, (x, y, z) / (count − 1))`
+ * per axis; an axis of one sample lies at `low`. Its sample is row `first_sample + x + count_x·(y +
+ * count_y·z)` of the sample table.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_QUERY_STRUCT = WebGPUStruct.from({
+    low: vec3f,
+    first_sample: u32,
+    high: vec3f,
+    count_x: u32,
+    count_y: u32,
+    count_z: u32,
+}, 'FluidQuery');
+
+/**
+ * One lattice sample: the wind there, m/s, `(x, y, z, 0)`. Written by the gather and read back
+ * whole, so a lattice lands as four floats a sample.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_QUERY_SAMPLE_STRUCT = WebGPUStruct.from({
+    velocity: vec4f,
+}, 'FluidQuerySample');
+
+/** Name of the request table within {@link FLUID_QUERY_DATABASE_SPEC}. */
+export const FLUID_QUERY_TABLE = "fluid_query";
+
+/** Name of the sample table within {@link FLUID_QUERY_DATABASE_SPEC}. */
+export const FLUID_QUERY_SAMPLE_TABLE = "fluid_query_sample";
+
+/**
+ * A lattice is tens to thousands of samples and a frame asks for a few lattices, so a 16 KB page
+ * (1,015 samples or 340 requests) holds a frame's worth, and the tables grow a page at a time past
+ * it.
+ *
+ * @type {number}
+ */
+export const FLUID_QUERY_DATABASE_PAGE_SIZE = 16 * KILOBYTE;
+
+/**
+ * The page address table (two tables of `GPU_DATABASE_PAGE_LIMIT` u32 slots, 32 KB) and a page of
+ * each table, before the database grows itself.
+ *
+ * @type {number}
+ */
+export const FLUID_QUERY_DATABASE_INITIAL_SIZE = 64 * KILOBYTE;
+
+/**
+ * # The GPU fluid read API's database
+ *
+ * GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §10, §12: the rows a request of the read API is, while
+ * it is in flight.
+ *
+ * | Table | Row | Lifecycle |
+ * |---|---|---|
+ * | `fluid_query` | one {@link FLUID_QUERY_STRUCT} per request: its box and lattice | added when the request is recorded; freed after its lattice is delivered or dropped |
+ * | `fluid_query_sample` | one {@link FLUID_QUERY_SAMPLE_STRUCT} per lattice sample, a run per request (`add_run_filled`) | written by the gather, read back as one run (`GPUDatabaseReadback#request_run`), freed with its request |
+ *
+ * A database of its own rather than tables in the forcing's (`FLUID_DATABASE_SPEC`): a request is
+ * answered with no `GPUFluidComponent` in the scene (the published field is then the far field
+ * alone), and the forcing and its database exist only while a domain does.
+ *
+ * @type {GPUDatabaseDefinition}
+ */
+export const FLUID_QUERY_DATABASE_SPEC = GPUDatabaseDefinition.from({
+    [FLUID_QUERY_TABLE]: FLUID_QUERY_STRUCT,
+    [FLUID_QUERY_SAMPLE_TABLE]: FLUID_QUERY_SAMPLE_STRUCT,
+}, FLUID_QUERY_DATABASE_PAGE_SIZE);
+
+/**
+ * @type {import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor}
+ */
+export const FLUID_QUERY_DESCRIPTOR = FLUID_QUERY_DATABASE_SPEC.get(FLUID_QUERY_TABLE);
+
+/**
+ * @type {import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor}
+ */
+export const FLUID_QUERY_SAMPLE_DESCRIPTOR = FLUID_QUERY_DATABASE_SPEC.get(FLUID_QUERY_SAMPLE_TABLE);

package/src/shade/renderer/fluid/query/GPUFluidQueries.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../wind/GPUSceneWind.js").GPUSceneWind} GPUSceneWind
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+/**
+ * Floats a lattice sample lands as in a request's target: the wind's `x, y, z`, then 0.
+ * @type {number}
+ */
+export const FLUID_QUERY_SAMPLE_FLOATS: number;
+/**
+ * # The GPU fluid read API, on the device
+ *
+ * GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §12: lattices of the published wind field, read back to
+ * the CPU. The device half of `GPUFluidSystem#request`; the system keeps the handles and statuses
+ * its callers read, and hands each request in here tagged with its handle.
+ *
+ * ## A frame
+ *
+ *     request(box, counts, target, target_offset, tag)   ×n, at FrameStart, before
+ *     record({ graph, wind })                            the frame's requests become rows and a pass
+ *     ...
+ *     apply()                                            at the system's apply point, once a frame:
+ *     settled_tag(i), settled_status(i)                    what settled, for i < settled_count
+ *
+ * - **Rows.** {@link record} makes each request a `fluid_query` row and a run of `fluid_query_sample`
+ *   rows, one a lattice point ({@link FLUID_QUERY_DATABASE_SPEC}), and asks the readback for the run
+ *   (`GPUDatabaseReadback#request_run`, all or nothing).
+ * - **The pass**, recorded after the frame's publish of the wind field: the database's upload, then
+ *   the gather (`shader_fluid_query_gather`), which evaluates `wind_field_sample` at every lattice
+ *   point into the runs, then `readback.encode` — right after the gather, in the same pass.
+ * - **Delivery** is the readback's: in order, a batch a frame, at most `max_in_flight` (4) batches
+ *   in flight, a frame's requests past it dropped with a status. A delivered lattice is copied into
+ *   its target at {@link apply}; a delivered or dropped request's rows are freed there.
+ *
+ * Nothing is allocated per request at steady state: requests and their rows are integer stores into
+ * retained arrays and tables, a frame's lattices share one pooled staging array, and the pass reuses
+ * its record and bindings.
+ */
+export class GPUFluidQueries {
+    /**
+     * Offer the pipelines the read API dispatches — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry: PipelineEnquiry): void;
+    /**
+     * @param {object} pass
+     * @param {import("../../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources} resources
+     * @param {{encoder: import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext}} context
+     */
+    static "__#267@#execute"(pass: object, resources: import("../../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources, context: {
+        encoder: import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+    }): void;
+    /**
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     */
+    constructor({ device }: {
+        device: GPUDevice;
+    });
+    /**
+     * The read API's database. For inspection.
+     * @returns {GPUDatabase}
+     */
+    get database(): GPUDatabase;
+    /**
+     * The readback the lattices travel through: its `in_flight_count`, `delivered_count`,
+     * `dropped_count` and `stalled_count`. For inspection.
+     * @returns {GPUDatabaseReadback}
+     */
+    get readback(): GPUDatabaseReadback;
+    /**
+     * Requests holding rows: recorded and not yet delivered or dropped.
+     * @returns {number}
+     */
+    get in_flight_count(): number;
+    /**
+     * Rows of `fluid_query`: one per request in flight.
+     * @returns {number}
+     */
+    get query_count(): number;
+    /**
+     * Rows of `fluid_query_sample`: the lattice points of every request in flight.
+     * @returns {number}
+     */
+    get sample_count(): number;
+    /**
+     * Requests the last {@link apply} (or {@link destroy}) settled.
+     * @returns {number}
+     */
+    get settled_count(): number;
+    /**
+     * @param {number} index below {@link settled_count}
+     * @returns {number} the tag the settled request was asked with
+     */
+    settled_tag(index: number): number;
+    /**
+     * @param {number} index below {@link settled_count}
+     * @returns {number} a {@link GPUReadbackStatus}: `Delivered`, its lattice now in its target, or
+     *   `Dropped`
+     */
+    settled_status(index: number): number;
+    /**
+     * Ask for the lattice of `counts` samples over a box, for the frame {@link record} records next.
+     * Its samples land in `target` from `target_offset`, {@link FLUID_QUERY_SAMPLE_FLOATS} floats a
+     * point, x fastest, at the {@link apply} that settles it Delivered.
+     *
+     * @param {number} min_x world metres
+     * @param {number} min_y
+     * @param {number} min_z
+     * @param {number} max_x
+     * @param {number} max_y
+     * @param {number} max_z
+     * @param {number} count_x samples along x, at least 1
+     * @param {number} count_y
+     * @param {number} count_z
+     * @param {Float32Array} target
+     * @param {number} target_offset in floats
+     * @param {number} tag the caller's, a u32, reported back when the request settles
+     */
+    request(min_x: number, min_y: number, min_z: number, max_x: number, max_y: number, max_z: number, count_x: number, count_y: number, count_z: number, target: Float32Array, target_offset: number, tag: number): void;
+    /**
+     * Make the frame's requests rows and record their pass into `graph`: the database's upload, the
+     * gather, and the readback's encode. After the frame's publish of `wind`, which the gather reads.
+     * Nothing is recorded with no request asked since the last call.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUSceneWind} options.wind the scene's published wind field
+     * @returns {boolean} whether a pass was recorded
+     */
+    record({ graph, wind }: {
+        graph: FrameGraph;
+        wind: GPUSceneWind;
+    }): boolean;
+    /**
+     * The apply point, once a frame (`GPUFluidSystem#update`): the readback delivers every batch
+     * whose mapping has landed, oldest first, and starts the maps of the frames submitted since.
+     * What settled is reported in {@link settled_count}: a delivered lattice copied into its target,
+     * a dropped one leaving its target as it was; either way its rows are freed.
+     */
+    apply(): void;
+    /**
+     * Release the database and the readback, discarding any mapping still out. Every request asked
+     * or in flight settles `Dropped`, reported in {@link settled_count} as an {@link apply} would.
+     * Passes recorded into a graph that has not run yet encode nothing. Safe to call twice.
+     */
+    destroy(): void;
+    #private;
+}
+export type FrameGraph = import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GPUSceneWind = import("../../wind/GPUSceneWind.js").GPUSceneWind;
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
+import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
+import { GPUDatabaseReadback } from "../../buffer/table/GPUDatabaseReadback.js";
+//# sourceMappingURL=GPUFluidQueries.d.ts.map

package/src/shade/renderer/fluid/query/GPUFluidQueries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUFluidQueries.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/query/GPUFluidQueries.js"],"names":[],"mappings":"AAsBA;;;;GAIG;AAEH;;;GAGG;AACH,wCAFU,MAAM,CAE2B;AA6D3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAOzB;IA6XD;;;;OAIG;IACH,+BAJW,MAAM,aACN,OAAO,sEAAsE,EAAE,kBAAkB,WACjG;QAAC,OAAO,EAAE,OAAO,2CAA2C,EAAE,sBAAsB,CAAA;KAAC,QAa/F;IAhUD;;;OAGG;IACH;QAF8B,MAAM;OA+BnC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;OAIG;IACH,oCAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,sBAJW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,eAbW,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,UACN,YAAY,iBACZ,MAAM,OACN,MAAM,QAkChB;IA2CD;;;;;;;;;OASG;IACH;QAJ+B,KAAK,EAAzB,UAAU;QACY,IAAI,EAA1B,YAAY;QACV,OAAO,CAoGnB;IA4DD;;;;;OAKG;IACH,cAcC;IAoFD;;;;OAIG;IACH,gBAyBC;;CACJ;yBA7qBY,OAAO,8DAA8D,EAAE,UAAU;2BACjF,OAAO,4BAA4B,EAAE,YAAY;8BACjD,OAAO,6CAA6C,EAAE,eAAe;4BAxBtD,mCAAmC;oCAC3B,2CAA2C"}