<!-- Three.js WebGPU - 基于立方体摄像机的光照探针演示
🎯 整体功能概述
这是一个使用Three.js WebGPU实现的实时环境光照生成系统。该示例展示了如何通过立方体摄像机捕获场景环境，生成环境贴图，并基于此创建光照探针，实现逼真的全局光照效果。用户可以通过鼠标交互自由探索3D场景，观察光照探针的实时效果。

🔧 主要技术点详解
1. WebGPU渲染技术
核心优势：替代传统的WebGL，提供更接近原生GPU的性能

技术特点：

支持计算着色器，可实现更复杂的光照计算

更细粒度的并行处理能力

减少CPU到GPU的数据传输开销

使用await renderer.init()进行异步初始化

2. 立方体摄像机（Cube Camera）系统
工作原理：从场景中的一点向6个方向（+X/-X, +Y/-Y, +Z/-Z）分别渲染，生成立方体贴图

实现代码：

javascript
const cubeRenderTarget = new THREE.WebGLCubeRenderTarget(256);
cubeCamera = new THREE.CubeCamera(1, 1000, cubeRenderTarget);
cubeCamera.update(renderer, scene); // 执行6个方向的渲染
3. 光照探针（Light Probe）技术
核心概念：使用球谐函数（Spherical Harmonics） 近似表示环境光照

数学原理：将复杂的环境光照分解为9个球谐系数（3阶SH）

生成流程：

javascript
// 从立方体贴图生成光照探针
const probe = await LightProbeGenerator.fromCubeRenderTarget(
    renderer, cubeRenderTarget
);
lightProbe.copy(probe);
4. 环境贴图（Environment Mapping）
作用：为场景提供背景和环境反射

加载过程：

javascript
// 加载6个方向的贴图
const urls = ['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png'];
new THREE.CubeTextureLoader().load(urls, function(cubeTexture) {
    scene.background = cubeTexture; // 设置为场景背景
});
5. 可视化辅助工具
光照探针辅助器（LightProbeHelper）：

在场景中显示球谐光照的可视化表示

帮助开发者理解和调试光照数据

javascript
scene.add(new LightProbeHelper(lightProbe, 5)); // 尺寸为5
轨道控制器（OrbitControls）：

提供鼠标交互：旋转、缩放、平移

javascript
const controls = new OrbitControls(camera, renderer.domElement);
controls.addEventListener('change', render); // 变化时重新渲染
6. 响应式设计
窗口大小自适应：

javascript
window.addEventListener('resize', onWindowResize);
// 调整渲染器大小和摄像机参数
renderer.setSize(window.innerWidth, window.innerHeight);
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
📊 技术架构流程
graph TD
    A[开始初始化] -> B[创建WebGPU渲染器]
    B -> C[创建场景和摄像机]
    C -> D[设置用户交互控制]
    D -> E[加载环境贴图作为背景]
    E -> F[创建立方体摄像机]
    F -> G[从6个方向渲染场景]
    G -> H[生成环境立方体贴图]
    H -> I[分析贴图生成光照探针]
    I -> J[添加可视化辅助工具]
    J -> K[渲染最终场景]
    K -> L{用户交互}
    L -> M[更新摄像机位置]
    M -> K
🎨 视觉效果特点
1. 基于图像的照明（IBL）
原理：使用真实环境图像作为光源

效果：物体表面会反射环境颜色和亮度

优势：比传统点光源/平行光源更真实

2. 动态光照更新
立方体摄像机可以实时更新环境贴图

光照探针会根据环境变化自动更新

适合动态场景或随时间变化的环境

3. 性能优化
球谐函数压缩：将复杂的光照数据压缩为9个系数

实时计算：在GPU上高效计算光照贡献

内存优化：相比完整环境贴图，球谐系数占用内存极小

🚀 应用场景
1. 游戏开发
角色在不同环境下的真实光照表现

动态天气/时间系统

室内外场景切换

2. 建筑可视化
建筑模型在不同光照条件下的展示

日间/夜间模式切换

不同季节的光照模拟

3. 产品展示
产品在不同环境下的视觉效果

材质反射和折射的真实表现

虚拟试装/试戴场景

4. 教育和研究
计算机图形学教学

光照模型研究

实时渲染技术演示

