<!-- 代码功能和技术点分析
📋 项目概述
这是一个基于Three.js WebGPU的高质量景深效果演示程序，展示了现代Web图形技术的强大能力。程序创建了一个由大量球体组成的3D场景，并应用了实时可调的景深后处理效果。

🎯 核心功能
1. 3D场景构建
大规模实例化渲染：创建了14×9×14网格布局的1764个球体，使用InstancedMesh技术高效渲染

动态材质效果：每个球体表面结合了：

立方体贴图环境反射（瑞典皇家城堡天空盒）

基于世界位置和时间的正弦波动画

交互式相机控制：支持鼠标拖拽旋转、滚轮缩放

2. 景深后处理效果
物理正确的景深模拟：

对焦距离控制：调节清晰对焦平面的位置

焦距调节：改变镜头的焦距参数

散景缩放：控制背景虚化光斑的大小

实时参数调整：通过GUI面板可即时修改所有景深参数

3. 用户体验
响应式设计：自动适应不同屏幕尺寸和分辨率

调试支持：内置Inspector工具，可查看场景结构、材质属性等

平滑交互：轨道控制器启用阻尼效果，操作体验流畅

🔧 主要技术点
1. WebGPU渲染技术
javascript
// 关键技术：现代图形API
import * as THREE from 'three/webgpu';
const renderer = new THREE.WebGPURenderer();
优势：相比WebGL，WebGPU提供：

更好的多线程支持

更高效的计算着色器

更低的CPU开销

更现代的API设计

2. TSL（Three.js Shading Language）
javascript
import { cubeTexture, positionWorld, oscSine, time, pass, uniform } from 'three/tsl';
节点化着色器：可视化、模块化的着色器编程

动态材质：在运行时修改材质属性

后处理管道：声明式的效果组合方式

3. 实例化渲染优化
javascript
const mesh = new THREE.InstancedMesh(geometry, material, count);
性能优势：

单个Draw Call渲染数千个相同对象

减少GPU状态切换

降低CPU到GPU的数据传输

4. 后处理管线架构
javascript
// 完整的渲染管线
postProcessing.outputNode = dof(
  scenePassColor,          // 场景颜色
  scenePassViewZ,          // 场景深度
  focusDistance,           // 对焦距离
  focalLength,            // 焦距
  bokehScale              // 散景缩放
);
多阶段渲染：

场景渲染到纹理

深度信息提取

景深效果计算

最终合成输出

5. 立方体贴图环境映射
javascript
// 6面天空盒加载
const textureCube = new THREE.CubeTextureLoader().load(urls);
const cubeTextureNode = cubeTexture(textureCube);
环境照明：提供全局光照信息

反射效果：球体表面反射周围环境

无限远感觉：创建场景深度感

6. 动态着色动画
javascript
// 基于位置和时间的动画
const oscPos = oscSine(positionWorld.div(1000).add(time.mul(.2)));
material.colorNode = cubeTextureNode.mul(oscPos);
程序化动画：无需关键帧，数学计算驱动

GPU计算：动画在着色器中执行，性能高效

平滑变化：正弦波提供自然的周期性变化

7. 统一值（Uniform）系统
javascript
const focusDistance = uniform(500);
gui.add(focusDistance, 'value', 10.0, 3000.0);
运行时参数更新：无需重新编译着色器

GUI集成：实时交互调整

类型安全：TSL确保数据类型正确性

🎨 视觉效果特点
1. 景深效果质量
渐进式模糊：离焦平面越远，模糊程度越高

散景效果：模拟真实镜头的光斑形状

平滑过渡：清晰与模糊区域自然过渡

2. 材质表现
金属感表面：立方体贴图反射产生金属质感

动态变化：随时间波动的表面颜色

空间感强：大量重复物体增强透视感

🚀 性能优化策略
1. 渲染优化
实例化技术：大批量物体高效渲染

WebGPU特性：利用现代GPU架构

管线化处理：减少中间纹理复制

2. 内存管理
共享几何体：所有实例使用相同几何数据

纹理复用：立方体贴图被所有球体共享

