<!-- Three.js WebGPU 级联阴影映射演示代码分析
🎯 整体功能概述
这是一个基于Three.js和WebGPU的实时级联阴影映射（Cascaded Shadow Maps, CSM） 技术演示。它展示了如何在大规模3D场景中实现高质量的动态阴影效果，特别适用于开放世界游戏、建筑可视化等需要远距离阴影的应用场景。

🏗️ 主要技术架构
1. 渲染引擎
Three.js WebGPU渲染器：使用下一代WebGPU图形API替代传统的WebGL

双相机系统：支持透视相机（模拟人眼）和正交相机（CAD视图）切换

实时交互：集成OrbitControls轨道控制器，支持鼠标拖拽、缩放、旋转

2. 核心阴影技术 - 级联阴影映射（CSM）
问题背景：传统阴影贴图在远距离时会出现严重的分辨率不足问题（阴影锯齿、模糊）

CSM解决方案：

text
相机视锥体（Frustum）
├── 第1级联：近处区域（0-100单位）- 使用高分辨率阴影贴图
├── 第2级联：中距离区域（100-400单位）- 中等分辨率
├── 第3级联：中远距离区域（400-800单位）- 较低分辨率
└── 第4级联：最远区域（800-2000单位）- 最低分辨率
三种分割算法：

uniform（均匀分割）：简单平均分割，性能好但质量一般

logarithmic（对数分割）：近处密集，远处稀疏，符合视觉特性

practical（实用分割）：平衡方案，结合前两者优点

3. 场景构成
text
场景层次结构：
├── 环境光（AmbientLight）- 基础均匀照明
├── 补充定向光（蓝色调）- 增强氛围
├── CSM主定向光（白色）- 产生阴影的主要光源
├── 巨大地板（10000×10000单位）- 接收阴影
└── 80个随机高度立方体（2排）- 投射和接收阴影
🔧 关键技术实现细节
1. WebGPU配置
javascript
// 使用WebGPU渲染器，启用抗锯齿
renderer = new THREE.WebGPURenderer({ antialias: true });

// 设置PCF软阴影（边缘柔和）
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
2. CSM系统配置
javascript
csm = new CSMShadowNode(csmDirectionalLight, {
    cascades: 4,           // 4级级联
    maxFar: params.maxFar, // 阴影最大距离
    mode: params.mode      // 分割算法
});

// 每级级联独立配置
csmDirectionalLight.shadow.mapSize.width = 2048;  // 每级阴影贴图分辨率
csmDirectionalLight.shadow.bias = -0.001;         // 阴影偏移，消除自阴影伪影
3. 动态更新机制
javascript
// 每帧更新CSM
function animate() {
    csm.updateFrustums();  // 根据相机位置重新计算级联分割
    renderer.render(scene, camera);
}
4. 性能优化特性
视锥体裁剪：只渲染相机可见范围内的阴影

自适应分辨率：近处高分辨率，远处低分辨率

阴影边界优化：自动调整阴影相机范围，减少不必要的渲染

🎮 交互与调试功能
1. 实时参数调整（通过GUI）
text
主要可调参数：
├── 相机模式：透视/正交切换
├── 阴影质量：最大距离、分割模式
├── 光源控制：方向(X,Y,Z)、边界裕量
├── 阴影相机：近/远裁剪面
└── 调试显示：视锥体、分割平面、阴影边界
2. CSM调试辅助器
可视化显示：用不同颜色显示各级级联区域

分割平面：显示视锥体如何被分割

阴影边界：显示每级阴影的有效范围

实时更新：调整参数立即看到效果

🌟 技术亮点
1. 高质量的远距离阴影
解决了传统阴影贴图的"透视锯齿"问题

在保持性能的同时提供一致的阴影质量

2. 自适应分割算法
根据场景深度动态调整分割比例

三种算法适应不同应用需求

3. 完整的调试工具
可视化理解CSM工作原理

实时参数调整和效果预览

4. 响应式设计
自动适应窗口大小变化

保持正确的阴影比例和相机参数

📊 性能特征
内存使用
每级级联：2048×2048 RGBA阴影贴图 ≈ 16MB

4级级联总计：约64MB显存