🔍 技术深度解析
1. 球谐函数（Spherical Harmonics）原理
text
光照探针使用3阶球谐函数，包含9个系数：
- 第0阶：1个系数（整体亮度）
- 第1阶：3个系数（主要方向）
- 第2阶：5个系数（细节分布）
总复杂度：O(9) vs 环境贴图O(6×256×256)
2. WebGPU vs WebGL性能对比
特性	WebGL	WebGPU
并行处理	有限	高度并行
计算着色器	不支持	支持
内存管理	自动	显式控制
命令缓冲	即时模式	命令列表
3. 环境贴图分辨率优化
256×256：平衡质量与性能

Mipmap生成：自动生成多级纹理

HDR支持：可加载高动态范围图像

💡 扩展可能性
动态环境更新：随时间变化的环境贴图

多重光照探针：不同区域使用不同光照探针

实时反射：结合屏幕空间反射（SSR）

体积光照：添加雾效和光轴效果

后处理效果：添加抗锯齿、色调映射等

🏆 技术亮点总结
现代化渲染流水线：使用WebGPU这一前沿技术

真实光照模拟：基于物理的光照探针技术

高效性能表现：球谐函数大幅降低计算开销

优秀用户体验：流畅的交互和响应式设计

完整技术栈：从资源加载到最终渲染的全流程展示 -->


