<!-- Three.js WebGPU 折射效果演示
一、代码整体功能
这是一个基于 Three.js + WebGPU 的3D交互式折射效果演示应用。主要实现了以下功能：

1. 核心视觉效果
动态折射效果：在场景中心创建一个透明平面，通过扭曲屏幕空间UV坐标来模拟光线折射

实时交互：用户可以通过鼠标控制相机视角（旋转、缩放、平移）

动画系统：一个带有自转的小球在场景中按照预设轨迹运动

2. 场景构建
创建了一个封闭的六面体房间（五个墙面+一个折射平面）

每个墙面使用不同颜色材质（红、绿、蓝、白），便于观察折射效果

配置了多光源系统（主光源+三个彩色辅助光源）

3. 技术特性
完整的WebGPU渲染管线

响应式设计，支持窗口大小自适应

集成调试工具（Inspector）

基于时间的动画系统

二、主要技术点详解
1. WebGPU渲染技术
javascript
// 使用Three.js的WebGPU后端
import * as THREE from 'three/webgpu';
const renderer = new THREE.WebGPURenderer();
优势：

相比WebGL，WebGPU提供更好的并行计算能力

更接近现代GPU架构，性能更优

支持更复杂的着色器操作

2. TSL着色器语言（Three.js Shading Language）
javascript
import { viewportSafeUV, viewportSharedTexture, screenUV, texture, uv } from 'three/tsl';

// 创建折射效果的核心代码
const verticalUVOffset = texture(floorNormal, uv().mul(5)).xy.mul(2).sub(1).mul(verticalNormalScale);
const refractorUV = screenUV.add(verticalUVOffset);
const verticalRefractor = viewportSharedTexture(viewportSafeUV(refractorUV));
技术点：

节点式着色器编程：声明式的着色器构建方式

视口纹理捕获：viewportSharedTexture 实时获取当前渲染结果

UV坐标操作：动态扭曲屏幕空间坐标实现折射效果

3. 折射效果实现原理
核心算法流程：
text
1. 获取当前帧渲染结果 → 作为折射源纹理
2. 加载法线贴图 → 提供折射偏移数据
3. 计算扭曲UV坐标：screenUV + normalOffset
4. 用扭曲后的UV采样视口纹理
5. 将结果渲染到透明平面上
数学原理：
法线贴图采样：texture(floorNormal, uv().mul(5))

将法线贴图重复5次，增加细节

从RGB通道中提取XY法向量

坐标映射转换：.mul(2).sub(1)

将 [0,1] 范围映射到 [-1,1] 范围

这是法线向量需要的标准范围

强度控制：.mul(verticalNormalScale)

verticalNormalScale=0.1 控制折射扭曲强度

4. 相机与交互系统
透视相机配置：
javascript
new THREE.PerspectiveCamera(45, window.innerWidth/window.innerHeight, 1, 500)
45度视野：接近人眼自然视角

1-500裁剪范围：优化渲染性能

自适应宽高比：防止图像拉伸

轨道控制器：
javascript
new OrbitControls(camera, renderer.domElement)
功能：

左键拖拽：围绕目标点旋转

右键拖拽：平移视图

滚轮：缩放视图

边界限制：防止相机穿墙或过远

5. 材质系统
折射平面材质：
javascript
new THREE.MeshBasicNodeMaterial({
    backdropNode: verticalRefractor  // 使用视口纹理作为背景
})
特点：

使用节点材质系统

transparent: true 启用透明度

完全依赖着色器计算，无需传统材质属性

墙面材质：
javascript
new THREE.MeshPhongMaterial({ 
    color: 0xffffff, 
    emissive: 0x7b7b7b, 
    flatShading: true 
})
特点：

冯氏光照模型：支持高光、漫反射、环境光

平面着色：每个面统一法线，产生棱角效果

自发光：确保在暗处可见

6. 动画系统
小球运动轨迹：
javascript
smallSphere.position.set(
    Math.cos(timer * 0.1) * 30,                    // X轴：圆周运动
    Math.abs(Math.cos(timer * 0.2)) * 20 + 5,      // Y轴：弹跳运动
    Math.sin(timer * 0.1) * 30                     // Z轴：圆周运动
)
运动分解：

水平面：X和Z轴使用 cos(t)/sin(t) 组合，产生半径30的圆周运动

