@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/scene/water.js

@@ -1,20 +1,21 @@
-import { Vector4, applyMixins, DRef, Vector3 } from '@zephyr3d/base';
+import { Vector4, applyMixins, DRef, Vector3, Vector2 } from '@zephyr3d/base';
 import { GraphNode } from './graph_node.js';
 import { mixinDrawable } from '../render/drawable_mixin.js';
 import { QUEUE_OPAQUE } from '../values.js';
-import '../render/render_queue.js';
 import { getDevice } from '../app/api.js';
+import '../render/render_queue.js';
 import { Primitive } from '../render/primitive.js';
 import '@zephyr3d/device';
-import '../material/shader/helper.js';
+import { ShaderHelper } from '../material/shader/helper.js';
 import '../material/lambert.js';
 import '../material/blinn.js';
 import '../material/unlit.js';
+import '../material/meshmaterial.js';
 import '../material/particle.js';
 import '../material/subsurfaceprofile.js';
-import '../material/skin.js';
+import '../material/sssprofile.js';
+import '../material/sss.js';
 import '../material/eye.js';
-import '../material/meshmaterial.js';
 import '../material/hair.js';
 import '../material/hairstrand.js';
 import '../material/grassmaterial.js';
@@ -31,11 +32,18 @@ import '../render/lightpass.js';
 import '../render/sky.js';
 import { Clipmap } from '../render/clipmap.js';
 import '../render/envlight.js';
+import '../render/lod.js';
 import '../render/dualdepthpeeling_oit.js';
 import { setWaterSubmergence } from '../render/underwater.js';
 import '../shaders/atmosphere.js';
 import { FBMWaveGenerator } from '../render/fbm_wavegenerator.js';
+import { InteractiveWaveGenerator } from '../render/water_interaction.js';
+import { RenderGraphExecutor } from '../render/rendergraph/executor.js';
 import '../render/rendergraph/scene_render_context.js';
+import '../render/sdf/scene_sdf.js';
+import '../render/sdf/global_sdf.js';
+import { TerrainWaterlineSource, WaterlineField } from '../render/sdf/waterline.js';
+import '../render/gi/voxelize_pass.js';
 import { WaterMaterial } from '../material/water.js';
 import { BoundingBox } from '../utility/bounding_volume.js';
 
@@ -43,17 +51,24 @@ import { BoundingBox } from '../utility/bounding_volume.js';
 /** Floor on the eye height feeding the horizon distance, in meters. @internal */ const MIN_HORIZON_EYE_HEIGHT = 0.1;
 /**
  * How far past the tessellated surface the skirt's outer edge is placed, as a
- * multiple of the view distance.
- *
- * Only has to be far enough that the ring reads as a horizon line rather than a
- * visible band; it is depth-pinned to the far plane regardless of how far out
- * it actually lands.
+ * multiple of the view distance. Its depth is pinned to the far plane.
  * @internal
  */ const SKIRT_DISTANCE_FACTOR = 10;
 /**
  * Region rectangle standing in for "no bounds", matching the WaterMaterial
  * default. @internal
  */ const WHOLE_DOMAIN = new Vector4(-99999, -99999, 99999, 99999);
+/**
+ * The shore field's levels around the camera: cells along a side and the
+ * finest cell size in metres, each level twice the size of the one before,
+ * laid out as the foam field's are.
+ */ const SHORE_FIELD_LEVELS = 4;
+const SHORE_FIELD_CELLS = 256;
+const SHORE_FIELD_CELL_SIZE = 0.5;
+/** Shore field levels rebuilt in a frame at most, so the camera crossing every level's cell at once is no spike. */ const SHORE_FIELD_REBUILDS = 2;
+/** No waterline grid: 0 cells. */ const NO_REGIONS = [
+    new Vector4(0, 0, 1, 0)
+];
 /**
  * Water scene node
  * @public
@@ -68,17 +83,30 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /** Wave clock, in seconds. Advanced by `animationSpeed` per frame. */ _waveTime;
     /** Elapsed time at the previous update, for the frame delta. */ _lastUpdateTime;
     _feedbackProgram;
+    /** Hash of the wave generator the feedback program was built for. */ _feedbackHash;
     _feedbackBindGroup;
     _feedbackPrimitive;
     _feedbackRenderTarget;
     _feedbackRenderStates;
