@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/pressure/FLUID_MG_PASS_STRUCT.js

@@ -0,0 +1,45 @@
+import { f32, u32, vec3i, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * One pass of the pressure solve over one level, as its kernel reads it from a uniform.
+ *
+ * A level's values are addressed like a {@link GRID_TILE_WINDOW_STRUCT} window: the finest level's
+ * pressure through the cascade's toroidal window, everything else window-local and linear, which is a
+ * window with its storage corner at 0 and a period of its size.
+ *
+ * - `corner`: the world cell at window-local (0, 0, 0) of the finest level; a Dirichlet ghost outside
+ *   the window is asked for by world cell. Unread below the finest level.
+ * - `size`: the level's cells, the cells the pass covers.
+ * - `input_corner_storage`, `input_period`: where the level's input values are stored.
+ * - `output_corner_storage`, `output_period`: where a smoother writes its output.
+ * - `coarse_size`: the next coarser level's cells: what the smoother prolongs from and the restriction
+ *   writes.
+ * - `level`: 0 on the finest level, whose ghosts are Dirichlet pressure; an error's ghost is 0.
+ * - `colours`: the smoother's colour mask, a {@link FluidMGColour}.
+ * - `sweeps`: the smoother's sweeps.
+ * - `prolong`: 1 when the smoother's load adds the coarser level's error.
+ * - `omega`: the smoother's relaxation factor.
+ * - `h2`: the level's `H²`, metres².
+ * - `edge_weight`: the level's window-edge face weight, `2 / (1 + h/H)`.
+ *
+ * The word builders read `size` only: the level they write.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_MG_PASS_STRUCT = WebGPUStruct.from({
+    corner: vec3i,
+    level: u32,
+    size: vec3u,
+    colours: u32,
+    input_corner_storage: vec3u,
+    sweeps: u32,
+    input_period: vec3u,
+    prolong: u32,
+    output_corner_storage: vec3u,
+    omega: f32,
+    output_period: vec3u,
+    h2: f32,
+    coarse_size: vec3u,
+    edge_weight: f32,
+}, 'FluidMGPass');

package/src/shade/renderer/fluid/pressure/GPUFluidPressureSolve.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The GPU fluid's pressure solve for one cascade window (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8):
+ * `Σ_f w_f·(p_nb − p) / H² = f` for the physical kinematic pressure `p` (m²/s²), with `f = div/dt`, a
+ * solid face closed and the window's edge a Dirichlet boundary at the ghost cell's centre. The
+ * cascade's parent's pressure at the ghost cell's centre is the ghost (`chunk_fluid_pressure_ghost`), as
+ * the step's pressure ghosts hold it.
+ *
+ * It owns its level transients, sized by the window and made when the window's size or the device
+ * changes, never per frame. Each `record_*` adds one graph pass that dispatches everything; each
+ * `encode_*` dispatches the same into the encoder of a pass the caller records itself:
+ *
+ * - **Weights**, once a solve: the finest level's words from the solid flags, then each coarse level's
+ *   from the one above (`shader_fluid_mg_level0_weights`, `shader_fluid_mg_coarse_weights`). The SOR
+ *   arm needs the finest only.
+ * - **{@link record_v_cycles}**, V-cycles of `3L − 2` dispatches over `L` levels: on each level above
+ *   the coarsest a smoother of {@link FLUID_MG_SMOOTH_SWEEPS} sweeps and a residual + restriction; the
+ *   coarsest level in one workgroup; then each level back up, one smoother whose load prolongs the
+ *   level below in. At 64×32×64, four levels: 10 dispatches a V-cycle, plus 4 for the weights.
+ * - **{@link record_sor}**, red-black SOR on the finest level at `sor_optimal_omega`, one colour a
+ *   dispatch: `2K` dispatches for `K` sweeps, plus 1 for the weights.
+ *
+ * A smoother never writes the buffer it reads, so the finest level goes pressure → scratch → pressure.
+ *
+ * Non-finite pressure, error and RHS are read as 0, and {@link nonfinite_counter} adds one for each such
+ * value a pass's owning invocation read. It is never reset.
+ *
+ * The window's edge is a Dirichlet boundary at the ghost cell's centre: the cascade's parent's
+ * pressure there, read from `ghost_pressure`, the step's pressure ghosts (`shader_fluid_cascade_ghosts`);
+ * the far field, a parent with no window, reads 0.
+ */
+export class GPUFluidPressureSolve {
+    /**
+     * @param {{solve: GPUFluidPressureSolve, arm: number, count: number, inputs: FluidPressureSolveInputs}} data
+     * @param {*} _resources
+     * @param {{encoder: ShadeGPUCommandContext}} context
+     */
+    static "__#262@#execute"(data: {
+        solve: GPUFluidPressureSolve;
+        arm: number;
+        count: number;
+        inputs: FluidPressureSolveInputs;
+    }, _resources: any, context: {
+        encoder: ShadeGPUCommandContext;
+    }): void;
+    /**
+     * One `u32`: how many non-finite values the solves recorded so far read and zeroed. Made with the
+     * level transients.
+     * @returns {GPUBuffer|null}
+     */
+    get nonfinite_counter(): any;
+    /**
+     * Record V-cycles into a pass of `graph`. Nothing is recorded for 0 cycles.
+     *
+     * @param {object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUBuffer} options.pressure the cascade's pressure, read as the warm start and written with
+     *   the answer: `f32` at each storage cell of `window`, x fastest
+     * @param {{corner: ArrayLike<number>, corner_storage: ArrayLike<number>, size: ArrayLike<number>, period: ArrayLike<number>}} options.window
+     *   where the pressure is stored, as {@link GRID_TILE_WINDOW_STRUCT}; its size is the solve's cells,
+     *   powers of two
+     * @param {GPUBuffer} options.rhs `f = div/dt` per cell, window-local and linear
+     * @param {GPUBuffer} options.solid solid flags per cell (bit 0), window-local and linear
+     * @param {number} options.h the cell's size, metres
+     * @param {GPUBuffer} options.ghost_pressure the finest level's Dirichlet ghosts (`chunk_fluid_pressure_ghost`):
+     *   the parent's pressure at every cell one past the window, `array<f32>` over the window grown by
+     *   one cell on every side, x fastest, as `shader_fluid_cascade_ghosts` writes it
+     * @param {number} options.cycles V-cycles
+     */
+    record_v_cycles({ graph, pressure, window, rhs, solid, h, ghost_pressure, cycles }: {
+        graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        pressure: GPUBuffer;
+        window: {
+            corner: ArrayLike<number>;
+            corner_storage: ArrayLike<number>;
+            size: ArrayLike<number>;
+            period: ArrayLike<number>;
+        };
+        rhs: GPUBuffer;
+        solid: GPUBuffer;
+        h: number;
+        ghost_pressure: GPUBuffer;
+        cycles: number;
+    }): void;
+    /**
+     * {@link record_v_cycles} into `encoder` itself, for a caller whose own frame-graph pass records
+     * the solve among its other dispatches, as a cascade's step does. Nothing is encoded for 0 cycles.
+     * `inputs` is read, not kept.
+     *
+     * @param {ShadeGPUCommandContext} encoder the encoder a frame-graph pass's callback was handed
+     * @param {FluidPressureSolveInputs} inputs
+     */
+    encode_v_cycles(encoder: ShadeGPUCommandContext, inputs: FluidPressureSolveInputs): void;
+    /**
+     * {@link record_sor} into `encoder` itself, as {@link encode_v_cycles}. Nothing is encoded for 0
+     * sweeps.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidPressureSolveInputs} inputs
+     */
+    encode_sor(encoder: ShadeGPUCommandContext, inputs: FluidPressureSolveInputs): void;
+    /**
+     * Record red-black SOR sweeps on the finest level into a pass of `graph`, one colour a dispatch.
+     * Nothing is recorded for 0 sweeps.
+     *
+     * @param {object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUBuffer} options.pressure as {@link record_v_cycles}
+     * @param {{corner: ArrayLike<number>, corner_storage: ArrayLike<number>, size: ArrayLike<number>, period: ArrayLike<number>}} options.window
+     * @param {GPUBuffer} options.rhs
+     * @param {GPUBuffer} options.solid
+     * @param {number} options.h
+     * @param {GPUBuffer} options.ghost_pressure
+     * @param {number} options.sweeps red-black sweeps
+     */
+    record_sor({ graph, pressure, window, rhs, solid, h, ghost_pressure, sweeps }: {
+        graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        pressure: GPUBuffer;
+        window: {
+            corner: ArrayLike<number>;
+            corner_storage: ArrayLike<number>;
+            size: ArrayLike<number>;
+            period: ArrayLike<number>;
+        };
+        rhs: GPUBuffer;
+        solid: GPUBuffer;
+        h: number;
+        ghost_pressure: GPUBuffer;
+        sweeps: number;
+    }): void;
+    /**
+     * Release the level transients and the counter.
+     */
+    dispose(): void;
+    #private;
+}
+export type ShadeGPUCommandContext = import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+/**
+ * A solve's inputs, as {@link GPUFluidPressureSolverecord_v_cycles } documents them, with `cycles` for
+ * the V-cycles or `sweeps` for SOR.
+ */
+export type FluidPressureSolveInputs = {
+    pressure: GPUBuffer;
+    window: {
+        corner: ArrayLike<number>;
+        corner_storage: ArrayLike<number>;
+        size: ArrayLike<number>;
+        period: ArrayLike<number>;
+    };
+    rhs: GPUBuffer;
+    solid: GPUBuffer;
+    h: number;
+    ghost_pressure: GPUBuffer;
+    cycles?: number;
+    sweeps?: number;
+};
+//# sourceMappingURL=GPUFluidPressureSolve.d.ts.map

package/src/shade/renderer/fluid/pressure/GPUFluidPressureSolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUFluidPressureSolve.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/pressure/GPUFluidPressureSolve.js"],"names":[],"mappings":"AAwEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAgKI;;;;OAIG;IACH,+BAJW;QAAC,KAAK,EAAE,qBAAqB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,wBAAwB,CAAA;KAAC,4BAE5F;QAAC,OAAO,EAAE,sBAAsB,CAAA;KAAC,QAI3C;IAzID;;;;OAIG;IACH,6BAEC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAdsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;QAC9D,QAAQ;QAEiG,MAAM,EAAlI;YAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,cAAc,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,IAAI,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAA;SAAC;QAG/F,GAAG;QACH,KAAK;QACR,CAAC,EAAjB,MAAM;QACa,cAAc;QAGjB,MAAM,EAAtB,MAAM;aAMhB;IAED;;;;;;;OAOG;IACH,yBAHW,sBAAsB,UACtB,wBAAwB,QASlC;IAED;;;;;;OAMG;IACH,oBAHW,sBAAsB,UACtB,wBAAwB,QASlC;IAED;;;;;;;;;;;;;OAaG;IACH;QATsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;QAC9D,QAAQ;QACiG,MAAM,EAAlI;YAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,cAAc,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,IAAI,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAA;SAAC;QAC/F,GAAG;QACH,KAAK;QACR,CAAC,EAAjB,MAAM;QACa,cAAc;QACjB,MAAM,EAAtB,MAAM;aAMhB;IA0RD;;OAEG;IACH,gBA0BC;;CACJ;qCA7fY,OAAO,2CAA2C,EAAE,sBAAsB;;;;;uCAO1E;IAAC,QAAQ,YAAY;IAAC,MAAM,EAAE;QAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAC;QAAC,cAAc,EAAE,UAAU,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,UAAU,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAA;KAAC,CAAC;IAAC,GAAG,YAAY;IAAC,KAAK,YAAY;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,YAAY;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC"}