可根据需要降低分辨率（1024×1024）

渲染开销
每帧渲染4次阴影贴图（每级一次）

根据物体在级联中的位置，可能只渲染部分级联

大量使用视锥体裁剪优化

适用场景
✅ 大型开放世界游戏

✅ 建筑与城市规划可视化

✅ 飞行/驾驶模拟器

✅ 需要高质量动态阴影的3D应用

🔍 实际效果展示
通过调整GUI参数，用户可以观察到：

光源方向变化：阴影角度和长度实时变化

分割模式对比：三种算法的阴影质量差异

距离调整：最大阴影距离对性能和质量的影响

调试视图：理解CSM的内部工作原理 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：显示页面主要内容 -->
		<title>Three.js WebGPU - 级联阴影映射演示</title>
		<!-- 字符编码设置：使用UTF-8支持多语言字符 -->
		<meta charset="utf-8">
		<!-- 视口设置：确保页面在不同设备上正确显示 -->
		<!-- width=device-width：宽度与设备宽度一致 -->
		<!-- user-scalable=no：禁止用户缩放（为3D应用保持固定比例） -->
		<!-- minimum-scale=1.0, maximum-scale=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>

		<!-- 主要3D场景容器：Three.js渲染器会将Canvas绘制在此div内 -->
		<div id="container"></div>

		<!-- 页面信息区域：显示标题、链接和作者信息 -->
		<div id="info">
			<!-- Three.js官方Logo链接 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link" title="访问Three.js官方网站"></a>

			<!-- 标题包装器：包含主标题和副标题 -->
			<div class="title-wrapper">
				<!-- 主标题链接：点击跳转到Three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：显示当前演示的具体技术 -->
				<span>级联阴影映射技术演示</span>
			</div>

			<!-- 作者和版权信息区域 -->
			<small>
				<!-- 作者信息 -->
				由 <a href="https://github.com/strandedkitty/" target="_blank" rel="noopener">StrandedKitty</a> 开发
				<!-- 原始仓库链接 -->
				（<a href="https://github.com/strandedkitty/three-csm" target="_blank" rel="noopener">查看源代码仓库</a>）。
				<!-- 中文翻译/修改说明 -->
				<br>本页面已进行中文本地化处理。
			</small>
		</div>

		<!-- 导入映射配置：定义JavaScript模块的别名和路径 -->
		<!-- 允许使用简短名称导入Three.js模块 -->
		<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渲染器主模块
			// WebGPU是新一代图形API，替代WebGL，提供更好的性能和功能
			import * as THREE from 'three/webgpu';

			// 导入轨道控制器：允许用户用鼠标拖拽、缩放、旋转相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入调试检查器：提供GUI界面，可以实时调整场景参数
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入CSM（级联阴影映射）相关模块
			// CSMShadowNode：级联阴影映射的核心实现
			// CSMHelper：CSM的调试辅助工具，可视化显示阴影分割
			import { CSMShadowNode } from 'three/addons/csm/CSMShadowNode.js';
			import { CSMHelper } from 'three/addons/csm/CSMHelper.js';

			// ==================== 全局变量声明 ====================
			// 这些变量将在整个应用中使用
			let renderer;       // WebGPU渲染器实例
			let scene;          // 3D场景对象，包含所有3D元素
			let camera;         // 透视相机：模拟人眼视角
			let orthoCamera;    // 正交相机：无透视效果，常用于CAD等应用
			let controls;       // 轨道控制器实例
			let csm;            // CSM（级联阴影映射）实例
			let csmHelper;      // CSM调试辅助器实例
			let csmDirectionalLight; // 用于CSM的定向光源

			// ==================== 参数配置对象 ====================
			// 这些参数可以通过GUI界面实时调整
			const params = {
				orthographic: false,      // 是否使用正交相机模式（true:正交, false:透视）
				fade: false,              // 是否启用阴影淡出过渡效果（当前代码中已注释，未完全实现）
				shadows: true,            // 是否启用阴影渲染
				maxFar: 1000,             // 阴影渲染的最大距离（单位：三维单位）
				mode: 'practical',        // 视锥体分割模式：可选'uniform'（均匀）、'logarithmic'（对数）、'practical'（实用）
				lightX: -1,               // 光源方向的X分量（归一化向量）
				lightY: -1,               // 光源方向的Y分量（归一化向量）
				lightZ: -1,               // 光源方向的Z分量（归一化向量）
				margin: 100,              // 光源边界裕量：控制阴影相机范围的大小
				shadowNear: 1,            // 阴影相机的近裁剪平面距离
				shadowFar: 2000,          // 阴影相机的远裁剪平面距离
				autoUpdateHelper: true,   // 是否自动更新CSM调试辅助器（true:每帧更新, false:手动更新）
				updateHelper: function () { // 手动更新CSM调试辅助器的函数
					csmHelper.update();   // 调用辅助器的更新方法
				}
			};

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

			// ==================== 函数定义 ====================

			/**
			 * 更新正交相机的函数
			 * 当切换到正交相机模式时，根据透视相机的参数计算正交相机的参数
			 */
			function updateOrthoCamera() {
				// 计算目标点到相机位置的距离，用于确定正交相机的可视范围
				const size = controls.target.distanceTo(camera.position);
				// 获取透视相机的宽高比（宽度/高度）
				const aspect = camera.aspect;
				
				// 设置正交相机的左右边界
				// 根据距离和宽高比计算，保持与透视相机相似的可视范围
				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);
				
				// 更新正交相机的投影矩阵
				// 在Three.js中，改变相机参数后必须调用此方法
				orthoCamera.updateProjectionMatrix();
			}

			/**
			 * 主初始化函数
			 * 创建所有3D对象、设置场景、配置渲染器、添加事件监听器等
			 */
			function init() {
				// ---------- 场景创建 ----------
				// 创建新的3D场景对象，所有3D元素都将添加到这个场景中
				scene = new THREE.Scene();
				// 设置场景背景颜色（深蓝色调）
				scene.background = new THREE.Color('#454e61');
				
				// ---------- 相机创建 ----------
				// 创建透视相机（模拟人眼视角）
				// 参数：视野角度(FOV)、宽高比、近裁剪面、远裁剪面
				camera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, 0.1, 5000);
				
				// 创建正交相机（无透视变形，物体大小不随距离改变）
				// 初始参数为0，将在updateOrthoCamera函数中设置
				orthoCamera = new THREE.OrthographicCamera();

				// ---------- 渲染器创建 ----------
				// 创建WebGPU渲染器实例
				// antialias: true 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer({ antialias: true });
				// 设置渲染器大小为整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 设置动画循环回调函数，每帧自动调用animate函数
				renderer.setAnimationLoop(animate);

				// ---------- 阴影配置 ----------
				// 启用渲染器的阴影映射功能
				renderer.shadowMap.enabled = params.shadows;
				// 设置阴影类型为PCF软阴影（Percentage-Closer Filtering）
				// 这种阴影边缘更柔和，质量更高
				renderer.shadowMap.type = THREE.PCFSoftShadowMap;

				// ---------- 调试工具 ----------
				// 创建调试检查器并附加到渲染器
				renderer.inspector = new Inspector();
				// 将渲染器的Canvas元素添加到页面body中
				document.body.appendChild(renderer.domElement);

				// ---------- 相机控制器 ----------
				// 创建轨道控制器，连接相机和渲染器的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.0为默认强度）
				const ambientLight = new THREE.AmbientLight(0xffffff, 1.5);
				scene.add(ambientLight);

				// 创建额外的定向光（补充照明，增强阴影细节）
				// 深蓝色光，增加场景的氛围感
				const additionalDirectionalLight = new THREE.DirectionalLight(0x000020, 1.5);
				// 设置光源方向并调整位置
				additionalDirectionalLight.position.set(params.lightX, params.lightY, params.lightZ).normalize().multiplyScalar(-200);
				scene.add(additionalDirectionalLight);

				// ---------- CSM主光源 ----------
				// 创建用于CSM的定向光源（白色，强度3.0）
				csmDirectionalLight = new THREE.DirectionalLight(0xffffff, 3.0);

				// 配置光源的阴影属性
				csmDirectionalLight.castShadow = true; // 此光源投射阴影
				csmDirectionalLight.shadow.mapSize.width = 2048;  // 阴影贴图宽度（像素）
				csmDirectionalLight.shadow.mapSize.height = 2048; // 阴影贴图高度（像素）
				csmDirectionalLight.shadow.camera.near = params.shadowNear; // 阴影相机近平面
				csmDirectionalLight.shadow.camera.far = params.shadowFar;   // 阴影相机远平面
				// 设置阴影相机的可视范围（上下左右边界）
				csmDirectionalLight.shadow.camera.top = 1000;
				csmDirectionalLight.shadow.camera.bottom = -1000;
				csmDirectionalLight.shadow.camera.left = -1000;
				csmDirectionalLight.shadow.camera.right = 1000;
				// 设置阴影偏移，减少阴影失真（自阴影伪影）
				csmDirectionalLight.shadow.bias = -0.001;

				// ---------- 创建CSM系统 ----------
				// 创建CSM阴影节点，连接到定向光源
				// 参数：光源对象，配置对象
				csm = new CSMShadowNode(csmDirectionalLight, {
					cascades: 4,           // 使用4级级联（将视锥体分为4个区域）
					maxFar: params.maxFar, // 阴影最大距离
					mode: params.mode      // 分割模式
				});

				// 设置CSM光源的位置（与额外光源方向一致）
				csmDirectionalLight.position.set(params.lightX, params.lightY, params.lightZ).normalize().multiplyScalar(-200);

				// 将CSM节点附加到光源的阴影属性上
				csmDirectionalLight.shadow.shadowNode = csm;

				// 将CSM光源添加到场景
				scene.add(csmDirectionalLight);

				// ---------- CSM调试辅助器 ----------
				// 创建CSM调试辅助器，用于可视化阴影分割
				csmHelper = new CSMHelper(csm);
				csmHelper.visible = false; // 默认不显示
				scene.add(csmHelper);

				// ---------- 创建地板 ----------
				// 创建地板材质（深灰色）
				const floorMaterial = new THREE.MeshPhongMaterial({ color: '#252a34' });

				// 创建地板网格（非常大的平面）
				// PlaneGeometry参数：宽度，高度，宽度分段数，高度分段数
				const floor = new THREE.Mesh(new THREE.PlaneGeometry(10000, 10000, 8, 8), floorMaterial);
				floor.rotation.x = -Math.PI / 2; // 旋转90度，使平面水平（默认平面是垂直的）
				floor.castShadow = true;    // 地板投射阴影（边缘处）
				floor.receiveShadow = true; // 地板接收阴影（显示其他物体的阴影）
				scene.add(floor);

				// ---------- 创建立方体材质 ----------
				// 创建两种颜色的Phong材质（有光泽的材质）
				const material1 = new THREE.MeshPhongMaterial({ color: '#08d9d6' }); // 青色
				const material2 = new THREE.MeshPhongMaterial({ color: '#ff2e63' }); // 粉色

				// ---------- 创建立方体几何体 ----------
				// 创建立方体几何体（默认尺寸为1x1x1，将在后面缩放）
				const geometry = new THREE.BoxGeometry(10, 10, 10);

				// ---------- 生成场景中的物体 ----------
				// 循环创建80个立方体（40对）
				for (let i = 0; i < 40; i++) {
					// 第一排立方体（在Z轴正方向）
					const cube1 = new THREE.Mesh(geometry, i % 2 === 0 ? material1 : material2);
					cube1.castShadow = true;    // 立方体投射阴影
					cube1.receiveShadow = true; // 立方体接收阴影（自身可能被其他物体投射阴影）
					scene.add(cube1);
					// 设置位置：X轴负方向排列，间距25单位
					cube1.position.set(-i * 25, 20, 30);
					// 随机缩放Y轴高度，创建不同高度的立方体
					cube1.scale.y = Math.random() * 2 + 6; // 高度在6-8之间

					// 第二排立方体（在Z轴负方向）
					const cube2 = new THREE.Mesh(geometry, i % 2 === 0 ? material2 : material1);
					cube2.castShadow = true;
					cube2.receiveShadow = true;
					scene.add(cube2);
					cube2.position.set(-i * 25, 20, -30);
					cube2.scale.y = Math.random() * 2 + 6;
				}

				// ==================== GUI调试面板设置 ====================
				// 创建名为"设置"的GUI面板
				const gui = renderer.inspector.createParameters('设置');

				// 添加正交相机切换控件
				gui.add(params, 'orthographic')
				   .name('使用正交相机')
				   .onChange(function (value) {
						// 切换相机时更新CSM使用的相机
						csm.camera = value ? orthoCamera : camera;
						// 更新CSM的视锥体分割
						csm.updateFrustums();
					});

				// 阴影启用/禁用控件
				gui.add(params, 'shadows')
				   .name('启用阴影')
				   .onChange(function (value) {
						csmDirectionalLight.castShadow = value;
					});

				// 最大阴影距离控件
				gui.add(params, 'maxFar', 1, 5000, 1)
				   .name('阴影最大距离')
				   .onChange(function (value) {
						csm.maxFar = value;
						csm.updateFrustums();
					});

				// 视锥体分割模式控件
				gui.add(params, 'mode', ['uniform', 'logarithmic', 'practical'])
				   .name('视锥体分割模式')
				   .onChange(function (value) {
						csm.mode = value;
						csm.updateFrustums();
					});

				// 光源方向X分量控件
				gui.add(params, 'lightX', -1, 1)
				   .name('光源方向 X')
				   .onChange(function () {
						csmDirectionalLight.position.set(params.lightX, params.lightY, params.lightZ).normalize().multiplyScalar(-200);
					});

				// 光源方向Y分量控件
				gui.add(params, 'lightY', -1, 1)
				   .name('光源方向 Y')
				   .onChange(function () {
						csmDirectionalLight.position.set(params.lightX, params.lightY, params.lightZ).normalize().multiplyScalar(-200);
					});

				// 光源方向Z分量控件
				gui.add(params, 'lightZ', -1, 1)
				   .name('光源方向 Z')
				   .onChange(function () {
						csmDirectionalLight.position.set(params.lightX, params.lightY, params.lightZ).normalize().multiplyScalar(-200);
					});

				// 光源边界裕量控件
				gui.add(params, 'margin', 0, 200)
				   .name('光源边界裕量')
				   .onChange(function (value) {
						csm.lightMargin = value;
					});

				// 阴影近平面控件
				gui.add(params, 'shadowNear', 1, 10000)
				   .name('阴影近平面')
				   .onChange(function (value) {
						// 更新所有级联阴影的相机近平面
						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, 'shadowFar', 1, 10000)
				   .name('阴影远平面')
				   .onChange(function (value) {
						// 更新所有级联阴影的相机远平面
						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('手动更新');

				// ==================== 窗口大小变化事件监听 ====================
				window.addEventListener('resize', function () {
					// 更新透视相机的宽高比
					camera.aspect = window.innerWidth / window.innerHeight;
					camera.updateProjectionMatrix(); // 必须调用以应用更改

					// 更新正交相机参数
					updateOrthoCamera();
					// 更新CSM视锥体分割
					csm.updateFrustums();

					// 更新渲染器大小以匹配窗口大小
					renderer.setSize(window.innerWidth, window.innerHeight);
				});
			}

			/**
			 * 动画循环函数
			 * 每帧自动调用，负责更新场景状态并渲染
			 */
			function animate() {
				// 更新相机世界矩阵（确保相机位置/旋转正确）
				camera.updateMatrixWorld();
				// 更新轨道控制器状态
				controls.update();

				// 根据当前相机模式选择渲染流程
				if (params.orthographic) {
					// 正交相机模式
					updateOrthoCamera();      // 更新正交相机参数
					csm.updateFrustums();     // 更新CSM视锥体分割

					// 如果需要，自动更新CSM调试辅助器
					if (params.autoUpdateHelper) {
						csmHelper.update();
					}

					// 使用正交相机渲染场景
					renderer.render(scene, orthoCamera);
				} else {
					// 透视相机模式
					// 如果需要，自动更新CSM调试辅助器
					if (params.autoUpdateHelper) {
						csmHelper.update();
					}

					// 使用透视相机渲染场景
					renderer.render(scene, camera);
				}
			}

		</script>

	</body>
</html>