+    /**
+   * Tail of the surface-query queue. The feedback pass reuses one vertex buffer
+   * and render target, so requests are serialized in issue order.
+   */ _feedbackQueue;
+    /**
+   * Frame numbers of the stages of the most recent surface-point query, for
+   * latency diagnostics: when it was requested, when its render was recorded,
+   * and when the readback resolved. All are `device.frameInfo.frameCounter`.
+   * @public
+   */ lastFeedbackTiming = {
+        issued: 0,
+        recorded: 0,
+        mapped: 0
+    };
     _material;
     /**
-   * Whether each camera was inside this body of water on its previous update.
-   *
-   * The submerged test has a dead band around the surface, so it needs to know
-   * which way it is crossing; per camera, because two views of one ocean can be
-   * on opposite sides of it.
+   * Whether each camera was inside this body of water on its previous update;
+   * the submerged test has a dead band around the surface, so it needs the
+   * crossing direction.
    */ _submerged;
     /**
    * Creates an instance of Water node
@@ -98,19 +126,25 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         this._lastUpdateTime = 0;
         this._material = new DRef(new WaterMaterial());
         this._material.get().region = new Vector4(-1, -1, 1, 1);
-        this._material.get().TAAStrength = 0.4;
+        this._material.get().TAAStrength = 0.2;
         this.waveGenerator = new FBMWaveGenerator();
         this._feedbackProgram = new DRef();
+        this._feedbackHash = '';
         this._feedbackBindGroup = new DRef();
         this._feedbackPrimitive = new DRef();
         this._feedbackRenderTarget = new DRef();
         this._feedbackRenderStates = null;
+        this._feedbackQueue = Promise.resolve();
         this._submerged = new WeakMap();
         scene.queuePerCameraUpdateNode(this);
     }
     /** Disposes the water node */ onDispose() {
         super.onDispose();
         this._clipmap.dispose();
+        this._shoreField?.dispose();
+        this._shoreSource?.dispose();
+        this._shoreField = null;
+        this._shoreSource = null;
         this._renderData = null;
         this._feedbackBindGroup.dispose();
         this._feedbackPrimitive.dispose();
@@ -132,8 +166,14 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /** Material of the water */ get material() {
         return this._material.get();
     }
-    /** Wave generator object of the water */ get waveGenerator() {
-        return this.material.waveGenerator;
+    /**
+   * Wave generator object of the water: the source of the ambient surface.
+   *
+   * While an {@link interaction} is attached the surface actually drawn is
+   * this generator plus the interaction field; this still returns the
+   * generator on its own.
+   */ get waveGenerator() {
+        return this.material.baseWaveGenerator;
     }
     set waveGenerator(waveGenerator) {
         this.material.waveGenerator = waveGenerator;
@@ -142,16 +182,30 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         }
     }
     /**
+   * Dynamic height field layered over the surface, driven by things touching
+   * the water, or null for none. See {@link WaterInteraction}.
+   *
+   * The field is stepped on this water's own clock, so {@link animationSpeed}
+   * scales it too; it is added everywhere the surface is evaluated, so
+   * {@link getSurfacePoint} and the caustics see it as well.
+   */ get interaction() {
+        return this.material.interaction;
+    }
+    set interaction(val) {
+        this.material.interaction = val;
+        if (this.material.needUpdate()) {
+            this.scene?.queueUpdateNode(this);
+        }
+    }
+    /**
    * Whether the surface reads as an unbounded ocean reaching the horizon,
    * rather than a body of water ending at the node's extent.
    *
-   * Off by default. A pond, a lake or a pool has an edge, and the region test
-   * that draws it is skipped entirely while this is on.
+   * Off by default. The region test is skipped while this is on.
    *
    * The horizon is reached without touching the camera's far plane: the
    * clipmap's outermost ring is drawn as a skirt whose outer vertices are
-   * pushed well past it with their depth pinned to the far value. A far plane
-   * sized for the near scene therefore keeps its depth precision.
+   * pushed well past it with their depth pinned to the far value.
    */ get infinite() {
         return this.material.infinite;
     }
@@ -166,12 +220,9 @@ import { BoundingBox } from '../utility/bounding_volume.js';
    * on, in meters. 0 derives it from the true horizon distance for the camera's
    * height above the water.
    *
-   * Raising it costs clipmap levels, which are logarithmic in the distance, so
-   * the geometry cost of a much larger value is small. What it really trades is
-   * against the sky's {@link SkyRenderer.aerialPerspectiveDistance}: build the
-   * water out further than the aerial perspective LUT reaches and the far water
-   * stops converging towards the sky colour, which puts back the hard band this
-   * setting exists to remove.
+   * Geometry cost grows only logarithmically. Keep it within the sky's
+   * {@link SkyRenderer.aerialPerspectiveDistance}, or the far water stops
+   * converging towards the sky colour and shows a hard band.
    */ get viewDistance() {
         return this._viewDistance;
     }
@@ -188,6 +239,17 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     set animationSpeed(val) {
         this._animationSpeed = val;
     }
+    /**
+   * The wave clock the surface is currently at, in seconds.
+   *
+   * The time the displaced surface was last evaluated with (the value
+   * {@link WaterMaterial.update} is handed), not the scene's elapsed time. CPU
+   * samplers of the surface should use this clock; it matches `elapsedInSeconds`
+   * from {@link SceneNode.update} only while {@link animationSpeed} is 1 and the
+   * water has not been paused.
+   */ get waveTime() {
+        return this._waveTime;
+    }
     /** TAA strength of the water */ get TAAStrength() {
         return this.material.TAAStrength;
     }
@@ -228,10 +290,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         this.material.causticsSceneDepth = val;
     }
     /**
-   * Furthest distance in meters from the camera the caustic map reaches.
-   *
-   * A cap rather than a fixed extent: the map is fitted to the part of the water
-   * within this distance.
+   * Furthest distance in meters from the camera the caustic map reaches; the
+   * map is fitted to the part of the water within this distance.
    */ get causticsRange() {
         return this.material.causticsRange;
     }
@@ -257,18 +317,21 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     set causticsWarp(val) {
         this.material.causticsWarp = val;
     }
+    /** Water depth in metres below which no caustics show. */ get causticsMinDepth() {
+        return this.material.causticsMinDepth;
+    }
+    set causticsMinDepth(val) {
+        this.material.causticsMinDepth = val;
+    }
     /**
    * Whether a camera inside this body of water sees the water from the inside:
    * the medium applied to the whole scene, the sky replaced by water, and the
    * surface read from below with its Snell window.
    *
    * Uses the same medium coefficients the surface does ({@link absorption},
-   * {@link scattering} and their scales), so the volume and the surface never
-   * disagree. Atmospheric fog is suppressed while submerged - the medium the eye
-   * is looking through is water, not air.
-   *
-   * Only reaches opaque geometry, like the atmospheric fog it replaces;
-   * transparent surfaces are not tinted by the column in front of them.
+   * {@link scattering} and their scales). Atmospheric fog is suppressed while
+   * submerged. Only reaches opaque geometry, like the atmospheric fog it
+   * replaces.
    */ get underwaterEnabled() {
         return this.material.underwaterEnabled;
     }
@@ -288,9 +351,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /**
    * Whether shafts of sunlight are marched through the water column.
    *
-   * Reads the caustic map as the surface's transmittance, so the shafts carry
-   * the same pattern that lands on the sea bed. Needs {@link causticsEnabled}
-   * and everything it needs; switches itself off wherever the map is
+   * Reads the caustic map as the surface's transmittance. Needs
+   * {@link causticsEnabled}; switches itself off wherever the map is
    * unavailable.
    */ get underwaterGodRays() {
         return this.material.underwaterGodRays;
@@ -306,8 +368,7 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     }
     /**
    * Samples taken along each view ray for the light shafts. Raise it when the
-   * shafts read as grain rather than as beams, which is what too few samples of
-   * a sharp caustic pattern look like.
+   * shafts read as grain rather than as beams.
    */ get underwaterGodRaySteps() {
         return this.material.underwaterGodRaySteps;
     }
@@ -318,11 +379,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
    * Whether geometry standing in the water breaks the light shafts. Off by
    * default.
    *
-   * The shafts come from the caustic map, which describes what the *surface* did
-   * to the sunlight and knows nothing about what is under it, so without this a
-   * shaft runs straight through a piling or a hull. Costs a shadow map lookup
-   * per march step, roughly doubling what the shafts cost. The sea bed's own
-   * shadows are unaffected either way.
+   * Without it a shaft runs straight through a piling or a hull. Costs a shadow
+   * map lookup per march step, roughly doubling the cost of the shafts.
    */ get underwaterGodRayShadow() {
         return this.material.underwaterGodRayShadow;
     }
@@ -340,11 +398,37 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         this.material.underwaterHysteresis = val;
     }
     /**
+   * Strength of the glow of a backlit wave crest, 0 to disable. Authored, not
+   * scaled by the light's intensity; {@link subsurfaceTint} supplies the hue.
+   */ get subsurfaceIntensity() {
+        return this.material.subsurfaceIntensity;
+    }
+    set subsurfaceIntensity(val) {
+        this.material.subsurfaceIntensity = val;
+    }
+    /**
+   * Height above the still-water level, in meters, over which the lit wall of
+   * a crest thins by a factor of `e`. Lower for a calm sea, higher so only the
+   * tallest crests glow.
+   */ get subsurfaceCrestHeight() {
+        return this.material.subsurfaceCrestHeight;
+    }
+    set subsurfaceCrestHeight(val) {
+        this.material.subsurfaceCrestHeight = val;
+    }
+    /**
+   * Colour of the crest glow, before the crest gate tints it with the medium's
+   * extinction.
+   */ get subsurfaceTint() {
+        return this.material.subsurfaceTint;
+    }
+    set subsurfaceTint(val) {
+        this.material.subsurfaceTint = val;
+    }
+    /**
    * Strength of the sunlight scattered out of the water column towards the eye,
-   * 1 for the value the medium coefficients imply.
-   *
-   * This is what makes a shadow falling on the water darken the water itself,
-   * and a low sun tint it. 0 leaves the body lit by the environment alone.
+   * 1 for the value the medium coefficients imply. Lets shadows darken the
+   * water body and a low sun tint it; 0 leaves it lit by the environment alone.
    */ get sunScatteringIntensity() {
         return this.material.sunScatteringIntensity;
     }
