<!-- Three.js WebGPU 运动模糊示例 - 详细分析
一、代码功能概述
这是一个基于 Three.js WebGPU 渲染器实现的运动模糊效果演示。该示例展示了如何通过速度向量（运动矢量）实现高质量的运动模糊效果，同时包含了完整的3D场景、动画、光照、阴影和交互功能。

核心功能模块：
3D场景构建

室内环境（地板+墙壁）

动态光照系统（主光源+环境光）

雾效增强深度感

阴影系统

动画系统

GLTF动画角色（机器人舞蹈）

动态物体（旋转的圆环、缩放动画）

基于时间的动画控制

运动模糊效果

基于速度向量的后处理模糊

可调节的模糊强度

多重渲染目标（MRT）技术

交互系统

鼠标控制相机（旋转/缩放）

实时参数调整面板

自动旋转演示模式

视觉效果增强

晕影（暗角）效果

调试显示面板

响应式布局

二、主要技术点详解
1. WebGPU 渲染器
javascript
renderer = new THREE.WebGPURenderer();
现代图形API：取代WebGL，提供更接近原生图形API的能力

性能优势：更好的多线程支持、更低的CPU开销

功能丰富：支持计算着色器、光线追踪等高级特性

自动内存管理：相比WebGL的手动内存管理更智能

2. 运动模糊实现原理
技术流程：
text
场景渲染 → 生成速度缓冲区 → 后处理模糊 → 最终合成
关键技术：
速度向量（Velocity Buffer）：

javascript
scenePass.setMRT( mrt( {
    output,     // 颜色缓冲区
    velocity    // 速度缓冲区
} ) );
每个像素存储从上一帧到当前帧的运动向量

包含方向（X,Y）和速度大小信息

多重渲染目标（MRT）：

单次渲染通道输出多个纹理

分别用于颜色和速度数据

减少渲染通道数量，提高性能

运动模糊着色器：

javascript
const mBlur = motionBlur( beauty, vel );
沿速度方向进行采样和混合

采样距离与速度大小成正比

支持运动向量缩放调整模糊强度

3. TSL（Three.js Shading Language）节点系统
javascript
import { pass, texture, uniform, output, mrt, velocity, uv, screenUV } from 'three/tsl';
特点：
可视化编程：通过节点连接构建着色器

实时编辑：可以在运行时修改着色器逻辑

模块化：预定义的效果节点可以重复使用

节点示例：
javascript
// 创建UV节点并缩放
const floorUV = uv().mul( 5 );

// 创建材质节点
const floorMaterial = new THREE.MeshPhongNodeMaterial();
floorMaterial.colorNode = texture( floorColor, floorUV );

// 晕影效果节点链
const vignette = screenUV.distance( .5 )
    .remap( .6, 1 )
    .mul( 2 )
    .clamp()
    .oneMinus();
4. 动画系统架构
时钟管理：
javascript
const clock = new THREE.Clock();
const delta = clock.getDelta(); // 帧时间差
三种动画类型：
骨骼动画（GLTF模型）：

javascript
mixer = new THREE.AnimationMixer( model );
mixer.update( delta * speed );
旋转动画（右侧圆环）：

javascript
boxRight.rotation.y += delta * 4 * speed;
缩放动画（左侧圆环）：

javascript
boxLeft.scale.setScalar( 1 + Math.sin( clock.elapsedTime * 10 * speed ) * .2 );
5. 光照与阴影系统
多层次光照：
主光源（DirectionalLight）：

模拟太阳光

投射动态阴影

黄色调温暖光

环境光（HemisphereLight）：

天空环境光（浅蓝色）

水面反射光（蓝紫色）

提供基础照明，避免完全黑暗区域

阴影优化：
javascript
sunLight.shadow.bias = - 0.001; // 解决阴影痤疮
sunLight.shadow.mapSize.width = 2048; // 高分辨率阴影贴图
6. 后处理管线
javascript
postProcessing = new THREE.PostProcessing( renderer );
postProcessing.outputNode = mBlur.mul( vignette );
处理流程：
场景渲染 → 颜色 + 速度缓冲区

