<!-- 代码功能和技术点详解
🎯 核心功能概述
这是一个基于 Three.js WebGPU 的渐进式光照贴图累积技术演示项目。它通过多帧累积的方式，将离线渲染质量的光照效果与实时渲染的交互性相结合，实现了高质量、可交互的光照计算系统。

主要功能亮点：
实时渐进式光照计算 - 光照效果随着时间逐步完善，越累积越精细

交互式光源控制 - 用户可以实时拖拽调整光源位置和模型位置

动态参数调节 - 通过GUI界面实时调整各种光照参数

物理正确采样 - 结合两种科学的采样策略模拟真实光照

WebGPU加速 - 利用现代GPU架构提供高性能计算

🛠️ 技术架构
1. 核心模块结构
text
Three.js WebGPU应用
├── 渲染引擎 (WebGPURenderer)
├── 场景管理 (Scene, Camera, Renderer)
├── 渐进式光照系统 (ProgressiveLightMapGPU)
├── 交互控制系统 (OrbitControls, TransformControls)
├── 模型加载系统 (GLTFLoader)
└── 参数调试系统 (Inspector GUI)
2. 渐进式光照贴图的工作流程
javascript
// 简化的工作流程
初始化阶段
    ↓
每帧循环开始
    ↓
更新光源位置（随机采样策略）
    ↓
渲染场景到光照贴图缓冲区
    ↓
累积到历史光照贴图（加权混合）
    ↓
应用后处理（边缘模糊等）
    ↓
将光照贴图应用到模型表面
    ↓
渲染最终场景到屏幕
    ↓
下一帧重复...
🔬 关键技术点详解
1. 蒙特卡洛光照积分
核心原理：使用随机采样近似计算复杂的光照积分

javascript
// 传统渲染的光照计算：
final_color = ∫(光照函数) dΩ  // 对所有方向积分 - 计算量大

// 蒙特卡洛方法：
final_color ≈ (1/N) * Σ(光照函数(随机方向))  // 随机采样近似 - 适合实时渲染
在代码中的实现：

每帧生成多个随机光源方向

累积多帧的采样结果

随着时间推移，近似结果趋近于精确解

2. 双策略重要性采样
代码实现了两种互补的采样策略，通过环境权重参数动态调配：

策略A：直接光采样（目标区域采样）
javascript
// 在光源原点周围的球形区域内随机采样
light_position = light_origin + random_vector * light_radius
数学基础：均匀分布随机采样

物理意义：模拟来自特定位置的点光源或面光源

适用场景：窗户、灯具等局部光源

策略B：环境光采样（半球均匀采样）
javascript
// 球面坐标转换
λ = acos(2*rand()-1) - π/2  // 余弦分布纬度
φ = 2π * rand()              // 均匀分布经度

// 转换为笛卡尔坐标（上半球）
x = cos(λ)*cos(φ)*radius
y = |cos(λ)*sin(φ)|*radius  // 绝对值确保在上半球
z = sin(λ)*radius
数学基础：球面均匀分布 + 余弦权重

物理意义：模拟天空光、环境反射等全局照明

适用场景：室外天光、室内间接光照

3. 光照贴图混合技术
累积公式：

text
new_lightmap = α * current_frame + (1-α) * accumulated_history
其中 α = 1 / blend_window

技术优势：

渐进收敛：随着帧数增加，噪声逐渐减少

实时反馈：用户可以立即看到光照变化

可中断性：随时可以停止或继续累积

4. WebGPU渲染管线优化
javascript
// WebGPU相比WebGL的主要优势：
1. 计算着色器支持 - 适合光照累积计算
2. 多线程命令缓冲 - 更好的CPU利用率  
3. 现代GPU特性 - 光线追踪、网格着色器等
4. 显式内存管理 - 减少驱动开销
5. 阴影映射技术
javascript
// 方向光阴影配置
dirLight.shadow.mapSize.width = 1024;  // 阴影贴图分辨率
dirLight.shadow.bias = -0.001;         // 阴影偏移，解决自阴影问题