垂直方向：使用 abs(cos(2t)) 确保Y坐标始终为正，产生弹跳效果

复合效果：小球在3D空间中沿螺旋轨迹运动

旋转动画：
javascript
smallSphere.rotation.y = (Math.PI / 2) - timer * 0.1;
smallSphere.rotation.z = timer * 0.8;
Y轴：随时间反向旋转

Z轴：随时间正向旋转

产生复杂的自转效果，增强视觉吸引力

7. 性能优化技术
几何体复用：
javascript
const planeGeo = new THREE.PlaneGeometry(100.1, 100.1);
// 所有墙面和折射平面使用相同的几何体实例
纹理优化：
法线贴图使用 THREE.RepeatWrapping：节省纹理内存

视口纹理共享：避免每帧创建新纹理

渲染优化：
合理的裁剪平面（1-500单位）

使用WebGPU的自动批处理和优化

8. 调试与开发支持
Inspector集成：
javascript
renderer.inspector = new Inspector();
verticalRefractor.toInspector('Viewport Texture');
调试功能：

实时查看渲染状态

检查材质和纹理

性能分析

场景层级浏览

9. 响应式设计
窗口大小适配：
javascript
window.addEventListener('resize', onWindowResize);
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
}
确保：

宽高比正确

渲染分辨率匹配显示分辨率