<!DOCTYPE html>
<!-- 声明HTML5文档类型 -->
<html lang="en">
	<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.0 -->
		<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>
		<!-- 页面信息展示区域：用于显示标题、链接和说明文字 -->
		<div id="info">
			<!-- Three.js官网链接：点击跳转到Three.js官方网站 -->
			<!-- target="_blank": 在新标签页中打开链接 -->
			<!-- rel="noopener": 安全设置，防止新页面访问原页面的window对象 -->
			<!-- class="logo-link": 通常用于添加Three.js的logo样式 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link">
				<!-- 这里通常包含Three.js的logo图片或文字 -->
			</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>

		<!-- 导入映射配置：现代JavaScript模块系统的路径映射 -->
		<!-- type="importmap": 指定这是一个导入映射，用于定义模块的别名 -->
		<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核心库的全部功能
			// 使用import * as语法将整个模块导入为THREE对象
			import * as THREE from 'three/webgpu';

			// 导入调试工具：Inspector允许在运行时检查和调试Three.js场景
			// 通常包含场景图查看器、属性编辑器等功能
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器：允许用户通过鼠标拖拽、滚轮缩放来交互式控制摄像机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入光照探针辅助显示工具（GPU版本）
			// 这个工具可以在场景中可视化显示光照探针的球谐函数系数
			import { LightProbeHelper } from 'three/addons/helpers/LightProbeHelperGPU.js';
			
			// 导入光照探针生成器：提供从各种源生成光照探针的工具函数
			import { LightProbeGenerator } from 'three/addons/lights/LightProbeGenerator.js';

			// ==================== 全局变量声明 ====================
			
			// 渲染器对象：负责将3D场景绘制到2D画布上
			let renderer;
			
			// 场景对象：包含所有的3D对象（网格、灯光、相机等）
			let scene;
			
			// 透视摄像机对象：用于观察场景的视角
			let camera;
			
			// 立方体摄像机对象：用于生成环境贴图，它从6个方向拍摄场景
			let cubeCamera;

			// 光照探针对象：存储场景光照信息的对象
			// 光照探针使用球谐函数来近似表示环境光照
			let lightProbe;

			// ==================== 初始化调用 ====================
			
			// 页面加载完成后立即调用初始化函数
			// 这是整个应用的入口点
			init();

			// ==================== 函数定义部分 ====================
			
			/**
			 * 初始化函数 - 整个Three.js应用的启动函数
			 * 主要职责：
			 * 1. 创建和配置渲染器
			 * 2. 创建场景和摄像机
			 * 3. 设置用户交互控制
			 * 4. 加载资源并设置光照
			 * 5. 绑定事件监听器
			 */
			function init() {
				// ========== 1. 渲染器初始化 ==========
				
				// 创建WebGPU渲染器实例
				// { antialias: true } 参数启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer({ antialias: true });
				
				// 设置渲染器的像素比，匹配设备像素比
				// 这对于高DPI显示器（如Retina显示屏）很重要
				// window.devicePixelRatio返回物理像素与CSS像素的比值
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器的大小为整个浏览器窗口的大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 将调试器附加到渲染器上，方便开发时调试
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（通常是canvas元素）添加到页面body中
				// 这是3D内容实际渲染的地方
				document.body.appendChild(renderer.domElement);

				// ========== 2. 场景创建 ==========
				
				// 创建一个新的三维场景
				// 场景是所有3D对象的容器，包括网格、灯光、相机等
				scene = new THREE.Scene();

				// ========== 3. 摄像机设置 ==========
				
				// 创建透视摄像机
				// 参数说明：
				// - 40: 视野角度（FOV），单位是度，决定摄像机能看到的范围
				// - window.innerWidth / window.innerHeight: 宽高比，匹配窗口比例
				// - 1: 近裁剪平面，距离摄像机小于此值的物体不会被渲染
				// - 1000: 远裁剪平面，距离摄像机大于此值的物体不会被渲染
				camera = new THREE.PerspectiveCamera(
					40,
					window.innerWidth / window.innerHeight,
					1,
					1000
				);
				
				// 设置摄像机的初始位置
				// 参数：x, y, z坐标
				// 这里将摄像机放在z轴30单位处，面向场景中心
				camera.position.set(0, 0, 30);

				// ========== 4. 立方体摄像机设置（用于生成环境贴图） ==========
				
				// 创建WebGL立方体渲染目标
				// 参数256表示每个面的分辨率是256x256像素
				// 立方体渲染目标包含6个纹理，分别对应立方体的6个面
				const cubeRenderTarget = new THREE.WebGLCubeRenderTarget(256);
				
				// 创建立方体摄像机
				// 立方体摄像机从当前位置向6个方向（上下左右前后）拍摄场景
				// 参数说明：
				// - 1: 近裁剪平面
				// - 1000: 远裁剪平面
				// - cubeRenderTarget: 渲染目标，摄像机拍摄的结果会存储在这里
				cubeCamera = new THREE.CubeCamera(1, 1000, cubeRenderTarget);

				// ========== 5. 用户交互控制设置 ==========
				
				// 创建轨道控制器
				// 轨道控制器允许用户：
				// - 鼠标左键拖拽：旋转摄像机
				// - 鼠标右键拖拽：平移摄像机（这里禁用了）
				// - 鼠标滚轮：缩放摄像机
				const controls = new OrbitControls(camera, renderer.domElement);
				
				// 添加变化事件监听器
				// 当用户通过控制器改变摄像机位置时，触发render函数重新渲染场景
				controls.addEventListener('change', render);
				
				// 设置摄像机距离目标的最近距离限制
				// 防止摄像机离场景中心太近
				controls.minDistance = 10;
				
				// 设置摄像机距离目标的最远距离限制
				// 防止摄像机离场景中心太远
				controls.maxDistance = 50;
				
				// 禁用平移控制（鼠标右键拖拽）
				// 这里只允许旋转和缩放
				controls.enablePan = false;

				// ========== 6. 光照探针初始化 ==========
				
				// 创建光照探针对象
				// 光照探针用于捕获和存储场景的环境光照信息
				// 它使用球谐函数（Spherical Harmonics）来近似表示来自各个方向的光照
				lightProbe = new THREE.LightProbe();
				
				// 将光照探针添加到场景中
				// 虽然光照探针本身不可见，但需要添加到场景中才能生效
				scene.add(lightProbe);

				// ========== 7. 环境贴图加载和光照探针生成 ==========
				
				/**
				 * 辅助函数：生成立方体贴图的6个面URL
				 * 立方体贴图需要6个图像文件，分别对应立方体的6个面
				 * 命名约定通常为：px(正X), nx(负X), py(正Y), ny(负Y), pz(正Z), nz(负Z)
				 * 
				 * @param {string} prefix - 路径前缀，如 'textures/cube/pisa/'
				 * @param {string} postfix - 文件后缀，如 '.png'
				 * @returns {Array} 包含6个URL的数组，顺序符合Three.js的要求
				 */
				const genCubeUrls = function (prefix, postfix) {
					return [
						prefix + 'px' + postfix, // 右面 (正X方向)
						prefix + 'nx' + postfix, // 左面 (负X方向)
						prefix + 'py' + postfix, // 上面 (正Y方向)
						prefix + 'ny' + postfix, // 下面 (负Y方向)
						prefix + 'pz' + postfix, // 前面 (正Z方向)
						prefix + 'nz' + postfix  // 后面 (负Z方向)
					];
				};

				// 生成Pisa环境贴图的6个面URL
				// 'textures/cube/pisa/' 是贴图文件的目录路径
				// '.png' 是贴图文件的扩展名
				const urls = genCubeUrls('textures/cube/pisa/', '.png');

				// 使用Three.js的立方体贴图加载器加载环境贴图
				// 加载是异步的，所以提供一个回调函数处理加载完成后的逻辑
				new THREE.CubeTextureLoader().load(urls, async function (cubeTexture) {
					// 注意：这个回调函数被声明为async，因为内部使用了await
					
					// 7.1 将加载的立方体贴图设置为场景背景
					// 这样场景的背景就会显示Pisa环境的全景图
					scene.background = cubeTexture;

					// 7.2 初始化WebGPU渲染器（异步操作）
					// WebGPU需要异步初始化，await会等待初始化完成再继续执行
					await renderer.init();

					// 7.3 使用立方体摄像机更新环境贴图
					// cubeCamera.update()会从当前位置拍摄场景的6个方向
					// 将结果存储到cubeRenderTarget中
					// 参数说明：
					// - renderer: 用于渲染的渲染器
					// - scene: 要拍摄的场景
					cubeCamera.update(renderer, scene);

					// 7.4 从立方体渲染目标生成光照探针
					// LightProbeGenerator.fromCubeRenderTarget()是一个异步函数
					// 它分析cubeRenderTarget中的环境贴图，计算球谐函数系数
					// 这些系数代表了环境光照的分布
					const probe = await LightProbeGenerator.fromCubeRenderTarget(
						renderer,          // WebGPU渲染器
						cubeRenderTarget   // 包含环境贴图的渲染目标
					);

					// 7.5 将生成的光照探针数据复制到场景中的lightProbe对象
					// lightProbe.copy()方法会将球谐函数系数从probe复制到lightProbe
					lightProbe.copy(probe);

					// 7.6 创建并添加光照探针辅助对象
					// LightProbeHelper可以在场景中可视化显示光照探针
					// 参数说明：
					// - lightProbe: 要可视化的光照探针对象
					// - 5: 辅助对象的显示尺寸
					// 这个辅助对象通常显示为一个球体，用颜色表示不同方向的光照强度
					scene.add(new LightProbeHelper(lightProbe, 5));

					// 7.7 执行首次渲染
					// 此时所有资源已加载，场景已设置完毕，开始渲染
					render();
				});

				// ========== 8. 事件监听器设置 ==========
				
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，调用onWindowResize函数
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 窗口大小变化处理函数
			 * 当浏览器窗口大小改变时，需要调整渲染器和摄像机以保持正确显示
			 */
			function onWindowResize() {
				// 8.1 更新渲染器的大小为新的窗口尺寸
				// 这确保3D内容填满整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);

				// 8.2 更新摄像机的宽高比
				// 宽高比 = 窗口宽度 / 窗口高度
				// 如果不更新，图像会被拉伸或压缩
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 8.3 更新摄像机的投影矩阵
				// 当摄像机参数（如宽高比）改变后，必须调用此方法
				// 以重新计算内部投影矩阵
				camera.updateProjectionMatrix();

				// 8.4 重新渲染场景
				// 使用新的窗口尺寸和摄像机设置重新绘制场景
				render();
			}

			/**
			 * 渲染函数
			 * 这是Three.js应用的核心渲染循环
			 * 将3D场景通过摄像机视角渲染到2D画布上
			 */
			function render() {
				// 执行渲染操作
				// 参数说明：
				// - scene: 要渲染的场景（包含所有3D对象）
				// - camera: 用于渲染的摄像机（决定观察视角）
				// 
				// 内部过程：
				// 1. 清理颜色和深度缓冲区
				// 2. 遍历场景中的所有对象
				// 3. 应用材质和纹理
				// 4. 执行顶点和片段着色器
				// 5. 将结果绘制到画布上
				renderer.render(scene, camera);
			}

		</script>

	</body>
</html>