# Tidewater

an FFT sea meeting a mirror-calm river under golden-hour rain.

```{raw} html
<a class="example-run-button" href="../demos/demos_tidewater.html">▶ Run in browser</a>

```

**Tags:** `3d` `ocean` `water` `river` `rain` `sky` `reflections` `showcase`

The render-modernization flagship. One cohesive coastal scene draws every new
rendering feature at once, each doing a real job rather than sitting in a
checklist:

* An open **FFT ocean** (``OceanSurface3D``, design D11) fills the horizon: a
  Tessendorf spectrum inverse-transformed each frame into rolling swell, choppy
  crests and wind-laced foam that curls around a rock stack out at sea.
* A **mirror-calm river** (``WaterSurface3D`` + ``PlanarReflection3D``, design
  D16 + RM-B4) runs between two wet rocky banks toward the sea. Its
  surface is a true planar mirror: the banks, the rain-slicked stones and the
  golden sky invert in it and track the world every frame, rippled by the small
  Gerstner swell and Fresnel-blended over the refraction below.
* A **dynamic procedural sky** (``sky_mode="procedural"``, design D12) is
  synthesized from the low golden-hour sun with a hazy turbidity, and drives
  both the sky background AND the image-based lighting the whole scene reflects.
* **Rain** (``Rain3D``, RM-E3) falls wind-slanted across the view, and the
  ``WorldEnvironment`` wetness/ripple channels turn every ``wetness_affected``
  rock dark and glossy with an animated puddle ripple on its up-faces. As they
  turn wet the stones drop roughness, so the procedural-sky **image-based
  lighting** mirrors the golden sky back off the slick banks.
* **Global illumination** grounds the shore with real indirect bounce: a baked
  ``IrradianceVolume3D`` (design D10) over the whole near shore lifts the shadowed
  undersides of the wet boulders with soft SH-L1 warmth from the rock and golden
  sky around them, while **SSGI** (``WorldEnvironment.ssgi_*``, design D8) adds the
  near-field, view-dependent colour bleed the screen already shows. Baked GI +
  screen-space GI, SSR and the planar mirror all run in the same frame.

A slow cinematic camera sways over the river mouth, looking downstream at the
sun-glinting sea. Press SPACE to pause the motion, ESC to quit.

SSR/SSGI NOTE: screen-space reflections (``WorldEnvironment.ssr_*``, design D7)
AND screen-space GI (``ssgi_*``, design D8) are both ON here and coexist with the
``PlanarReflection3D`` river in the same frame (the RM-BUG1 frame-order fix that
previously crashed this exact combination). SSR gives the wet shelf and boulders
crisp near-field reflections of the real scene geometry that IBL alone cannot,
composited over the golden-sky IBL specular without double-counting (design D8fix);
SSGI adds the soft indirect diffuse bounce; the planar-mirror river remains the
hero reflection. All three activate/read the thin G-buffer, which now also lives on
the offscreen RenderView target so the shared forward pipelines stay
render-pass-compatible.

WEB PARITY: the whole scene is now cross-backend. The FFT ocean (design D11) runs
on web too via its WebGPU Stockham-compute twin (RM-E7w / RM-G1), so the open sea
is an ``OceanSurface3D`` on both desktop and web. SSR + SSGI + the
``PlanarReflection3D`` river also coexist on the web renderer (RM-G14, the web
analogue of the desktop RM-BUG1 fix): when SSR/SSGI activate the thin G-buffer's
second forward attachment, the built-in water + ocean transparent pipelines pick up
a matching second, write-masked colour target so they stay render-pass-compatible
with the 2-attachment forward pass. The single-attachment path is untouched when the
G-buffer is off.


Usage:
    uv run python examples/demos/tidewater.py
    uv run python examples/demos/tidewater.py --test   # headless self-check

Controls:
    SPACE   - Pause / resume the camera motion
    ESC     - Quit

## Source

```{literalinclude} ../../examples/demos/tidewater.py
:language: python
:linenos:
```