<!-- 代码功能与主要技术点分析
一、整体功能概述
这是一个基于Three.js的级联阴影映射（Cascaded Shadow Maps, CSM）技术演示项目，主要展示了在大规模3D场景中如何实现高质量、高性能的动态阴影效果。

核心功能：
实时级联阴影渲染：将场景划分为多个区域，分别渲染阴影

交互式场景控制：通过GUI面板调整所有阴影参数

双相机系统支持：可在透视相机和正交相机之间切换

可视化调试工具：内置CSM辅助器，用于理解阴影工作原理

响应式设计：自动适应不同屏幕尺寸

二、主要技术点详解
1. 级联阴影映射（CSM）技术
技术原理：
javascript
// 核心优势：解决传统阴影贴图的"远近矛盾"问题
// 传统阴影：一个贴图覆盖整个视锥体 → 近处锯齿严重 / 远处浪费分辨率
// CSM方案：将视锥体分成多个级联 → 每个级联独立渲染阴影贴图

csm = new CSM({
    cascades: 4,           // 4个级联
    maxFar: 1000,          // 最大阴影距离
    mode: 'practical',     // 实用分割模式
    shadowMapSize: 1024    // 每个贴图1024x1024
});
三种分割模式：
uniform（均匀分割）：等间距划分，实现简单但效率不高

logarithmic（对数分割）：近处密集、远处稀疏，符合透视规律

practical（实用分割）：综合考虑性能和效果，实际应用中最常用

技术优势：
近处高精度：第一级联覆盖最近的区域，阴影细节清晰

远处低开销：末级联覆盖远处区域，节省计算资源

平滑过渡：级联之间实现无缝混合，避免可见接缝

2. 双相机渲染系统
javascript
// 透视相机（Perspective Camera）
camera = new THREE.PerspectiveCamera(70, aspect, 0.1, 5000);
// 特点：模拟人眼，有近大远小的透视效果

// 正交相机（Orthographic Camera）
orthoCamera = new THREE.OrthographicCamera(left, right, top, bottom, near, far);
// 特点：无透视变形，保持物体实际尺寸，常用于CAD、2D游戏
相机切换机制：
javascript
// 实时切换，保持视角一致
csm.camera = value ? orthoCamera : camera;
// 切换时重新计算所有级联的视锥体
csm.updateFrustums();
3. 阴影优化技术
阴影质量提升：
PCF（Percentage-Closer Filtering）：柔化阴影边缘

javascript
renderer.shadowMap.type = THREE.PCFShadowMap;
阴影渐变（Fade）：远距离阴影逐渐淡出

javascript
csm.fade = true;  // 启用渐变效果
边缘余量（Margin）：防止阴影在视口边缘被裁剪

javascript
csm.lightMargin = 100;  // 100单位的缓冲区
性能优化：
视锥体裁剪：只渲染相机可见范围内的阴影

动态分辨率：根据级联距离调整阴影贴图精度

材质更新优化：仅在参数变化时重新编译着色器

4. 灯光系统设计
三层灯光架构：
javascript
// 1. 环境光（Ambient Light） - 基础照明
const ambientLight = new THREE.AmbientLight(0xffffff, 1.5);

// 2. CSM主光源 - 投射阴影
csm = new CSM({
    lightDirection: new THREE.Vector3(-1, -1, -1).normalize()
});

// 3. 辅助方向光 - 补充照明
const additionalLight = new THREE.DirectionalLight(0x000020, 1.5);
5. 交互与控制界面
GUI控制系统：
javascript
const gui = new GUI();
// 分组控制：阴影参数、光源设置、辅助器显示
可调节参数：
阴影参数：距离、模式、边缘余量、渐变开关

光源参数：方向、远近裁剪面

相机设置：透视/正交切换

辅助工具：CSM可视化开关

6. 场景构建与对象管理
场景结构：
javascript
// 大规模地面（10,000 x 10,000单位）
const floor = new THREE.Mesh(
    new THREE.PlaneGeometry(10000, 10000, 8, 8),
    floorMaterial
);

