<!-- Three.js WebGPU 光照探针演示 - 功能描述与技术分析
🎯 项目核心功能
1. 核心演示功能
光照探针技术展示：演示Three.js中光照探针的工作原理和应用效果

环境光照系统：展示基于图像的环境照明(IBL)技术

实时参数调节：提供交互式控制面板，实时调整各种光照参数

WebGPU渲染：展示下一代图形APIWebGPU在Three.js中的应用

2. 用户交互功能
3D场景导航：支持鼠标拖拽旋转、滚轮缩放、右键平移

实时参数调整：

光照探针强度：控制间接环境光照的亮度

方向光强度：控制直接平行光源的亮度

环境贴图反射强度：控制物体表面的环境反射程度

调试辅助：内置调试检查器，可查看和修改场景对象属性

3. 视觉效果
动态环境映射：使用意大利比萨斜塔的360度全景环境贴图

PBR材质渲染：基于物理的材质系统，支持金属度和粗糙度

实时反射：球体表面实时反射周围环境

多重光照合成：结合直接光照、间接光照和环境光照

🔧 主要技术点分析
1. WebGPU渲染技术
javascript
// 核心技术特征
- 下一代图形API，替代WebGL
- 更好的多线程支持和GPU利用率
- 原生支持计算着色器
- 更低的CPU开销
- 自动内存管理
2. 光照探针系统
技术组件	功能描述	关键技术
LightProbe	存储场景光照信息	球谐函数(SH)编码
生成器	从环境贴图生成探针	LightProbeGenerator
辅助器	可视化探针数据	LightProbeHelperGPU
应用	影响场景所有物体	实时全局光照
3. PBR材质系统
金属度-粗糙度工作流：行业标准PBR实现方式

线性颜色空间：保持物理正确的光照计算

环境贴图反射：基于图像的反射和折射

能量守恒：确保光照计算的物理准确性

4. 环境贴图技术
javascript
// 立方体贴图技术栈
CubeTextureLoader → 加载6张图片 → 创建立方体贴图
    ↓
场景背景 + 物体反射贴图
    ↓
LightProbeGenerator → 转换为光照探针
5. 模块化架构
javascript
// ES6模块系统
import * as THREE from 'three/webgpu';           // 核心模块
import { OrbitControls } from 'three/addons/...'; // 控制器模块
import { LightProbeGenerator } from 'three/addons/...'; // 光照模块
import { Inspector } from 'three/addons/...';    // 调试模块
🏗️ 系统架构设计
1. 渲染管线流程
text
1. 资源加载 → 环境贴图、几何体数据
2. 场景构建 → 场景图、相机、光源、物体
3. 光照计算 → 直接光 + 间接光 + 环境光
4. 材质应用 → PBR材质参数计算
5. WebGPU渲染 → 提交GPU命令缓冲区
6. 屏幕输出 → 绘制到HTML Canvas
2. 光照计算层次
text
第一层：方向光（直接照明）
    ↓ 模拟太阳光，产生明确阴影
    
第二层：光照探针（间接照明）
    ↓ 捕捉环境光，提供柔和全局光照
    
第三层：环境贴图（反射/背景）
    ↓ 基于图像的照明和反射效果
3. 性能优化特性
按需渲染：使用requestAnimationFrame进行动画循环

资源复用：环境贴图同时用于背景和反射

GPU加速：所有计算在WebGPU管线中执行

内存管理：自动垃圾回收和资源释放

📊 技术参数规格
1. 渲染配置
javascript
{
  渲染器: "WebGPURenderer",
  抗锯齿: "启用",
  色调映射: "NoToneMapping (线性空间)",
  像素比: "设备自适应",
  更新频率: "60FPS (vsync同步)"
}
2. 场景配置
javascript
{
  几何体: "SphereGeometry (半径5, 分段64x32)",
  材质: "MeshStandardMaterial",
  相机: "PerspectiveCamera (FOV:40°, 近裁剪:1, 远裁剪:1000)",
  控制器: "OrbitControls"
}
3. 光照参数范围
javascript
{
  光照探针强度: "0.0 - 1.0 (步进0.02)",
  方向光强度: "0.0 - 1.0 (步进0.02)",
  环境贴图强度: "0.0 - 1.0 (步进0.02)"
}
🚀 扩展性与应用场景
1. 可扩展功能
多光源支持：可添加点光源、聚光灯等

