Three Vue3Three Vue3
指南
在线演示
AI 智能体
  • English
  • 简体中文
GitHub
指南
在线演示
AI 智能体
  • English
  • 简体中文
GitHub
    • 快速开始
    • 场景
    • 参数总线
    • 天空盒
    • 模型加载器

      • 组件加载器
      • 函数加载器
    • 弹出窗口
    • 标注
    • 动态元素
    • 动画
    • 模型旋转器
    • 拾取
    • 相机自适应
    • 网格模型

      • 波动圆
      • 流动线网格
    • 效果

      • 自然

        • 雨
        • 雪
        • 海洋水面
          • 默认用法
          • 自定义形状
          • 属性
          • 渲染器支持
        • 互动水池
        • 沙滩漫步
      • 天空与大气

        • 天空穹顶
        • 高度雾
        • 星云星系
      • 光照

        • 泛光
        • 扫光
        • 灯光渐变
        • 光柱
        • 雷达扫描
        • 信号波
        • 力场护盾
      • 粒子与精灵

        • 烟花
        • 文字烟花
        • 光晕精灵
    • 地理

      • 地理参考系
      • GeoObject 地理对象
      • GeoJsonLayer 图层
      • 瓦片图层

类型

组件

<tv-water> 在 <tv-scene> 中渲染电影感的浅海海面,是 Evan Wallace 的 webgl-water 与 react-three-lite Water 组件的移植版本,并扩展了多波 Gerstner 风格波谱、平面反射与折射,以及自定义水面轮廓。

一个 420 米的位移平面由 14 组波谱叠加分形噪声驱动。同一套 CPU 采样器也与雨滴碰撞高度图共享,因此 height-map 雨滴会精确落在动态海面上。

全部由 TSL 节点材质实现,因此在 WebGPURenderer(默认)和经由 WebGLNodesHandler 的传统 WebGLRenderer 上都能渲染。给 <tv-scene> 加上 renderer-type="webgl" 即可对比两种后端。

默认用法

点击我查看代码
<template>
  <tv-scene class="scene" bg-color="rgb(40, 42, 54)" @created="created">
    <tv-water />
  </tv-scene>
</template>

<script lang="ts" setup>
import * as THREE from 'three'
import { globalParameterBus } from 'three-vue3'

const created = (_scene: THREE.Scene, { camera }: { camera?: THREE.Camera }) => {
  if (!camera) return
  camera.position.set(0, 1.5, 3)
  globalParameterBus.set('sunDirection', new THREE.Vector3(-0.58, 0.1, -0.81))
}
</script>

<style>
.scene {
  margin-top: 10px;
  margin-bottom: 16px;
  width: 100%;
  height: 300px;
}
</style>

在 <tv-water> 初始化前设置 globalParameterBus,让水面与场景中的其他对象使用相同的太阳方向。水面会订阅后续方向更新,直到组件销毁。

自定义形状

传入凸 [x, z] 轮廓,或顶点可投影到 XZ 平面的 BufferGeometry,即可三角化出不规则水面。

点击我查看代码
<template>
  <tv-scene
    class="scene"
    bg-color="rgb(40, 42, 54)"
    :axes-helper="false"
    :grid-helper="false"
    @created="created"
  >
    <tv-water :shape="LAKE_OUTLINE" :segments="160" />
  </tv-scene>
</template>

<script lang="ts" setup>
import * as THREE from 'three'
import type { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'

const LAKE_OUTLINE: [number, number][] = [
  [-8, -2.5],
  [-4.5, -5.5],
  [1.5, -6],
  [6.5, -3.5],
  [8, 1],
  [4.5, 5],
  [-1.5, 5.5],
  [-6.5, 3]
]

const created = (
  _scene: THREE.Scene,
  { camera, controls }: { camera?: THREE.Camera; controls?: OrbitControls }
) => {
  if (!camera) return
  camera.position.set(0, 6, 15)
  if (controls) controls.target.set(0, 0, 0)
  camera.lookAt(0, 0, 0)
}
</script>

<style>
.scene {
  margin-top: 10px;
  margin-bottom: 16px;
  width: 100%;
  height: 300px;
}
</style>

属性

属性类型默认值说明
captureResolutionnumber512可选 平面反射与折射捕获的最长边设备像素数,限制在 64–2048 且不超过绘制缓冲区。
segmentsnumber240可选 每轴平面细分数,限制在 16–1024。使用 shape 时,它表示轮廓总采样预算。
sizenumber420可选 方形水面的边长,单位为场景世界单位。提供 shape 时忽略。
shapeWaterPoolOutline | BufferGeometry—可选 自定义凸水面轮廓,或投影到 XZ 平面的几何体。
positionVector3 | [number, number, number][0, 0, 0]可选 水面中心的世界坐标。
type WaterPoolOutline = readonly (readonly [number, number])[]

自定义点与几何体顶点会简化为凸包并移除共线点。凸包必须包含原点,且至少具有三个非共线点。未提供 shape 时,segments 细分 size × size 平面的每条轴;提供后则控制轮廓总采样预算。position 同时移动网格与反射平面,水下采样也始终以定位后的水面为基准。

渲染器支持

  • WebGPU 通过 WebGPURenderer 直接执行 TSL 节点图。
  • WebGL 通过 WebGLNodesHandler 将同一份节点图编译为 GLSL。

修改属性会重建网格、几何体、贴图与渲染目标。替换资源及组件卸载时,旧资源、监听器、动画回调与太阳方向订阅都会被释放。

在 GitHub 上编辑此页
Last Updated:
Contributors: Shing Rui, ruixinglong
Prev
雪
Next
互动水池