# Ocean Swell

Aperveil / Light, shaped for the web.

A calm ocean background for React with directional swell and a visible horizon. Tune wave shape, roughness and sky colors, then export the WebGPU scene.

[Aperveil integration guide](https://www.aperveil.com/docs)

## What it does

Ocean Swell combines directional waves, analytic surface slopes and a bounded surface intersection to render water beneath a sky. Detail is controlled with distance to keep the horizon calmer.

## Choose it for

Open a travel or wellbeing page with a quiet horizon. Place the heading in the sky and keep the water visible across the lower part of the viewport.

## Limits

There is no mouse interaction, buoyancy system, foam simulation or FFT ocean spectrum. It is a self-contained procedural scene for interfaces.

## Current look

Default. Color Looks change colors only; motion, geometry and typography remain unchanged.

[Open editor](https://www.aperveil.com/shaders/ocean-swell/edit?look=default)

## Install

Download the Export Kit from the editor. No shader-specific npm package or CLI is published yet.

```sh
npm install ./vendor/aperveil-runtime-0.1.0.tgz ./vendor/aperveil-react-0.1.0.tgz
```

Every control in the editor is a typed prop. Leave a prop out to keep the value you exported; change one and the running shader updates without restarting. Give the surface a size and pass fallback for browsers without WebGPU.

```tsx
"use client";

import OceanSwell from "./OceanSwell";

export default function Hero() {
  return (
    <OceanSwell
      className="hero-shader"
      waveHeight={0.45} deepColor="#041923ff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

// .hero-shader { width: 100%; height: 560px; }
```

Component props: `deepColor`, `shallowColor`, `skyColor`, `highlightColor`, `waveHeight`, `waveScale`, `waveDirection`, `crestSharpness`, `horizon`, `roughness`, `flowSpeed`, `opacity`, `className`, `style`, `paused`, `fallback`, `onReady`, `onError`.

Raw WGSL is included for a custom WebGPU host; it is not CSS. Keep semantic headings and links in HTML.

## Controls

- Deep water (`deepColor`, color): Colour of the water body.
- Shallow water (`shallowColor`, color): Lighter water colour on the faces of the swells.
- Sky reflection (`skyColor`, color): Colour of the sky reflected on the water and the haze at the horizon.
- Specular light (`highlightColor`, color): Colour of the sun's glints on the water.
- Wave height (`waveHeight`, slider): How tall the swells are.
- Wavelength (`waveScale`, slider): Length of the swells; higher values give longer waves.
- Wave direction (`waveDirection`, slider): Direction the swells travel, in radians.
- Crest sharpness (`crestSharpness`, slider): How peaked the wave crests are; 1 gives rounded swells.
- Horizon height (`horizon`, slider): Height of the horizon in the frame.
- Roughness (`roughness`, slider): How soft and spread the reflections on the water are.
- Wave speed (`flowSpeed`, slider): How fast the waves move.
- Opacity (`opacity`, slider): Opacity of the complete effect, including its background.

## Compatibility

WebGPU rendering requires a supported browser and secure context. The landing shows a real poster for the selected Look when live rendering is unavailable. The standard exported component does not bundle a poster fallback. Supply your own fallback in the host layout. Text exports also retain readable HTML typography.

## Performance

2.818 ms GPU timestamp median; p95 3.342 ms. 1440x900 @ dpr 2; Metal driver on macOS Version 26.6.2 (Build 25G83); measured 2026-09-05. This is a recorded headless sample, not a browser FPS or mobile-performance guarantee.

## Questions

### Does Ocean Swell react to the mouse?

No. The surface advances with time. Wave height, direction, wavelength, crest sharpness and speed are editor controls, not pointer inputs.

### How can I keep the ocean calm behind a headline?

Start with a lower Wave height and a slower Wave speed. Wavelength and Roughness change the shape and fine appearance of the water. Adjust Horizon height to give the heading space; this is an artistic scene, not a forecast of sea conditions.

### What should I not use Ocean Swell for?

There is no mouse interaction, buoyancy system, foam simulation or FFT ocean spectrum. It is a self-contained procedural scene for interfaces.

### What happens without WebGPU?

This landing shows a still poster of your selected Color Look. The raw WGSL needs a WebGPU host. Landing posters are not bundled in the Export Kit: add your own fallback around the exported component.

### Can I use this shader commercially?

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## License

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## Related shaders

- [Caustics](https://www.aperveil.com/shaders/caustics)
- [Aurora Drift](https://www.aperveil.com/shaders/aurora-drift)
- [Grain Gradient](https://www.aperveil.com/shaders/grain-gradient)