运动模糊 → 应用速度向量的模糊

晕影效果 → 屏幕边缘变暗

最终合成 → 模糊结果 × 晕影

7. 交互与调试系统
轨道控制器：
javascript
controls = new OrbitControls( camera, renderer.domElement );
controls.enableDamping = true; // 启用阻尼（惯性效果）
调试面板：
javascript
const gui = renderer.inspector.createParameters( '运动模糊设置' );
gui.add( blurAmount, 'value', 0, 3 ).name( '模糊强度' );
调试显示：
javascript
.toInspector( 'Color' )    // 显示颜色缓冲区
.toInspector( 'Velocity' ) // 显示速度缓冲区
8. 性能优化技术
纹理优化：
javascript
floorColor.wrapS = THREE.RepeatWrapping; // 纹理重复
floorColor.colorSpace = THREE.SRGBColorSpace; // 正确颜色空间
几何体优化：
javascript
const floor = new THREE.Mesh( new THREE.BoxGeometry( 15, .001, 15 ), ... );
// 使用薄盒子代替平面，避免单面渲染问题
渲染优化：
MRT减少渲染次数

按需更新（requestAnimationFrame）

设备像素比适配（高DPI屏幕）

9. 资源管理
异步加载：
javascript
loader.load( 'models/gltf/Xbot.glb', function ( gltf ) {
    // 加载完成后的回调
    model = gltf.scene;
    // ... 设置模型
});
纹理管理：
纹理重复减少内存占用

正确的颜色空间转换

纹理过滤和包裹设置

三、技术架构图
text
┌─────────────────────────────────────────────────────┐
│                   用户交互层                          │
│  • 鼠标控制相机                                      │
│  • GUI参数调整                                      │
│  • 自动旋转模式                                      │
└───────────────┬─────────────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────────┐
│                 Three.js应用层                        │
│  • 场景管理                                          │
│  • 相机控制器                                        │
│  • 动画系统                                          │
│  • 资源加载器                                        │
└───────────────┬─────────────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────────┐
│                 渲染管线层                            │
│  ┌─────────────────────────────────────────────┐    │
│  │  场景渲染通道                                │    │
│  │  • 输出颜色缓冲区                            │    │
│  │  • 输出速度缓冲区                            │    │
│  └───────────────┬─────────────────────────────┘    │
│                  │                                   │
│  ┌───────────────▼─────────────────────────────┐    │
│  │  后处理通道                                  │    │
│  │  • 运动模糊效果                              │    │
│  │  • 晕影效果                                  │    │
│  │  • 最终合成                                  │    │
│  └─────────────────────────────────────────────┘    │
└───────────────┬─────────────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────────┐
│                WebGPU驱动层                          │
│  • 着色器编译                                        │
│  • 缓冲区管理                                        │
│  • 渲染命令提交                                      │
└─────────────────────────────────────────────────────┘
四、关键技术优势
1. 真实的运动模糊
基于物理：使用真实的运动向量，而非屏幕空间近似

高质量：支持任意方向和大小的运动

可调节：模糊强度实时可调

2. 现代渲染管线
WebGPU原生支持：充分利用现代GPU架构

节点化着色器：易于理解和修改效果

模块化设计：各个效果可以独立启用/禁用

3. 完整的学习示例
代码结构清晰：适合学习Three.js高级特性

完整的功能：包含3D开发的所有基本要素

良好的文档：详细的注释和调试信息

4. 生产就绪特性
性能优化：适合实际应用场景

错误处理：异步加载的资源管理

