@yali-engine/water 0.0.0-stage → 0.12.0

package/dist/water.d.ts

@@ -0,0 +1,137 @@
+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 {
+    /** The sea's mean level, world metres (default 0). */
+    readonly level?: number;
+    /** Rings and segments of the surface's grid (defaults 240 × 384: 184,320 triangles out to ~9 km). */
+    readonly rings?: number;
+    readonly segments?: number;
+    /** The Jacobian below which foam starts (default 0.6; lower: less foam), and foam's strength (default 1). */
+    readonly foamThreshold?: number;
+    readonly foam?: number;
+    /** The water body's scattering colour (linear; default a deep teal-blue) and calm water's roughness (default 0.04). */
+    readonly bodyColor?: readonly [number, number, number];
+    readonly roughness?: number;
+    /** The colour of light through a crest (linear) and its strength (defaults a green-cyan, 0.5). */
+    readonly subsurfaceColor?: readonly [number, number, number];
+    readonly subsurface?: number;
+    /** The water's absorption per metre, red green blue (default coastal seawater: red gone in ~2 m, blue in ~20). */
+    readonly absorption?: readonly [number, number, number];
+    /** How far the refraction bends the view, pixels at a metre of water (default 60). */
+    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.
+ *
+ * @example
+ * import { water } from '@yali-engine/water';
+ * renderPlugin({ canvas, sky: { model: 'atmosphere' }, post: { passes: postPasses, taa: true }, features: [water({ wind: 12 })] });
+ */
+export declare function water(o?: WaterOptions): RenderFeatureFactory;
+export declare class Water implements RenderFeature {
+    #private;
+    readonly name = "water";
+    readonly device: GPUDevice;
+    readonly waves: WaterWaves;
+    /** Live knobs. */
+    level: number;
+    foamThreshold: number;
+    foam: number;
+    bodyColor: [number, number, number];
+    roughness: number;
+    subsurfaceColor: [number, number, number];
+    subsurface: number;
+    absorption: [number, number, number];
+    refraction: number;
+    shoreFoam: number;
+    reflections: number;
+    reflectionSteps: number;
+    /** Holds the waves at this time, seconds (live; null: they follow the app's clock). For stills and A/B checks. */
+    frozenAt: number | null;
+    /** A debug view: only the scene the reflections found (red where none). */
+    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 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 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;
+}