threejs-spectral-ocean

谱海洋

选择由目标视图决定的表示方式。开阔水域海况采用显式的频域控制。海滩视角的碎浪则采用耦合的带限波场、海岸表示、拍岸状态、泡沫历史和沙滩响应。不要将任何一种目标简化为滚动法线贴图或互不相关的泡沫噪声。

此技能包含示范性示例和资源，不只是描述性指南；值得研究、参考，甚至直接复制。请在相关时充分使用，切勿盲目跳过。

谱构建顺序

1. 定义海况谱和确定性高斯种子。
2. 将波长划分为互不重叠的级联。
3. 使用解析输入独立验证逆 FFT。
4. 生成初始频谱并进行共轭打包。
5. 在频域中演化打包后的位移场和导数场。
6. 对每个打包场进行逆变换，并显式设置步骤间屏障。
7. 组合位移、导数和持久化雅可比泡沫贴图。
8. 根据累加后的级联位移和导数进行着色。
9. 仅在已解析的模拟频带以下添加子网格细节。
10. 提供频谱、高度、坡度、雅可比和泡沫历史诊断信息。

在实现或审查谱海洋前，请阅读 references/spectral-cascade-ocean-system.md。

在实现或审查海岸碎浪系统的水体到湿沙过渡前，请阅读 references/coastal-breaker-and-swash-ocean.md。

请阅读谱级联海洋系统 及其相邻的频谱、FFT、材质和细节模块，了解级联、FFT、导数、雅可比、泡沫历史和着色约定。其中的 WebGL2 片段着色器 FFT 后端是一个明确的兼容层级；当目标支持时，应保留参考文档中描述的生产级 WebGPU/TSL 架构。

当目标需要一种可从水面上方和下方观察的风格化 FFT 海洋时，请阅读 风格化水面上下海洋材质：它包含基于高度梯度的水色、沿日光路径的闪光、浪峰散射、雅可比泡沫、带水色调的海底焦散，以及由场景深度驱动的水下 Beer-Lambert 合成。

当摄像机必须在 WebGPU 谱表面下方保持水下视角时，请阅读 水下 Snell 海洋系统：它提供精确的水到空气 Fresnel 效应、经过导数滤波的临界角遮罩、针对物理亮度上涌水下表面的全内反射、符合能量守恒的透射阳光光瓣、将水上结构正向投影到水下视窗、共享的 HDR 天空辐射、水生消光与体散射、具有足迹渐隐效果的微分面积焦散、全分辨率光柱、悬浮微粒以及最终 HDR 调色。

当决定性视角位于水线处时，请阅读 海岸碎浪海洋系统：它提供确定性的带限重力波场和毛细波场、有符号距离大陆与岛屿海岸、沿海岸法线传播的浅水拍岸波链、持久化的碎浪泡沫和水膜、跟随摄像机的变形几何、湿沙光学效果以及共享的天空辐射。

当海滩由保正性有限体积求解器控制时，请阅读 海滩海浪实现：它提供岩石海岸网格、重建的水体与湿沙场、平流泡沫、浅水膜光学效果、反射和折射的天空辐射，以及由撞击触发的飞沫。

Spectral 不可妥协的门槛

• 必须使用 2 的幂次网格，并通过 FFT 脉冲／频率测试。
• 保持各级联的波数区间互不重叠。
• 法线必须由变换后的导数推导，不能使用独立的法线贴图。
• 根据水平位移的雅可比矩阵检测破碎。
• 在模拟状态中持久化泡沫；不要每帧都重新推断所有泡沫。
• 提交 FFT 阶段时，必须使用当前后端所需的同步机制。
• 可见天空与海洋反射必须共用太阳和天空参数。
• 通过正向投影传输另一介质中的结构：将这些结构自身的顶点光栅化到其折射后的屏幕位置。对于开放界面，绝不要从水面像素反向追踪到源屏幕位置，也绝不要根据某个方向的消失点是否落在屏幕内来决定是否传输辐射。（只从空气侧观察的有界水体仍可在 $threejs-water-optics 中使用屏幕空间偏移；摄像机介质会发生变化的海洋则不行。）
• 水侧穿越求解的搜索区间应由临界角限定（tan θc ≈ 1.1346 乘以光线自身到界面的距离），而不是由摄像机到源点的距离决定。
• 根据像素覆盖范围缩放频谱 LOD，即 distance² · pixelAngle / heightGap，并将其应用于顶点位移、导数以及依赖这些量的每个频带。若频带作为反照率或辐射项，则将其渐隐至该频带自身的均值。
• 对临界角域测试进行约一个输出像素范围的滤波；绝不要通过滤波界面法线来稳定穿过界面的传输效果。
• 根据同一个摄像机介质状态控制整个光学侧；不要按三角形分别选择上方／下方的行为。
• 远处的水下视线应以完全没入水中的地形边缘终止；不要用视线对齐的散射层遮挡空旷的海床／海洋地平线。
• 使用确定性种子和固定摄像机进行截图对比。

海岸破浪门槛

• 将海岸 SDF、弧长表、带状几何体和涌浪列纳入同一套海岸约定；不要根据 SDF 梯度推导不稳定的列顺序。
• 将离岸波浪水位传入海岸法线方向上的守恒体积链；线性弹簧链无法唯一确定平坦的自由水面。
• 同时持久化世界空间中的破浪泡沫和以海岸参数化的薄膜泡沫。
• 根据实际水柱混合水、湿沙和干沙，而不是使用独立的海岸线贴花。
• 水面法线应根据使表面产生位移的同一组重力／毛细场推导；在掠射距离处对沙地法线细节进行导数滤波。
• 可见环境与海洋反射必须共用天空辐射和太阳方向。
• 保持轨道摄像机位于地形上方，并使用固定水位线摄像机进行对比。

转到其他工具

• 对于空气侧浅水 FFT 光学、RGB 焦散和衍射眩光，请使用 $threejs-water-optics 及其 photoreal-water 示例。对于有界水体、屏幕空间折射、深度厚度、岸线吸收和解析波面，也请使用该技能。它的屏幕空间折射适用于这些情况，因为摄像机始终处于空气中，且水体有边界；但它不能替代本技能中跨开放界面的正向投影。
• 仅在需要波峰飞沫或交互溅水时，才添加 $threejs-procedural-vfx。
• 如需跨种子、时间和 GPU 方面的证据，请添加 $threejs-visual-validation。