// 动态立方体阵列（80个，分两排）
for (let i = 0; i < 40; i++) {
    // 随机高度：6-8倍缩放
    cube1.scale.y = Math.random() * 2 + 6;
}
材质管理：
javascript
// CSM材质预处理
csm.setupMaterial(material);
// 功能：为材质注入CSM专用的uniform和着色器代码
7. 调试与可视化工具
CSM辅助器：
javascript
csmHelper = new CSMHelper(csm);
// 可显示：视锥体分割线、阴影边界框、光源范围
可视化选项：
显示视锥体：查看各个级联的覆盖范围

显示分割平面：查看级联之间的分界线

显示阴影边界：查看每个阴影贴图的有效区域

8. 性能与兼容性考虑
性能特性：
按需更新：相机静止时不更新阴影贴图

资源复用：共享几何体和材质实例

批量渲染：使用InstancedMesh优化大量相同物体

兼容性设计：
ES6模块化：使用import/export语法

现代浏览器支持：基于WebGL 2.0/1.0特性检测

移动端适配：触摸控制、响应式布局

三、技术实现流程
渲染管线流程：
text
1. 初始化阶段
   ├── 创建场景、相机、渲染器
   ├── 设置CSM参数和级联数量
   ├── 创建灯光系统和几何体
   └── 初始化GUI控制系统

2. 动画循环（每帧）
   ├── 更新相机矩阵和控制器
   ├── 更新CSM（重新计算阴影）
   ├── 更新辅助器（如果需要）
   └── 执行渲染（根据相机类型选择）

3. 交互响应
   ├── GUI参数变化 → 更新CSM配置
   ├── 窗口大小变化 → 更新相机和渲染器
   └── 相机切换 → 重新计算投影矩阵
CSM工作流程：
text
1. 分割视锥体：根据模式将相机视锥体分为N个级联
2. 计算光照空间：将每个级联转换到光源视角
3. 渲染阴影贴图：为每个级联生成独立的深度贴图
4. 应用阴影：在最终渲染时，根据距离选择对应的级联贴图
5. 混合过渡：在级联边界处进行平滑混合
四、应用场景与优势
适用场景：
大规模开放世界游戏：地形、植被、建筑的动态阴影

建筑可视化：室内外场景的真实光照效果

GIS地理信息系统：地形地貌的精确阴影表现

虚拟仿真训练：需要真实光照的模拟环境

技术优势对比：
技术方案	优点	缺点	适用场景
传统阴影贴图	实现简单，性能开销小	远近精度矛盾，大场景效果差	小规模场景
CSM技术	大场景阴影质量高，性能可调节	实现复杂，内存占用较大	大规模开放世界
光线追踪阴影	效果最真实，物理准确	性能要求极高，硬件依赖	离线渲染，高端设备
性能优化建议：
级联数量选择：

移动设备：2-3个级联

桌面设备：4个级联

高端设备：4-5个级联

阴影贴图分辨率：

低端：512x512

中端：1024x1024

高端：2048x2048

裁剪优化：

设置合理的阴影距离（maxFar）

根据场景复杂度调整级联分布

五、扩展与改进方向
1. 高级功能扩展
javascript
// 示例：添加软阴影和接触硬化
csm.shadowFilterSize = 5;      // 增加过滤尺寸实现更软阴影
csm.contactHardening = true;   // 接触硬化：近物体阴影更清晰
2. 性能优化方向
虚拟纹理技术：动态加载阴影贴图

异步渲染：将阴影计算移至Web Worker

LOD系统：根据距离简化阴影计算

3. 质量提升方案
PCSS软阴影：基于距离的软阴影过滤

VSM/ESM：方差/指数阴影映射，减少阴影锯齿

光线步进：结合屏幕空间技术进一步提升质量 -->