响应式设计：适应不同屏幕尺寸 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示示例名称和使用的技术 -->
		<title>Three.js WebGPU示例 - 运动模糊效果演示</title>
		<!-- 字符编码：指定文档使用UTF-8编码，支持多语言字符 -->
		<meta charset="utf-8">
		<!-- 视口设置：针对移动设备优化，禁止用户缩放，确保WebGL内容正确显示 -->
		<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 id="info">
			<!-- Three.js官方Logo链接：点击跳转到Three.js官网 -->
			<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>
			<br>
			<!-- 操作说明 -->
			<small style="margin-top: 20px;">操作指南：鼠标拖拽旋转视角，滚轮缩放，右侧面板调整参数</small>
		</div>

		<!-- 模块导入映射表（Import Map）：定义JavaScript模块的别名和路径 -->
		<!-- 作用：简化模块导入语句，让浏览器知道从哪里加载模块 -->
		<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模块，支持模块化导入 -->
		<script type="module">

			// ==================== 模块导入区域 ====================
			// 导入Three.js核心库（WebGPU版本）
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js Shading Language）节点
			// TSL是Three.js的着色器语言，用于节点化材质和后处理
			import { pass, texture, uniform, output, mrt, velocity, uv, screenUV } from 'three/tsl';
			
			// 导入运动模糊后处理效果
			import { motionBlur } from 'three/addons/tsl/display/MotionBlur.js';
			
			// 导入GLTF模型加载器，用于加载3D模型
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			
			// 导入轨道控制器，用于鼠标控制相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入调试器/检查器，用于创建参数控制面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ==================== 全局变量声明 ====================
			// Three.js核心对象
			let camera;     // 相机：决定3D场景的观察视角
			let scene;      // 场景：包含所有3D对象的容器
			let renderer;   // 渲染器：负责将3D场景渲染到2D画布上
			
			// 场景对象和动画控制器
			let boxLeft;    // 左侧盒子对象（进行缩放动画）
			let boxRight;   // 右侧盒子对象（进行旋转动画）
			let model;      // 加载的GLTF模型（动画角色）
			let mixer;      // 动画混合器：控制模型动画的播放
			let clock;      // 时钟对象：用于精确的时间计算和动画控制
			
			// 后处理和交互
			let postProcessing; // 后处理对象：管理所有后处理效果
			let controls;       // 轨道控制器：鼠标控制相机的移动和旋转
			
			// ==================== 参数配置对象 ====================
			// 存储可调整的参数，这些参数可以通过GUI面板修改
			const params = {
				speed: 1.0 // 动画速度控制因子（0-2范围），影响所有动画的速度
			};

			// ==================== 初始化函数调用 ====================
			// 程序入口：页面加载完成后开始初始化
			init();

			/**
			 * 初始化函数 - 程序的起点
			 * 功能：创建并设置Three.js的所有核心组件
			 * 包括：场景、相机、灯光、物体、材质、渲染器、控制器、后处理等
			 */
			function init() {

				// ---------- 1. 创建相机 ----------
				// 透视相机：模拟人眼视角，物体近大远小
				// 参数：视野角度50度，宽高比，近裁剪面0.25，远裁剪面30
				camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.25, 30 );
				// 设置相机初始位置：X=0, Y=1.5（大约人眼高度）, Z=4.5（向后一些）
				camera.position.set( 0, 1.5, 4.5 );

				// ---------- 2. 创建场景 ----------
				scene = new THREE.Scene();
				// 添加雾效：模拟大气透视，增强场景深度感
				// 参数：雾的颜色（浅蓝色），雾的起始距离7，完全遮挡距离25
				scene.fog = new THREE.Fog( 0x0487e2, 7, 25 );

				// ---------- 3. 创建光源系统 ----------
				// 主光源（模拟太阳光）：平行光，黄色调，强度5
				const sunLight = new THREE.DirectionalLight( 0xFFE499, 5 );
				sunLight.castShadow = true; // 启用阴影投射功能
				
				// 阴影相机参数设置：定义阴影的可见范围
				sunLight.shadow.camera.near = .1;   // 阴影近裁剪面
				sunLight.shadow.camera.far = 10;    // 阴影远裁剪面
				sunLight.shadow.camera.right = 2;   // 阴影相机右边界
				sunLight.shadow.camera.left = - 2;  // 阴影相机左边界
				sunLight.shadow.camera.top = 2;     // 阴影相机上边界
				sunLight.shadow.camera.bottom = - 2;// 阴影相机下边界
				
				// 阴影贴图分辨率：决定阴影质量，值越高阴影越清晰
				sunLight.shadow.mapSize.width = 2048;
				sunLight.shadow.mapSize.height = 2048;
				
				// 阴影偏移：解决阴影痤疮问题（自阴影导致的条纹）
				sunLight.shadow.bias = - 0.001;
				
				// 设置光源位置
				sunLight.position.set( 4, 4, 2 );

				// 环境光1（水面色调）：半球光，模拟水面反射的天空光
				const waterAmbientLight = new THREE.HemisphereLight( 0x333366, 0x74ccf4, 5 );
				
				// 环境光2（天空色调）：半球光，模拟天空的环境光
				const skyAmbientLight = new THREE.HemisphereLight( 0x74ccf4, 0, 1 );

				// 将所有光源添加到场景
				scene.add( sunLight );
				scene.add( skyAmbientLight );
				scene.add( waterAmbientLight );

				// ---------- 4. 创建时钟 ----------
				// 用于精确计算帧间时间差，保证动画速度与时间相关而非帧率相关
				clock = new THREE.Clock();

				// ---------- 5. 加载动画模型 ----------
				// 创建GLTF加载器实例
				const loader = new GLTFLoader();
				
				// 异步加载GLTF模型文件
				loader.load( 'models/gltf/Xbot.glb', function ( gltf ) {
					// 加载完成后的回调函数

					model = gltf.scene; // 获取模型的主场景对象
					model.rotation.y = Math.PI / 2; // 将模型旋转90度（面向相机）

					// 遍历模型的所有子对象
					model.traverse( function ( child ) {
						// 如果子对象是网格（Mesh）
						if ( child.isMesh ) {
							// 启用阴影：网格可以投射和接收阴影
							child.castShadow = true;
							child.receiveShadow = true;
						}
					} );

					// 创建动画混合器：用于控制模型的骨骼动画
					mixer = new THREE.AnimationMixer( model );

					// 获取模型的动画片段并播放（这里播放第4个动画）
					const action = mixer.clipAction( gltf.animations[ 3 ] );
					action.play(); // 开始播放动画

					// 将模型添加到主场景
					scene.add( model );

				} );

				// ---------- 6. 加载纹理 ----------
				// 创建纹理加载器
				const textureLoader = new THREE.TextureLoader();

				// 加载地板颜色纹理
				const floorColor = textureLoader.load( 'textures/floors/FloorsCheckerboard_S_Diffuse.jpg' );
				floorColor.wrapS = THREE.RepeatWrapping; // 水平方向纹理重复
				floorColor.wrapT = THREE.RepeatWrapping; // 垂直方向纹理重复
				floorColor.colorSpace = THREE.SRGBColorSpace; // 设置颜色空间（sRGB用于颜色纹理）

				// 加载地板法线纹理（用于法线贴图）
				const floorNormal = textureLoader.load( 'textures/floors/FloorsCheckerboard_S_Normal.jpg' );
				floorNormal.wrapS = THREE.RepeatWrapping;
				floorNormal.wrapT = THREE.RepeatWrapping;

				// ---------- 7. 创建地板 ----------
				// 创建UV节点：将纹理坐标缩放5倍，实现纹理重复效果
				const floorUV = uv().mul( 5 );

				// 使用节点系统创建地板材质
				const floorMaterial = new THREE.MeshPhongNodeMaterial();
				// 设置颜色节点：将纹理应用到材质
				floorMaterial.colorNode = texture( floorColor, floorUV );

				// 创建地板网格：使用盒子几何体（非常薄）
				const floor = new THREE.Mesh( new THREE.BoxGeometry( 15, .001, 15 ), floorMaterial );
				floor.receiveShadow = true; // 地板接收阴影
				floor.position.set( 0, 0, 0 );
				scene.add( floor );

				// ---------- 8. 创建墙壁 ----------
				// 使用与地板相同的材质，但设置为背面渲染
				const walls = new THREE.Mesh( 
					new THREE.BoxGeometry( 15, 15, 15 ), 
					new THREE.MeshPhongNodeMaterial( { 
						colorNode: floorMaterial.colorNode, 
						side: THREE.BackSide // 渲染背面，形成室内空间
					} ) 
				);
				scene.add( walls );

				// ---------- 9. 创建测试物体 ----------
				// 加载测试纹理（UV网格图，用于调试）
				const map = new THREE.TextureLoader().load( 'textures/uv_grid_opengl.jpg' );
				map.colorSpace = THREE.SRGBColorSpace;

				// 创建圆环几何体（环形）
				const geometry = new THREE.TorusGeometry( .8 );
				// 创建基础材质（只显示纹理）
				const material = new THREE.MeshBasicMaterial( { map } );

				// 创建右侧旋转盒子
				boxRight = new THREE.Mesh( geometry, material );
				boxRight.position.set( 3.5, 1.5, - 4 );
				scene.add( boxRight );

				// 创建左侧缩放盒子
				boxLeft = new THREE.Mesh( geometry, material );
				boxLeft.position.set( - 3.5, 1.5, - 4 );
				scene.add( boxLeft );

				// ---------- 10. 创建渲染器 ----------
				// 创建WebGPU渲染器（Three.js的新一代渲染器）
				renderer = new THREE.WebGPURenderer();
				renderer.setPixelRatio( window.devicePixelRatio ); // 设置设备像素比，适配高DPI屏幕
				renderer.setSize( window.innerWidth, window.innerHeight ); // 设置渲染器尺寸为窗口大小
				renderer.setAnimationLoop( animate ); // 设置动画循环回调函数
				renderer.shadowMap.enabled = true; // 启用阴影映射系统
				renderer.inspector = new Inspector(); // 创建调试器实例
				document.body.appendChild( renderer.domElement ); // 将渲染器的canvas元素添加到页面

				// ---------- 11. 创建相机控制器 ----------
				controls = new OrbitControls( camera, renderer.domElement );
				controls.minDistance = 1; // 最小缩放距离
				controls.maxDistance = 10; // 最大缩放距离
				controls.maxPolarAngle = Math.PI / 2; // 最大垂直旋转角度（90度，防止相机翻转）
				controls.autoRotate = true; // 启用自动旋转（场景自动缓慢旋转）
				controls.autoRotateSpeed = 1; // 自动旋转速度
				controls.target.set( 0, 1, 0 ); // 设置相机观察的目标点
				controls.enableDamping = true; // 启用阻尼效果（惯性效果）
				controls.dampingFactor = 0.05; // 阻尼系数（值越小惯性越大）
				controls.update(); // 初始化更新控制器

				// ==================== 后处理系统设置 ====================
				// ---------- 12. 创建模糊强度参数 ----------
				// uniform变量：可以在着色器中访问的全局变量
				const blurAmount = uniform( 1 ); // 初始值1

				// ---------- 13. 创建渲染通道 ----------
				// pass节点：定义一个渲染通道，渲染整个场景
				const scenePass = pass( scene, camera );
				
				// 设置多重渲染目标（MRT）：同时输出多个缓冲区
				// output: 颜色缓冲区（正常渲染结果）
				// velocity: 速度缓冲区（每个像素的运动向量）
				scenePass.setMRT( mrt( {
					output,     // 颜色输出
					velocity    // 速度向量输出（用于运动模糊）
				} ) );

				// ---------- 14. 获取渲染结果 ----------
				// 获取颜色纹理节点，并添加到调试器显示（标签为"Color"）
				const beauty = scenePass.getTextureNode().toInspector( 'Color' );
				
				// 获取速度纹理节点，乘以模糊强度，并添加到调试器显示
				const vel = scenePass.getTextureNode( 'velocity' )
					.toInspector( 'Velocity' )
					.mul( blurAmount ); // 应用模糊强度参数

				// ---------- 15. 创建运动模糊效果 ----------
				// 将颜色纹理和速度纹理传入运动模糊函数
				const mBlur = motionBlur( beauty, vel );

				// ---------- 16. 创建晕影效果 ----------
				// 屏幕空间UV：获取当前像素在屏幕上的坐标（0-1范围）
				// distance(.5)：计算每个像素到屏幕中心(0.5,0.5)的距离
				// remap(.6,1)：将距离值从[0.6,1]重新映射到[0,1]
				// mul(2).clamp()：乘以2并限制在[0,1]范围
				// oneMinus()：反转值（中心亮，边缘暗）
				const vignette = screenUV.distance( .5 )
					.remap( .6, 1 )
					.mul( 2 )
					.clamp()
					.oneMinus();

				// ---------- 17. 创建后处理对象 ----------
				postProcessing = new THREE.PostProcessing( renderer );
				// 设置最终输出节点：运动模糊结果 × 晕影效果
				postProcessing.outputNode = mBlur.mul( vignette );

				// ==================== 调试面板设置 ====================
				// 创建GUI控制面板，标题为"运动模糊设置"
				const gui = renderer.inspector.createParameters( '运动模糊设置' );
				gui.add( controls, 'autoRotate' ).name( '自动旋转' ); // 自动旋转开关
				gui.add( blurAmount, 'value', 0, 3 ).name( '模糊强度' ); // 模糊强度滑块
				gui.add( params, 'speed', 0, 2 ).name( '动画速度' ); // 动画速度滑块

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

			}

			/**
			 * 窗口大小变化处理函数
			 * 当浏览器窗口改变大小时调用，确保渲染正确适配新窗口尺寸
			 */
			function onWindowResize() {

				// 更新相机的宽高比（匹配新窗口比例）
				camera.aspect = window.innerWidth / window.innerHeight;
				// 必须调用updateProjectionMatrix()来应用新的宽高比
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸（匹配新窗口大小）
				renderer.setSize( window.innerWidth, window.innerHeight );

			}

			/**
			 * 动画循环函数
			 * 每一帧自动调用，更新场景状态并重新渲染
			 * 这是Three.js应用的核心循环
			 */
			function animate() {

				// ---------- 1. 更新控制器 ----------
				// 更新轨道控制器状态（处理用户输入、阻尼等）
				controls.update();

				// ---------- 2. 获取时间信息 ----------
				// delta：上一帧到当前帧的时间差（秒），用于时间相关动画
				const delta = clock.getDelta();
				// speed：从参数配置中获取当前速度因子
				const speed = params.speed;

				// ---------- 3. 更新场景物体 ----------
				// 更新右侧盒子：持续旋转
				// delta * 4 * speed：旋转速度 = 基础速度4弧度/秒 × 速度因子
				boxRight.rotation.y += delta * 4 * speed;
				
				// 更新左侧盒子：正弦波缩放动画
				// Math.sin(clock.elapsedTime * 10 * speed)：生成正弦波动画
				// .2：缩放幅度（±20%）
				boxLeft.scale.setScalar( 1 + Math.sin( clock.elapsedTime * 10 * speed ) * .2 );

				// ---------- 4. 更新模型动画 ----------
				// 如果模型已成功加载
				if ( model ) {
					// 更新动画混合器：推进动画时间
					// delta * speed：动画时间步长 × 速度因子
					mixer.update( delta * speed );
				}

				// ---------- 5. 渲染场景 ----------
				// 执行后处理渲染：应用运动模糊和晕影效果
				postProcessing.render();

			}

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