智能缓冲：自动管理GPU内存

3. 响应式设计
自适应分辨率：根据屏幕DPR调整渲染分辨率

动态重绘：只在需要时更新

资源懒加载：纹理按需加载

🔍 调试与开发支持
1. 内置调试工具
javascript
renderer.inspector = new Inspector();
场景层级查看：可视化3D场景结构

材质属性检查：实时查看和修改材质参数

性能监控：帧率、内存使用等指标

2. 开发友好特性
热重载支持：通过import maps实现模块化

详细的错误提示：TSL提供编译时错误检查

渐进式增强：核心功能优先，高级效果可选 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js WebGPU - 景深后处理效果演示 -->
		<title>Three.js WebGPU - 景深后处理效果演示</title>
		<!-- 字符编码设置为UTF-8，支持中文字符 -->
		<meta charset="utf-8">
		<!-- 
			视口元标签，用于移动端适配：
			- width=device-width: 宽度设置为设备宽度
			- user-scalable=no: 禁止用户缩放
			- minimum-scale=1.0, maximum-scale=1.0: 最小和最大缩放比例都设为1，完全禁止缩放
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 引入外部CSS样式表文件，用于页面样式定义 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			页面信息展示区域，包含logo、标题和描述
			id="info": 用于CSS样式和JavaScript操作
		-->
		<div id="info">
			<!-- 
				three.js官网链接：
				- href: 跳转目标网址
				- target="_blank": 在新标签页打开
				- rel="noopener": 安全属性，防止新页面访问原页面的window.opener
				- class="logo-link": CSS样式类，通常用于设置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>高质量景深效果 - 使用WebGPU和TSL着色语言实现</small>
		</div>

		<!-- 
			导入映射表(Import Maps):
			现代JavaScript模块导入机制，允许开发者映射模块标识符到实际URL
			使import语句更简洁，无需写完整路径
		-->
		<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语法
			浏览器会自动延迟执行模块代码，直到HTML文档解析完成
		-->
		<script type="module">

			// ========== 模块导入部分 ==========
			
			// 导入Three.js的WebGPU渲染器核心模块
			// * as THREE: 将所有导出内容命名为THREE对象
			import * as THREE from 'three/webgpu';
			
			// 从three/tsl模块导入TSL着色语言节点
			// cubeTexture: 立方体贴图节点
			// positionWorld: 世界空间位置节点
			// oscSine: 正弦振荡器节点
			// time: 时间节点（自动更新）
			// pass: 渲染通道节点
			// uniform: 统一值节点（可在运行时修改）
			import { cubeTexture, positionWorld, oscSine, time, pass, uniform } from 'three/tsl';
			
			// 导入景深（Depth of Field）后处理节点
			// dof: 景深效果函数，用于创建景深后处理节点
			import { dof } from 'three/addons/tsl/display/DepthOfFieldNode.js';
			
			// 导入轨道控制器
			// OrbitControls: 允许用户用鼠标控制相机旋转、平移和缩放
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入调试检查器
			// Inspector: 可视化调试工具，可以查看场景层次、材质、纹理等
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ========== 全局变量声明 ==========
			
			// Three.js核心对象变量声明（未初始化）
			let camera;      // 相机：定义观察者的视角
			let scene;       // 场景：包含所有3D对象的容器
			let renderer;    // 渲染器：负责将3D场景绘制到2D画布
			let mesh;        // 网格：具体的3D物体（这里是实例化球体）
			let controls;    // 控制器：用户交互控制

			// 窗口尺寸变量
			let width = window.innerWidth;   // 当前窗口内部宽度（不包含浏览器UI）
			let height = window.innerHeight; // 当前窗口内部高度（不包含浏览器UI）

			// 后处理对象
			let postProcessing; // 用于管理和执行后处理效果链

			// ========== 初始化调用 ==========
			
			// 程序入口：调用初始化函数
			init();

			/**
			 * 初始化函数 - Three.js应用程序的起点
			 * 负责创建和设置所有核心组件：
			 * 1. 创建场景、相机、渲染器
			 * 2. 创建3D物体和材质
			 * 3. 设置光照、环境
			 * 4. 配置后处理效果
			 * 5. 设置用户交互
			 * 6. 绑定事件监听器
			 */
			function init() {

				// ----- 相机创建 -----
				// 创建透视相机：模拟人眼视角，物体近大远小
				// 参数说明：
				// 70: 垂直视野角度（FOV），单位度，影响视野范围
				// width / height: 宽高比，确保渲染不拉伸
				// 1: 近裁剪面，距离相机1个单位内的物体不显示
				// 3500: 远裁剪面，距离相机3500个单位外的物体不显示
				camera = new THREE.PerspectiveCamera( 70, width / height, 1, 3500 );
				// 设置相机初始位置：沿Z轴正方向移动200个单位
				// 在Three.js中：X轴向右，Y轴向上，Z轴向屏幕外
				camera.position.z = 200;

				// ----- 场景创建 -----
				// 创建场景对象：所有3D物体、光源、相机的容器
				scene = new THREE.Scene();
				// 注意：这里没有设置背景色或环境光，完全依赖立方体贴图照明

				// ----- 立方体贴图加载 -----
				// 准备立方体贴图（天空盒）的路径
				// 立方体贴图由6张图片组成，模拟无限远的环境
				const path = 'textures/cube/SwedishRoyalCastle/'; // 纹理文件夹路径
				const format = '.jpg'; // 图片格式
				// 六个面的图片文件名数组（顺序重要）：
				// 正X（右），负X（左），正Y（上），负Y（下），正Z（前），负Z（后）
				const urls = [
					path + 'px' + format, path + 'nx' + format, // 右面和左面
					path + 'py' + format, path + 'ny' + format, // 上面和下面
					path + 'pz' + format, path + 'nz' + format  // 前面和后面
				];

				// ----- 实例化网格参数设置 -----
				// 定义3D网格布局：在X、Y、Z轴上均匀分布球体
				const xgrid = 14; // X轴方向网格数量
				const ygrid = 9;  // Y轴方向网格数量
				const zgrid = 14; // Z轴方向网格数量
				const count = xgrid * ygrid * zgrid; // 计算总实例数量：14*9*14 = 1764个球体

				// 加载立方体贴图纹理
				// CubeTextureLoader是Three.js内置的纹理加载器
				// load()方法异步加载6张图片并创建立方体贴图对象
				const textureCube = new THREE.CubeTextureLoader().load( urls );
				
				// 创建TSL立方体贴图节点
				// cubeTexture()函数将Three.js纹理对象转换为TSL节点
				// 可以在着色器程序中使用这个节点
				const cubeTextureNode = cubeTexture( textureCube );
				
				// 创建动态动画节点：基于世界位置和时间
				// oscSine(): 正弦振荡器节点，生成-1到1的正弦波
				// positionWorld: 当前像素的世界坐标
				// .div(1000): 除以1000，缩小坐标值，使动画频率合适
				// time: 当前时间（秒），随时间自动递增
				// .mul(.2): 乘以0.2，控制动画速度
				// .add(): 将位置和时间的计算结果相加
				const oscPos = oscSine( positionWorld.div( 1000 /* 场景距离缩放因子 */ ).add( time.mul( .2 ) ) );

				// ----- 几何体和材质创建 -----
				// 创建球体几何体：
				// 参数说明：
				// 60: 球体半径
				// 20: 水平分段数（经线数量），值越高球体越光滑
				// 10: 垂直分段数（纬线数量），值越高球体越光滑
				const geometry = new THREE.SphereGeometry( 60, 20, 10 );
				
				// 创建基于节点的材质：
				// MeshBasicNodeMaterial: 基础节点材质，不受光照影响
				// 使用TSL节点图定义材质外观，而非固定参数
				const material = new THREE.MeshBasicNodeMaterial();
				
				// 设置材质颜色节点：
				// 将立方体贴图颜色与正弦振荡值相乘
				// 效果：球体表面颜色随位置和时间波动变化
				material.colorNode = cubeTextureNode.mul( oscPos );

				// ----- 实例化网格创建 -----
				// InstancedMesh: 高性能实例化网格
				// 优点：大量相同几何体只上传一次GPU，通过实例化矩阵区分位置
				// 参数说明：
				// geometry: 基础几何体（所有实例共享）
				// material: 基础材质（所有实例共享）
				// count: 实例总数（1764个）
				mesh = new THREE.InstancedMesh( geometry, material, count );
				// 将网格添加到场景中
				scene.add( mesh );

				// ----- 实例位置设置 -----
				// 创建临时矩阵对象，用于设置每个实例的变换
				const matrix = new THREE.Matrix4();
				// 实例索引，从0开始
				let index = 0;

				// 三层嵌套循环：遍历三维网格的每个位置
				for ( let i = 0; i < xgrid; i ++ ) {
					for ( let j = 0; j < ygrid; j ++ ) {
						for ( let k = 0; k < zgrid; k ++ ) {
							// 计算当前实例的坐标位置
							// 公式：200 * (当前位置索引 - 网格中心)
							// 使整个网格布局以场景原点为中心
							const x = 200 * ( i - xgrid / 2 ); // X坐标
							const y = 200 * ( j - ygrid / 2 ); // Y坐标
							const z = 200 * ( k - zgrid / 2 ); // Z坐标

							// 设置当前实例的变换矩阵
							// matrix.identity(): 将矩阵重置为单位矩阵（无变换）
							// .setPosition(x, y, z): 设置平移变换
							// mesh.setMatrixAt(): 将变换矩阵赋给指定索引的实例
							mesh.setMatrixAt( index, matrix.identity().setPosition( x, y, z ) );
							
							// 索引递增，处理下一个实例
							index ++;
						}
					}
				}

				// ----- 渲染器创建与配置 -----
				// 创建WebGPURenderer：使用现代WebGPU API的渲染器
				// 相比WebGLRenderer，WebGPU提供更好的性能和新特性支持
				renderer = new THREE.WebGPURenderer();
				
				// 设置设备像素比：
				// window.devicePixelRatio: 物理像素与CSS像素的比率
				// 高DPI屏幕（如Retina）此值大于1，设置后可以渲染更高分辨率
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器画布尺寸：
				// 使用窗口的完整内部尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数：
				// animate函数将在每一帧被调用（通常60fps）
				// 替代传统的requestAnimationFrame手动调用
				renderer.setAnimationLoop( animate );
				
				// 附加调试检查器到渲染器：
				// Inspector是可视化调试工具，可以查看场景结构、材质属性等
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到网页body中
				// renderer.domElement: 渲染器创建的<canvas>元素
				document.body.appendChild( renderer.domElement );

				// ----- 景深效果控制器 -----
				// 创建景深效果参数控制器
				// uniform(): 创建TSL统一值节点，这些值可以在运行时通过GUI修改
				const effectController = {
					focusDistance: uniform( 500 ),  // 对焦距离：相机到清晰对焦平面的距离（默认500）
					focalLength: uniform( 200 ),    // 焦距：镜头焦距长度，影响景深强度（默认200）
					bokehScale: uniform( 10 )       // 散景缩放：背景虚化光斑的大小（默认10）
				};

				// ----- 后处理管道配置 -----
				// 创建后处理对象
				// PostProcessing: Three.js的后处理管理器
				// 参数：渲染器实例，用于创建后处理所需的各种缓冲区和纹理
				postProcessing = new THREE.PostProcessing( renderer );

				// 创建场景渲染通道
				// pass(): TSL函数，创建场景渲染通道节点
				// 参数1：要渲染的场景对象
				// 参数2：渲染使用的相机
				// 该节点会输出场景的颜色纹理和深度信息
				const scenePass = pass( scene, camera );

				// 从场景通道获取颜色纹理节点
				// getTextureNode(): 获取颜色输出纹理节点
				// toInspector('Color'): 将节点注册到检查器，标签为"Color"，可在调试面板查看
				const scenePassColor = scenePass.getTextureNode().toInspector( 'Color' );
				
				// 从场景通道获取深度节点
				// getViewZNode(): 获取视图空间Z深度节点
				// 深度信息对于景深效果至关重要，决定哪些区域应该模糊
				const scenePassViewZ = scenePass.getViewZNode();

				// 创建景深效果节点
				// dof(): TSL景深函数，创建景深处理节点
				// 参数1：输入颜色纹理（场景原始渲染）
				// 参数2：深度信息（用于计算模糊强度）
				// 参数3：对焦距离（从effectController获取的uniform节点）
				// 参数4：焦距
				// 参数5：散景缩放
				const dofPass = dof( scenePassColor, scenePassViewZ, 
					effectController.focusDistance, 
					effectController.focalLength, 
					effectController.bokehScale 
				);

				// 设置后处理管道的最终输出节点
				// outputNode: 后处理链的最终输出节点
				// 这里设置为景深效果节点，表示渲染流程为：场景渲染 → 景深处理 → 屏幕输出
				postProcessing.outputNode = dofPass;

				// ----- 用户交互控制器 -----
				// 创建轨道控制器
				// OrbitControls: 允许用户通过鼠标/触摸控制相机
				// 参数1：要控制的相机对象
				// 参数2：事件监听的DOM元素（渲染器画布）
				controls = new OrbitControls( camera, renderer.domElement );
				
				// 启用阻尼效果：
				// 使相机运动有惯性，松开鼠标后缓慢停止，操作更平滑
				controls.enableDamping = true;

				// ----- 窗口大小变化监听 -----
				// 添加窗口大小变化事件监听器
				// 当用户调整浏览器窗口大小时，自动更新相机和渲染器
				window.addEventListener( 'resize', onWindowResize );

				// ----- 图形用户界面（GUI）创建 -----
				// 使用检查器创建参数控制面板
				// createParameters('Settings'): 创建名为"Settings"的参数面板
				const gui = renderer.inspector.createParameters( 'Settings' );
				
				// 添加对焦距离控制滑块：
				// add(): 添加控制项
				// 参数1：要控制的对象（effectController.focusDistance）
				// 参数2：要控制的属性名（'value'，因为uniform节点值存储在value属性）
				// 参数3和4：最小值10.0和最大值3000.0
				// name(): 设置控制项显示名称
				gui.add( effectController.focusDistance, 'value', 10.0, 3000.0 ).name( '对焦距离' );
				
				// 添加焦距控制滑块：
				// 范围50到750
				gui.add( effectController.focalLength, 'value', 50, 750 ).name( '焦距' );
				
				// 添加散景缩放控制滑块：
				// 范围1到20
				gui.add( effectController.bokehScale, 'value', 1, 20 ).name( '散景缩放' );
			}

			/**
			 * 窗口大小变化事件处理函数
			 * 当用户调整浏览器窗口大小时自动调用
			 * 确保渲染正确适应新窗口尺寸
			 */
			function onWindowResize() {
				// 更新窗口尺寸变量
				width = window.innerWidth;
				height = window.innerHeight;

				// 更新相机宽高比
				// 保持相机视野比例正确，避免图像拉伸
				camera.aspect = width / height;
				
				// 更新相机投影矩阵
				// 当相机参数（如宽高比）改变后，必须调用此方法重新计算投影矩阵
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				// 使画布尺寸与新窗口尺寸一致
				renderer.setSize( width, height );
			}

			/**
			 * 动画循环函数
			 * 每一帧自动调用（通常每秒60次）
			 * 负责更新场景状态和渲染
			 */
			function animate() {
				// 更新轨道控制器
				// 必须每帧调用，特别是启用了阻尼效果时
				// 内部会更新相机位置和旋转
				controls.update();

				// 执行后处理渲染
				// postProcessing.render(): 
				// 1. 首先渲染场景到纹理（scenePass）
				// 2. 然后应用景深效果（dofPass）
				// 3. 最后将结果绘制到屏幕
				// 整个过程自动处理，无需手动调用renderer.render()
				postProcessing.render();
			}

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