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

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

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

      • 自然

        • 雨
        • 雪
        • 海洋水面
        • 互动水池
          • 默认用法
          • 不规则水池
          • 属性
          • 实现原理
          • 渲染器支持
        • 沙滩漫步
      • 天空与大气

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

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

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

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

类型

组件

<tv-water-pool> 在 <tv-scene> 中渲染一个可交互的射线追踪水池,是 Evan Wallace 的 webgl-water 与 react-three-lite WaterPool 组件的移植版本。

CPU 高度场驱动涟漪与焦散光照贴图,并以数据纹理上传到 GPU。水面、瓷砖池壁与程序化天空都在片元着色器中通过解析射线着色,因此 WebGPU 与 WebGL 的反射、折射和焦散结果一致,且不需要额外的场景捕获。

默认用法

点击我查看水池设置
<template>
  <tv-scene
    class="scene"
    bg-color="rgb(40, 42, 54)"
    :axes-helper="false"
    :grid-helper="false"
    @created="created"
  >
    <tv-water-pool :shape="WATER_OUTLINE" :scale="WATER_SCALE" />
  </tv-scene>
</template>

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

const WATER_SCALE = 0.7
const TUB_SCALE: [number, number, number] = [1.59, 1.15, 0.868]
const WATER_HALF_X = (0.33 * TUB_SCALE[0] + 0.02) / WATER_SCALE
const WATER_HALF_Z = (0.72 * TUB_SCALE[2] + 0.02) / WATER_SCALE
const WATER_OUTLINE: [number, number][] = [
  [-WATER_HALF_X, -WATER_HALF_Z],
  [WATER_HALF_X, -WATER_HALF_Z],
  [WATER_HALF_X, WATER_HALF_Z],
  [-WATER_HALF_X, WATER_HALF_Z]
]

const created = (
  _scene: THREE.Scene,
  { camera, controls }: { camera?: THREE.Camera; controls?: OrbitControls }
) => {
  globalParameterBus.set('sunDirection', new THREE.Vector3(0.55, 0.9, 0.35))
  if (!camera) return
  camera.position.set(1.75, 2.2, 2.0)
  if (controls) controls.target.set(0, 0, 0)
  camera.lookAt(0, 0, 0)
}
</script>

在线示例在不使用 Draco 的情况下加载 /models/water-tub.glb,缩放为 [1.59, 1.15, 0.868],位置为 [0, 0.09 - 0.53 * 1.15, 0]。其 SkyDome 使用地平线 0x94c2f0、低空 0x7fb4ec、高空 0x3d7bd5、天顶 0x296bc7、辉光 0xfff1d8、太阳 0xfff7e6、强度 2.2 和太阳大小 5,并保留默认半径 420 与 48 段。场景销毁时会释放模型、天空穹顶以及卸载后才完成的异步加载。

拖动水面可产生涟漪;在水池外拖动可旋转相机。

不规则水池

点击我查看形状水池设置
<tv-water-pool :shape="TUB_OUTLINE" :scale="0.536 * 1.7" :position="[0, 0.33 * 1.7, 0]" />

<script lang="ts" setup>
const TUB_OUTLINE: [number, number][] = [
  [-1, 0],
  [-0.987, -0.106],
  [-0.945, -0.207],
  [-0.879, -0.291],
  [-0.795, -0.358],
  [-0.694, -0.399],
  [-0.588, -0.412],
  [0.513, -0.412],
  [0.619, -0.399],
  [0.72, -0.358],
  [0.804, -0.291],
  [0.871, -0.207],
  [0.981, -0.028],
  [0.981, 0.028],
  [0.871, 0.207],
  [0.804, 0.291],
  [0.72, 0.358],
  [0.619, 0.399],
  [0.513, 0.412],
  [-0.588, 0.412],
  [-0.694, 0.399],
  [-0.795, 0.358],
  [-0.879, 0.291],
  [-0.945, 0.207],
  [-0.987, 0.106]
]
</script>

相机位置为 [1.7, 1.35, 1.9],目标为 [0, 0.3, 0],背景为 rgb(40, 42, 54),并禁用坐标轴和网格辅助器。此示例使用与默认水池相同的太阳方向和 SkyDome 配置。在不使用 Draco 的情况下加载 /models/bathtub.glb,统一缩放为 1.7,位置为 [-0.595 * 1.7, 0, 0.28 * 1.7]。

属性

属性类型默认值说明
resolutionnumber128可选 每轴高度场网格数量,限制在 8–512。
shape'box' | WaterPoolOutline | BufferGeometryWATER_POOL_IRREGULAR_CUBE_OUTLINE可选 内置方形、自定义凸轮廓,或投影到 XZ 平面的几何体。
segmentsnumber160可选 沿解析后水池轮廓的细分数。
autoRipplesbooleantrue可选 每 1.8 秒自动产生一个随机涟漪。
interactivebooleantrue可选 允许拖动水面产生水滴。
positionVector3 | [number, number, number][0, 0, 0]可选 水面中心的世界坐标。
scalenumber1可选 同时应用于水池轮廓与深度的正数统一缩放。
type WaterPoolOutline = readonly (readonly [number, number])[]

shape="box" 解析为 WATER_POOL_BOX_OUTLINE,即 x、z 范围为 -1 到 1 的方形。默认 WATER_POOL_IRREGULAR_CUBE_OUTLINE 是倾斜四边形。自定义轮廓与几何体顶点会简化为凸包并移除共线点;结果必须包含原点且保持在 -1…1 范围内。两个内置轮廓均可从库中导入复用。

组件通过 globalParameterBus 获取太阳方向,不再提供本地扩展的显式太阳、方块、天空、曲率或边缘宽度属性。指针射线与水滴会转换到水池局部坐标,因此修改 position 和 scale 后,交互仍与水面保持一致。

实现原理

  • CPU 高度场按网格保存 (高度, 速度, 法线.x, 法线.z),并运行两次波动方程迭代。数据以 RGBA 半浮点 DataTexture 上传,在顶点节点中位移水面。
  • 焦散贴图将水面网格沿折射后的太阳光线投影到池底。投影的局部压缩会把光线聚集成动态焦散。
  • 单一水面在 TSL 中使用解析射线追踪,反射与折射瓷砖池壁、池底和程序化天空。
  • 拖动水面会向高度场添加水滴,产生扩散的波纹,同时保留水池外的轨道控制器交互。
  • 模拟使用固定 1/60 秒的时间累加器,每帧最多补算三步,因此涟漪在不同刷新率下表现一致。

瓷砖贴图在 canvas 中生成,因此组件本身不会下载任何资源。这些示例中的 GLB 仅用于演示场景。重建和卸载时,旧几何体、材质、纹理、监听器、动画回调与订阅都会被释放。

渲染器支持

所有着色均使用 TSL 节点材质,两种渲染器均可运行:

  • WebGPU 通过 WebGPURenderer 直接执行节点图。
  • WebGL 通过 WebGLNodesHandler 将同一份 TSL 节点图编译为 GLSL。
在 GitHub 上编辑此页
Last Updated:
Contributors: Shing Rui, ruixinglong
Prev
海洋水面
Next
沙滩漫步