动态环境：支持动态更新环境贴图

后处理效果：添加色调映射、Bloom等后期特效

VR/AR支持：适配WebXR API

2. 应用场景
产品可视化：展示产品的材质和光照效果

建筑渲染：室内外场景的光照模拟

游戏开发：实时全局光照系统

教育培训：计算机图形学教学示例

3. 学习价值
WebGPU入门：学习下一代Web图形API

PBR材质理解：掌握基于物理的渲染原理

光照系统设计：学习现代实时渲染的光照技术

Three.js高级特性：深入了解Three.js的扩展功能

🔍 关键技术实现细节
1. 光照探针数据生成
javascript
// 从立方体贴图生成球谐函数系数
lightProbe.copy(LightProbeGenerator.fromCubeTexture(cubeTexture));
// 这个过程包含：
// 1. 采样立方体贴图的各个方向
// 2. 计算每个方向的亮度
// 3. 拟合到球谐函数基函数
// 4. 存储为9个RGB向量（三阶球谐）
2. 环境贴图的双重用途
javascript
// 同一贴图的两种应用
scene.background = cubeTexture;     // 作为场景背景
material.envMap = cubeTexture;      // 作为反射贴图
// 优势：节省内存，保持视觉一致性
3. 线性颜色空间处理
javascript
// 禁用色调映射，保持线性计算
renderer.toneMapping = THREE.NoToneMapping;
// 重要性：
// - 物理正确的光照叠加
// - 精确的能量守恒
// - 准确的材质表现
🎨 视觉效果特点
1. 真实感渲染
物理正确性：基于物理的光照和材质模型

能量守恒：反射光不会比入射光更亮

微表面理论：通过粗糙度控制表面微观结构

2. 交互性
实时反馈：所有参数调节立即生效

直观控制：GUI滑块提供精确控制

多视角观察：自由旋转相机观察不同角度

3. 视觉层次
前景物体：使用PBR材质的球体

背景环境：360度全景环境贴图

辅助元素：光照探针可视化辅助器

UI界面：非侵入式的控制面板 -->


