<!-- Three.js WebGPU VSM阴影示例 - 功能描述与技术要点
一、项目功能概述
1. 核心功能
交互式3D场景演示：展示了一个完整的3D虚拟环境，包含复杂几何体、多种光源和阴影效果

VSM阴影技术展示：专门演示Variance Shadow Mapping（方差阴影映射）这一先进阴影技术

实时参数调节：通过GUI控制面板实时调整阴影参数，观察效果变化

动画系统：提供了可控制的动画效果，展示动态光影变化

2. 视觉元素
主要模型：旋转的圆环结（Torus Knot）作为焦点对象

场景布局：四根柱子支撑结构，平坦地面作为基础

光源系统：红色聚光灯 + 蓝色平行光，双光源混合照明

视觉效果：深蓝色背景、雾效增强深度感、高质量阴影

3. 用户交互
相机控制：鼠标拖拽旋转视角、滚轮缩放、右键平移

参数调节：实时调整阴影模糊度、采样质量

动画控制：一键启停所有动画效果

二、主要技术要点
1. WebGPU渲染技术
javascript
// 使用Three.js的WebGPU后端
renderer = new THREE.WebGPURenderer({ antialias: true });
下一代图形API：替代WebGL，提供更现代的图形编程接口

性能优势：更好的多线程支持，更低的CPU开销

高级特性：支持计算着色器、更灵活的渲染管线

跨平台：在支持WebGPU的浏览器中统一运行

2. VSM阴影映射技术（核心技术）
javascript
renderer.shadowMap.type = THREE.VSMShadowMap;
VSM工作原理：
传统阴影贴图问题：

存储单深度值，导致硬边缘和阴影痤疮

需要复杂的bias调节

VSM解决方案：

存储两个值：深度 + 深度的平方

计算方差：Var = E(X²) - E(X)²

切比雪夫不等式：估计遮挡概率

技术优势：

柔化阴影：天然支持阴影边缘模糊

减少痤疮：更好的数值稳定性

性能优化：可在GPU上高效实现模糊

3. 阴影参数系统
javascript
// 可调节参数
spotLight.shadow.radius = 4;        // 模糊半径
spotLight.shadow.blurSamples = 8;   // 采样数
关键技术参数：
参数	作用	影响效果
radius	阴影模糊半径	值越大阴影越模糊，边缘越柔和
blurSamples	模糊采样数	值越高阴影质量越好，性能消耗越大
bias	阴影偏移	解决自阴影问题，防止阴影痤疮
mapSize	阴影贴图分辨率	决定阴影细节精度
4. 光源系统设计
a) 聚光灯（Spot Light）
javascript
spotLight = new THREE.SpotLight(0xff8888, 400);
spotLight.angle = Math.PI / 5;      // 36度锥角
spotLight.penumbra = 0.3;          // 30%边缘柔化
特性：方向性光源，有明确照射范围

阴影相机：使用透视投影，符合光的实际传播

b) 平行光（Directional Light）
javascript
dirLight = new THREE.DirectionalLight(0x8888ff, 3);
特性：模拟太阳光，所有光线平行

阴影相机：使用正交投影，适合大面积场景

5. 材质与渲染系统
javascript
const material = new THREE.MeshPhongMaterial({
    color: 0x999999,
    shininess: 0,
    specular: 0x222222
});
Phong材质：支持镜面高光的经典材质模型

材质优化：禁用高光（shininess: 0）聚焦阴影效果展示

雾效系统：增强场景深度感和氛围

6. 动画与交互系统
a) 动画控制器
javascript
const delta = clock.getDelta();  // 帧率无关的时间增量
torusKnot.rotation.y += 0.5 * delta;
Clock系统：确保动画速度不受帧率影响

复合动画：模型旋转 + 光源运动组合效果

b) 轨道控制器（OrbitControls）
三轴控制：旋转、缩放、平移完整支持

目标点锁定：围绕指定点旋转视角

平滑插值：提供自然的相机运动

7. GUI调试系统
javascript
const gui = renderer.inspector.createParameters('设置');
实时反馈：参数修改立即反映到渲染效果

分组管理：相关参数组织在文件夹中

范围控制：滑块限制参数的合理范围

8. 响应式设计
javascript
window.addEventListener('resize', onWindowResize);
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
}
自适应布局：自动适应浏览器窗口大小变化

动态宽高比：相机投影矩阵实时更新

像素比适配：支持高DPI显示屏

三、技术架构特点
1. 模块化设计
ES6模块系统：清晰的依赖管理

