@equinor/videx-3d 2.0.0 → 3.1.0

package/dist/src/sdk/materials/shaderLib/procedural-normal.glsl

@@ -0,0 +1,274 @@
+// Procedural (texture-free) normal-detail helpers.
+//
+// Pure functions - no uniforms, no varyings - so any material can reuse them by
+// supplying its own inputs and controls. Include this file in a FRAGMENT shader
+// (it relies on screen-space derivatives, dFdx/dFdy).
+//
+// Dependencies the consuming material must provide when calling perturbNormalHeight:
+//   - normal   : the shading normal to perturb, in VIEW space
+//   - viewPos  : the surface position in VIEW space (e.g. -vViewPosition)
+//   - height   : a scalar height field sampled at this fragment (produced by the
+//                pnGranular / pnGrain / pnScratches helpers below, summed); the caller
+//                scales it to taste (its "strength"/bump amount) and may fade it by
+//                distance
+// And when sampling a pattern height (pnGranular / pnGrain / pnScratches):
+//   - uv         : a 2D coordinate ALREADY scaled by the caller's frequency. The
+//                  caller owns the units (world distance, normalized, radius-based,
+//                  ...) and which axis maps to uv.y (the grain/stretch axis).
+//   - octaves    : fbm octave count for pnGranular / pnGrain (1..N). pnScratches is
+//                  segment-based and takes NO octave count.
+//   - periodX    : if > 0, the noise tiles seamlessly every `periodX` cells in x (pass
+//                  the number of cells around a circumference to remove the wrap seam
+//                  on a closed cylinder; pass 0 to disable). Tiling is exact for
+//                  granular and for grain/scratches at angle 0.
+// The patterns return scalar heights; combine several by summing (optionally weighted)
+// and feed the result to perturbNormalHeight.
+//
+// "width" of the features is controlled by the caller's frequency/anisotropy/angle
+// folded into uv; "height" of the bump is the caller-owned scalar passed to
+// perturbNormalHeight. No CPU data or vertex attributes are required beyond whatever
+// the material already uses to build its uv.
+
+// Lattice wrap period (cells). The value-noise lattice (and the scratch seed grid) repeat
+// every PN_WRAP cells per axis, so a caller that reduces a very large sample coordinate
+// into [0, PN_WRAP) - to keep floor()/fract() float-precise at oilfield scale, where
+// metres-along-trajectory x frequency reaches ~1e5 and fract() quantises into visible
+// banding - still tiles SEAMLESSLY at the wrap. Large enough (4096 cells) that the repeat
+// is invisible for fine detail; a no-op (mod = identity) for the small coords normal use
+// produces.
+#define PN_WRAP 4096.0
+
+// Precision-robust 2D->1D hash (Dave Hoskins). fract() is applied BEFORE any multiply/
+// dot so the working values stay in [0,1) - this survives the large sample coordinates
+// that occur at oilfield scale (a pattern sampled by metres-along-trajectory times a
+// frequency reaches ~1e5+), where the older fract(p*c) + dot(p, p) form overflowed
+// float32 precision so fract() returned near-constant values and the noise collapsed /
+// stretched with distance down the well.
+float pnHash2(vec2 p) {
+  vec3 p3 = fract(vec3(p.xyx) * 0.1031);
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.x + p3.y) * p3.z);
+}
+
+// 2D value noise (smoothstep-interpolated).
+float pnValueNoise2(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  // Wrap the integer lattice at PN_WRAP so the noise tiles seamlessly when a caller reduces
+  // a huge coordinate into [0, PN_WRAP) (identity for the small coords normal use produces).
+  vec2 i0 = mod(i, PN_WRAP);
+  vec2 i1 = mod(i + 1.0, PN_WRAP);
+  float a = pnHash2(i0);
+  float b = pnHash2(vec2(i1.x, i0.y));
+  float c = pnHash2(vec2(i0.x, i1.y));
+  float d = pnHash2(i1);
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+// Fractional Brownian motion with a dynamic (uniform-driven) octave count. The loop
+// bound is a compile-time constant (GLSL requirement); `octaves` clamps it at runtime.
+float pnFbm2(vec2 p, int octaves) {
+  float sum = 0.0;
+  float amp = 0.5;
+  float norm = 0.0;
+  for(int o = 0; o < 8; o++) {
+    if(o >= octaves)
+      break;
+    sum += amp * pnValueNoise2(p);
+    norm += amp;
+    p *= 2.02;
+    amp *= 0.5;
+  }
+  return norm > 0.0 ? sum / norm : 0.0;
+}
+
+// Tiling value noise: the integer lattice wraps at `periodX` cells in x, so a pattern
+// sampled over exactly `periodX` units in x is seamless (used to wrap around a
+// cylinder's circumference). y is not tiled.
+float pnValueNoise2Tiled(vec2 p, float periodX) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  float x0 = mod(i.x, periodX);
+  float x1 = mod(i.x + 1.0, periodX);
+  float y0 = mod(i.y, PN_WRAP);
+  float y1 = mod(i.y + 1.0, PN_WRAP);
+  float a = pnHash2(vec2(x0, y0));
+  float b = pnHash2(vec2(x1, y0));
+  float c = pnHash2(vec2(x0, y1));
+  float d = pnHash2(vec2(x1, y1));
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+// fbm on the x-tiling noise; lacunarity 2.0 so every octave's period stays integer.
+float pnFbm2Tiled(vec2 p, float periodX, int octaves) {
+  float sum = 0.0;
+  float amp = 0.5;
+  float norm = 0.0;
+  float per = max(periodX, 1.0);
+  for(int o = 0; o < 8; o++) {
+    if(o >= octaves)
+      break;
+    sum += amp * pnValueNoise2Tiled(p, per);
+    norm += amp;
+    p *= 2.0;
+    per *= 2.0;
+    amp *= 0.5;
+  }
+  return norm > 0.0 ? sum / norm : 0.0;
+}
+
+// fbm that tiles in x when periodX > 0, else plain (non-tiling) fbm.
+float pnFbm2Auto(vec2 p, int octaves, float periodX) {
+  return periodX > 0.5 ? pnFbm2Tiled(p, periodX, octaves) : pnFbm2(p, octaves);
+}
+
+// GRANULAR: isotropic value-noise bumps; `anisotropy` (0..1) stretches the cells along
+// uv.y. Signed height. periodX > 0 tiles x (e.g. a circumference).
+float pnGranular(vec2 uv, float anisotropy, int octaves, float periodX) {
+  vec2 p = vec2(uv.x, uv.y * mix(1.0, 0.04, anisotropy));
+  return pnFbm2Auto(p, octaves, periodX) - 0.5;
+}
+
+// BRUSHED: a directional fine grain - thin parallel ridges running at `angle` (radians;
+// 0 = along uv.y). `sharpness` (0..1) thins the ridges (their "width"); `uniformity`
+// (0..1) blends from an irregular grain to perfectly regular flutes. Positive height.
+// Tiling is exact only for angle == 0; other angles degrade gracefully (a faint seam).
+float pnGrain(vec2 uv, float angle, float sharpness, float uniformity, int octaves, float periodX) {
+  float ca = cos(angle), sa = sin(angle);
+  vec2 r = vec2(uv.x * ca - uv.y * sa, uv.x * sa + uv.y * ca);
+  float tile = abs(angle) < 1e-3 ? periodX : 0.0;
+  float n = pnFbm2Auto(vec2(r.x, r.y * 0.06), octaves, tile);
+  // Irregular grain (fbm-smooth, so it has no cusp to alias); `sharpness` thins the ridges.
+  float irregular = pow(1.0 - abs(2.0 * n - 1.0), mix(2.0, 8.0, clamp(sharpness, 0.0, 1.0)));
+  // Regular flutes: footprint-anti-aliased evenly-spaced ridges (period 1 in r.x). A
+  // smoothstep whose transition is never narrower than the pixel footprint (fwidth)
+  // keeps the ridge crisp up close WITHOUT the sharp cusp of the old (1-|sin|)^pow form
+  // - that cusp under-sampled the normal and shimmered even close up - and naturally
+  // band-limits into a flat tone once a flute drops below a pixel far away. `sharpness`
+  // sets the ridge width.
+  float dCentre = abs(r.x - floor(r.x + 0.5)); // 0 at a flute centre .. 0.5 between
+  float hw = mix(0.35, 0.05, clamp(sharpness, 0.0, 1.0));
+  float aaw = max(fwidth(r.x), 1e-4);
+  float regular = 1.0 - smoothstep(hw - aaw, hw + aaw, dCentre);
+  // Once a flute period approaches the pixel footprint (fwidth ~ 0.5, i.e. the sine is
+  // near screen-Nyquist at the grazing sides of the shell), flatten the flutes toward
+  // their duty-cycle mean (~2*hw). Without this the ridge stays a smooth-but-undersampled
+  // sine there and still shimmers even though the edges are footprint-AA'd.
+  regular = mix(regular, 2.0 * hw, smoothstep(0.3, 0.5, aaw));
+  return mix(irregular, regular, clamp(uniformity, 0.0, 1.0));
+}
+
+// SCRATCHES: sparse, thin grooves crossing at varied angles/lengths - a cell/segment
+// field rather than parallel lanes, so it reads like real scuffing. `density` (0..1) =
+// fraction of seed cells that carry a scratch; `angle` = orientation bias and `wander`
+// (0..1) widens the spread of directions around it (0 = all parallel, 1 = fully random);
+// `lengthScale` (>0) scales each groove's length; `halfWidth` sets the groove width in
+// sample (uv) units - pass (world-width x frequency) to get a FREQUENCY-INDEPENDENT width
+// so lowering the frequency lengthens/thins-out the scratches without widening them. Two
+// families are summed by pnScratches:
+// a fine layer (short/medium scratches) plus a coarse layer (fewer, much longer ones).
+// Each groove is analytically anti-aliased (edge widened to the pixel footprint).
+// Negative height.
+
+// One scratch "family": line segments seeded on an integer grid at the coordinate scale
+// of `r`. Each present cell (gated by `density`) spawns a groove with a random midpoint,
+// direction (biased toward `angle`, spread by `wander`), half-length, width and depth. A
+// 3x3 neighbourhood is scanned so segments crossing in from adjacent cells are caught;
+// half-length is capped below the search radius so grooves stay unbroken. `seed`
+// decorrelates layers; x wraps at `periodX` cells (when angle ~ 0) for a seamless
+// circumference seam.
+float pnScratchLayer(vec2 r, float angle, float density, float lengthScale, float halfWidth, float wander, float periodX, float seed) {
+  float aaw = max(length(fwidth(r)), 1e-4);
+  vec2 cell = floor(r);
+  float acc = 0.0;
+  bool tile = periodX > 0.5 && abs(angle) < 1e-3;
+  for(int j = -1; j <= 1; j++) {
+    for(int i = -1; i <= 1; i++) {
+      vec2 c = cell + vec2(float(i), float(j));
+      vec2 h = mod(c, PN_WRAP); // keep hash coords small/precise + seamless at the axial wrap
+      if(tile)
+        // max() keeps the divisor provably non-zero: callers that disable tiling pass
+        // periodX = 0.0, and some backends (ANGLE/D3D) constant-fold the mod() division
+        // inside this branch BEFORE dead-code elimination and warn "X4008: floating
+        // point division by zero". Only reached when tile (periodX > 0.5), so this is a
+        // no-op at runtime.
+        h.x = mod(c.x, max(periodX, 1.0)); // seamless wrap around the circumference
+      h += seed;
+      if(pnHash2(h + 3.1) > density)
+        continue; // sparsity
+      vec2 mid = c + vec2(pnHash2(h + 7.3), pnHash2(h + 13.7));
+      float a = angle + (pnHash2(h + 21.1) - 0.5) * 3.14159265 * clamp(wander, 0.0, 1.0);
+      vec2 d = vec2(cos(a), sin(a));
+      vec2 perp = vec2(-d.y, d.x);
+      float hl = clamp(mix(0.1, 0.55, pnHash2(h + 29.3)) * max(lengthScale, 0.05), 0.03, 0.92);
+      float w = halfWidth * mix(0.7, 1.3, pnHash2(h + 41.7)); // world-scaled half-width (freq-independent)
+      float rStr = mix(0.3, 1.0, pnHash2(h + 37.7));   // random depth/brightness
+      float bend = (pnHash2(h + 51.9) - 0.5) * 0.7;    // shallow curvature so lines aren't dead straight
+      vec2 pr = r - mid;
+      float t = clamp(dot(pr, d), -hl, hl);            // nearest point on the straight axis
+      float u = t / max(hl, 1e-3);
+      vec2 foot = d * t + perp * (bend * u * u * hl);  // bow the centre-line across its length
+      float dist = length(pr - foot);
+      acc = max(acc, (1.0 - smoothstep(w - aaw, w + aaw, dist)) * rStr);
+    }
+  }
+  return acc;
+}
+
+float pnScratches(vec2 uv, float angle, float density, float lengthScale, float halfWidth, float wander, float periodX, float coarseWeight) {
+  float ca = cos(angle), sa = sin(angle);
+  vec2 r = vec2(uv.x * ca - uv.y * sa, uv.x * sa + uv.y * ca);
+
+  // Fine family: many short/medium scratches at the caller's frequency.
+  float fine = pnScratchLayer(r, angle, density, lengthScale, halfWidth, wander, periodX, 0.0);
+
+  // Coarse family: a few much longer grooves, seeded on a ~3x larger grid (bigger cells
+  // => longer scratches within the same 3x3 search). x is rescaled to an INTEGER period
+  // so the circumference seam stays seamless; y (never tiled) is just divided down. The
+  // half-width is scaled by the same factor so the coarse grooves keep the SAME world
+  // width as the fine ones (longer, not fatter). It is the most repetition-prone / "big"
+  // family AND doubles the per-fragment cost, so `coarseWeight` lets the caller drop it
+  // entirely (pass 0 - the whole 3x3 loop is then skipped): the branch is expected to be
+  // driven by a uniform (e.g. a quality knob) so it stays divergence-free.
+  float coarse = 0.0;
+  if(coarseWeight > 0.0) {
+    float coarsePeriod = max(floor(periodX / 3.0 + 0.5), 1.0);
+    float scale = coarsePeriod / max(periodX, 1.0);
+    vec2 rc = vec2(r.x * scale, r.y / 3.0);
+    coarse = pnScratchLayer(rc, angle, density * 0.5, lengthScale, halfWidth * scale, wander, coarsePeriod, 7.0) * coarseWeight;
+  }
+
+  return -max(fine, coarse);
+}
+
+// Footprint anti-aliasing factor (1 near .. 0 sub-pixel). Fades a pattern out as its
+// finest octave shrinks toward a pixel - with distance or at grazing angles - so the
+// high-frequency detail never becomes a shimmering/aliasing signal. `uv` is the
+// (frequency-scaled) sample coordinate; `octaves` is the fbm octave count. Must be
+// called under uniform control flow (uses screen-space derivatives).
+float pnFootprintFade(vec2 uv, int octaves) {
+  // cells per pixel of the sample coordinate (mildly boosted for finer octaves). Fade
+  // BEFORE the Nyquist limit: a cell must stay >~2 px to sample cleanly, so start fading
+  // around 2.5 px/cell and reach zero by ~1 px/cell. (A looser threshold left the pattern
+  // near full strength at ~1 cell/pixel, so it stippled/aliased on thin, minified faces
+  // such as the end caps and slice faces.)
+  float cellsPerPixel = max(fwidth(uv.x), fwidth(uv.y)) * (1.0 + 0.5 * float(octaves - 1));
+  return 1.0 - smoothstep(0.4, 1.0, cellsPerPixel);
+}
+
+// Perturb a view-space normal by a scalar height field using the screen-space surface
+// gradient (Mikkelsen) - no tangent/bitangent attributes needed. `height` must be the
+// value sampled at THIS fragment; its screen-space derivatives give the slope.
+vec3 perturbNormalHeight(vec3 normal, vec3 viewPos, float height) {
+  vec3 sx = dFdx(viewPos);
+  vec3 sy = dFdy(viewPos);
+  float hx = dFdx(height);
+  float hy = dFdy(height);
+  vec3 r1 = cross(sy, normal);
+  vec3 r2 = cross(normal, sx);
+  float det = dot(sx, r1);
+  vec3 grad = sign(det) * (hx * r1 + hy * r2);
+  return normalize(abs(det) * normal - grad);
+}

package/dist/types/components/Ocean/Ocean.d.ts

@@ -0,0 +1,333 @@
+import { ReactNode } from 'react';
+import { BufferGeometry, Group } from 'three';
+import { CommonComponentProps, CustomMaterialProps } from '../../common/types';
+import { Vec2, Vec3 } from '../../sdk/types/common';
+/**
+ * Ocean props
+ * @expand
+ */
+export type OceanProps = CommonComponentProps & CustomMaterialProps & {
+    /**
+     * Geometry to render as the ocean surface. Typically a large plane lying in
+     * the world X/Z plane at sea level (e.g. `createOceanBox(...).surface`). All
+     * wave/foam animation is evaluated in world coordinates, so tiled/patched
+     * geometry aligns seamlessly.
+     */
+    geometry: BufferGeometry;
+    /**
+     * Optional water-body (side walls) geometry, e.g.
+     * `createOceanBox(...).body`. When provided, it is rendered as a separate,
+     * double-sided, transparent-blue volume mesh so the water reads as a body.
+     */
+    bodyGeometry?: BufferGeometry;
+    /**
+     * Optional sea-bed geometry, e.g. `createOceanBox(...).bed`. When provided,
+     * it is rendered as a separate sun-shaded mesh below the surface.
+     */
+    bedGeometry?: BufferGeometry;
+    /** Wind direction in world X/Z (drives wave + foam direction). */
+    windDirection?: Vec2;
+    /**
+     * Wind speed in m/s (U10). Primary driver of the sea state: wave height,
+     * wavelength and foam all follow North-Sea JONSWAP/Pierson-Moskowitz
+     * relations (e.g. ~10 m/s ⇒ Hs ~ 2.1 m, peak wavelength ~ 88 m).
+     */
+    windSpeed?: number;
+    /** Wave height multiplier on top of the spectrum's physical Hs. */
+    amplitude?: number;
+    /** Angular spread (radians) of the wave directions around the wind. */
+    directionalSpread?: number;
+    /** Apparent surface choppiness (normal exaggeration / Gerstner sharpness). */
+    steepness?: number;
+    /**
+     * Enables vertex displacement (`false` = off / flat, per-pixel normals
+     * only). Off by default; at oilfield scale real displacement is
+     * imperceptible except very close to the surface, where only the longest
+     * swells displace. Mainly useful to let floating objects follow the surface
+     * height.
+     */
+    displacement?: boolean;
+    /** Number of summed spectral wave components (compile-time). */
+    waveCount?: number;
+    /** Number of FBM micro-ripple octaves (compile-time). */
+    detailOctaves?: number;
+    /** Deep water colour (seen looking straight down). */
+    deepColor?: string;
+    /** Shallow/scatter water colour (seen at grazing angles). */
+    shallowColor?: string;
+    /** Base body opacity looking straight down (0 = clear, 1 = opaque). */
+    waterOpacity?: number;
+    /** Strength of the large-scale tonal variation (currents / slicks), 0 = off. */
+    tonalVariation?: number;
+    /** Approximate size of the tonal variation patches, in kilometers. */
+    tonalScale?: number;
+    /** Crispness of the tonal variation patch edges (0 = soft, 1 = hard). */
+    tonalSharpness?: number;
+    /** Colour the water drifts toward in the tonal variation (current / algae / pollution tint). */
+    tonalColor?: string;
+    /** Zenith sky colour used for the procedural reflection. */
+    skyColor?: string;
+    /** Horizon sky colour used for the procedural reflection. */
+    horizonColor?: string;
+    /** Reflection intensity multiplier. */
+    reflectionIntensity?: number;
+    /** Sun direction in world space (specular highlight + reflected glow). */
+    sunDirection?: Vec3;
+    /** Sun colour. */
+    sunColor?: string;
+    /** Sun specular shininess exponent. */
+    sunShininess?: number;
+    /** Foam colour. */
+    foamColor?: string;
+    /** Foam amount, 0 = none. */
+    foamAmount?: number;
+    /** Fresnel exponent (higher = reflections concentrated near the horizon). */
+    fresnelPower?: number;
+    /** Micro-ripple frequency (waves per world unit) for close-up detail. */
+    detailScale?: number;
+    /** Micro-ripple normal strength. */
+    detailStrength?: number;
+    /**
+     * Sea-bed base (sandy/yellowish) colour. Only used when `bedGeometry` is
+     * provided. Default `#b8a06a`.
+     */
+    seaBedColor?: string;
+    /**
+     * Strength of the water-colour tint applied to the water-facing (top) side
+     * of the sea bed (0..1). Only used when `bedGeometry` is provided.
+     */
+    seaBedWaterTint?: number;
+    /**
+     * Sea-bed opacity (0..1). Only used when `bedGeometry` is provided. The sea
+     * bed is OIT-routed, so values below 1 let the subsurface geometry below it
+     * show through; 1 (default) makes it a solid occluder.
+     */
+    seaBedOpacity?: number;
+    /**
+     * Sea-bed sand-dune relief strength (0 = off). Only used when `bedGeometry`
+     * is provided. Perturbs the bed's shading normal by a procedural,
+     * footprint-anti-aliased dune height field, adding a subtle sense of depth
+     * and scale that resolves up close and fades to flat far out. Default 0.15.
+     */
+    seaBedDuneStrength?: number;
+    /**
+     * Base sand-dune crest spacing in meters. Only used when `bedGeometry` is
+     * provided. Default 180.
+     */
+    seaBedDuneWavelength?: number;
+    /**
+     * Sand-dune ridge direction in world X/Z. Only used when `bedGeometry` is
+     * provided. Default `[1, 0.6]`.
+     */
+    seaBedDuneDirection?: Vec2;
+    /**
+     * Extra sand-dune crest/trough albedo banding (0 = off). Only used when
+     * `bedGeometry` is provided. Lightens the dune crests and darkens the
+     * troughs on top of the relief shading for a stronger depth cue; fades out
+     * far away like the rest of the dune detail. Default 0.
+     */
+    seaBedDuneSharpness?: number;
+    /**
+     * Per-meter tint build-up of the water body. Only used when `bodyGeometry`
+     * is provided.
+     */
+    bodyFogDensity?: number;
+    /** Densest water-body tint reached far through the water (0..1). */
+    bodyMaxOpacity?: number;
+    /** Animated shimmer amount of the water body, 0 = off. */
+    bodyShimmer?: number;
+    /** Master opacity multiplier (also drives OIT routing). */
+    opacity?: number;
+    /** Toggles visibility of the water-surface mesh. Default `true`. */
+    surfaceVisible?: boolean;
+    /**
+     * Toggles visibility of the water-body (side walls) mesh. Only has an effect
+     * when `bodyGeometry` is provided. Default `true`.
+     */
+    bodyVisible?: boolean;
+    /**
+     * Toggles visibility of the sea-bed mesh. Only has an effect when
+     * `bedGeometry` is provided. Default `true`.
+     */
+    bedVisible?: boolean;
+    /** Debug: render all ocean materials (surface, body, sea bed) as wireframe. */
+    wireframe?: boolean;
+    /**
+     * Children rendered inside the ocean's group, in its local frame. They
+     * receive an {@link OceanSampler} via context (see `useOceanSampler` /
+     * `useBuoyancy`) so floating objects (e.g. a vessel) can follow the waves.
+     */
+    children?: ReactNode;
+};
+/**
+ * Stylized animated ocean surface.
+ *
+ * Renders the provided geometry as a procedurally animated, OIT-compatible
+ * water surface. The wave field is sampled from a North-Sea JONSWAP spectrum
+ * driven by the wind speed (m/s); the visible waves are reconstructed per-pixel
+ * as surface normals (plus a fine micro-ripple layer up close), all evaluated
+ * in world X/Z space so the pattern is continuous across tiled patches with no
+ * repeating texture assets. Level-of-detail uses per-wave footprint
+ * anti-aliasing, so there is no visible LOD ring. Transparency is Fresnel-driven
+ * (see-through looking down, reflective at grazing angles) and composites
+ * correctly with the other transparent subsurface geometry through the
+ * OITRenderPass.
+ *
+ * @example
+ * <Ocean geometry={planeGeometry} windDirection={[1, 0.3]} windSpeed={10} />
+ *
+ * @group Components
+ */
+export declare const Ocean: import('react').ForwardRefExoticComponent<CommonComponentProps & CustomMaterialProps & {
+    /**
+     * Geometry to render as the ocean surface. Typically a large plane lying in
+     * the world X/Z plane at sea level (e.g. `createOceanBox(...).surface`). All
+     * wave/foam animation is evaluated in world coordinates, so tiled/patched
+     * geometry aligns seamlessly.
+     */
+    geometry: BufferGeometry;
+    /**
+     * Optional water-body (side walls) geometry, e.g.
+     * `createOceanBox(...).body`. When provided, it is rendered as a separate,
+     * double-sided, transparent-blue volume mesh so the water reads as a body.
+     */
+    bodyGeometry?: BufferGeometry;
+    /**
+     * Optional sea-bed geometry, e.g. `createOceanBox(...).bed`. When provided,
+     * it is rendered as a separate sun-shaded mesh below the surface.
+     */
+    bedGeometry?: BufferGeometry;
+    /** Wind direction in world X/Z (drives wave + foam direction). */
+    windDirection?: Vec2;
+    /**
+     * Wind speed in m/s (U10). Primary driver of the sea state: wave height,
+     * wavelength and foam all follow North-Sea JONSWAP/Pierson-Moskowitz
+     * relations (e.g. ~10 m/s ⇒ Hs ~ 2.1 m, peak wavelength ~ 88 m).
+     */
+    windSpeed?: number;
+    /** Wave height multiplier on top of the spectrum's physical Hs. */
+    amplitude?: number;
+    /** Angular spread (radians) of the wave directions around the wind. */
+    directionalSpread?: number;
+    /** Apparent surface choppiness (normal exaggeration / Gerstner sharpness). */
+    steepness?: number;
+    /**
+     * Enables vertex displacement (`false` = off / flat, per-pixel normals
+     * only). Off by default; at oilfield scale real displacement is
+     * imperceptible except very close to the surface, where only the longest
+     * swells displace. Mainly useful to let floating objects follow the surface
+     * height.
+     */
+    displacement?: boolean;
+    /** Number of summed spectral wave components (compile-time). */
+    waveCount?: number;
+    /** Number of FBM micro-ripple octaves (compile-time). */
+    detailOctaves?: number;
+    /** Deep water colour (seen looking straight down). */
+    deepColor?: string;
+    /** Shallow/scatter water colour (seen at grazing angles). */
+    shallowColor?: string;
+    /** Base body opacity looking straight down (0 = clear, 1 = opaque). */
+    waterOpacity?: number;
+    /** Strength of the large-scale tonal variation (currents / slicks), 0 = off. */
+    tonalVariation?: number;
+    /** Approximate size of the tonal variation patches, in kilometers. */
+    tonalScale?: number;
+    /** Crispness of the tonal variation patch edges (0 = soft, 1 = hard). */
+    tonalSharpness?: number;
+    /** Colour the water drifts toward in the tonal variation (current / algae / pollution tint). */
+    tonalColor?: string;
+    /** Zenith sky colour used for the procedural reflection. */
+    skyColor?: string;
+    /** Horizon sky colour used for the procedural reflection. */
+    horizonColor?: string;
+    /** Reflection intensity multiplier. */
+    reflectionIntensity?: number;
+    /** Sun direction in world space (specular highlight + reflected glow). */
+    sunDirection?: Vec3;
+    /** Sun colour. */
+    sunColor?: string;
+    /** Sun specular shininess exponent. */
+    sunShininess?: number;
+    /** Foam colour. */
+    foamColor?: string;
+    /** Foam amount, 0 = none. */
+    foamAmount?: number;
+    /** Fresnel exponent (higher = reflections concentrated near the horizon). */
+    fresnelPower?: number;
+    /** Micro-ripple frequency (waves per world unit) for close-up detail. */
+    detailScale?: number;
+    /** Micro-ripple normal strength. */
+    detailStrength?: number;
+    /**
+     * Sea-bed base (sandy/yellowish) colour. Only used when `bedGeometry` is
+     * provided. Default `#b8a06a`.
+     */
+    seaBedColor?: string;
+    /**
+     * Strength of the water-colour tint applied to the water-facing (top) side
+     * of the sea bed (0..1). Only used when `bedGeometry` is provided.
+     */
+    seaBedWaterTint?: number;
+    /**
+     * Sea-bed opacity (0..1). Only used when `bedGeometry` is provided. The sea
+     * bed is OIT-routed, so values below 1 let the subsurface geometry below it
+     * show through; 1 (default) makes it a solid occluder.
+     */
+    seaBedOpacity?: number;
+    /**
+     * Sea-bed sand-dune relief strength (0 = off). Only used when `bedGeometry`
+     * is provided. Perturbs the bed's shading normal by a procedural,
+     * footprint-anti-aliased dune height field, adding a subtle sense of depth
+     * and scale that resolves up close and fades to flat far out. Default 0.15.
+     */
+    seaBedDuneStrength?: number;
+    /**
+     * Base sand-dune crest spacing in meters. Only used when `bedGeometry` is
+     * provided. Default 180.
+     */
+    seaBedDuneWavelength?: number;
+    /**
+     * Sand-dune ridge direction in world X/Z. Only used when `bedGeometry` is
+     * provided. Default `[1, 0.6]`.
+     */
+    seaBedDuneDirection?: Vec2;
+    /**
+     * Extra sand-dune crest/trough albedo banding (0 = off). Only used when
+     * `bedGeometry` is provided. Lightens the dune crests and darkens the
+     * troughs on top of the relief shading for a stronger depth cue; fades out
+     * far away like the rest of the dune detail. Default 0.
+     */
+    seaBedDuneSharpness?: number;
+    /**
+     * Per-meter tint build-up of the water body. Only used when `bodyGeometry`
+     * is provided.
+     */
+    bodyFogDensity?: number;
+    /** Densest water-body tint reached far through the water (0..1). */
+    bodyMaxOpacity?: number;
+    /** Animated shimmer amount of the water body, 0 = off. */
+    bodyShimmer?: number;
+    /** Master opacity multiplier (also drives OIT routing). */
+    opacity?: number;
+    /** Toggles visibility of the water-surface mesh. Default `true`. */
+    surfaceVisible?: boolean;
+    /**
+     * Toggles visibility of the water-body (side walls) mesh. Only has an effect
+     * when `bodyGeometry` is provided. Default `true`.
+     */
+    bodyVisible?: boolean;
+    /**
+     * Toggles visibility of the sea-bed mesh. Only has an effect when
+     * `bedGeometry` is provided. Default `true`.
+     */
+    bedVisible?: boolean;
+    /** Debug: render all ocean materials (surface, body, sea bed) as wireframe. */
+    wireframe?: boolean;
+    /**
+     * Children rendered inside the ocean's group, in its local frame. They
+     * receive an {@link OceanSampler} via context (see `useOceanSampler` /
+     * `useBuoyancy`) so floating objects (e.g. a vessel) can follow the waves.
+     */
+    children?: ReactNode;
+} & import('react').RefAttributes<Group<import('three').Object3DEventMap>>>;

package/dist/types/components/Ocean/index.d.ts

@@ -0,0 +1,6 @@
+export * from './Ocean';
+export * from './ocean-bed-material';
+export * from './ocean-contact';
+export * from './ocean-material';
+export * from './ocean-sampler';
+export * from './ocean-volume-material';

package/dist/types/components/Ocean/ocean-bed-material.d.ts

@@ -0,0 +1,60 @@
+import { Color, ShaderMaterial, ShaderMaterialParameters, Vector2, Vector3 } from 'three';
+export type OceanBedMaterialParameters = ShaderMaterialParameters;
+/**
+ * OIT-compatible sea-bed material for the bottom face of an ocean box. Applies
+ * simple sun-direction diffuse shading so the procedural bed relief is visible,
+ * tints the water-facing (top) side toward the water colour, and keeps the
+ * underside a light sandy/yellowish colour. Rendered double-sided.
+ *
+ * At opacity 1 the OITRenderPass routes it through the opaque pass (writing
+ * depth), so it occludes geometry below it; lower opacity keeps it in the
+ * transparency passes so subsurface geometry shows through. Because the material
+ * has no `opacity` uniform, callers must mirror the alpha onto `material.opacity`
+ * to drive that routing.
+ *
+ * Wired for the OITRenderPass via {@link attachOitVariants} (variants share this
+ * material's `uniforms` by reference, so animated uniforms stay live).
+ */
+export declare class OceanBedMaterial extends ShaderMaterial {
+    isOceanBedMaterial: boolean;
+    constructor(parameters?: OceanBedMaterialParameters);
+    get color(): Color;
+    set color(value: Color | string | number);
+    get waterColor(): Color;
+    set waterColor(value: Color | string | number);
+    /** Strength of the water tint on the water-facing side (0..1). */
+    get waterTint(): number;
+    set waterTint(value: number);
+    get sunDirection(): Vector3;
+    set sunDirection(value: Vector3);
+    get sunColor(): Color;
+    set sunColor(value: Color | string | number);
+    /** Ambient light floor (0..1). */
+    get ambient(): number;
+    set ambient(value: number);
+    /** Bed opacity (also mirror onto `material.opacity` for OIT routing). */
+    get bedOpacity(): number;
+    set bedOpacity(value: number);
+    get masterOpacity(): number;
+    set masterOpacity(value: number);
+    /**
+     * Sand-dune relief strength (0 = off). Perturbs the shading normal by the
+     * analytic slope of a procedural, footprint-anti-aliased dune height field, so
+     * the bed reads with subtle relief up close and fades to flat far out.
+     */
+    get duneStrength(): number;
+    set duneStrength(value: number);
+    /** Base dune crest spacing in meters. */
+    get duneWavelength(): number;
+    set duneWavelength(value: number);
+    /** Dune ridge propagation direction in world X/Z. */
+    get duneDirection(): Vector2;
+    set duneDirection(value: Vector2);
+    /**
+     * Extra crest/trough albedo banding (0 = off). Lightens the dune crests and
+     * darkens the troughs on top of the normal-based shading for a stronger sense
+     * of relief; follows the same footprint fade so it also vanishes far out.
+     */
+    get duneSharpness(): number;
+    set duneSharpness(value: number);
+}