<!DOCTYPE html>
<!-- 声明HTML5文档类型 -->
<html lang="en">
	<!-- 文档头部开始 -->
	<head>
		<!-- 页面标题：显示在浏览器标签页上 -->
		<title>Three.js WebGL - 级联阴影映射技术演示</title>
		<!-- 字符编码设置：使用UTF-8编码支持多语言字符 -->
		<meta charset="utf-8">
		<!-- 
			移动端视口设置：
			width=device-width - 视口宽度等于设备宽度
			user-scalable=no - 禁止用户手动缩放
			minimum-scale=1.0 - 最小缩放比例为1倍
			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="main.css">
	</head>
	<!-- 文档主体开始 -->
	<body>
		<!-- 
			渲染器容器：
			这个div将包含Three.js创建的canvas元素
			所有3D场景都将在这个容器内渲染
		-->
		<div id="container"></div>
		<!-- 
			信息显示面板：
			显示项目信息和相关链接
			通常位于页面角落，半透明显示
		-->
		<div id="info">
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> WebGL - 级联阴影映射技术演示<br>
			基于 <a href="https://github.com/strandedkitty/" target="_blank" rel="noopener">StrandedKitty</a> 的 <a href="https://github.com/strandedkitty/three-csm" target="_blank" rel="noopener">CSM插件</a>开发
		</div>

		<!-- 
			模块导入映射表（Import Maps）：
			现代浏览器支持的模块解析配置
			定义模块标识符到实际URL的映射关系
			允许在代码中使用简洁的导入路径
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module"表示这是一个ES6模块
			模块中的代码有自己的作用域，不会污染全局
			支持使用import/export语法
		-->
		<script type="module">
			// ==================== 模块导入部分 ====================
			// 导入Three.js核心库：包含所有基础3D功能
			import * as THREE from 'three';
			// 导入轨道控制器：允许用户用鼠标交互控制相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入GUI库：创建可视化参数控制面板
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
			// 导入级联阴影映射核心类：实现CSM的主要功能
			import { CSM } from 'three/addons/csm/CSM.js';
			// 导入CSM辅助器：用于调试和可视化CSM的各个部分
			import { CSMHelper } from 'three/addons/csm/CSMHelper.js';

			// ==================== 全局变量声明 ====================
			// 这些变量将在多个函数中共享使用
			let renderer;      // Three.js渲染器：负责将3D场景绘制到canvas
			let scene;         // 场景对象：包含所有的3D对象、灯光、相机
			let camera;        // 透视相机：模拟人眼视角，有透视效果
			let orthoCamera;   // 正交相机：无透视效果，物体大小与距离无关
			let controls;      // 轨道控制器实例：处理用户输入控制相机
			let csm;           // CSM实例：级联阴影映射系统
			let csmHelper;     // CSM辅助器实例：帮助理解和调试CSM

			// ==================== CSM参数配置对象 ====================
			// 这个对象存储所有可调节的CSM参数，GUI将绑定到这些参数
			const params = {
				orthographic: false,      // 是否使用正交相机（true）还是透视相机（false）
				fade: false,              // 是否启用阴影渐变效果：使远距离阴影逐渐消失
				shadows: true,            // 全局阴影开关：控制是否渲染阴影
				far: 1000,                // 阴影最大可见距离：超过此距离的物体不投射阴影
				mode: 'practical',        // 视锥体分割模式：可选'uniform'、'logarithmic'、'practical'
				lightX: -1,               // 光源方向向量的X分量：-1到1之间
				lightY: -1,               // 光源方向向量的Y分量：-1到1之间
				lightZ: -1,               // 光源方向向量的Z分量：-1到1之间
				margin: 100,              // 阴影边缘余量：防止阴影在视口边缘被裁剪
				lightFar: 5000,           // 光源远裁剪平面：光源能照射到的最远距离
				lightNear: 1,             // 光源近裁剪平面：光源开始照射的最近距离
				autoUpdateHelper: true,   // 是否自动更新CSM辅助器（每帧更新）
				updateHelper: function () {  // 手动更新CSM辅助器的函数（GUI按钮调用）
					csmHelper.update();   // 调用辅助器的更新方法
				}
			};

			// ==================== 初始化入口 ====================
			// 页面加载完成后调用init函数开始设置场景
			init();

			// ==================== 函数定义部分 ====================

			/**
			 * 更新正交相机函数
			 * 当切换到正交相机模式时，根据当前透视相机的参数
			 * 重新计算和设置正交相机的各个参数
			 * 
			 * 正交相机没有透视效果，常用于CAD、2D游戏或需要精确尺寸的场景
			 */
			function updateOrthoCamera() {
				// 计算控制目标点到相机当前位置的距离
				// 这个距离将决定正交相机的视口大小
				const size = controls.target.distanceTo(camera.position);
				
				// 获取当前透视相机的宽高比（宽度/高度）
				// 保持相同的宽高比确保画面不被拉伸
				const aspect = camera.aspect;

				// 设置正交相机的六个裁剪平面：
				// left/right - 左右裁剪平面位置
				// top/bottom - 上下裁剪平面位置
				// 这些值决定了相机能看到的世界范围
				orthoCamera.left = size * aspect / -2;   // 左边界：负值表示向左延伸
				orthoCamera.right = size * aspect / 2;   // 右边界：正值表示向右延伸
				orthoCamera.top = size / 2;              // 上边界
				orthoCamera.bottom = size / -2;          // 下边界
				
				// 使正交相机与透视相机保持相同的位置
				// 这样切换相机时视角不会跳跃
				orthoCamera.position.copy(camera.position);
				
				// 使正交相机与透视相机保持相同的旋转角度
				orthoCamera.rotation.copy(camera.rotation);
				
				// 更新正交相机的投影矩阵
				// 这是必须的一步，否则相机参数变化不会生效
				orthoCamera.updateProjectionMatrix();
			}

			/**
			 * 主初始化函数
			 * 这是整个应用程序的入口点，负责创建和配置所有必要的组件
			 * 包括：场景、相机、渲染器、灯光、几何体、GUI等
			 */
			function init() {
				// ---------- 创建场景 ----------
				// 场景是Three.js的核心容器，所有3D对象都添加到场景中
				scene = new THREE.Scene();
				
				// 设置场景背景色（深蓝灰色）
				// 使用十六进制颜色代码
				scene.background = new THREE.Color('#454e61');
				
				// ---------- 创建相机 ----------
				// 创建透视相机：模拟人眼视角，远处的物体看起来更小
				// 参数：视野角度FOV、宽高比、近裁剪平面、远裁剪平面
				camera = new THREE.PerspectiveCamera(
					70,                              // 70度视野角度（常见值）
					window.innerWidth / window.innerHeight, // 根据窗口尺寸计算宽高比
					0.1,                             // 近裁剪平面：0.1个单位距离以内的物体不显示
					5000                             // 远裁剪平面：5000个单位距离以外的物体不显示
				);
				
				// 创建正交相机：无透视效果，所有物体保持实际尺寸
				// 参数将在updateOrthoCamera函数中设置
				orthoCamera = new THREE.OrthographicCamera();

				// ---------- 创建渲染器 ----------
				// WebGLRenderer是Three.js的核心渲染器
				// antialias: true 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGLRenderer({ antialias: true });
				
				// 设置渲染器尺寸为整个浏览器窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// setAnimationLoop是requestAnimationFrame的封装
				// animate函数将在每一帧被调用
				renderer.setAnimationLoop(animate);
				
				// 将渲染器的canvas元素添加到页面body中
				// renderer.domElement就是canvas元素
				document.body.appendChild(renderer.domElement);
				
				// 启用渲染器的阴影映射功能
				// 这是渲染阴影的前提条件
				renderer.shadowMap.enabled = params.shadows;
				
				// 设置阴影映射类型为PCF（Percentage-Closer Filtering）
				// PCF阴影会产生更柔和的阴影边缘
				renderer.shadowMap.type = THREE.PCFShadowMap;

				// ---------- 创建轨道控制器 ----------
				// 轨道控制器允许用户通过鼠标交互控制相机
				// 参数：要控制的相机、事件监听的DOM元素
				controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置最大极角为90度（π/2弧度）
				// 防止相机旋转到地面以下（避免看到地面下方）
				controls.maxPolarAngle = Math.PI / 2;
				
				// 设置相机初始位置（x, y, z坐标）
				camera.position.set(60, 60, 0);
				
				// 设置控制器的目标点（相机围绕这个点旋转）
				// 这是场景中的一个固定点
				controls.target = new THREE.Vector3(-100, 10, 0);
				
				// 更新控制器内部状态
				// 通常在相机或目标位置改变后调用
				controls.update();

				// ---------- 创建环境光 ----------
				// 环境光提供均匀的全场景照明，没有方向性
				// 参数：颜色（白色）、强度（1.5倍）
				const ambientLight = new THREE.AmbientLight(0xffffff, 1.5);
				scene.add(ambientLight);

				// ---------- 创建额外的方向光 ----------
				// 这个方向光用于补充照明，不是主要的阴影投射光源
				const additionalDirectionalLight = new THREE.DirectionalLight(0x000020, 1.5);
				
				// 设置光源方向并调整位置：
				// 1. 从参数中获取方向向量
				// 2. 归一化（长度为1）
				// 3. 乘以-200，将光源移动到相反方向200个单位处
				// 这是因为Three.js中方向光的方向是从光源位置指向原点
				additionalDirectionalLight.position.set(
					params.lightX, 
					params.lightY, 
					params.lightZ
				).normalize().multiplyScalar(-200);
				scene.add(additionalDirectionalLight);

				// ---------- 创建级联阴影映射（CSM）系统 ----------
				// CSM是解决大场景阴影质量问题的关键技术
				// 它将视锥体分为多个区域（级联），每个区域使用独立的阴影贴图
				csm = new CSM({
					maxFar: params.far,            // 阴影最大可见距离
					cascades: 4,                   // 级联数量：将视锥体分为4个区域
					mode: params.mode,             // 分割模式：决定如何划分级联
					parent: scene,                 // 父场景：CSM创建的光源将添加到这个场景
					shadowMapSize: 1024,           // 每个阴影贴图的尺寸（像素）
					lightDirection: new THREE.Vector3(  // 主阴影光源的方向
						params.lightX, 
						params.lightY, 
						params.lightZ
					).normalize(),
					camera: camera                 // 关联的相机：CSM根据这个相机计算视锥体
				});

				// ---------- 创建CSM辅助器 ----------
				// 辅助器用于调试和可视化CSM的内部工作原理
				// 可以显示：视锥体分割、阴影边界、光源位置等
				csmHelper = new CSMHelper(csm);
				csmHelper.visible = false;  // 默认不显示，可以通过GUI开启
				scene.add(csmHelper);       // 将辅助器添加到场景

				// ---------- 创建地板 ----------
				// 创建地板材质：使用Phong材质，支持高光和阴影
				const floorMaterial = new THREE.MeshPhongMaterial({ color: '#252a34' });
				
				// 为地板材质设置CSM支持
				// 这会在材质着色器中添加CSM相关的uniform和代码
				csm.setupMaterial(floorMaterial);

				// 创建地板网格：
				// PlaneGeometry创建平面几何体，参数：宽度、高度、宽度分段数、高度分段数
				const floor = new THREE.Mesh(
					new THREE.PlaneGeometry(10000, 10000, 8, 8),  // 非常大的地板（10000x10000单位）
					floorMaterial
				);
				
				// 将地板旋转-90度（-π/2弧度）
				// 默认平面是垂直的，旋转后变为水平地面
				floor.rotation.x = -Math.PI / 2;
				
				// 设置阴影属性：
				floor.castShadow = true;    // 地板本身投射阴影（边缘可能有微弱阴影）
				floor.receiveShadow = true; // 地板接收其他物体的阴影
				
				// 将地板添加到场景
				scene.add(floor);

				// ---------- 创建两种立方体材质 ----------
				// 材质1：青蓝色，用于交替显示的立方体
				const material1 = new THREE.MeshPhongMaterial({ color: '#08d9d6' });
				csm.setupMaterial(material1);  // 设置CSM支持
				
				// 材质2：粉红色，用于交替显示的立方体
				const material2 = new THREE.MeshPhongMaterial({ color: '#ff2e63' });
				csm.setupMaterial(material2);  // 设置CSM支持

				// 创建立方体几何体：10x10x10单位的立方体
				const geometry = new THREE.BoxGeometry(10, 10, 10);

				// ---------- 创建多排立方体 ----------
				// 创建40对立方体，形成两排柱子
				for (let i = 0; i < 40; i++) {
					// 第一排立方体（在正Z方向）
					// 根据i的奇偶性交替使用两种材质
					const cube1 = new THREE.Mesh(
						geometry, 
						i % 2 === 0 ? material1 : material2
					);
					
					// 设置阴影属性
					cube1.castShadow = true;     // 立方体投射阴影
					cube1.receiveShadow = true;  // 立方体接收阴影（主要是自身的阴影）
					
					// 添加到场景
					scene.add(cube1);
					
					// 设置位置：沿X轴负方向等距排列
					// X: -i*25（每25单位一个）
					// Y: 20（离地面20单位）
					// Z: 30（在正Z方向30单位处）
					cube1.position.set(-i * 25, 20, 30);
					
					// 随机缩放Y轴：6到8倍之间
					// 产生不同高度的柱子效果
					cube1.scale.y = Math.random() * 2 + 6;

					// 第二排立方体（在负Z方向）
					// 材质与第一排交替（产生棋盘效果）
					const cube2 = new THREE.Mesh(
						geometry, 
						i % 2 === 0 ? material2 : material1
					);
					
					cube2.castShadow = true;
					cube2.receiveShadow = true;
					scene.add(cube2);
					
					// 与第一排对称，但Z坐标为负值
					cube2.position.set(-i * 25, 20, -30);
					cube2.scale.y = Math.random() * 2 + 6;
				}

				// ==================== GUI控制面板设置 ====================
				// 创建GUI实例：参数控制面板将出现在页面右上角
				const gui = new GUI();

				// ---------- 正交相机切换控制 ----------
				gui.add(params, 'orthographic')
				   .name('正交相机')  // 设置显示名称
				   .onChange(function (value) {
						// 切换CSM使用的相机类型
						csm.camera = value ? orthoCamera : camera;
						// 更新CSM的视锥体分割
						csm.updateFrustums();
				   });

				// ---------- 阴影渐变控制 ----------
				gui.add(params, 'fade')
				   .name('阴影渐变')
				   .onChange(function (value) {
						// 启用或禁用阴影边缘的渐变效果
						csm.fade = value;
						// 更新CSM的视锥体分割
						csm.updateFrustums();
				   });

				// ---------- 全局阴影开关 ----------
				gui.add(params, 'shadows')
				   .name('阴影开关')
				   .onChange(function (value) {
						// 启用或禁用渲染器的阴影映射功能
						renderer.shadowMap.enabled = value;

						// 遍历场景中的所有对象
						// 当阴影开关改变时，需要更新所有材质
						scene.traverse(function (child) {
							// 检查对象是否有材质属性
							if (child.material) {
								// 标记材质需要更新
								// 这会触发着色器重新编译
								child.material.needsUpdate = true;
							}
						});
				   });

				// ---------- 阴影最大距离控制 ----------
				gui.add(params, 'far', 1, 5000)
				   .step(1)                     // 每次调整的步长为1
				   .name('阴影距离')             // 设置显示名称
				   .onChange(function (value) {
						// 设置CSM的最大阴影距离
						csm.maxFar = value;
						// 更新CSM的视锥体分割
						csm.updateFrustums();
				   });

				// ---------- 视锥体分割模式控制 ----------
				gui.add(params, 'mode', ['uniform', 'logarithmic', 'practical'])
				   .name('分割模式')  // 设置显示名称
				   .onChange(function (value) {
						// 设置CSM的视锥体分割模式
						csm.mode = value;
						// 更新CSM的视锥体分割
						csm.updateFrustums();
				   });

				// ---------- 光源方向控制（X轴） ----------
				gui.add(params, 'lightX', -1, 1)
				   .name('光源X方向')
				   .onChange(function (value) {
						// 更新CSM光源的方向向量X分量
						csm.lightDirection.x = value;
				   });

				// ---------- 光源方向控制（Y轴） ----------
				gui.add(params, 'lightY', -1, 1)
				   .name('光源Y方向')
				   .onChange(function (value) {
						// 更新CSM光源的方向向量Y分量
						csm.lightDirection.y = value;
				   });

				// ---------- 光源方向控制（Z轴） ----------
				gui.add(params, 'lightZ', -1, 1)
				   .name('光源Z方向')
				   .onChange(function (value) {
						// 更新CSM光源的方向向量Z分量
						csm.lightDirection.z = value;
				   });

				// ---------- 阴影边缘余量控制 ----------
				gui.add(params, 'margin', 0, 200)
				   .name('阴影边缘余量')
				   .onChange(function (value) {
						// 设置CSM的阴影边缘余量
						// 防止阴影在视口边缘突然消失
						csm.lightMargin = value;
				   });

				// ---------- 光源近平面控制 ----------
				gui.add(params, 'lightNear', 1, 10000)
				   .name('光源近平面')
				   .onChange(function (value) {
						// 遍历CSM创建的所有光源（每个级联一个光源）
						for (let i = 0; i < csm.lights.length; i++) {
							// 更新每个光源的阴影相机的近裁剪平面
							csm.lights[i].shadow.camera.near = value;
							// 更新阴影相机的投影矩阵
							// 这是必须的，否则参数变化不会生效
							csm.lights[i].shadow.camera.updateProjectionMatrix();
						}
				   });

				// ---------- 光源远平面控制 ----------
				gui.add(params, 'lightFar', 1, 10000)
				   .name('光源远平面')
				   .onChange(function (value) {
						// 遍历CSM创建的所有光源
						for (let i = 0; i < csm.lights.length; i++) {
							// 更新每个光源的阴影相机的远裁剪平面
							csm.lights[i].shadow.camera.far = value;
							// 更新阴影相机的投影矩阵
							csm.lights[i].shadow.camera.updateProjectionMatrix();
						}
				   });

				// ==================== CSM辅助器控制面板 ====================
				// 创建一个独立的文件夹来组织辅助器相关的控制项
				const helperFolder = gui.addFolder('CSM辅助器');
				
				// 辅助器可见性控制
				helperFolder.add(csmHelper, 'visible')
				   .name('显示辅助器');
				
				// 视锥体显示控制
				helperFolder.add(csmHelper, 'displayFrustum')
				   .name('显示视锥体')
				   .onChange(function () {
						// 更新辅助器的可见性状态
						csmHelper.updateVisibility();
				   });
				
				// 平面显示控制
				helperFolder.add(csmHelper, 'displayPlanes')
				   .name('显示分割平面')
				   .onChange(function () {
						// 更新辅助器的可见性状态
						csmHelper.updateVisibility();
				   });
				
				// 阴影边界显示控制
				helperFolder.add(csmHelper, 'displayShadowBounds')
				   .name('显示阴影边界')
				   .onChange(function () {
						// 更新辅助器的可见性状态
						csmHelper.updateVisibility();
				   });
				
				// 自动更新开关
				helperFolder.add(params, 'autoUpdateHelper')
				   .name('自动更新');
				
				// 手动更新按钮
				helperFolder.add(params, 'updateHelper')
				   .name('手动更新');
				
				// 默认展开辅助器文件夹
				helperFolder.open();

				// ==================== 窗口大小变化事件处理 ====================
				// 监听浏览器窗口大小变化事件
				window.addEventListener('resize', function () {
					// 更新相机的宽高比为新的窗口宽高比
					camera.aspect = window.innerWidth / window.innerHeight;
					
					// 更新相机的投影矩阵
					// 宽高比变化后必须调用此方法
					camera.updateProjectionMatrix();

					// 更新正交相机的参数
					// 确保正交相机也适应新的窗口尺寸
					updateOrthoCamera();
					
					// 更新CSM的视锥体分割
					// 窗口大小变化会影响视锥体形状
					csm.updateFrustums();

					// 更新渲染器的尺寸为新的窗口尺寸
					// 这确保渲染填满整个窗口
					renderer.setSize(window.innerWidth, window.innerHeight);
				});
			}

			/**
			 * 动画循环函数
			 * 这个函数在每一帧都会被调用（通常是每秒60次）
			 * 负责更新场景状态和重新渲染
			 */
			function animate() {
				// ---------- 更新相机矩阵 ----------
				// 更新相机的世界矩阵
				// 这是计算物体在屏幕中位置所必需的
				camera.updateMatrixWorld();

				// ---------- 更新CSM系统 ----------
				// 更新级联阴影映射系统
				// 这会重新计算阴影贴图、更新光源位置等
				csm.update();

				// ---------- 更新轨道控制器 ----------
				// 处理用户输入（鼠标、触摸）并更新相机位置
				controls.update();

				// ---------- 根据相机模式选择渲染路径 ----------
				if (params.orthographic) {
					// 使用正交相机的渲染路径
					
					// 更新正交相机参数
					// 确保正交相机与透视相机同步
					updateOrthoCamera();
					
					// 更新CSM的视锥体分割
					// 正交相机有不同的视锥体，需要重新计算
					csm.updateFrustums();

					// 如果启用了自动更新辅助器
					// 则在每一帧更新CSM辅助器的显示
					if (params.autoUpdateHelper) {
						csmHelper.update();
					}

					// 使用正交相机渲染整个场景
					// 参数：要渲染的场景、使用的相机
					renderer.render(scene, orthoCamera);
				} else {
					// 使用透视相机的渲染路径
					
					// 如果启用了自动更新辅助器
					// 则在每一帧更新CSM辅助器的显示
					if (params.autoUpdateHelper) {
						csmHelper.update();
					}

					// 使用透视相机渲染整个场景
					renderer.render(scene, camera);
				}
			}
		</script>
	</body>
</html>