职责分离：场景初始化、渲染设置、动画逻辑分离

配置驱动：所有可调参数集中管理

2. 性能优化策略
阴影贴图尺寸优化：根据光源重要性分配不同分辨率

采样数可控：平衡质量和性能

相机裁剪优化：只渲染必要的区域

对象复用：使用clone()减少内存占用

3. 可扩展性设计
GUI系统：方便添加新的可调参数

模块化代码：易于添加新功能或修改现有功能

配置对象：集中管理所有设置，便于维护

四、学习价值
1. 现代Web图形编程
WebGPU API的实际应用

现代阴影技术的完整实现

3D图形学核心概念实践

2. 实时渲染技术
阴影算法的实现与优化

光照模型的应用

性能优化技巧

3. 交互设计模式
用户界面与3D场景的交互

实时参数反馈系统

相机控制系统设计

4. 代码架构
大型3D应用的组织结构

模块化设计原则

配置管理与状态控制 -->


<!DOCTYPE html>
<!-- HTML文档声明，指定文档类型为HTML5 -->
<html lang="en">
	<head>
		<!-- 
			文档头部开始
			lang="en" 表示文档语言为英语
		-->
		
		<!-- 页面标题：显示在浏览器标签页上的文字 -->
		<title>Three.js WebGPU - VSM阴影效果示例</title>
		
		<!-- 
			字符编码设置
			charset="utf-8" 指定文档使用UTF-8编码，支持多国语言字符
		-->
		<meta charset="utf-8">
		
		<!-- 
			视口（Viewport）设置 - 移动端网页适配的关键
			width=device-width: 视口宽度等于设备宽度
			user-scalable=no: 禁止用户手动缩放页面
			minimum-scale=1.0: 最小缩放比例为100%
			maximum-scale=1.0: 最大缩放比例为100%
			这些设置确保页面在不同设备上有一致的显示效果
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		
		<!-- 
			外部CSS样式表链接
			type="text/css": 指定链接的文件类型为CSS
			rel="stylesheet": 定义当前文档与链接文件的关系为样式表
			href="example.css": 指定样式表文件路径
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<!-- 文档头部结束 -->

	<body>
		<!-- 
			页面主体内容开始
			包含所有可见的页面元素
		-->

		<!-- 
			ID为"info"的信息显示区域
			用于展示页面标题、链接和说明信息
		-->
		<div id="info">
			<!-- 
				Three.js官方网站链接
				target="_blank": 在新标签页中打开链接
				rel="noopener": 安全设置，防止新页面访问原页面的window对象
				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>VSM阴影效果演示</span>
			</div>

			<!-- 
				副标题区域，显示示例的详细信息和作者
				<small>标签表示小字号文本
			-->
			<small>
				<!-- 示例说明 -->
				VSM阴影技术示例 作者：
				<!-- 作者GitHub链接 -->
				<a href="https://github.com/supereggbert">Paul Brunt</a>
			</small>
		</div>
		<!-- 信息区域结束 -->

		<!-- 
			导入映射（Import Maps）配置
			现代JavaScript模块系统的配置部分
			允许浏览器识别和重定向模块导入语句
		-->
		<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核心库的所有导出内容
			// 使用import * as语法将所有导出内容打包到THREE对象中
			import * as THREE from 'three/webgpu';

			// 从Three.js附加组件中导入调试检查器（Inspector）
			// Inspector用于创建图形用户界面（GUI），方便调试和参数调节
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 从Three.js附加组件中导入轨道控制器（OrbitControls）
			// 轨道控制器允许用户通过鼠标拖拽、滚轮缩放来操控3D场景中的相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ============= 全局变量声明部分 =============
			
			// 场景核心对象变量声明
			let camera,     // 相机对象 - 决定观察3D场景的视角
				scene,      // 场景对象 - 包含所有3D模型、光源等元素的容器
				renderer,   // 渲染器对象 - 负责将3D场景渲染到2D屏幕上
				clock;      // 时钟对象 - 用于精确的时间管理和动画帧率控制

			// 光源对象变量声明
			let dirLight,   // 平行光（Directional Light）对象 - 模拟太阳光等远距离光源
				spotLight;  // 聚光灯（Spot Light）对象 - 模拟手电筒等有方向性的光源

			// 3D模型和组对象变量声明
			let torusKnot,  // 圆环结（Torus Knot）模型 - 主要的展示对象
				dirGroup;   // 平行光组 - 将平行光放入组中便于整体控制和动画

			// 配置对象 - 存储用户可调节的所有参数
			// 这些值将在GUI控制面板中显示并可实时修改
			const config = {
				spotlightRadius: 4,    // 聚光灯光影模糊半径，值越大阴影越模糊
				spotlightSamples: 8,   // 聚光灯光影采样数，值越高阴影质量越好但性能消耗越大
				dirlightRadius: 4,     // 平行光阴影模糊半径
				dirlightSamples: 8,    // 平行光阴影采样数
				animate: true          // 动画开关，控制场景中所有动画效果的启停
			};

			// ============= 程序初始化 =============
			
			// 调用初始化函数，启动整个3D应用程序
			init();

			/**
			 * 主初始化函数
			 * 这是整个程序的入口点，按顺序调用各个初始化函数
			 * 负责设置场景、渲染器、GUI控制和事件监听
			 */
			function init() {

				// 第一步：初始化3D场景，创建所有3D对象、光源和材质
				initScene();
				
				// 第二步：初始化其他组件，包括渲染器、控制器和时钟
				initMisc();

				// ============= GUI控制面板初始化 =============
				
				// 创建调试检查器的参数面板，标题为"Settings"
				// 这个面板将显示在页面上，允许用户实时调节参数
				const gui = renderer.inspector.createParameters('设置');

				// 创建聚光灯控制文件夹
				// 文件夹可以将相关参数分组显示，提高GUI的组织性
				const spotlightFolder = gui.addFolder('聚光灯设置');
				
				// 添加聚光灯阴影半径控制滑块
				spotlightFolder.add(config, 'spotlightRadius', 0, 25) // 参数名，最小值，最大值
					.name('阴影模糊半径') // 在GUI中显示的名称
					.onChange(function (value) {
						// 当滑块值改变时的回调函数
						spotLight.shadow.radius = value; // 更新聚光灯的阴影模糊半径
					});

				// 添加聚光灯阴影采样数控制滑块
				spotlightFolder.add(config, 'spotlightSamples', 1, 25, 1) // 第三个参数1表示步长
					.name('阴影采样数')
					.onChange(function (value) {
						spotLight.shadow.blurSamples = value; // 更新聚光灯光影的采样数
					});

				// 创建平行光控制文件夹
				const dirlightFolder = gui.addFolder('平行光设置');
				
				// 添加平行光阴影半径控制滑块
				dirlightFolder.add(config, 'dirlightRadius', 0, 25)
					.name('阴影模糊半径')
					.onChange(function (value) {
						dirLight.shadow.radius = value; // 更新平行光的阴影模糊半径
					});

				// 添加平行光阴影采样数控制滑块
				dirlightFolder.add(config, 'dirlightSamples', 1, 25, 1)
					.name('阴影采样数')
					.onChange(function (value) {
						dirLight.shadow.blurSamples = value; // 更新平行光阴影的采样数
					});

				// 添加动画开关复选框
				// 这是一个简单的复选框，用于启用或禁用所有动画
				gui.add(config, 'animate').name('启用动画');

				// ============= DOM操作和事件监听 =============
				
				// 将渲染器的canvas元素（3D渲染区域）添加到页面body中
				// renderer.domElement是一个<canvas>元素，所有3D内容都渲染在这里面
				document.body.appendChild(renderer.domElement);
				
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，确保3D场景正确适配新的窗口尺寸
				window.addEventListener('resize', onWindowResize);

			}

			/**
			 * 初始化3D场景函数
			 * 创建和配置所有3D对象：相机、光源、几何体、材质等
			 * 这是场景搭建的核心部分
			 */
			function initScene() {

				// ============= 相机初始化 =============
				
				/*
				创建透视投影相机（PerspectiveCamera）
				参数说明：
				45 - 视野角度（Field of View），单位是度，类似人眼的视角范围
				window.innerWidth / window.innerHeight - 宽高比，根据窗口大小动态计算
				1 - 近裁剪面距离，距离相机小于此值的物体不会被渲染
				1000 - 远裁剪面距离，距离相机大于此值的物体不会被渲染
				
				透视相机模拟人眼观察世界的方式，近大远小，适合大多数3D场景
				*/
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 1, 1000);
				
				// 设置相机初始位置 (x, y, z)
				// x: 水平方向，y: 垂直方向，z: 深度方向
				camera.position.set(0, 10, 30);

				// ============= 场景初始化 =============
				
				// 创建场景对象，它是所有3D元素的容器
				scene = new THREE.Scene();
				
				// 设置场景背景颜色，使用十六进制颜色值
				// 0x222244 表示深蓝色背景，营造夜空效果
				scene.background = new THREE.Color(0x222244);
				
				/*
				添加雾效（Fog）
				参数说明：
				0x222244 - 雾的颜色，通常与背景色相同以实现自然过渡
				50 - 雾开始生效的距离（从相机位置算起）
				100 - 物体完全被雾遮盖的距离
				
				雾效可以增强场景的深度感和氛围，同时优化性能（远处的物体会被雾遮盖）
				*/
				scene.fog = new THREE.Fog(0x222244, 50, 100);

				// ============= 光源系统初始化 =============
				// 光源是3D场景照明的关键，决定了物体的明暗、阴影和颜色

				// 1. 环境光（Ambient Light）
				// 环境光提供均匀的全局照明，没有方向性，不会产生阴影
				// 参数：颜色值（0x444444表示中等灰色）
				scene.add(new THREE.AmbientLight(0x444444));

				// 2. 聚光灯（Spot Light）设置
				// 聚光灯模拟有明确方向、有锥形照射范围的光源，如手电筒、舞台灯
				spotLight = new THREE.SpotLight(0xff8888, 400);  // 参数：颜色(红色调)，强度
				spotLight.angle = Math.PI / 5;                    // 照射锥角，单位是弧度，这里约36度
				spotLight.penumbra = 0.3;                         // 半影系数，控制光照边缘的柔和度(0-1)
				spotLight.position.set(8, 10, 5);                 // 光源在3D空间中的位置
				spotLight.castShadow = true;                      // 启用阴影投射，让聚光灯产生阴影
				
				// 阴影相机设置（聚光灯使用透视投影阴影相机）
				spotLight.shadow.camera.near = 8;                // 阴影相机近裁剪面
				spotLight.shadow.camera.far = 200;               // 阴影相机远裁剪面
				spotLight.shadow.mapSize.width = 256;            // 阴影贴图宽度（像素），影响阴影质量
				spotLight.shadow.mapSize.height = 256;           // 阴影贴图高度（像素）
				spotLight.shadow.bias = -0.002;                  // 阴影偏移，解决自阴影（阴影痤疮）问题
				spotLight.shadow.radius = 4;                     // 阴影模糊半径，VSM阴影特有的模糊控制
				
				// 将聚光灯添加到场景中
				scene.add(spotLight);

				// 3. 平行光（Directional Light）设置
				// 平行光模拟无限远的光源（如太阳），所有光线平行照射
				dirLight = new THREE.DirectionalLight(0x8888ff, 3);  // 参数：颜色(蓝色调)，强度
				dirLight.position.set(3, 12, 17);                    // 光源位置（方向由位置和目标点决定）
				dirLight.castShadow = true;                          // 启用阴影投射
				
				// 阴影相机设置（平行光使用正交投影阴影相机）
				dirLight.shadow.camera.near = 0.1;                  // 近裁剪面，很接近0以包含近距离物体
				dirLight.shadow.camera.far = 500;                   // 远裁剪面
				
				// 设置正交相机的可视范围（长方体区域）
				// 只有在这个区域内的物体才会被渲染到阴影贴图中
				dirLight.shadow.camera.right = 17;     // 右侧边界
				dirLight.shadow.camera.left = -17;     // 左侧边界
				dirLight.shadow.camera.top = 17;       // 顶部边界
				dirLight.shadow.camera.bottom = -17;   // 底部边界
				
				dirLight.shadow.mapSize.width = 512;   // 阴影贴图尺寸，比聚光灯大（平行光通常需要更高质量）
				dirLight.shadow.mapSize.height = 512;
				dirLight.shadow.radius = 4;            // 阴影模糊半径
				dirLight.shadow.bias = -0.0005;        // 阴影偏移（值很小，因为平行光阴影问题不同）

				// 创建组（Group）来包含平行光
				// 组可以将多个对象作为一个整体进行操作（如旋转、移动）
				dirGroup = new THREE.Group();
				dirGroup.add(dirLight);  // 将平行光添加到组中
				scene.add(dirGroup);     // 将组添加到场景中

				// ============= 几何体（3D模型）初始化 =============
				// 创建和配置各种3D模型，包括主展示对象和场景装饰

				// 1. 创建圆环结（Torus Knot）几何体
				// 圆环结是一种复杂的几何形状，由两个圆环交织而成，常用于展示复杂的光影效果
				// 参数：主半径，管道半径，管道的分段数，圆环的分段数
				const geometry = new THREE.TorusKnotGeometry(25, 8, 75, 20);
				
				// 创建Phong材质
				// Phong材质支持镜面高光，可以创建光滑的表面效果
				const material = new THREE.MeshPhongMaterial({
					color: 0x999999,      // 基础漫反射颜色（浅灰色）
					shininess: 0,         // 高光亮度（0-128），0表示无镜面高光
					specular: 0x222222    // 高光颜色（深灰色）
				});

				// 创建圆环结网格对象（Mesh）
				// 网格 = 几何体 + 材质，是实际可渲染的3D对象
				torusKnot = new THREE.Mesh(geometry, material);
				torusKnot.scale.multiplyScalar(1 / 18);  // 缩放模型，使其大小适合场景
				torusKnot.position.y = 3;                // 设置垂直位置
				torusKnot.castShadow = true;             // 该模型可以投射阴影
				torusKnot.receiveShadow = true;          // 该模型可以接收其他物体投射的阴影
				scene.add(torusKnot);                    // 添加到场景

				// 2. 创建柱子几何体（圆柱体）
				// 用于场景的四根装饰柱子
				// 参数：顶部半径，底部半径，高度，径向分段数
				const cylinderGeometry = new THREE.CylinderGeometry(0.75, 0.75, 7, 32);

				// 创建第一根柱子
				const pillar1 = new THREE.Mesh(cylinderGeometry, material);
				pillar1.position.set(8, 3.5, 8);  // 设置位置（场景右上角）
				pillar1.castShadow = true;        // 投射阴影
				pillar1.receiveShadow = true;     // 接收阴影

				// 使用clone()方法快速创建其他三根柱子
				// clone()会复制几何体和材质，但创建新的网格实例
				const pillar2 = pillar1.clone();
				pillar2.position.set(8, 3.5, -8);  // 场景右下角
				
				const pillar3 = pillar1.clone();
				pillar3.position.set(-8, 3.5, 8);  // 场景左上角
				
				const pillar4 = pillar1.clone();
				pillar4.position.set(-8, 3.5, -8); // 场景左下角

				// 将所有柱子添加到场景中
				scene.add(pillar1);
				scene.add(pillar2);
				scene.add(pillar3);
				scene.add(pillar4);

				// 3. 创建地面几何体
				// 地面是场景的基础，所有物体都放置在地面上
				const planeGeometry = new THREE.PlaneGeometry(200, 200);  // 平面几何体，宽度和高度
				
				// 地面材质，使用与柱子相同的Phong材质但参数略有不同
				const planeMaterial = new THREE.MeshPhongMaterial({
					color: 0x999999,      // 基础颜色
					shininess: 0,         // 无高光（地面通常不是光滑的）
					specular: 0x111111    // 轻微的高光反射
				});

				// 创建地面网格
				const ground = new THREE.Mesh(planeGeometry, planeMaterial);
				ground.rotation.x = -Math.PI / 2;  // 绕X轴旋转-90度，使平面水平（默认平面是垂直的）
				ground.scale.multiplyScalar(3);    // 放大地面，确保覆盖整个视野
				ground.castShadow = true;          // 地面可以投射阴影（虽然通常不需要，但保留选项）
				ground.receiveShadow = true;       // 地面必须接收阴影，否则看不到物体在地面上的影子
				scene.add(ground);

			}

			/**
			 * 初始化其他辅助组件
			 * 包括渲染器、控制器、时钟等非场景对象的初始化
			 */
			function initMisc() {

				// ============= WebGPU渲染器初始化 =============
				/*
				创建WebGPURenderer实例
				这是Three.js的WebGPU后端渲染器，使用现代图形API
				相比传统的WebGLRenderer，WebGPU提供更好的性能和更多高级特性
				参数：{ antialias: true } 启用抗锯齿，使边缘更平滑
				*/
				renderer = new THREE.WebGPURenderer({ antialias: true });
				
				// 设置设备像素比，确保在高DPI屏幕（如Retina显示屏）上清晰显示
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器的输出尺寸为整个浏览器窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// animate函数将在每一帧被调用，实现平滑动画
				renderer.setAnimationLoop(animate);
				
				// 将Inspector实例附加到渲染器上，方便通过GUI控制
				renderer.inspector = new Inspector();
				
				// 启用阴影贴图系统
				renderer.shadowMap.enabled = true;
				
				/*
				设置阴影贴图类型为VSM（Variance Shadow Mapping）
				这是本示例的核心技术
				相比传统的阴影贴图，VSM提供：
				1. 更柔和的阴影边缘
				2. 支持动态模糊
				3. 减少阴影痤疮问题
				4. 更好的性能（在某些情况下）
				*/
				renderer.shadowMap.type = THREE.VSMShadowMap;

				// ============= 轨道控制器初始化 =============
				/*
				创建OrbitControls实例
				参数：
				camera - 要控制的相机对象
				renderer.domElement - 事件监听的DOM元素（canvas）
				
				功能：允许用户通过以下方式控制相机：
				- 左键拖拽：旋转视角
				- 右键拖拽/滚轮：缩放
				- 中键拖拽：平移
				*/
				const controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置控制器的目标点（相机围绕旋转的中心点）
				controls.target.set(0, 2, 0);
				
				// 更新控制器内部状态
				controls.update();

				// ============= 时钟初始化 =============
				/*
				创建Clock实例
				用于精确的时间管理，确保动画在不同帧率下保持一致性
				主要用途：
				1. 计算帧间时间差（delta time）
				2. 实现与帧率无关的动画
				3. 精确控制动画速度
				*/
				clock = new THREE.Clock();

			}

			/**
			 * 窗口大小变化事件处理函数
			 * 当用户调整浏览器窗口大小时自动调用
			 * 确保3D场景正确适配新的窗口尺寸
			 */
			function onWindowResize() {

				// 更新相机的宽高比
				// 窗口大小改变后，需要重新计算宽高比以保持正确透视
				camera.aspect = window.innerWidth / window.innerHeight;
				
				/*
				更新相机的投影矩阵
				当相机参数（如aspect）改变后，必须调用此方法
				重新计算内部投影矩阵，否则渲染会出错
				*/
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸，匹配新的窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);

			}

			/**
			 * 动画循环函数
			 * 这是整个3D应用程序的核心循环，每帧调用一次
			 * 负责更新动画状态和渲染场景
			 * 
			 * @param {number} time - 当前时间戳（毫秒）
			 * 由requestAnimationFrame或setAnimationLoop自动传入
			 * 表示从页面加载开始经过的时间
			 */
			function animate(time) {

				/*
				获取时间增量（delta time）
				clock.getDelta()返回自上一次调用此方法以来经过的时间（秒）
				这是实现与帧率无关动画的关键
				无论用户设备是60fps还是144fps，动画速度都保持一致
				*/
				const delta = clock.getDelta();

				// 检查动画开关状态
				// 用户可以通过GUI控制是否播放动画
				if (config.animate === true) {

					// ============= 圆环结旋转动画 =============
					// 使圆环结在三个轴上以不同速度旋转，创造复杂的运动效果
					torusKnot.rotation.x += 0.25 * delta;  // X轴：每秒0.25弧度
					torusKnot.rotation.y += 0.5 * delta;   // Y轴：每秒0.5弧度（更快）
					torusKnot.rotation.z += 1 * delta;     // Z轴：每秒1弧度（最快）

					// ============= 平行光组旋转动画 =============
					// 使包含平行光的组绕Y轴旋转
					// 这样平行光就会围绕场景中心旋转，动态改变阴影方向
					dirGroup.rotation.y += 0.7 * delta;  // 每秒0.7弧度
					
					// ============= 平行光Z轴位置动画 =============
					// 使用正弦函数使平行光在Z轴上做周期性往复运动
					// time * 0.001：将毫秒转换为秒，并降低频率
					// Math.sin()：正弦函数，产生-1到1之间的平滑变化
					// * 5：振幅，控制运动范围
					// + 17：基准位置
					dirLight.position.z = 17 + Math.sin(time * 0.001) * 5;

				}

				// ============= 场景渲染 =============
				/*
				调用渲染器的render方法，将3D场景绘制到2D屏幕上
				参数：
				scene - 要渲染的场景对象（包含所有3D元素）
				camera - 观察场景的相机（决定视角）
				
					渲染过程包括：
					1. 清除上一帧的画面
					2. 计算相机视图矩阵和投影矩阵
					3. 遍历场景中的所有对象
					4. 应用材质、光照和阴影
					5. 执行顶点着色器和片段着色器
					6. 输出到canvas元素
				*/
				renderer.render(scene, camera);

			}

		</script>
		<!-- 主JavaScript模块结束 -->
	</body>
	<!-- 文档主体结束 -->
</html>
<!-- HTML文档结束 -->