画面不变形 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面基础元数据设置
			1. charset=utf-8: 确保中文和其他Unicode字符正确显示
			2. viewport: 移动端适配配置
			   - width=device-width: 视口宽度等于设备宽度
			   - user-scalable=no: 禁止用户手动缩放（适合WebGL应用）
			   - minimum-scale=1.0, maximum-scale=1.0: 固定缩放比例为1
		-->
		<title>Three.js WebGPU - 折射效果演示</title>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			信息展示面板
			这个div包含Three.js的logo链接、标题和简短描述
			id="info" 通常用于CSS样式定位和JavaScript操作
		-->
		<div id="info">
			<!-- 
				Three.js官方Logo链接
				- href: 点击跳转到Three.js官网
				- target="_blank": 在新标签页打开
				- rel="noopener": 安全属性，防止新页面访问原页面的window对象
				- class="logo-link": CSS类名，通常用于设置背景图片显示Three.js Logo
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 
				标题包装容器
				包含主标题和副标题
			-->
			<div class="title-wrapper">
				<!-- 主标题链接：点击跳转到Three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：显示当前示例的具体内容 -->
				<span>折射效果演示</span>
			</div>

			<!-- 
				简短描述文本
				<small> 标签表示小号字体，通常用于免责声明、版权信息等次要内容
				这里描述当前示例的技术特点
			-->
			<small>
				使用视口背景纹理实现的动态折射效果
			</small>
		</div>

		<!-- 
			ES模块导入映射(Import Maps)
			这是现代浏览器支持的模块解析机制，允许开发者控制模块的导入路径
			
			作用：
			1. 将简短模块名映射到具体文件路径
			2. 方便版本管理和模块替换
			3. 避免在代码中使用相对路径的复杂性
			
			在这个配置中：
			- "three": 指向Three.js的WebGPU版本构建文件
			- "three/webgpu": 同样指向WebGPU版本，提供特定导入路径
			- "three/tsl": 指向Three.js着色器语言(TSL)构建文件
			- "three/addons/": 指向附加模块(插件)的目录
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.webgpu.js",
					"three/webgpu": "../build/three.webgpu.js",
					"three/tsl": "../build/three.tsl.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块
			type="module" 表示这是一个ES6模块，支持import/export语法
			模块中的代码具有自己的作用域，不会污染全局命名空间
		-->
		<script type="module">

			// ========== 模块导入部分 ==========
			
			// 导入Three.js的核心WebGPU模块
			// * as THREE 表示将整个模块导入为THREE对象，包含所有Three.js的类和函数
			import * as THREE from 'three/webgpu';
			
			// 从three/tsl模块导入着色器语言相关函数：
			// - viewportSafeUV: 确保UV坐标在安全范围内(0-1之间)，防止纹理采样越界
			// - viewportSharedTexture: 获取当前视口的渲染结果作为纹理，用于后处理效果
			// - screenUV: 屏幕空间的UV坐标(0到1)，从屏幕左下角到右上角
			// - texture: 纹理采样函数，用于在着色器中读取纹理数据
			// - uv: UV坐标函数，返回当前像素的纹理坐标
			import { viewportSafeUV, viewportSharedTexture, screenUV, texture, uv } from 'three/tsl';

			// 导入轨道控制器模块
			// OrbitControls 允许用户通过鼠标/触摸控制相机：
			// - 左键拖拽：旋转视图
			// - 右键拖拽：平移视图
			// - 滚轮：缩放视图
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入调试检查器模块
			// Inspector 提供WebGL场景的实时调试界面，可以查看：
			// - 渲染状态
			// - 材质属性
			// - 性能指标
			// - 场景层级结构
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ========== 全局变量声明 ==========
			// 这些变量将在多个函数中共享使用
			let camera, scene, renderer; // Three.js核心三要素：相机、场景、渲染器
			let cameraControls;          // 相机控制器实例
			let smallSphere;             // 可移动的小球对象引用，用于动画更新

			// ========== 初始化调用 ==========
			// 页面加载完成后立即执行初始化
			init();

			/**
			 * 初始化函数
			 * 这是整个Three.js应用的入口点，负责：
			 * 1. 创建场景、相机、渲染器等核心对象
			 * 2. 创建3D模型和材质
			 * 3. 设置灯光和阴影
			 * 4. 配置用户交互
			 * 5. 启动渲染循环
			 */
			function init() {

				// ========== 场景创建 ==========
				// Scene对象是所有3D对象的容器，包含：
				// - 网格(Mesh)
				// - 灯光(Light)
				// - 相机(Camera)
				// - 其他辅助对象
				scene = new THREE.Scene();

				// ========== 相机创建与配置 ==========
				// 创建透视相机(PerspectiveCamera)，模拟人眼视角：
				// 参数说明：
				// 1. fov: 视野角度(45度)，决定可见范围大小
				// 2. aspect: 宽高比(窗口宽度/高度)，确保渲染不变形
				// 3. near: 近裁剪面(1)，距离相机1单位以内的物体不显示
				// 4. far: 远裁剪面(500)，距离相机500单位以外的物体不显示
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 1, 500);
				// 设置相机初始位置：x=0, y=50(离地面50单位), z=160(向后160单位)
				camera.position.set(0, 50, 160);

				// ========== 创建可移动的小球 ==========
				// 1. 创建几何体：二十面体(Icosahedron)
				//    参数说明：radius=5, detail=0(细分级别，0表示基础形状)
				const geometry = new THREE.IcosahedronGeometry(5, 0);
				
				// 2. 创建材质：冯氏材质(MeshPhongMaterial)
				//    支持高光、环境光、漫反射等多种光照效果
				const material = new THREE.MeshPhongMaterial({
					color: 0xffffff,      // 基础颜色：白色(RGB: 255,255,255)
					emissive: 0x7b7b7b,   // 自发光颜色：灰色，使物体在暗处也可见
					flatShading: true     // 平面着色：每个面使用统一法线，产生棱角效果
				});
				
				// 3. 创建网格对象：几何体+材质
				smallSphere = new THREE.Mesh(geometry, material);
				
				// 4. 将小球添加到场景中
				scene.add(smallSphere);

				// ========== 纹理加载与处理 ==========
				// TextureLoader用于从URL加载图像纹理
				const loader = new THREE.TextureLoader();

				// 加载地板法线贴图
				// 法线贴图用于在不增加几何体复杂度的情况下模拟表面细节
				const floorNormal = loader.load('textures/floors/FloorsCheckerboard_S_Normal.jpg');
				
				// 设置纹理包裹方式：
				// THREE.RepeatWrapping表示纹理在UV方向上重复
				floorNormal.wrapS = THREE.RepeatWrapping;  // S方向(U轴，水平方向)
				floorNormal.wrapT = THREE.RepeatWrapping;  // T方向(V轴，垂直方向)

				// ========== 折射平面创建（核心特效） ==========
				// 这部分使用Three.js着色器语言(TSL)创建动态折射效果
				
				// 法线缩放系数：控制折射效果的强度
				// 值越小，折射效果越微弱；值越大，扭曲效果越明显
				const verticalNormalScale = 0.1;
				
				// 创建UV偏移量：
				// 1. texture(floorNormal, uv().mul(5)): 对法线贴图采样，UV坐标乘以5实现纹理重复
				// 2. .xy: 取纹理的红色和绿色通道（法线贴图的X和Y分量）
				// 3. .mul(2).sub(1): 将[0,1]范围映射到[-1,1]范围（法线向量需要的范围）
				// 4. .mul(verticalNormalScale): 乘以缩放系数，控制偏移强度
				const verticalUVOffset = texture(floorNormal, uv().mul(5)).xy.mul(2).sub(1).mul(verticalNormalScale);

				// 计算折射UV坐标：
				// 屏幕UV坐标 + 法线贴图产生的偏移 = 动态扭曲效果
				// 当小球移动时，折射效果会随之变化
				const refractorUV = screenUV.add(verticalUVOffset);
				
				// 创建视口共享纹理：
				// 1. viewportSafeUV(refractorUV): 确保折射UV在安全范围内
				// 2. viewportSharedTexture(): 获取当前帧缓冲区的渲染结果作为纹理
				// 3. .toInspector('Viewport Texture'): 将纹理暴露给调试检查器，便于查看
				const verticalRefractor = viewportSharedTexture(viewportSafeUV(refractorUV)).toInspector('Viewport Texture');

				// 创建平面几何体用于显示折射效果
				// 尺寸略大于100(100.1)以避免Z-fighting（深度冲突）
				const planeGeo = new THREE.PlaneGeometry(100.1, 100.1);

				// 创建折射平面材质：
				// MeshBasicNodeMaterial是Three.js的节点材质系统
				// backdropNode属性指定背景纹理节点，这里使用我们创建的视口纹理
				const planeRefractor = new THREE.Mesh(planeGeo, new THREE.MeshBasicNodeMaterial({
					backdropNode: verticalRefractor  // 将视口纹理作为背景/折射源
				}));
				
				// 启用材质透明：允许看到后面的物体
				planeRefractor.material.transparent = true;
				
				// 设置位置：y=50，位于场景中间高度
				planeRefractor.position.y = 50;
				
				// 添加到场景
				scene.add(planeRefractor);

				// ========== 创建房间墙壁（包围盒） ==========
				// 创建一个封闭空间，便于观察折射效果
				
				// 1. 顶部墙面（白色）
				const planeTop = new THREE.Mesh(planeGeo, new THREE.MeshPhongMaterial({ color: 0xffffff }));
				planeTop.position.y = 100;              // 位置：顶部
				planeTop.rotateX(Math.PI / 2);          // 绕X轴旋转90度，使其水平
				scene.add(planeTop);

				// 2. 底部墙面（白色）
				const planeBottom = new THREE.Mesh(planeGeo, new THREE.MeshPhongMaterial({ color: 0xffffff }));
				planeBottom.rotateX(-Math.PI / 2);      // 绕X轴旋转-90度
				scene.add(planeBottom);

				// 3. 背面墙面（浅蓝色）
				const planeBack = new THREE.Mesh(planeGeo, new THREE.MeshPhongMaterial({ color: 0x7f7fff }));
				planeBack.position.z = -50;             // Z轴负方向
				planeBack.position.y = 50;              // 高度与折射平面对齐
				scene.add(planeBack);

				// 4. 右侧墙面（绿色）
				const planeRight = new THREE.Mesh(planeGeo, new THREE.MeshPhongMaterial({ color: 0x00ff00 }));
				planeRight.position.x = 50;             // X轴正方向
				planeRight.position.y = 50;
				planeRight.rotateY(-Math.PI / 2);       // 绕Y轴旋转-90度，使其朝内
				scene.add(planeRight);

				// 5. 左侧墙面（红色）
				const planeLeft = new THREE.Mesh(planeGeo, new THREE.MeshPhongMaterial({ color: 0xff0000 }));
				planeLeft.position.x = -50;             // X轴负方向
				planeLeft.position.y = 50;
				planeLeft.rotateY(Math.PI / 2);         // 绕Y轴旋转90度，使其朝内
				scene.add(planeLeft);

				// ========== 灯光系统配置 ==========
				// 灯光对于3D场景的视觉效果至关重要
				
				// 1. 主光源（白色点光源）
				// 参数：颜色(0xe7e7e7), 强度(2.5), 距离(250), 衰减(0)
				const mainLight = new THREE.PointLight(0xe7e7e7, 2.5, 250, 0);
				mainLight.position.y = 60;  // 位于场景上方
				scene.add(mainLight);

				// 2. 辅助光源1（绿色）
				// 位于场景右侧远处，提供彩色氛围光
				const greenLight = new THREE.PointLight(0x00ff00, 0.5, 1000, 0);
				greenLight.position.set(550, 50, 0);
				scene.add(greenLight);

				// 3. 辅助光源2（红色）
				// 位于场景左侧远处
				const redLight = new THREE.PointLight(0xff0000, 0.5, 1000, 0);
				redLight.position.set(-550, 50, 0);
				scene.add(redLight);

				// 4. 辅助光源3（蓝色）
				// 位于场景后方远处
				const blueLight = new THREE.PointLight(0xbbbbfe, 0.5, 1000, 0);
				blueLight.position.set(0, 50, 550);
				scene.add(blueLight);

				// ========== 渲染器配置 ==========
				// WebGPURenderer是Three.js的下一代渲染器，相比WebGLRenderer：
				// - 性能更好，支持多线程渲染
				// - 支持更现代的GPU特性
				// - 更好的内存管理
				
				// 创建WebGPU渲染器实例
				// 注释掉的 { antialias: true } 表示可以启用抗锯齿（消耗更多性能）
				renderer = new THREE.WebGPURenderer( /*{ antialias: true }*/ );
				
				// 设置设备像素比：确保在高DPI屏幕上清晰显示
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染尺寸为窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// 替代传统的requestAnimationFrame，Three.js的现代API
				renderer.setAnimationLoop(animate);
				
				// 附加调试检查器到渲染器
				// 通常按F12或特定快捷键可以打开调试界面
				renderer.inspector = new Inspector();
				
				// 将渲染器的canvas元素添加到页面body中
				// renderer.domElement 是实际的<canvas>元素
				document.body.appendChild(renderer.domElement);

				// ========== 用户交互控制 ==========
				// 创建轨道控制器，绑定相机和渲染器的canvas元素
				cameraControls = new OrbitControls(camera, renderer.domElement);
				
				// 设置控制目标点：相机围绕这个点旋转
				cameraControls.target.set(0, 50, 0);
				
				// 限制相机与目标点的距离
				cameraControls.maxDistance = 400;  // 最大距离
				cameraControls.minDistance = 10;   // 最小距离（防止穿入物体）
				
				// 更新控制器内部状态
				cameraControls.update();

				// ========== 事件监听器 ==========
				// 监听窗口大小变化事件
				window.addEventListener('resize', onWindowResize);

			}

			/**
			 * 窗口大小变化处理函数
			 * 当用户调整浏览器窗口大小时自动调用
			 * 确保3D场景始终正确适配窗口尺寸
			 */
			function onWindowResize() {
				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵
				// 在Three.js中，修改相机参数后必须调用此方法才能使更改生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数
			 * 每一帧（通常60fps）都会被调用
			 * 负责：
			 * 1. 更新场景中物体的状态（位置、旋转等）
			 * 2. 调用渲染器进行渲染
			 */
			function animate() {
				// 创建基于时间的计数器
				// Date.now()返回毫秒时间戳，乘以0.01将其转换为较小的数值
				const timer = Date.now() * 0.01;

				// 更新小球的位置，创建圆周运动效果：
				// X轴：余弦函数 * 半径(30)，产生左右摆动
				// Y轴：余弦函数的绝对值 * 振幅(20) + 基础高度(5)，确保小球不会低于5单位
				// Z轴：正弦函数 * 半径(30)，产生前后摆动
				// 这样小球会在水平面上做圆周运动，同时在垂直方向上上下浮动
				smallSphere.position.set(
					Math.cos(timer * 0.1) * 30,                    // X坐标
					Math.abs(Math.cos(timer * 0.2)) * 20 + 5,      // Y坐标
					Math.sin(timer * 0.1) * 30                     // Z坐标
				);

				// 更新小球的旋转：
				// Y轴：固定角度(Math.PI/2 ≈ 1.57弧度)减去随时间变化的角度
				// Z轴：随时间匀速旋转
				smallSphere.rotation.y = (Math.PI / 2) - timer * 0.1;
				smallSphere.rotation.z = timer * 0.8;

				// 执行渲染：将场景从相机视角绘制到屏幕上
				// 这是Three.js最核心的方法，每帧必须调用
				renderer.render(scene, camera);
			}

		</script>
	</body>
</html>