@yali-engine/water 0.11.0 → 0.13.0

package/dist/water.d.ts

@@ -1,4 +1,5 @@
 import type { FrameGraph, PipelineCache, RenderFeature, RenderFeatureFactory, RenderFeatureFrame, SceneRenderer } from '@yali-engine/render';
+import { type Seabed, type ShoreField } from './shore.ts';
 import { WaterWaves, type WaterWavesOptions } from './waves.ts';
 /** The ocean's knobs. */
 export interface WaterOptions extends WaterWavesOptions {
@@ -22,10 +23,30 @@ export interface WaterOptions extends WaterWavesOptions {
     readonly refraction?: number;
     /** Water shallower than this foams at a shore, metres (default 0.12). */
     readonly shoreFoam?: number;
+    /** The quality tier (ADR-0220, default 'high'): see `Water.quality`. */
+    readonly quality?: WaterQuality;
     /** How far the mirror ray is marched for reflections of the scene, metres (default 40; 0: the sky only), and its steps (24). */
     readonly reflections?: number;
     readonly reflectionSteps?: number;
+    /**
+     * The surf on a shore (ADR-0213), once `setSeabed` gives the water its seabed: its height in deep water (m, default 0.9),
+     * period (s, 8), breaking ratio γ (0.78), how far crests lean before breaking (0.55), the depth it rises out of the sea
+     * at (7 m) and the depth over which the open sea's waves calm (4 m).
+     */
+    readonly surf?: {
+        readonly height?: number;
+        readonly period?: number;
+        readonly breaking?: number;
+        readonly lean?: number;
+        readonly start?: number;
+        readonly calm?: number;
+        readonly variety?: number;
+        readonly lip?: number;
+        readonly spray?: number;
+    };
 }
+/** How much the water may cost (ADR-0220): the iGPU target is `medium` or `low` (≤ 2.5 ms, water research §1.1). */
+export type WaterQuality = 'high' | 'medium' | 'low';
 /**
  * An ocean (ADR-0198): FFT waves (JONSWAP, Donelan–Banner) on a radial grid to the horizon, lit by the scene's sky, sun and
  * fog. WebGPU with HDR only.
@@ -59,12 +80,68 @@ export declare class Water implements RenderFeature {
     debugMirror: boolean;
     /** Off: nothing is drawn or computed (live). */
     enabled: boolean;
+    /** The waves' own motion for TAA (ADR-0210; live): off, TAA sees the surface as still (the camera's motion only). */
+    motion: boolean;
+    /** The surf's height in deep water, metres (ADR-0213; live). */
+    surfHeight: number;
+    /** The breaking ratio γ: a wave breaks when it is taller than γ × the depth (0.78, live). */
+    surfBreaking: number;
+    /** How far crests lean shoreward before they break (Gerstner's Q, 0–1, live). */
+    surfLean: number;
+    /** The depth (m) at which the surf rises out of the sea, and over which the open sea's waves calm (live). */
+    surfStart: number;
+    surfCalm: number;
+    /** The surf's period, seconds: set before `setSeabed` (the crests' phase is baked for it). */
+    surfPeriod: number;
+    /**
+     * How much waves differ (ADR-0218; live, 0–1): 1 = swell in sets, each crest's height varying along the shore so it breaks
+     * in sections; 0 = every wave alike.
+     */
+    surfVariety: number;
+    /** How far a crest that starts to break throws its lip forward (ADR-0218; live, 0–1). */
+    surfLip: number;
+    /** Spray thrown up by breaking waves (ADR-0218; live, 0 = none, 1 = default). */
+    spray: number;
+    /** The ripples finer than the cascades (ADR-0223; live, 0 none, 1 Cox & Munk's slope for the wind). */
+    ripples: number;
+    /**
+     * The quality tier (ADR-0220; live): `high` everything; `medium` the coarse foam pattern only, 16 reflection steps, half
+     * the spray; `low` no caustics, no scene reflections, no spray. Setting it sets those knobs (they stay live after).
+     */
+    get quality(): WaterQuality;
+    set quality(q: WaterQuality);
     readonly rings: number;
     readonly segments: number;
     constructor(device: GPUDevice, o: WaterOptions);
     init(cache: PipelineCache, format: GPUTextureFormat): Promise<void>;
     prepare(f: RenderFeatureFrame): void;
+    /**
+     * The surf field's GPU cost, ms a frame (ADR-0223): one submission of `frames` + 1 dispatches less one of 1, over
+     * `frames`, each timed to `onSubmittedWorkDone` (the render loop's own frames land in either window, and the difference
+     * cancels them; the field runs in its own submission, which the frame graph's timers do not see). Null without a seabed.
+     *
+     * @example
+     * const ms = await ocean.measureSurf();
+     */
+    measureSurf(frames?: number): Promise<number | null>;
+    /**
+     * The seabed under the water (ADR-0213): bakes the shore field (`bakeShore`: depth, the crests' arrival phase for
+     * `surfPeriod`, their direction) and uploads it; the surf then rises, bends to the beach and breaks. Call again after
+     * changing `surfPeriod` or the seabed.
+     *
+     * @example
+     * ocean.setSeabed({ heights, size: 256, cell: 1, origin: [-128, -198] });
+     */
+    setSeabed(seabed: Seabed): ShoreField;
+    /** The baked shore field, or null before `setSeabed`. */
+    get shoreField(): ShoreField | null;
+    addMotionPasses(graph: FrameGraph, motion: string, depth: string): void;
     addPasses(graph: FrameGraph, color: string, depth: string, scene: SceneRenderer): void;
+    /**
+     * Its agent tools (ADR-0204): `water.state` reads the sea, `water.set` turns its knobs, `water.sea` makes a new sea.
+     * Errors carry the argument's `path`.
+     */
+    tools(): ReturnType<NonNullable<RenderFeature['tools']>>;
     /** What the sea holds on the GPU (its waves; the surface has no buffers). */
     get gpuBytes(): number;
     destroy(): void;