"""OceanSurface3D: a large open-sea plane driven by the FFT ocean (design D11).
Where :class:`~simvx.core.water.WaterSurface3D` displaces its grid by a handful
of analytic Gerstner waves, an :class:`OceanSurface3D` displaces it by a sampled
FFT ocean: a Tessendorf Phillips spectrum inverse-transformed into per-cascade
displacement + slope + foam maps (see the renderer's ocean pass). It reuses the
:class:`~simvx.core.water.WaterMaterial` value object for shading (colour, depth
fade, Fresnel, refraction, foam) exactly like the built-in water pass (design
D16); the difference is entirely in how the surface is displaced and how its
normal + foam are derived.
The wind that drives the spectrum comes from the scene ``WorldEnvironment``
(FrameGlobals wind), and the cascade texture size + count come from the graphics
quality tier (``QualitySettings.ocean_size`` / ``ocean_cascades``), so an ocean
scales with the same one dial as the rest of the renderer. Place the node at sea
level: its world XZ plane (local +Y up) is the mean surface.
Example::
sea = OceanSurface3D(position=(0, 0, 0), size=(600, 600), subdivisions=256)
sea.material = WaterMaterial(wave_amplitude=1.4, wave_steepness=0.7)
scene.add_child(sea)
"""
from __future__ import annotations
from .descriptors import Property
from .math.types import Vec3
from .nodes_3d.node3d import Node3D
from .water import WaterMaterial
__all__ = ["OceanSurface3D"]
[docs]
class OceanSurface3D(Node3D):
"""A large FFT-ocean plane rendered by the built-in ocean pass.
Properties:
size: Ocean plane extent in world units (x, z). Make it large: the FFT
cascades tile across it, so a big plane reads as open sea.
subdivisions: Grid resolution per axis. Higher resolves the FFT
displacement more finely near the camera (at more vertices).
visible: Standard Node visibility; a hidden surface neither draws nor
triggers the scene colour/depth copy the refraction reads.
"""
size = Property((500.0, 500.0), hint="Ocean plane extent in world units (x, z)", group="Ocean")
subdivisions = Property(256, range=(2, 512), hint="Grid tessellation per axis", group="Ocean")
gizmo_colour = Property((0.15, 0.4, 0.7, 0.5))
def __init__(self, material: WaterMaterial | None = None, **kwargs):
super().__init__(**kwargs)
self._material: WaterMaterial = (
material
if material is not None
else WaterMaterial(wave_amplitude=1.2, wave_steepness=0.7, depth_fade_distance=6.0)
)
@property
def material(self) -> WaterMaterial:
"""The :class:`WaterMaterial` controlling this ocean's shading."""
return self._material
[docs]
@material.setter
def material(self, mat: WaterMaterial | None) -> None:
self._material = mat if mat is not None else WaterMaterial()
[docs]
def get_gizmo_lines(self) -> list[tuple[Vec3, Vec3]]:
"""Editor gizmo: the mean-surface rectangle at the node's world plane."""
sx, sz = float(self.size[0]) * 0.5, float(self.size[1]) * 0.5
p = self.world_position
corners = [
Vec3(p.x - sx, p.y, p.z - sz),
Vec3(p.x + sx, p.y, p.z - sz),
Vec3(p.x + sx, p.y, p.z + sz),
Vec3(p.x - sx, p.y, p.z + sz),
]
return [(corners[i], corners[(i + 1) % 4]) for i in range(4)]