// 阴影相机视锥体优化
dirLight.shadow.camera.left/right/top/bottom = ±150
// 只渲染需要阴影的区域，提高性能
📊 性能优化策略
1. 多光源并行采样
javascript
// 同时使用4个方向光进行采样
const lightCount = 4;
// 总光照强度保持恒定：每个光源强度 = Math.PI / lightCount
原理：多光源并行加速收敛速度

数学保证：总能量守恒（总强度 = π）

2. 分层细节渲染
javascript
// 对不需要的对象禁用渲染
child.layers.disableAll();
仅渲染需要光照贴图的对象

忽略辅助对象（骨骼、空节点等）

3. 自适应采样
根据环境权重动态调整采样策略比例

实时GUI调节参数，无需重新编译

🎨 视觉特效实现
1. 边缘模糊处理
javascript
progressiveSurfacemap.update(camera, blendWindow, blurEdges)
目的：消除光照贴图的硬边瑕疵

方法：对光照贴图纹理进行高斯模糊

控制：通过模糊边缘复选框启用/禁用

2. 雾效增强深度感
javascript
scene.fog = new THREE.Fog(0x949494, 1000, 3000);
近雾开始：1000单位

远雾结束：3000单位

效果：增强场景的空间深度感

🎮 交互系统设计
1. 双变换控制器架构
javascript
control.attach(lightOrigin);   // 控制光源原点
control2.attach(object);       // 控制3D模型

// 互斥控制逻辑
controls.enabled = !event.value; // 拖拽时禁用轨道控制
2. 光源目标跟随系统
javascript
// 所有方向光指向同一个目标点
for (let l = 0; l < dirLights.length; l++) {
    dirLights[l].target = lightTarget;
}

// 目标点跟随模型移动
object.add(lightTarget);
🔧 调试与开发支持
1. 实时参数调节GUI
javascript
const params = {
    '启用累积': true,          // 主开关
    '模糊边缘': true,          // 后处理开关
    '混合窗口': 200,           // 收敛速度控制
    '光源半径': 50,            // 采样范围控制
    '环境权重': 0.5,           // 采样策略配比
    '调试模式': false          // 可视化调试
};
2. Three.js Inspector集成
场景树查看

对象属性编辑

性能分析工具

着色器调试

🚀 应用场景与扩展
适用领域：
建筑可视化 - 实时评估不同时间、不同天气的光照效果

产品设计 - 高质量的产品渲染和材质展示

游戏开发 - 预计算静态场景光照，保持动态物体交互性

虚拟现实 - 提供物理正确的光照环境

影视预演 - 快速预览光照效果

可能的扩展方向：
动态场景支持

javascript
// 检测物体移动，重新计算受影响区域的光照
if (object.position.changed) {
    progressiveSurfacemap.invalidateRegion(object.boundingBox);
}
多级细节光照

javascript
// 根据距离使用不同分辨率的光照贴图
lightmap_resolution = getLODBasedResolution(distance_to_camera);
GPU驱动收敛控制

javascript
// 自动检测收敛程度，停止不必要的计算
if (calculateConvergence(lightmap) > threshold) {
    params['启用累积'] = false;
}
光照烘焙导出

javascript
// 将累积好的光照贴图导出为图片文件
progressiveSurfacemap.exportLightmap('baked_lightmap.png');
📈 性能指标
内存使用：
每个1024x1024光照贴图：~4MB（RGBA Float32）

场景几何数据：依赖模型复杂度

阴影贴图：4个1024x1024 = ~16MB

计算复杂度：
每帧光源采样：O(lightCount)

光照累积：O(lightMapRes²)

混合操作：O(n) per pixel

收敛速度：
初始几帧：显著改善

100-200帧：基本收敛

1000+帧：高度精细

🎯 技术优势总结
质量与性能的平衡 - 接近离线渲染的质量，保持实时性能

物理正确性 - 基于物理的渲染和采样方法

交互性 - 实时参数调节和场景操作

渐进性 - 逐步完善，随时可中断

