wave_screen library

Composable, GPU-shader-driven animated wave surfaces for Flutter.

Classes

DriftMotion

Linear, endlessly travelling motion.

GerstnerWaveShape

A sharpened, Gerstner-style crest. The profile is a gamma-shaped sine: with steepness 0 it equals a sine; larger values narrow the crests and widen the troughs, approximating the trochoidal ocean look as a pure height field.

MetaballWaveShape

A gooey crest made of blobCount evenly-spaced blobs that drift with the motion phase. Each blob is a Gaussian bump of the given radius; blobs are combined with a smooth union so nearby blobs merge into one bulge peaking at amplitude, while distant blobs stay separate.

PingPongMotion

Smooth back-and-forth motion: the phase follows a sine of the elapsed time, easing to +sway and -sway once per period seconds.

PointerRippleEffect

A pointer-driven ripple. Placed in a Wave's effects, it makes the enclosing WaveField interactive: taps and drags spawn ripples that radiate out from the pointer and fade. The displacement is a pure function of position and age, so both the CPU and GPU paths — and tests — agree.

SineWaveShape

A pure single-frequency sine surface.

StillMotion

A wave that does not move.

Wave

A single wave surface, described entirely by swappable traits: shape (geometry), style (appearance), motion (time evolution), and composable effects. Compose several Waves in a WaveField to build a layered scene.

WaveEffect

A composable overlay applied to a wave — interaction (pointer ripples) or decoration (foam). The effect system is fleshed out in a later milestone; this base exists so Wave can already carry an (empty) effect list.

WaveField

Composites a list of Wave layers into a single animated surface. Rendering runs on the GPU via the wave fragment shader; a CPU path is used as a fallback so the field never blanks. When any wave carries a PointerRippleEffect the field becomes interactive: taps and drags spawn ripples that displace the surface, reported through onRipple as a normalized position.

WaveMotion

How a wave surface evolves over time. A motion contributes a phase (in radians) for a given time t (seconds); the shape turns that phase into a height. This keeps time-evolution a swappable trait, independent of geometry.

WavePresets

A broad, curated library of WaveScreenPresets spanning all shapes and the interactive ripple effect. Presets are reachable by name via byName or as an ordered list via all.

WaveScreen

A full-bleed animated wave background. Supply a curated WaveScreenPreset or build one inline with WaveScreen.custom. An optional child is layered on top of the waves.

WaveScreenPreset

A named, curated arrangement of a background and a stack of Wave layers, consumed by WaveScreen and produced by WavePresets.

WaveShape

The geometry trait of a wave: a height field sampled at a normalized horizontal position with a motion-supplied phase. The GPU shader mirrors this exact model so CPU-side sampleAt and the rendered surface agree.

WaveStyle

The appearance trait of a wave: how the surface is filled. Kept independent of geometry and motion so the same shape can be restyled freely.