@@ -352,91 +436,160 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         this.material.sunScatteringIntensity = val;
     }
     /**
-   * Coverage of the foam that collects where the water meets a surface, 0 to
-   * disable. Off by default.
-   *
-   * Independent of the crest foam the wave generator produces: this one is keyed
-   * on how far the surface is from whatever is behind it, measured to that
-   * surface's own plane - the depth of water over a bed, the horizontal distance
-   * to a piling or a hull - so one band covers both the shoreline and the contact
-   * line around anything standing in the water.
-   * {@link shoreFoamWashAmount} is what makes it run up and drain back rather
-   * than sit there as a rim.
-   *
-   * Estimated from the depth buffer, so it only knows about what the camera can
-   * see: water in front of something standing above the surface gets no foam
-   * rather than a guess. See {@link WaterMaterial.shoreFoamAmount}.
-   */ get shoreFoamAmount() {
-        return this.material.shoreFoamAmount;
+   * Crest to trough height in metres of the waves rolling in to the shore,
+   * breaking and running up the beach, 0 for none. They come square on to the
+   * coast whatever its shape, and boats ride them. Needs the scene signed
+   * distance field (WebGPU, scene SDF enabled).
+   */ get shoreWaveHeight() {
+        return this.material.shoreWaveHeight;
     }
-    set shoreFoamAmount(val) {
-        this.material.shoreFoamAmount = val;
+    set shoreWaveHeight(val) {
+        this.material.shoreWaveHeight = val;
     }
-    /**
-   * How far, in meters, the foam band reaches from the surface behind it. A depth
-   * of water over a bed, a horizontal distance against anything vertical. How
-   * wide that is on screen depends on the geometry: a thin line on a steep
-   * drop-off, a broad stretch on a flat shelf.
-   */ get shoreFoamDepth() {
-        return this.material.shoreFoamDepth;
+    /** Thickness in metres over which a thin sheet of water fades in from the ground under it; 0 disables it. */ get edgeFadeWidth() {
+        return this.material.edgeFadeWidth;
     }
-    set shoreFoamDepth(val) {
-        this.material.shoreFoamDepth = val;
+    set edgeFadeWidth(val) {
+        this.material.edgeFadeWidth = val;
     }
-    /**
-   * Falloff across the band. Above 1 pushes the coverage towards the near end and
-   * keeps the outer edge thin and broken.
-   */ get shoreFoamFalloff() {
-        return this.material.shoreFoamFalloff;
+    /** Distance in metres between shore wave crests at the outer edge of their zone. */ get shoreWaveLength() {
+        return this.material.shoreWaveLength;
     }
-    set shoreFoamFalloff(val) {
-        this.material.shoreFoamFalloff = val;
+    set shoreWaveLength(val) {
+        this.material.shoreWaveLength = val;
     }
-    /**
-   * Size of the clumps the band's edge breaks into, as cycles across the band.
-   *
-   * Relative to {@link shoreFoamDepth} rather than in cycles per metre, so one
-   * setting reads the same on a shoreline metres across and on a collar a
-   * handspan wide around a piling.
-   */ get shoreFoamScale() {
-        return this.material.shoreFoamScale;
+    /** Seconds between successive shore waves. */ get shoreWavePeriod() {
+        return this.material.shoreWavePeriod;
     }
-    set shoreFoamScale(val) {
-        this.material.shoreFoamScale = val;
+    set shoreWavePeriod(val) {
+        this.material.shoreWavePeriod = val;
     }
-    /**
-   * How far the band's edge runs back and forth, as a fraction of
-   * {@link shoreFoamDepth}. 0 leaves a static band.
-   */ get shoreFoamWashAmount() {
-        return this.material.shoreFoamWashAmount;
+    /** How far out from the waterline the shore waves rise, in metres. */ get shoreWaveZone() {
+        return this.material.shoreWaveZone;
     }
-    set shoreFoamWashAmount(val) {
-        this.material.shoreFoamWashAmount = val;
+    set shoreWaveZone(val) {
+        this.material.shoreWaveZone = val;
     }
-    /** Run-up cycles per second. Swell rather than wind waves, so well under 1. */ get shoreFoamWashSpeed() {
-        return this.material.shoreFoamWashSpeed;
+    /** How sharp the shore wave crests become at the shore, 0 for a sine and towards 1 for a cusp. */ get shoreWaveSharpness() {
+        return this.material.shoreWaveSharpness;
     }
-    set shoreFoamWashSpeed(val) {
-        this.material.shoreFoamWashSpeed = val;
+    set shoreWaveSharpness(val) {
+        this.material.shoreWaveSharpness = val;
     }
-    /**
-   * Spatial frequency of the run-up phase, in cycles per meter. At 0 the whole
-   * waterline advances in lockstep, which reads as the water level rising and
-   * falling; a cycle every few tens of meters breaks it into sections.
-   */ get shoreFoamWashScale() {
-        return this.material.shoreFoamWashScale;
+    /** How far the shore wave crests lean towards the shore there, 0 for upright, 1 for a steep front face. */ get shoreWaveLean() {
+        return this.material.shoreWaveLean;
+    }
+    set shoreWaveLean(val) {
+        this.material.shoreWaveLean = val;
+    }
+    /** How irregular the shore waves are, 0..1: 0 for parallel crests a fixed wavelength apart, higher for each wave with a period and a bend of its own. */ get shoreWaveIrregularity() {
+        return this.material.shoreWaveIrregularity;
+    }
+    set shoreWaveIrregularity(val) {
+        this.material.shoreWaveIrregularity = val;
+    }
+    /** How fast the foam fades, per second (Crest's Foam Fade Rate): lower leaves longer trails behind breaking waves. */ get foamFadeRate() {
+        return this.material.foamFadeRate;
+    }
+    set foamFadeRate(val) {
+        this.material.foamFadeRate = val;
+    }
+    /** How much foam the open water's breaking crests leave behind to drift and fade; 0 keeps foam only while a crest breaks. */ get foamTrailStrength() {
+        return this.material.foamTrailStrength;
+    }
+    set foamTrailStrength(val) {
+        this.material.foamTrailStrength = val;
+    }
+    /** Share of the wind speed the foam drifts at, about 0.03 in nature. */ get foamDrift() {
+        return this.material.foamDrift;
+    }
+    set foamDrift(val) {
+        this.material.foamDrift = val;
+    }
+    /** Side in metres of the finest square of water around the view whose foam lingers, in the most detail; coarser squares reach eight times as far, beyond which foam shows only while crests break. */ get foamFieldSize() {
+        return this.material.foamFieldSize;
+    }
+    set foamFieldSize(val) {
+        this.material.foamFieldSize = val;
+    }
+    /** How much foam the breaking shore waves make (Crest's Wave Foam Strength). */ get shoreWaveFoamStrength() {
+        return this.material.shoreWaveFoamStrength;
+    }
+    set shoreWaveFoamStrength(val) {
+        this.material.shoreWaveFoamStrength = val;
+    }
+    /** How much of the shore waves makes foam, 0..1, higher for more (Crest's Wave Foam Coverage). */ get shoreWaveFoamCoverage() {
+        return this.material.shoreWaveFoamCoverage;
+    }
+    set shoreWaveFoamCoverage(val) {
+        this.material.shoreWaveFoamCoverage = val;
+    }
+    /** Water shallower than this many metres makes foam (Crest's Shoreline Foam Max Depth). */ get shoreWaveShallowFoamDepth() {
+        return this.material.shoreWaveShallowFoamDepth;
+    }
+    set shoreWaveShallowFoamDepth(val) {
+        this.material.shoreWaveShallowFoamDepth = val;
     }
-    set shoreFoamWashScale(val) {
-        this.material.shoreFoamWashScale = val;
+    /** How much foam shallow water makes (Crest's Shoreline Foam Strength). */ get shoreWaveShallowFoamStrength() {
+        return this.material.shoreWaveShallowFoamStrength;
+    }
+    set shoreWaveShallowFoamStrength(val) {
+        this.material.shoreWaveShallowFoamStrength = val;
+    }
+    /** How opaque the foam is that the water makes against walls, rocks and piers standing in it, 0..1; it always rings them whole. */ get wallFoamStrength() {
+        return this.material.wallFoamStrength;
+    }
+    set wallFoamStrength(val) {
+        this.material.wallFoamStrength = val;
+    }
+    /** Speed in metres per second the water has to hit a wall at before it makes any foam there. */ get wallFoamMinSpeed() {
+        return this.material.wallFoamMinSpeed;
+    }
+    set wallFoamMinSpeed(val) {
+        this.material.wallFoamMinSpeed = val;
+    }
+    /** Speed in metres per second at which water hitting a wall makes the most foam. */ get wallFoamMaxSpeed() {
+        return this.material.wallFoamMaxSpeed;
+    }
+    set wallFoamMaxSpeed(val) {
+        this.material.wallFoamMaxSpeed = val;
+    }
+    /** Speed in metres per second the foam drifts out from walls, rocks and piers at: higher for a wider ring of foam around them. */ get wallFoamDrift() {
+        return this.material.wallFoamDrift;
+    }
+    set wallFoamDrift(val) {
+        this.material.wallFoamDrift = val;
+    }
+    /** Seconds the foam each breaking wave brings in lasts, behind the crest and up the beach. */ get surfFoamDuration() {
+        return this.material.surfFoamDuration;
+    }
+    set surfFoamDuration(val) {
+        this.material.surfFoamDuration = val;
+    }
+    /** Water depth in metres at and below which foam stops drifting and stays where it is. */ get foamSettleDepth() {
+        return this.material.foamSettleDepth;
+    }
+    set foamSettleDepth(val) {
+        this.material.foamSettleDepth = val;
+    }
+    /** Water depth in metres at and beyond which foam drifts freely. */ get foamDriftDepth() {
+        return this.material.foamDriftDepth;
+    }
+    set foamDriftDepth(val) {
+        this.material.foamDriftDepth = val;
+    }
+    /** How fast foam settled in shallow water and on the sand fades, as a share of the foam's fade. */ get settledFoamFade() {
+        return this.material.settledFoamFade;
+    }
+    set settledFoamFade(val) {
+        this.material.settledFoamFade = val;
     }
     /**
    * How the refracted view sample is located. Defaults to `march`.
    *
-   * `offset` drops the depth-buffer search - a fixed number of texture fetches
-   * per water pixel - and displaces the screen UV by the wave normal instead.
-   * The water still refracts, but to the wrong point: a submerged silhouette
-   * smears rather than holding still. Set it on hardware that cannot afford the
-   * search.
+   * `offset` skips the depth-buffer search and displaces the screen UV by the
+   * wave normal instead: cheaper, but submerged silhouettes smear. For hardware
+   * that cannot afford the search.
    */ get refractionMode() {
         return this.material.refractionMode;
     }
@@ -457,9 +610,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
    * Depth in meters the cheap refraction mode assumes the water is, used only
    * when {@link refractionMode} is `offset`.
    *
-   * Sets how strong the cheap distortion looks. A constant rather than the real
-   * distance to the bottom, because an offset scaled by that distance paints a
-   * second copy of anything breaking the surface.
+   * Sets how strong the cheap distortion looks. A constant, because an offset
+   * scaled by the real depth paints a second copy of anything breaking the surface.
    */ get cheapRefractionDepth() {
         return this.material.cheapRefractionDepth;
     }
@@ -514,15 +666,10 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /**
    * Artistic scale on the refracted view offset. 1 is physical, 0 disables it.
    *
-   * The offset itself is derived: the view ray is refracted at the surface by
-   * Snell's law, walked to whatever is behind the water, and the hit point is
-   * projected back to the screen. That already accounts for the incidence angle,
-   * the depth of the receiver and the perspective foreshortening, so this exists
-   * only to dial the result back for a stylised look - not to make it correct.
-   *
-   * Values above 1 exaggerate; the surface stays continuous, but the sample can
-   * wander far enough from the true hit point that the medium tint stops
-   * matching what is visible through it.
+   * The offset comes from refracting the view ray by Snell's law and projecting
+   * its hit point back to the screen; this only dials it for a stylised look.
+   * Values above 1 exaggerate, and the medium tint may stop matching what is
+   * visible through the water.
    */ get refractionScale() {
         return this.material.refractionScale;
     }
@@ -532,11 +679,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /**
    * Scale on the Fresnel reflectance, 1 for the physical value.
    *
-   * Below 1 the surface reflects less than it should and shows more of what is
-   * beneath it. Water reflects almost everything at a grazing angle, which is
-   * physically right but can bury a sea bed the shot is about; this is the knob
-   * that trades that reflection away. The F0 floor is scaled with it, so 0 gives
-   * a surface with no specular response at all.
+   * Below 1 the surface reflects less and shows more of what is beneath it. The
+   * F0 floor is scaled with it, so 0 gives no specular response at all.
    */ get reflectionStrength() {
         return this.material.reflectionStrength;
     }
@@ -546,9 +690,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /**
    * How much of a folded texel reads as foam.
    *
-   * The wave generator reports where the surface has folded over on itself,
-   * which is a measure of the fold rather than of area; this scales it into a
-   * coverage fraction. 0 disables foam.
+   * Scales the wave generator's fold measure into a coverage fraction. 0
+   * disables foam.
    */ get foamAmount() {
         return this.material.foamAmount;
     }
@@ -558,9 +701,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /**
    * Falloff applied to foam coverage before it is scaled.
    *
-   * Above 1 this pushes light folding towards no foam at all, so only a crest
-   * that has genuinely broken shows any - which is what keeps a windy sea from
-   * turning uniformly white.
+   * Above 1 this pushes light folding towards no foam, so only broken crests
+   * show any.
    */ get foamFalloff() {
         return this.material.foamFalloff;
     }
@@ -576,38 +718,46 @@ import { BoundingBox } from '../utility/bounding_volume.js';
     /** {@inheritDoc SceneNode.update} */ update(frameId, elapsedInSeconds) {
         if (this.material.needUpdate()) {
             this.scene?.queueUpdateNode(this);
+            if (this.hidden) {
+                // Nothing shows the waves, the interaction or the foam: leave them be, and
+                // pick the phase up from here once the water shows again
+                this._lastUpdateTime = elapsedInSeconds;
+                return;
+            }
             if (this._timeStart === 0) {
                 this._timeStart = elapsedInSeconds;
             }
-            // A running clock rather than `elapsed * speed`: scaling the absolute
-            // elapsed time by the speed makes a speed of zero freeze the surface at
-            // the origin of the timeline instead of where it is, so pausing snapped
-            // the waves back to their first frame. Accumulating the delta keeps the
-            // phase where it was, and a speed of zero simply stops advancing it.
+            // Accumulate the scaled delta so a speed of zero freezes the phase in place.
             this._waveTime += Math.max(0, elapsedInSeconds - Math.max(this._timeStart, this._lastUpdateTime)) * this._animationSpeed;
             this._lastUpdateTime = elapsedInSeconds;
+            const interaction = this.material.interaction;
+            if (interaction) {
+                interaction.resolveNodes(this.scene);
+                interaction.setWaterLevel(this.worldMatrix.m13);
+            }
             this.material.update(frameId, this._waveTime);
             this.invalidateWorldBoundingVolume(false);
         }
     }
     /** {@inheritDoc SceneNode.updatePerCamera} */ updatePerCamera(camera, _elapsedInSeconds, _deltaInSeconds) {
         const mat = this._material.get();
+        if (mat && this.hidden) {
+            // Not drawn: no surface to gather, no shore or foam field to step
+            this.scene?.queuePerCameraUpdateNode(this);
+            return;
+        }
         if (mat) {
             const that = this;
             const infinite = mat.infinite;
             let viewDistance = 0;
             if (infinite) {
                 viewDistance = this._viewDistance > 0 ? this._viewDistance : this.horizonDistance(camera);
-                // The skirt's outer edge sits beyond where the surface is tessellated,
-                // so the band between them is what hides the last ring of geometry.
+                // The skirt's outer edge sits beyond the tessellated surface to hide its last ring.
                 mat.setSkirtDistance(viewDistance * SKIRT_DISTANCE_FACTOR);
             }
             this._renderData = this._clipmap.gather({
                 camera,
-                // An unbounded surface is not clipped to the node's extent, and the
-                // region rectangle is what the clipmap would otherwise reject tiles
-                // against. The material's own default is already this whole-domain
-                // value; passing it keeps the two agreeing.
+                // An unbounded surface is not clipped to the node's region.
                 minMaxWorldPos: infinite ? WHOLE_DOMAIN : mat.region,
                 gridScale: Math.max(0.01, this._gridScale),
                 userData: this,
@@ -616,8 +766,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
                 skirt: infinite,
                 calcAABB (userData, minX, maxX, minZ, maxZ, outAABB) {
                     const p = that.worldMatrix.transformPointAffine(Vector3.zero());
-                    if (that.waveGenerator) {
-                        that.waveGenerator.calcClipmapTileAABB(minX, maxX, minZ, maxZ, p.y, outAABB);
+                    if (mat.waveGenerator) {
+                        mat.waveGenerator.calcClipmapTileAABB(minX, maxX, minZ, maxZ, p.y, outAABB);
                     } else {
                         outAABB.minPoint.setXYZ(minX, p.y, minZ);
                         outAABB.maxPoint.setXYZ(maxX, p.y + 1, maxZ);
@@ -625,25 +775,135 @@ import { BoundingBox } from '../utility/bounding_volume.js';
                 }
             });
             this.updateSubmergence(camera, mat);
+            const interaction = mat.interaction;
+            const wantsDepth = !!interaction && interaction.shallowDepth > 0;
+            if ((mat.shoreWaveHeight > 0 || wantsDepth) && this.scene?.sdf.enabled) {
+                // The interaction field and the shore waves read the waterline at the rest level
+                this.scene.sdf.global?.waterline.request(this.worldMatrix.m13);
+            }
+            if (mat.shoreWaveHeight > 0) {
+                // The waves and the beach's foam follow the terrain alone, in levels
+                // out to the foam field's reach; the foam against walls, rocks and
+                // piers the scene field's single level. Without a terrain the scene
+                // field shapes the waves too.
+                const terrainField = this.updateShoreField(camera);
+                const waterline = this.scene?.sdf.enabled ? this.scene.sdf.global?.waterline : null;
+                const wall = waterline?.ready ? waterline : null;
+                const shore = terrainField?.ready ? terrainField : terrainField ? null : wall;
+                mat.setShoreWaveFrame(shore?.smoothTexture ?? null, shore?.regions ?? NO_REGIONS, wall?.smoothTexture ?? null, wall?.region ?? NO_REGIONS[0], this.worldMatrix.m13);
+            }
+            if (interaction) {
+                interaction.setBathymetry(wantsDepth ? this.findBathymetry() : null);
+            }
+            if (interaction && interaction.followMode === 'camera') {
+                const focus = this.viewFocus(camera, interaction.windowSize * 0.5);
+                interaction.setFocus(focus.x, focus.y);
+            }
+            // After the shore waves' frame, which the foam field's sources read
+            const foamFocus = this.viewFocus(camera, mat.foamFieldSize * 0.5);
+            RenderGraphExecutor.profileScope('WaterFoamField', ()=>mat.updateFoamField(foamFocus.x, foamFocus.y));
             this.scene?.queuePerCameraUpdateNode(this);
         }
     }
     /**
+   * Where the interaction field reads the depth of the water: the scene
+   * field's waterline grid when there is one, else the first terrain's height
+   * map, else nothing.
+   * @internal
+   */ findBathymetry() {
+        const level = this.worldMatrix.m13;
+        const waterline = this.scene?.sdf.enabled ? this.scene.sdf.global?.waterline : null;
+        if (waterline?.ready && waterline.texture) {
+            const r = waterline.region;
+            return {
+                kind: 'field',
+                texture: waterline.texture,
+                region: [
+                    r.x,
+                    r.y,
+                    r.z * r.w,
+                    r.z * r.w
+                ],
+                level
+            };
+        }
+        let terrain = this.findTerrain();
+        const heightMap = terrain?.heightMap;
+        if (!terrain || !heightMap) {
+            return null;
+        }
+        const region = terrain.worldRegion;
+        return {
+            kind: 'height',
+            texture: heightMap,
+            region: [
+                region.x,
+                region.y,
+                region.z - region.x,
+                region.w - region.y
+            ],
+            level,
+            heightScale: Math.abs(terrain.scale.y),
+            heightOffset: terrain.worldMatrix.m13
+        };
+    }
+    /** The first terrain in the scene, cached while it stays in it. @internal */ findTerrain() {
+        let terrain = this._bathyTerrain?.attached && this._bathyTerrain.scene === this.scene ? this._bathyTerrain : null;
+        if (!terrain && this.scene) {
+            this.scene.rootNode.iterate((node)=>{
+                if (node.isClipmapTerrain()) {
+                    terrain = node;
+                    return true;
+                }
+                return false;
+            });
+            this._bathyTerrain = terrain;
+        }
+        return terrain;
+    }
+    /**
+   * Rebuilds the shore field, the waterline of the terrain alone in levels
+   * around the camera, which the shore waves read, and returns it. Null
+   * without a terrain or off WebGPU.
+   * @internal
+   */ updateShoreField(camera) {
+        const terrain = this.findTerrain();
+        const device = getDevice();
+        if (!terrain?.heightMap || device.type !== 'webgpu') {
+            return null;
+        }
+        if (!this._shoreField) {
+            this._shoreSource = new TerrainWaterlineSource();
+            this._shoreField = new WaterlineField(this._shoreSource, {
+                levels: SHORE_FIELD_LEVELS,
+                resolution: SHORE_FIELD_CELLS,
+                cellSize: SHORE_FIELD_CELL_SIZE,
+                maxRebuilds: SHORE_FIELD_REBUILDS
+            });
+        }
+        this._shoreSource.setTerrain(terrain);
+        this._shoreField.request(this.worldMatrix.m13);
+        device.pushDeviceStates();
+        try {
+            RenderGraphExecutor.profileScope('WaterShoreField', ()=>this._shoreField.update(camera.getWorldPosition()));
+        } finally{
+            device.popDeviceStates();
+        }
+        return this._shoreField;
+    }
+    /** @internal */ _shoreSource = null;
+    /** @internal */ _shoreField = null;
+    /** @internal */ _bathyTerrain = null;
+    /**
    * Decide whether `camera` is inside this body of water and publish the result.
    *
-   * Run from `updatePerCamera`, which the node re-queues every frame regardless
-   * of culling - the state has to survive the surface leaving the frustum, which
-   * is exactly what a camera on the sea bed looking down does to it.
-   *
-   * The test is against the rest plane rather than the displaced surface. Reading
-   * the real wave height means a GPU readback ({@link Water.getSurfacePoint}) and
-   * the frame or two of latency that comes with it; against that, the plane is
-   * wrong only while the eye is within a wave height of the surface, which is
-   * also the one case this feature deliberately does not try to render.
+   * Run from `updatePerCamera`, which runs every frame regardless of culling, so
+   * the state survives the surface leaving the frustum.
    *
-   * A dead band of {@link WaterMaterial.underwaterHysteresis} around the plane
-   * keeps an eye parked at water level from flipping state every frame: crossing
-   * in has to reach below the band, crossing out has to reach above it.
+   * The test is against the rest plane rather than the displaced surface, which
+   * would need a GPU readback. A dead band of
+   * {@link WaterMaterial.underwaterHysteresis} around the plane keeps an eye at
+   * water level from flipping state every frame.
    * @internal
    */ updateSubmergence(camera, mat) {
         const surfaceY = this.worldMatrix.transformPointAffine(Vector3.zero()).y;
@@ -651,9 +911,7 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         if (!this.hidden && this.attached) {
             const camPos = camera.getWorldPosition();
             const region = mat.region;
-            // An unbounded surface has no edge to fall outside of; a bounded one is
-            // only entered from within its own footprint, so a camera beside a pool at
-            // the height of its water is not in it.
+            // A bounded surface is only entered from within its own footprint.
             const inside = mat.infinite || camPos.x >= region.x && camPos.x <= region.z && camPos.z >= region.y && camPos.z <= region.w;
             if (inside) {
                 const band = mat.underwaterHysteresis;
@@ -664,19 +922,44 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         setWaterSubmergence(camera, this, submerged, surfaceY);
     }
     /**
+   * The water the camera is looking at, on which a window that follows the
+   * view (the interaction field, the foam field) is centred.
+   *
+   * Where the view direction meets the rest plane, no further ahead than
+   * `reach` (half a window), so the window covers the visible water rather
+   * than putting it in the sponge band at its edge.
+   * @internal
+   */ viewFocus(camera, reach) {
+        const camPos = camera.getWorldPosition();
+        const m = camera.worldMatrix;
+        // The camera looks down its local -Z.
+        const fx = -m.m02;
+        const fy = -m.m12;
+        const fz = -m.m22;
+        const horizontal = Math.hypot(fx, fz);
+        let ahead = reach;
+        if (fy < -1e-4) {
+            const t = (this.worldMatrix.m13 - camPos.y) / fy;
+            if (t > 0) {
+                ahead = Math.min(reach, t * horizontal);
+            }
+        }
+        if (horizontal < 1e-6) {
+            return new Vector2(camPos.x, camPos.z);
+        }
+        return new Vector2(camPos.x + fx / horizontal * ahead, camPos.z + fz / horizontal * ahead);
+    }
+    /**
    * Distance to the true horizon for the camera's height above this water, in
    * meters.
    *
    * `sqrt(2 * R * h)` for earth's radius: about 5km from an eye 2m up, 25km
-   * from 50m. Using the real figure rather than a constant is what makes the
-   * horizon move correctly as the camera climbs, which is most of what sells
-   * the scale of an ocean.
+   * from 50m.
    * @internal
    */ horizonDistance(camera) {
         const camPos = camera.getWorldPosition();
         const waterLevel = this.worldMatrix.transformPointAffine(Vector3.zero()).y;
-        // A camera below the surface still needs a surface to look at; the floor
-        // also keeps the sqrt away from zero when the eye is exactly at water level.
+        // Floored for cameras at or below the surface.
         const height = Math.max(camPos.y - waterLevel, MIN_HORIZON_EYE_HEIGHT);
         return Math.sqrt(2 * EARTH_RADIUS * height);
     }
@@ -719,11 +1002,6 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         return this._material.get()?.needSceneDepth() ?? false;
     }
     /**
-   * {@inheritDoc Drawable.needHiZNearest}
-   */ needHiZNearest() {
-        return this._material.get()?.needHiZNearest() ?? false;
-    }
-    /**
    * {@inheritDoc Drawable.getMaterial}
    */ getMaterial() {
         return this._material.get();
@@ -749,10 +1027,8 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         const p = this.worldMatrix.transformPointAffine(Vector3.zero());
         const mat = this._material?.get();
         if (mat) {
-            // An unbounded surface has no box to test. Null reaches the cull visitor
-            // as ClipState.CLIPPED, which keeps the node in the queue and defers the
-            // decision to the clipmap's per-tile culling - the only place that can
-            // decide it, since the surface is built around wherever the camera is.
+            // Null keeps an unbounded surface in the queue (ClipState.CLIPPED) and
+            // leaves culling to the clipmap's per-tile test.
             if (mat.infinite) {
                 return null;
             }
@@ -803,7 +1079,7 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         const mat = this._material?.get();
         if (mat) {
             this.bind(ctx, renderQueue);
-            mat.setClipmapGridInfo(this._gridScale, this.worldMatrix.m03, this.worldMatrix.m23);
+            mat.setClipmapGridInfo(this._gridScale, this.worldMatrix.m03, this.worldMatrix.m23, this._clipmap.tileResolution);
             mat.apply(ctx);
             for (const info of this._renderData){
                 mat.draw(info.primitive, ctx, info.numInstances);
@@ -811,99 +1087,185 @@ import { BoundingBox } from '../utility/bounding_volume.js';
         }
     }
     /**
-   * Retreive the disturbed world position and normal at water surface
-   */ async getSurfacePoint(points, outPos, outNorm) {
+   * Retrieve the disturbed world position and normal at water surface.
+   * Set includeDisturbers to false for buoyancy: retain ambient waves and
+   * external impulses, but exclude waves generated by moving disturbers.
+   */ async getSurfacePoint(points, outPos, outNorm, includeDisturbers = true) {
+        if (!outPos && !outNorm) {
+            return;
+        }
+        const hits = await this._evaluateSurfacePoints(points, !!outNorm, includeDisturbers);
+        if (!hits) {
+            return;
+        }
+        for(let i = 0; i < points.length; i++){
+            outPos && outPos[i].setXYZ(hits[i].x, hits[i].y, hits[i].z);
+            outNorm && outNorm[i].setXYZ(hits[i].nx, hits[i].ny, hits[i].nz);
+        }
+    }
+    /**
+   * Evaluate the disturbed surface over a set of world XZ positions.
+   *
+   * Evaluated by the same wave generator the material draws with, so it is
+   * exact by construction. Costs one point-list draw plus one readback per call.
+   * Requests are serialized because the vertex buffer and render target are
+   * shared.
+   *
+   * @param points - World XZ positions to evaluate. Y is ignored.
+   * @param withNormal - Whether to also read the surface normal back, which
+   * costs a second readback of the same size.
+   * @returns One hit per input point, or null if `points` was empty.
+   * @internal
+   */ async _evaluateSurfacePoints(points, withNormal, includeDisturbers = true) {
         const device = getDevice();
         if (!points || points.length === 0) {
-            return;
+            return null;
         }
         points = points.map((v)=>v.clone());
-        await device.runNextFrameAsync(async ()=>{
-            if (!this._feedbackProgram.get()) {
-                this._feedbackProgram.set(this._createFeedbackProgram(device));
-                this._feedbackBindGroup.set(device.createBindGroup(this._feedbackProgram.get().bindGroupLayouts[0]));
-            }
-            if (!this._feedbackPrimitive.get()) {
-                this._feedbackPrimitive.set(new Primitive());
-                this._feedbackPrimitive.get().primitiveType = 'point-list';
-            }
-            if (!this._feedbackRenderStates) {
-                this._feedbackRenderStates = device.createRenderStateSet();
-                this._feedbackRenderStates.useDepthState().enableTest(false).enableWrite(false);
-                this._feedbackRenderStates.useRasterizerState().setCullMode('none');
-            }
-            const primitive = this._feedbackPrimitive.get();
-            const vertices = new Float32Array(points.length * 4);
-            for(let i = 0; i < points.length; i++){
-                vertices[i * 4 + 0] = points[i].x;
-                vertices[i * 4 + 1] = points[i].y;
-                vertices[i * 4 + 2] = points[i].z;
-                vertices[i * 4 + 3] = i;
-            }
-            let vb = primitive.getVertexBuffer('position');
-            if (!vb || vb.byteLength !== vertices.byteLength) {
-                vb = device.createVertexBuffer('position_f32x4', vertices, {
-                    dynamic: true
-                });
-                primitive.setVertexBuffer(vb);
-            } else {
-                vb.bufferSubData(0, vertices);
-            }
-            const fb = this._feedbackRenderTarget.get();
-            if (!fb || fb.getColorAttachment(0).width < points.length) {
-                const rt0 = device.createTexture2D('rgba32f', points.length, 1, {
-                    mipmapping: false
-                });
-                const rt1 = device.createTexture2D('rgba32f', points.length, 1, {
-                    mipmapping: false
-                });
-                if (fb) {
-                    fb.getColorAttachment(0).dispose();
-                    fb.getColorAttachment(1).dispose();
-                    this._feedbackRenderTarget.dispose();
+        const timing = {
+            issued: device.frameInfo.frameCounter,
+            recorded: 0,
+            mapped: 0
+        };
+        // Take and replace the queue's tail in one synchronous step before awaiting,
+        // so two callers arriving together cannot both pass the same settled tail.
+        const previous = this._feedbackQueue;
+        let release = ()=>{};
+        this._feedbackQueue = new Promise((resolve)=>release = resolve);
+        await previous;
+        const hits = points.map(()=>({
+                x: 0,
+                y: 0,
+                z: 0,
+                nx: 0,
+                ny: 1,
+                nz: 0
+            }));
+        try {
+            await device.runNextFrameAsync(async ()=>{
+                timing.recorded = device.frameInfo.frameCounter;
+                const renderedGenerator = this.material.waveGenerator;
+                const waveGenerator = !includeDisturbers && renderedGenerator instanceof InteractiveWaveGenerator ? new InteractiveWaveGenerator(renderedGenerator.base, renderedGenerator.interaction, false) : renderedGenerator;
+                const feedbackHash = waveGenerator?.getHash() ?? '';
+                if (this._feedbackProgram.get() && this._feedbackHash !== feedbackHash) {
+                    // The wave generator changed; rebuild the program for it.
+                    this._feedbackBindGroup.dispose();
+                    this._feedbackProgram.dispose();
                 }
-                this._feedbackRenderTarget.set(device.createFrameBuffer([
-                    rt0,
-                    rt1
-                ], null));
-            }
-            primitive.indexCount = points.length;
-            const bindGroup = this._feedbackBindGroup.get();
-            bindGroup.setValue('textureWidth', this._feedbackRenderTarget.get().getWidth());
-            this.waveGenerator.applyWaterBindGroup(bindGroup);
-            device.pushDeviceStates();
-            device.setProgram(this._feedbackProgram.get());
-            device.setBindGroup(0, this._feedbackBindGroup.get());
-            device.setFramebuffer(this._feedbackRenderTarget.get());
-            this._feedbackPrimitive.get().draw();
-            device.popDeviceStates();
-            const pos = new Float32Array(points.length * 4);
-            const norm = new Float32Array(points.length * 4);
-            await Promise.all([
-                this._feedbackRenderTarget.get().getColorAttachment(0).readPixels(0, 0, points.length, 1, 0, 0, pos),
-                this._feedbackRenderTarget.get().getColorAttachment(1).readPixels(0, 0, points.length, 1, 0, 0, norm)
-            ]);
-            for(let i = 0; i < points.length; i++){
-                if (outPos) {
-                    outPos[i].setXYZ(pos[i * 4 + 0], pos[i * 4 + 1], pos[i * 4 + 2]);
+                if (!this._feedbackProgram.get()) {
+                    this._feedbackHash = feedbackHash;
+                    this._feedbackProgram.set(this._createFeedbackProgram(device, waveGenerator));
+                    this._feedbackBindGroup.set(device.createBindGroup(this._feedbackProgram.get().bindGroupLayouts[0]));
                 }
-                if (outNorm) {
-                    outNorm[i].setXYZ(norm[i * 4 + 0], norm[i * 4 + 1], norm[i * 4 + 2]);
+                if (!this._feedbackPrimitive.get()) {
+                    this._feedbackPrimitive.set(new Primitive());
+                    this._feedbackPrimitive.get().primitiveType = 'point-list';
                 }
-            }
-        });
+                if (!this._feedbackRenderStates) {
+                    this._feedbackRenderStates = device.createRenderStateSet();
+                    this._feedbackRenderStates.useDepthState().enableTest(false).enableWrite(false);
+                    this._feedbackRenderStates.useRasterizerState().setCullMode('none');
+                }
+                const primitive = this._feedbackPrimitive.get();
+                const vertices = new Float32Array(points.length * 4);
+                // The generators displace from the still-water level, so it replaces the caller's Y.
+                const level = this.worldMatrix.m13;
+                for(let i = 0; i < points.length; i++){
+                    vertices[i * 4 + 0] = points[i].x;
+                    vertices[i * 4 + 1] = level;
+                    vertices[i * 4 + 2] = points[i].z;
+                    vertices[i * 4 + 3] = i;
+                }
+                let vb = primitive.getVertexBuffer('position');
+                if (!vb || vb.byteLength !== vertices.byteLength) {
+                    vb = device.createVertexBuffer('position_f32x4', vertices, {
+                        dynamic: true
+                    });
+                    primitive.setVertexBuffer(vb);
+                } else {
+                    vb.bufferSubData(0, vertices);
+                }
+                const fb = this._feedbackRenderTarget.get();
+                if (!fb || fb.getColorAttachment(0).width < points.length) {
+                    const rt0 = device.createTexture2D('rgba32f', points.length, 1, {
+                        mipmapping: false
+                    });
+                    const rt1 = device.createTexture2D('rgba32f', points.length, 1, {
+                        mipmapping: false
+                    });
+                    if (fb) {
+                        fb.getColorAttachment(0).dispose();
+                        fb.getColorAttachment(1).dispose();
+                        this._feedbackRenderTarget.dispose();
+                    }
+                    this._feedbackRenderTarget.set(device.createFrameBuffer([
+                        rt0,
+                        rt1
+                    ], null));
+                }
+                primitive.indexCount = points.length;
+                const bindGroup = this._feedbackBindGroup.get();
+                bindGroup.setValue('textureWidth', this._feedbackRenderTarget.get().getWidth());
+                if (waveGenerator) {
+                    waveGenerator.applyWaterBindGroup(bindGroup);
+                    ShaderHelper.setStandaloneCameraTime(bindGroup);
+                }
+                device.pushDeviceStates();
+                device.setProgram(this._feedbackProgram.get());
+                device.setBindGroup(0, this._feedbackBindGroup.get());
+                device.setFramebuffer(this._feedbackRenderTarget.get());
+                this._feedbackPrimitive.get().draw();
+                device.popDeviceStates();
+                const pos = new Float32Array(points.length * 4);
+                // The normal attachment is only read when wanted, halving the readback otherwise.
+                const norm = withNormal ? new Float32Array(points.length * 4) : null;
+                // readPixels records its copy synchronously; flushing right after lets the
+                // readback start before this frame's main render is recorded. This runs from
+                // beginFrame, so the submit carries only the feedback work.
+                const readPos = this._feedbackRenderTarget.get().getColorAttachment(0).readPixels(0, 0, points.length, 1, 0, 0, pos);
+                const readNorm = norm ? this._feedbackRenderTarget.get().getColorAttachment(1).readPixels(0, 0, points.length, 1, 0, 0, norm) : Promise.resolve();
+                device.flush();
+                await Promise.all([
+                    readPos,
+                    readNorm
+                ]);
+                timing.mapped = device.frameInfo.frameCounter;
+                this.lastFeedbackTiming = timing;
+                for(let i = 0; i < points.length; i++){
+                    hits[i].x = pos[i * 4 + 0];
+                    hits[i].y = pos[i * 4 + 1];
+                    hits[i].z = pos[i * 4 + 2];
+                    if (norm) {
+                        hits[i].nx = norm[i * 4 + 0];
+                        hits[i].ny = norm[i * 4 + 1];
+                        hits[i].nz = norm[i * 4 + 2];
+                    }
+                }
+            });
+        } finally{
+            release();
+        }
+        return hits;
     }
-    /** @internal */ _createFeedbackProgram(device) {
-        const that = this;
+    /** @internal */ _createFeedbackProgram(device, waveGenerator) {
         const program = device.buildRenderProgram({
             vertex (pb) {
                 this.$inputs.position = pb.vec4().attrib('position');
                 this.textureWidth = pb.float().uniform(0);
-                that.waveGenerator.setupUniforms(this, 0);
+                if (waveGenerator) {
+                    waveGenerator.setupUniforms(this, 0);
+                    // Wave generators animate from camera.elapsedTime, declared standalone here
+                    ShaderHelper.declareStandaloneCameraTime(this, 0);
+                }
                 pb.main(function() {
-                    this.$l.worldPos = pb.vec3();
-                    this.$l.worldNorm = pb.vec3();
-                    that.waveGenerator.calcVertexPositionAndNormal(this, this.$inputs.position.xyz, this.worldPos, this.worldNorm);
+                    if (waveGenerator) {
+                        this.$l.worldPos = pb.vec3();
+                        this.$l.worldNorm = pb.vec3();
+                        waveGenerator.calcVertexPositionAndNormal(this, this.$inputs.position.xyz, this.worldPos, this.worldNorm);
+                    } else {
+                        this.$l.worldPos = this.$inputs.position.xyz;
+                        this.$l.worldNorm = pb.vec3(0, 1, 0);
+                    }
                     this.$outputs.worldPos = this.worldPos;
                     this.$outputs.worldNorm = this.worldNorm;
                     this.$outputs.xz = this.$inputs.position.xz;
@@ -917,10 +1279,13 @@ import { BoundingBox } from '../utility/bounding_volume.js';
             fragment (pb) {
                 this.$outputs.worldPos = pb.vec4();
                 this.$outputs.worldNorm = pb.vec4();
-                that.waveGenerator.setupUniforms(this, 0);
+                if (waveGenerator) {
+                    waveGenerator.setupUniforms(this, 0);
+                    ShaderHelper.declareStandaloneCameraTime(this, 0);
+                }
                 pb.main(function() {
                     this.$outputs.worldPos = pb.vec4(this.$inputs.worldPos, 1);
-                    this.$outputs.worldNorm = pb.vec4(that.waveGenerator.calcFragmentNormal(this, this.$inputs.xz, this.$inputs.worldNorm), 1);
+                    this.$outputs.worldNorm = waveGenerator ? pb.vec4(waveGenerator.calcFragmentNormal(this, this.$inputs.xz, this.$inputs.worldNorm), 1) : pb.vec4(0, 1, 0, 1);
                 });
             }
         });