现代架构 - 基于WebGPU，面向未来硬件 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面元信息设置
			- charset: 指定文档字符编码为UTF-8，支持中文
			- viewport: 移动端适配设置，禁止用户缩放，保持1:1缩放比例
			- title: 页面标题，显示在浏览器标签页上
		-->
		<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">
		
		<!-- 
			引入外部CSS样式表
			- type="text/css": 指定样式表类型为CSS
			- href="example.css": 样式表文件路径
			这个文件通常包含页面布局、颜色、字体等样式定义
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>
		<!-- 
			3D场景容器
			- id="container": 用于JavaScript获取DOM元素的标识符
			- Three.js渲染器会将Canvas元素自动添加到这里
			这个div作为Three.js 3D场景的显示区域
		-->
		<div id="container"></div>

		<!-- 
			页面信息展示区域
			- id="info": 信息区域的唯一标识
			这个区域显示Three.js的logo、标题、作者信息和灵感来源
		-->
		<div id="info">
			<!-- 
				Three.js官方logo链接
				- href: 点击跳转到Three.js官网
				- target="_blank": 在新标签页打开链接
				- rel="noopener": 安全设置，防止新页面访问原页面的window对象
				- class="logo-link": CSS类名，通常用于设置logo背景图片
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题容器 -->
			<div class="title-wrapper">
				<!-- 主标题链接 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题 -->
				<span>渐进式光照贴图技术演示</span>
			</div>

			<!-- 
				作者信息和灵感来源
				- <small>: 表示小号字体，通常用于次要信息
			-->
			<small>
				<!-- 作者信息 -->
				作者：<a href="https://github.com/zalo" target="_blank" rel="noopener">zalo</a>
				<!-- 分隔符 -->
				&nbsp;|&nbsp;
				<!-- 灵感来源 -->
				灵感来源于：<a href="http://madebyevan.com/shaders/lightmap/" target="_blank" rel="noopener">evanw的光照贴图生成技术</a>
			</small>
		</div>

		<!-- 
			导入映射配置 (Import Maps)
			- type="importmap": 现代浏览器支持的模块导入映射功能
			这个配置允许我们在import语句中使用简短的模块路径别名
			而不需要完整的URL路径
		-->
		<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对象的属性
			import * as THREE from 'three/webgpu';

			// 导入调试检查器，用于场景调试和参数调整
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入GLTF模型加载器，用于加载.glb或.gltf格式的3D模型
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			
			// 导入轨道控制器，实现用鼠标控制相机旋转、平移和缩放
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入变换控制器，提供可视化工具来移动、旋转、缩放3D对象
			import { TransformControls } from 'three/addons/controls/TransformControls.js';
			
			// 导入渐进式光照贴图处理器（GPU版本）
			// 这是本示例的核心组件，负责累积计算光照信息
			import { ProgressiveLightMap } from 'three/addons/misc/ProgressiveLightMapGPU.js';

			// ==================== 常量定义 ====================
			
			// 阴影贴图分辨率：决定阴影质量的参数，值越高阴影越精细
			const shadowMapRes = 1024;
			
			// 光照贴图分辨率：决定光照贴图质量的参数
			// 光照贴图是预计算的光照信息纹理，贴到模型表面
			const lightMapRes = 1024;
			
			// 方向光数量：用于光照采样的光源数量
			// 多个光源并行采样可以加速光照收敛过程
			const lightCount = 4;

			// ==================== 全局变量声明 ====================
			
			// Three.js核心对象
			let camera;          // 相机：决定观察3D场景的视角
			let scene;           // 场景：包含所有3D对象的容器
			let renderer;        // 渲染器：负责将3D场景绘制到2D Canvas
			
			// 控制器对象
			let controls;        // 轨道控制器：控制相机运动
			let control;         // 变换控制器1：控制光源原点
			let control2;        // 变换控制器2：控制3D模型
			
			// 3D对象
			let object = new THREE.Mesh();  // 主3D模型对象，初始化为一个空网格
			let lightOrigin = null;          // 光源原点：所有方向光的参考位置点
			
			// 光照贴图处理器
			let progressiveSurfacemap;  // 渐进式表面光照贴图处理器实例
			
			// 数组容器
			const dirLights = [];        // 存储所有方向光源对象的数组
			const lightmapObjects = [];  // 存储所有需要生成光照贴图的对象的数组
			
			// ==================== 配置参数对象 ====================
			
			// 这个对象的所有属性都可以通过GUI界面实时调整
			const params = {
				'启用累积': true,          // 总开关：启用或禁用光照贴图累积计算
				'模糊边缘': true,          // 是否对光照贴图边缘进行模糊处理，消除硬边
				'混合窗口': 200,           // 控制新旧光照信息混合的速度，值越小更新越快
				'光源半径': 50,            // 光源采样半径，控制光源在原点周围的随机范围
				'环境权重': 0.5,           // 环境光与直接光的权重平衡（0-1之间）
				'调试模式': false          // 是否显示光照贴图调试视图
			};

			// ==================== 初始化函数调用 ====================
			
			// 程序入口点：先初始化Three.js环境，然后创建GUI界面
			init();          // 初始化3D场景、相机、渲染器等核心组件
			createGUI();     // 创建用户控制界面

			/**
			 * 初始化函数 - Three.js应用程序的启动配置
			 * 
			 * 这个函数执行以下关键任务：
			 * 1. 创建WebGPU渲染器并配置其参数
			 * 2. 设置相机和场景
			 * 3. 初始化渐进式光照贴图系统
			 * 4. 创建光源和控制器
			 * 5. 加载3D模型
			 * 6. 设置事件监听器
			 * 
			 * 函数没有参数，也没有返回值，但会设置所有全局变量
			 */
			function init() {
				// ========== 第1部分：WebGPU渲染器配置 ==========
				
				// 创建WebGPU渲染器实例
				// 参数说明：
				// { antialias: true } - 启用抗锯齿，使3D边缘更平滑
				renderer = new THREE.WebGPURenderer({ antialias: true });
				
				// 设置设备像素比：根据屏幕DPI自动调整，防止在高DPI屏幕上模糊
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为整个浏览器窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// 与传统的requestAnimationFrame不同，这是WebGPU/WebRender的专用方法
				// animate函数将在每一帧被自动调用
				renderer.setAnimationLoop(animate);
				
				// 启用阴影贴图系统
				// 阴影贴图是一种常见的实时阴影技术，将深度信息渲染到纹理中
				renderer.shadowMap.enabled = true;
				
				// 创建并附加调试检查器
				// Inspector提供场景树查看、对象属性编辑等功能
				renderer.inspector = new Inspector();
				
				// 将渲染器的Canvas元素添加到DOM中
				// renderer.domElement是渲染器创建的<canvas>元素
				document.body.appendChild(renderer.domElement);

				// ========== 第2部分：相机配置 ==========
				
				// 创建透视投影相机
				// 参数说明（构造函数参数按顺序）：
				// 1. 视野角度(FOV) - 70度，接近人眼自然视野
				// 2. 宽高比 - 根据窗口尺寸动态计算
				// 3. 近裁剪面 - 1个单位，比这近的物体不显示
				// 4. 远裁剪面 - 1000个单位，比这远的物体不显示
				camera = new THREE.PerspectiveCamera(
					70,
					window.innerWidth / window.innerHeight,
					1,
					1000
				);
				
				// 设置相机初始位置
				// 三个参数分别对应：X轴（左右）、Y轴（上下）、Z轴（前后）
				camera.position.set(0, 100, 200);
				
				// 给相机命名，方便在调试器中识别
				camera.name = '主相机';

				// ========== 第3部分：场景配置 ==========
				
				// 创建3D场景对象
				// Scene是所有3D对象的容器，包含几何体、光源、相机等
				scene = new THREE.Scene();
				
				// 设置场景背景颜色
				// 0x949494是十六进制颜色值，表示浅灰色
				scene.background = new THREE.Color(0x949494);
				
				// 添加雾效（Fog）
				// 参数说明：
				// 1. 雾的颜色（与背景色相同）
				// 2. 雾效开始距离 - 1000单位处开始有雾
				// 3. 雾效结束距离 - 3000单位处完全被雾遮盖
				// 雾效可以增加场景的深度感和距离感
				scene.fog = new THREE.Fog(0x949494, 1000, 3000);

				// ========== 第4部分：渐进式光照贴图初始化 ==========
				
				// 创建渐进式光照贴图处理器
				// 参数说明：
				// 1. renderer - 需要渲染器实例来创建WebGPU纹理和渲染目标
				// 2. lightMapRes - 光照贴图的分辨率，影响光照细节和质量
				progressiveSurfacemap = new ProgressiveLightMap(renderer, lightMapRes);

				// ========== 第5部分：光源系统设置 ==========
				
				// 创建光源原点组
				// Group对象可以包含多个子对象，方便整体变换
				lightOrigin = new THREE.Group();
				
				// 设置光源原点的初始位置
				// 这个位置将作为方向光采样的参考中心点
				lightOrigin.position.set(60, 150, 100);
				
				// 将光源原点添加到场景中
				scene.add(lightOrigin);

				// ========== 第6部分：控制器设置 ==========
				
				// 创建第一个变换控制器（用于控制光源原点）
				// 参数说明：
				// 1. camera - 控制器需要知道相机视角来计算交互
				// 2. renderer.domElement - 控制器需要监听Canvas上的鼠标事件
				control = new TransformControls(camera, renderer.domElement);
				
				// 监听控制器的拖拽状态变化事件
				// 当用户开始拖拽控制器时，临时禁用轨道控制器，避免冲突
				control.addEventListener('dragging-changed', (event) => {
					// event.value: true表示开始拖拽，false表示结束拖拽
					// 当拖拽控制器时，禁用轨道控制器；拖拽结束时，重新启用
					controls.enabled = !event.value;
				});
				
				// 将控制器附加到光源原点对象
				// 这样控制器就能控制lightOrigin的位置、旋转和缩放
				control.attach(lightOrigin);
				
				// 获取控制器的辅助线（Gizmo）并添加到场景
				// 辅助线是可见的3D控件，帮助用户理解变换操作
				scene.add(control.getHelper());

				// ========== 第7部分：方向光源创建 ==========
				
				// 创建多个方向光（平行光）
				// 使用多个光源并行采样可以显著加速光照收敛过程
				for (let l = 0; l < lightCount; l++) {
					// 创建方向光实例
					// 参数说明：
					// 1. 0xffffff - 光源颜色（白色）
					// 2. Math.PI / lightCount - 光源强度
					//    总强度为π，平均分配到每个光源，保持总能量守恒
					const dirLight = new THREE.DirectionalLight(0xffffff, Math.PI / lightCount);
					
					// 设置光源名称（在调试器中显示）
					dirLight.name = '方向光源 ' + l;
					
					// 设置光源初始位置
					// 这只是初始位置，实际在animate()中每帧都会更新
					dirLight.position.set(200, 200, 200);
					
					// 启用阴影投射
					// 只有启用了这个，光源才能产生阴影
					dirLight.castShadow = true;
					
					// 配置光源的阴影相机（正交相机）
					// 阴影相机决定了哪些区域会被渲染到阴影贴图中
					
					// 近裁剪面：100单位以内的物体不产生阴影（优化性能）
					dirLight.shadow.camera.near = 100;
					
					// 远裁剪面：5000单位以外的物体不产生阴影
					dirLight.shadow.camera.far = 5000;
					
					// 定义阴影相机的视锥体边界
					// 这些值定义了一个长方体区域，只有在这个区域内的物体会被考虑用于阴影计算
					dirLight.shadow.camera.right = 150;    // 右边界
					dirLight.shadow.camera.left = -150;    // 左边界
					dirLight.shadow.camera.top = 150;      // 上边界
					dirLight.shadow.camera.bottom = -150;  // 下边界
					
					// 设置阴影贴图的分辨率
					// 分辨率越高，阴影边缘越清晰，但性能消耗越大
					dirLight.shadow.mapSize.width = shadowMapRes;   // 宽度分辨率
					dirLight.shadow.mapSize.height = shadowMapRes;  // 高度分辨率
					
					// 设置阴影偏移（Bias）
					// 这是一个微调参数，用于解决阴影失真（shadow acne）问题
					// 负值将阴影稍微推向光源方向，避免表面自阴影
					dirLight.shadow.bias = -0.001;
					
					// 将光源添加到光照贴图对象数组
					// 注意：光源本身也需要参与光照贴图计算
					lightmapObjects.push(dirLight);
					
					// 将光源添加到方向光数组，方便后续统一管理
					dirLights.push(dirLight);
				}

				// ========== 第8部分：地面创建 ==========
				
				// 创建一个平面网格作为地面
				const groundMesh = new THREE.Mesh(
					// 几何体：600x600单位的平面
					new THREE.PlaneGeometry(600, 600),
					
					// 材质：使用Phong着色模型，支持高光和阴影
					new THREE.MeshPhongMaterial({
						color: 0xffffff,     // 材质颜色（白色）
						depthWrite: true     // 启用深度写入，确保正确的遮挡关系
					})
				);
				
				// 将地面稍微下移，避免与模型底部产生z-fighting（深度冲突）
				groundMesh.position.y = -0.1;
				
				// 将地面旋转90度，使其水平（PlaneGeometry默认是垂直的）
				groundMesh.rotation.x = -Math.PI / 2;  // -90度
				
				// 设置地面名称
				groundMesh.name = '地面网格';
				
				// 将地面添加到光照贴图对象数组
				// 地面也需要接收光照贴图，以显示正确的阴影和光照
				lightmapObjects.push(groundMesh);
				
				// 将地面添加到场景
				scene.add(groundMesh);

				// ========== 第9部分：模型加载回调函数 ==========
				
				/**
				 * 模型加载完成后的回调函数
				 * 当GLTF模型加载完成后，这个函数被调用
				 * 主要任务：
				 * 1. 配置模型的材质和阴影属性
				 * 2. 将模型添加到光照贴图系统
				 * 3. 设置光源目标
				 * 4. 添加模型变换控制器
				 */
				function loadModel() {
					// 遍历模型的所有子对象
					// traverse()方法递归访问对象及其所有后代
					object.traverse(function(child) {
						// 检查子对象是否是网格（Mesh）
						if (child.isMesh) {
							// 设置网格名称
							child.name = '已加载模型';
							
							// 启用阴影投射：模型可以产生阴影
							child.castShadow = true;
							
							// 启用阴影接收：模型可以接收其他物体投射的阴影
							child.receiveShadow = true;
							
							// 使用Phong材质替换原始材质
							// Phong材质支持高光、阴影和光照贴图
							child.material = new THREE.MeshPhongMaterial();
							
							// 将模型网格添加到光照贴图对象数组
							lightmapObjects.push(child);
							
							// 将所有光照贴图对象注册到渐进式光照贴图处理器
							// 这个方法告诉光照贴图系统哪些对象需要生成光照贴图
							progressiveSurfacemap.addObjectsToLightMap(lightmapObjects);
						} else {
							// 对于非网格对象（如骨骼、空节点等）
							// 禁用所有渲染层，使其不可见
							// 这可以优化性能，避免渲染不必要的辅助对象
							child.layers.disableAll();
						}
					});
					
					// 将模型添加到场景中
					scene.add(object);
					
					// 设置模型缩放：放大2倍
					object.scale.set(2, 2, 2);
					
					// 设置模型位置：稍微下移
					object.position.set(0, -16, 0);
					
					// ========== 第10部分：模型变换控制器 ==========
					
					// 创建第二个变换控制器（用于控制模型）
					control2 = new TransformControls(camera, renderer.domElement);
					
					// 监听控制器的拖拽事件
					control2.addEventListener('dragging-changed', (event) => {
						// 拖拽模型时，禁用轨道控制器
						controls.enabled = !event.value;
					});
					
					// 将控制器附加到模型
					control2.attach(object);
					
					// 将控制器的辅助线添加到场景
					scene.add(control2.getHelper());
					
					// ========== 第11部分：光源目标设置 ==========
					
					// 创建光源目标组
					// 方向光需要指定一个目标点，所有光线都平行射向这个目标
					const lightTarget = new THREE.Group();
					
					// 设置目标点位置（在模型上方20单位处）
					lightTarget.position.set(0, 20, 0);
					
					// 将所有方向光的目标设置为这个目标组
					for (let l = 0; l < dirLights.length; l++) {
						dirLights[l].target = lightTarget;
					}
					
					// 将光源目标添加到模型
					// 这样当模型移动时，光源目标也会跟随移动
					object.add(lightTarget);
				}

				// ========== 第12部分：GLTF模型加载 ==========
				
				// 创建加载管理器
				// LoadingManager可以管理多个加载任务，并提供一个完成回调
				const manager = new THREE.LoadingManager(loadModel);
				
				// 创建GLTF加载器实例
				// GLTF是一种现代的3D文件格式，支持几何体、材质、动画等
				const loader = new GLTFLoader(manager);
				
				// 加载GLTF模型文件
				// 参数说明：
				// 1. 'models/gltf/ShadowmappableMesh.glb' - 模型文件路径
				// 2. 加载成功回调函数
				loader.load('models/gltf/ShadowmappableMesh.glb', function(obj) {
					// 获取场景的第一个子对象（通常是主要模型）
					// obj.scene是加载的GLTF场景，可能包含多个对象
					object = obj.scene.children[0];
				});

				// ========== 第13部分：轨道控制器配置 ==========
				
				// 创建轨道控制器实例
				// 轨道控制器允许用户用鼠标控制相机：
				// - 左键拖拽：旋转视角
				// - 右键拖拽：平移视角
				// - 滚轮：缩放
				controls = new OrbitControls(camera, renderer.domElement);
				
				// 启用阻尼（惯性效果）
				// 当用户停止拖拽后，相机会继续移动一小段距离，产生平滑感
				controls.enableDamping = true;
				
				// 设置阻尼系数：值越小，惯性越强
				controls.dampingFactor = 0.05;
				
				// 启用屏幕空间平移
				// 这意味着平移操作是基于屏幕坐标而不是世界坐标
				controls.screenSpacePanning = true;
				
				// 设置相机最小距离：不能比100单位更靠近目标
				controls.minDistance = 100;
				
				// 设置相机最大距离：不能比500单位更远离目标
				controls.maxDistance = 500;
				
				// 设置最大俯仰角：限制相机不能看到正下方或正上方
				// Math.PI / 1.5 约等于 120度
				controls.maxPolarAngle = Math.PI / 1.5;
				
				// 设置轨道控制器的目标点（围绕哪个点旋转）
				// 这里设置为场景中心点上方100单位处
				controls.target.set(0, 100, 0);
			
				// ========== 第14部分：窗口事件监听 ==========
				
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，重新调整渲染器和相机
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 创建图形用户界面（GUI）
			 * 
			 * 这个函数创建了一个控制面板，允许用户实时调整光照参数
			 * 所有调整都会立即生效，无需刷新页面
			 * 
			 * GUI使用了Three.js Inspector的内置功能来创建控件
			 */
			function createGUI() {
				// 在调试检查器中创建一个新的参数面板
				// '累积设置' 是面板的标题
				const gui = renderer.inspector.createParameters('累积设置');
				
				// 添加"启用累积"复选框
				// 参数说明：
				// 1. params - 目标对象
				// 2. '启用累积' - 要绑定的属性名
				gui.add(params, '启用累积');
				
				// 添加"模糊边缘"复选框
				// 控制是否对光照贴图边缘进行模糊处理
				gui.add(params, '模糊边缘');
				
				// 添加"混合窗口"滑块控件
				// 参数说明：
				// 1. params - 目标对象
				// 2. '混合窗口' - 属性名
				// 3. 1 - 最小值
				// 4. 500 - 最大值
				// 5. 1 - 步长（每次调整的变化量）
				gui.add(params, '混合窗口', 1, 500, 1);
				
				// 添加"光源半径"滑块
				// 控制光源在原点周围的随机采样范围
				gui.add(params, '光源半径', 0, 200, 10);
				
				// 添加"环境权重"滑块
				// 控制环境光与直接光的平衡
				gui.add(params, '环境权重', 0, 1, 0.1);
				
				// 添加"调试模式"复选框，并绑定change事件
				// 当用户切换调试模式时，调用showDebugLightmap方法
				gui.add(params, '调试模式').onChange((value) => 
					// 将调试状态传递给光照贴图处理器
					progressiveSurfacemap.showDebugLightmap(value)
				);
			}

			/**
			 * 窗口大小调整处理函数
			 * 
			 * 当浏览器窗口大小改变时，这个函数被调用
			 * 它确保3D场景正确适应新的窗口尺寸
			 * 
			 * 这个函数没有参数，也没有返回值
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// 宽高比 = 窗口宽度 / 窗口高度
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机参数改变后，必须调用这个方法重新计算内部矩阵
				camera.updateProjectionMatrix();
				
				// 更新渲染器的尺寸，使其匹配窗口新尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数 - 每帧自动调用
			 * 
			 * 这是Three.js应用的核心循环，每秒被调用60次（通常）
			 * 每一帧执行以下任务：
			 * 1. 更新控制器状态
			 * 2. 累积光照贴图信息
			 * 3. 更新光源位置
			 * 4. 渲染整个场景
			 * 
			 * 这个函数没有参数，也没有返回值
			 */
			function animate() {
				// ========== 第1步：更新控制器 ==========
				
				// 更新轨道控制器
				// 如果启用了阻尼（惯性），这个方法会计算相机的平滑运动
				controls.update();

				// ========== 第2步：累积表面光照贴图 ==========
				
				// 检查是否启用了光照贴图累积
				if (params['启用累积']) {
					// 更新渐进式光照贴图系统
					// 这个方法会：
					// 1. 使用当前光源设置渲染场景到光照贴图
					// 2. 将新结果与历史结果混合
					// 3. 应用模糊处理（如果启用）
					progressiveSurfacemap.update(
						camera,                    // 当前相机，用于确定视角
						params['混合窗口'],        // 混合窗口大小，控制新旧信息混合速度
						params['模糊边缘']         // 是否对边缘进行模糊处理
					);
				}

				// ========== 第3步：更新方向光位置 ==========
				
				// 遍历所有方向光，每帧更新它们的位置
				// 这种动态光源位置是实现渐进式光照累积的关键
				for (let l = 0; l < dirLights.length; l++) {
					// 根据环境权重决定使用哪种采样策略
					// Math.random()生成0到1之间的随机数
					
					if (Math.random() > params['环境权重']) {
						// 策略1：在光源原点周围随机采样（模拟直接光照）
						// 这种采样在光源原点附近产生随机位置
						// 适合模拟来自特定方向的光源（如窗户、灯具）
						dirLights[l].position.set(
							// X坐标：光源原点X + 随机偏移（范围：0到光源半径）
							lightOrigin.position.x + (Math.random() * params['光源半径']),
							
							// Y坐标：光源原点Y + 随机偏移
							lightOrigin.position.y + (Math.random() * params['光源半径']),
							
							// Z坐标：光源原点Z + 随机偏移
							lightOrigin.position.z + (Math.random() * params['光源半径'])
						);
					} else {
						// 策略2：半球均匀采样（模拟环境光遮蔽）
						// 这种采样在整个上半球均匀分布
						// 适合模拟来自所有方向的天空光和环境反射光
						
						// 生成球面坐标（用于均匀球面分布）
						// λ（lambda）：纬度角，范围[-π/2, π/2]
						// Math.acos(2*rand-1)-π/2 产生余弦分布的纬度
						const lambda = Math.acos(2 * Math.random() - 1) - (Math.PI / 2.0);
						
						// φ（phi）：经度角，范围[0, 2π]
						const phi = 2 * Math.PI * Math.random();
						
						// 将球面坐标转换为笛卡尔坐标（3D直角坐标）
						// 球面坐标转换公式：
						// x = cos(λ) * cos(φ) * r
						// y = cos(λ) * sin(φ) * r
						// z = sin(λ) * r
						// 这里r=300是采样半径
						
						dirLights[l].position.set(
							// X坐标：球面坐标转换，加上模型位置作为中心
							((Math.cos(lambda) * Math.cos(phi)) * 300) + object.position.x,
							
							// Y坐标：取绝对值确保光从上方向下照射，加上模型高度偏移
							// 使用Math.abs确保Y坐标始终为正（上半球）
							Math.abs((Math.cos(lambda) * Math.sin(phi)) * 300) + object.position.y + 20,
							
							// Z坐标：球面坐标转换
							(Math.sin(lambda) * 300) + object.position.z
						);
					}
				}

				// ========== 第4步：渲染场景 ==========
				
				// 使用当前相机渲染整个场景
				// 这是将3D数据绘制到2D屏幕的最后一步
				renderer.render(scene, camera);
			}
		</script>
	</body>
</html>