<!DOCTYPE html>
<!-- 文档类型声明，使用HTML5标准 -->
<html lang="zh-CN">
	<!-- 设置文档语言为简体中文 -->
	<head>
		<!-- 头部开始，包含元数据和页面标题 -->
		
		<!-- 页面标题，显示在浏览器标签页上 -->
		<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样式表链接 -->
		<!-- type="text/css": 指定MIME类型为CSS -->
		<!-- rel="stylesheet": 定义当前文档与链接资源的关系为样式表 -->
		<!-- href="example.css": 样式表文件路径 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<!-- 头部结束 -->

	<body>
		<!-- 页面主体内容开始 -->

		<!-- 信息展示区域 -->
		<!-- id="info": 为div元素指定唯一标识符，便于CSS和JavaScript操作 -->
		<div id="info">
			<!-- Three.js官方网站链接 -->
			<!-- href: 目标URL地址 -->
			<!-- target="_blank": 在新标签页中打开链接 -->
			<!-- rel="noopener": 安全属性，防止新页面通过window.opener访问原页面 -->
			<!-- 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>
				<!-- 描述文本：说明本示例的主要内容 -->
				本示例展示了Three.js中的光照探针技术和环境光照应用。
				光照探针用于捕捉场景中的光照信息，实现更真实的全局光照效果。
				您可以通过右侧控制面板调整各种光源的强度参数。
			</small>
			
			
		</div>

		<!-- 模块导入映射配置 -->
		<!-- 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模块，支持模块化导入导出 -->
		<script type="module">
			// ============================================
			// 模块导入部分
			// ============================================
			
			// 导入Three.js WebGPU核心模块
			// * as THREE: 将整个模块导入到THREE命名空间对象中
			import * as THREE from 'three/webgpu';

			// 导入调试检查器工具
			// Inspector: 用于创建运行时调试界面，可以查看和修改场景对象属性
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器
			// OrbitControls: 提供鼠标/触摸控制相机旋转、缩放和平移的功能
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入光照探针生成器
			// LightProbeGenerator: 用于从环境贴图或其他光源生成光照探针数据
			import { LightProbeGenerator } from 'three/addons/lights/LightProbeGenerator.js';

			// 导入光照探针辅助器（WebGPU专用版本）
			// LightProbeHelperGPU: 可视化光照探针位置和方向的辅助对象
			import { LightProbeHelper } from 'three/addons/helpers/LightProbeHelperGPU.js';

			// ============================================
			// 全局变量声明
			// ============================================
			
			// 场景对象变量
			let mesh;        // 三维网格对象，包含几何体和材质
			let renderer;    // WebGPU渲染器实例，负责将3D场景绘制到canvas
			let scene;       // 场景图根节点，包含所有要渲染的对象
			let camera;      // 相机对象，定义观察场景的视角和投影方式

			// GUI相关变量
			let gui;         // 图形用户界面实例，用于参数调节

			// 光照相关变量
			let lightProbe;         // 光照探针对象，存储场景中的间接光照信息
			let directionalLight;   // 方向光对象，模拟太阳等平行光源

			// API配置对象
			// 存储可调节的光照参数，使用线性颜色空间值（0-1范围）
			const API = {
				lightProbeIntensity: 1.0,        // 光照探针强度，控制间接光照的亮度
				directionalLightIntensity: 0.6,  // 方向光强度，控制直接光照的亮度
				envMapIntensity: 1               // 环境贴图强度，控制环境反射的明显程度
			};

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

			/**
			 * 初始化函数
			 * 
			 * 这是整个应用的入口函数，负责：
			 * 1. 创建和配置WebGPU渲染器
			 * 2. 构建3D场景（场景图、相机、光源、物体）
			 * 3. 加载资源（环境贴图）
			 * 4. 设置用户交互（控制器、GUI）
			 * 5. 绑定事件监听器
			 * 
			 * 函数执行流程：
			 * 1. 渲染器设置 → 2. 场景创建 → 3. 相机设置 → 4. 控制器设置
			 * 5. 光照设置 → 6. 环境贴图加载 → 7. 物体创建 → 8. GUI设置
			 * 9. 事件监听绑定
			 */
			function init() {
				// --------------------------------------------------
				// 1. WebGPU渲染器创建与配置
				// --------------------------------------------------
				
				// 创建WebGPURenderer实例
				// { antialias: true }: 启用多重采样抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer({ antialias: true });
				
				// 设置设备像素比
				// window.devicePixelRatio: 获取设备的物理像素与CSS像素的比率
				// 高DPI屏幕（如Retina显示屏）该值可能为2或更高
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为窗口大小
				// 确保3D场景填满整个浏览器窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// animate函数将在每一帧被调用，实现连续渲染
				renderer.setAnimationLoop(animate);
				
				// 附加调试检查器到渲染器
				// 可以通过快捷键（通常是Ctrl+Shift+I）打开调试面板
				renderer.inspector = new Inspector();
				
				// 将渲染器的canvas元素添加到DOM中
				// renderer.domElement: 渲染器创建的<canvas>元素
				document.body.appendChild(renderer.domElement);

				// 配置色调映射
				// THREE.NoToneMapping: 禁用色调映射，保持线性颜色空间
				// 线性颜色空间更符合物理光照计算，但可能需要后期处理才能正确显示
				renderer.toneMapping = THREE.NoToneMapping;

				// --------------------------------------------------
				// 2. 场景图创建
				// --------------------------------------------------
				
				// 创建场景对象
				// 场景是3D对象的容器，所有要渲染的物体、光源、相机都添加到场景中
				scene = new THREE.Scene();

				// --------------------------------------------------
				// 3. 相机创建与配置
				// --------------------------------------------------
				
				// 创建透视相机（Perspective Camera）
				// 参数说明：
				// - 40: 垂直视野角度（Field of View），单位度，类似人眼的视野范围
				// - 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. 用户交互控制器设置
				// --------------------------------------------------
				
				// 创建轨道控制器（Orbit Controls）
				// 将相机和渲染器的canvas元素关联，实现鼠标控制
				const controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置相机最小缩放距离
				// 防止相机过于靠近物体导致透视失真
				controls.minDistance = 10;
				
				// 设置相机最大缩放距离
				// 防止相机过于远离物体
				controls.maxDistance = 50;
				
				// 禁用平移控制
				// 只允许旋转和缩放，不能拖动场景
				controls.enablePan = false;

				// --------------------------------------------------
				// 5. 光照系统设置
				// --------------------------------------------------
				
				// 创建光照探针（Light Probe）
				// 光照探针用于捕捉场景中的间接光照信息
				// 与直接光源不同，它存储的是来自各个方向的环境光照
				lightProbe = new THREE.LightProbe();
				
				// 将光照探针添加到场景中
				// 注意：光照探针本身不渲染，只提供光照数据
				scene.add(lightProbe);

				// 创建方向光（Directional Light）
				// 参数说明：
				// - 0xffffff: 光的颜色，十六进制白色
				// - API.directionalLightIntensity: 光强，从API对象获取初始值
				directionalLight = new THREE.DirectionalLight(0xffffff, API.directionalLightIntensity);
				
				// 设置方向光的位置
				// 方向光的位置影响阴影计算，但不影响光照方向
				// 真正的光照方向是从位置指向原点(0,0,0)
				directionalLight.position.set(10, 10, 10);
				
				// 将方向光添加到场景中
				scene.add(directionalLight);

				// --------------------------------------------------
				// 6. 环境贴图加载与处理
				// --------------------------------------------------
				
				/**
				 * 生成立方体贴图URL的辅助函数
				 * 
				 * 立方体贴图由6个正方形纹理组成，对应立方体的6个面：
				 * 正X（右）、负X（左）、正Y（上）、负Y（下）、正Z（前）、负Z（后）
				 * 
				 * @param {string} prefix - 路径前缀，如'textures/cube/pisa/'
				 * @param {string} postfix - 文件后缀，如'.png'
				 * @returns {string[]} 包含6个URL的数组，按特定顺序排列
				 */
				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环境贴图的URL数组
				// 使用意大利比萨斜塔的360度全景图作为环境贴图
				const urls = genCubeUrls('textures/cube/pisa/', '.png');

				// 创建立方体贴图加载器并加载贴图
				// CubeTextureLoader: Three.js提供的立方体贴图专用加载器
				new THREE.CubeTextureLoader().load(urls, function (cubeTexture) {
					// --------------------------------------------------
					// 回调函数：贴图加载完成后的处理
					// --------------------------------------------------
					
					// 设置场景背景为加载的立方体贴图
					// 这将在场景中所有物体后面显示环境全景
					scene.background = cubeTexture;

					// 从立方体贴图生成光照探针数据
					// LightProbeGenerator.fromCubeTexture(): 
					//   分析立方体贴图的颜色和亮度，生成对应的球谐函数系数
					// lightProbe.copy(): 将生成的探针数据复制到已创建的光照探针中
					lightProbe.copy(LightProbeGenerator.fromCubeTexture(cubeTexture));
					
					// 设置光照探针的强度
					lightProbe.intensity = API.lightProbeIntensity;
					
					// 设置光照探针的位置
					// 注意：在Three.js中，光照探针的位置通常不影响光照计算
					// 这里设置位置主要是为了让LightProbeHelper辅助器能够正确显示
					lightProbe.position.set(-10, 0, 0);

					// --------------------------------------------------
					// 7. 创建3D物体（几何体+材质）
					// --------------------------------------------------
					
					// 创建球体几何体
					// 参数说明：
					// - 5: 球体半径
					// - 64: 宽度分段数（经线分段），影响曲面平滑度
					// - 32: 高度分段数（纬线分段），影响曲面平滑度
					const geometry = new THREE.SphereGeometry(5, 64, 32);
					
					// 备用几何体：环形结（Torus Knot）
					// 已注释，如果需要更复杂的几何体可以取消注释
					// 参数说明：环半径4，管半径1.5，径向分段256，管分段32，p值2，q值3
					// const geometry = new THREE.TorusKnotGeometry(4, 1.5, 256, 32, 2, 3);

					// 创建基于物理的渲染材质（PBR材质）
					// MeshStandardMaterial支持金属度-粗糙度工作流
					const material = new THREE.MeshStandardMaterial({
						color: 0xffffff,           // 基础颜色：白色
						metalness: 0,               // 金属度：0表示完全非金属
						roughness: 0,               // 粗糙度：0表示完全光滑（镜面反射）
						envMap: cubeTexture,        // 环境贴图：用于反射
						envMapIntensity: API.envMapIntensity, // 环境贴图强度
					});

					// 创建网格对象
					// Mesh: Three.js中最基本的3D对象，组合几何体和材质
					mesh = new THREE.Mesh(geometry, material);
					
					// 将网格添加到场景中
					scene.add(mesh);

					// --------------------------------------------------
					// 8. 创建辅助对象（用于可视化调试）
					// --------------------------------------------------
					
					// 创建光照探针辅助器
					// 参数说明：
					// - lightProbe: 要可视化的光照探针对象
					// - 1: 辅助器的大小缩放因子
					const helper = new LightProbeHelper(lightProbe, 1);
					
					// 将辅助器添加到场景中
					// 辅助器会显示光照探针的位置和球谐函数的可视化表示
					scene.add(helper);
				});

				// --------------------------------------------------
				// 9. 图形用户界面（GUI）设置
				// --------------------------------------------------
				
				// 在调试检查器中创建参数控制面板
				// "Intensity": 面板的标题
				gui = renderer.inspector.createParameters('光照强度控制');

				// 添加光照探针强度控制滑块
				gui.add(API, 'lightProbeIntensity', 0, 1, 0.02)
					.name('光照探针强度')        // 显示在GUI中的标签名
					.onChange(function () {      // 值改变时的回调函数
						// 更新光照探针的实际强度
						lightProbe.intensity = API.lightProbeIntensity;
					});

				// 添加方向光强度控制滑块
				gui.add(API, 'directionalLightIntensity', 0, 1, 0.02)
					.name('方向光强度')
					.onChange(function () {
						// 更新方向光的实际强度
						directionalLight.intensity = API.directionalLightIntensity;
					});

				// 添加环境贴图强度控制滑块
				gui.add(API, 'envMapIntensity', 0, 1, 0.02)
					.name('环境贴图反射强度')
					.onChange(function () {
						// 更新网格材质的环境贴图强度
						// 注意：这里假设mesh已经创建，在环境贴图加载回调中
						if (mesh && mesh.material) {
							mesh.material.envMapIntensity = API.envMapIntensity;
						}
					});

				// --------------------------------------------------
				// 10. 事件监听器绑定
				// --------------------------------------------------
				
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，重新调整渲染尺寸
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 窗口大小变化处理函数
			 * 
			 * 当浏览器窗口大小改变时，需要：
			 * 1. 更新渲染器的尺寸以匹配新窗口大小
			 * 2. 更新相机的宽高比以避免图像拉伸
			 * 3. 更新相机的投影矩阵以应用新的宽高比
			 * 
			 * 这个函数作为事件监听器的回调函数被调用
			 */
			function onWindowResize() {
				// 更新渲染器尺寸
				// 确保canvas元素填满整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);

				// 更新相机宽高比
				// 相机的aspect属性需要与窗口宽高比保持一致
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵
				// 修改相机属性后，必须调用此方法来重新计算投影矩阵
				camera.updateProjectionMatrix();
			}

			/**
			 * 动画循环函数
			 * 
			 * 这是Three.js应用的核心循环函数：
			 * 1. 由renderer.setAnimationLoop()设置
			 * 2. 在每一帧自动调用（通常60fps）
			 * 3. 负责渲染当前帧的场景
			 * 
			 * 注意：在这个简单示例中，我们没有动画逻辑
			 * 更复杂的应用会在这里更新物体位置、旋转等
			 */
			function animate() {
				// 渲染当前帧
				// renderer.render(): 使用指定的相机将场景绘制到canvas
				// 参数：
				// - scene: 要渲染的场景图
				// - camera: 用于观察场景的相机
				renderer.render(scene, camera);
				
				// 注意：这里没有使用时间delta参数
				// 如果需要有时间依赖的动画，函数签名可以改为：
				// function animate(time) { ... }
				// 其中time是从页面加载开始经过的毫秒数
			}

			// ============================================
			// 可选的扩展功能建议（未实现）
			// ============================================
			
			// 1. 性能监控：添加stats.js显示FPS和内存使用
			// 2. 加载指示器：在环境贴图加载期间显示进度条
			// 3. 错误处理：添加贴图加载失败的回调处理
			// 4. 响应式设计：添加移动设备触摸事件支持
			// 5. 键盘控制：添加键盘快捷键切换光源或材质
			// 6. 多视图：添加多个相机视角（顶视图、侧视图等）
			// 7. 截图功能：添加保存当前视图为图片的功能
			// 8. 全屏切换：添加全屏模式切换按钮

		</script>
		<!-- 主JavaScript模块结束 -->

	</body>
	<!-- 页面主体内容结束 -->
</html>
<!-- HTML文档结束 -->