<!-- 代码功能和技术点分析
一、项目概述
这是一个基于Three.js WebGPU的投影灯效果演示应用，展示了三种不同类型的投影效果：程序化生成的焦散效果、视频投影和纹理投影。应用包含交互式的3D场景，用户可以实时调节各种参数并观察效果变化。

二、核心功能
1. 三种投影模式
程序化焦散效果：使用Worley噪声算法实时生成动态水波纹效果

视频投影：将视频文件作为纹理投射到场景中的物体上

纹理投影：将静态图片作为纹理投射到场景中

2. 交互功能
鼠标拖拽旋转视角（OrbitControls）

滚轮缩放场景

实时参数调节面板（GUI）

自动旋转的投影灯展示

3. 3D场景构成
地面平面（接收阴影）

Lucy雕像模型（投射和接收阴影）

环境光照（HemisphereLight）

主投影灯（ProjectorLight）

三、主要技术点
1. WebGPU渲染器
javascript
renderer = new THREE.WebGPURenderer({ antialias: true });
使用下一代图形API WebGPU替代传统的WebGL

提供更好的性能和更现代的图形功能

支持并行计算和更高效的GPU资源管理

2. TSL着色器语言
javascript
import { Fn, color, mx_worley_noise_float, time } from 'three/tsl';
TSL（Three.js Shader Language）：Three.js的着色器语言系统

允许在JavaScript中以声明式方式编写着色器代码

支持节点式编程，简化复杂着色器的创建

3. 程序化焦散效果
javascript
const causticEffect = Fn(([ projectorUV ]) => {
    const waterLayer0 = mx_worley_noise_float(projectorUV.mul(10).add(time));
    return waterLayer0.mul(color(0x5abcd8)).mul(2);
});
Worley噪声算法：生成细胞状/水波纹状图案

UV坐标变换：缩放（mul）和偏移（add）操作

时间动画：使用time变量实现动态效果

4. 投影灯系统
javascript
projectorLight = new THREE.ProjectorLight(0xffffff, 100);
ProjectorLight：Three.js的投影灯类型

支持颜色节点（colorNode）用于程序化效果

支持纹理投影（map）用于视频/图片投影

可调节参数：角度、半影、衰减、距离等

5. 阴影系统
javascript
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
PCF软阴影：产生边缘柔和的真实阴影

阴影贴图：1024×1024分辨率的高质量阴影

阴影偏移：解决阴影痤疮（shadow acne）问题

动态阴影聚焦：可调节阴影清晰度

6. 色调映射
javascript
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1;
ACES Filmic色调映射：电影工业标准算法

将HDR颜色转换为适合显示的LDR范围

提供更自然的对比度和色彩表现

7. 模型加载系统
javascript
new PLYLoader().load('models/ply/binary/Lucy100k.ply', ...);
PLY格式：多边形文件格式，存储3D模型数据

顶点法线计算：几何体加载后计算法线用于光照

模型缩放和定位：调整模型大小和位置

8. 响应式设计
javascript
window.addEventListener('resize', onWindowResize);
监听窗口大小变化

动态更新相机宽高比

调整渲染器尺寸以匹配窗口

9. 调试界面
javascript
import { Inspector } from 'three/addons/inspector/Inspector.js';
实时参数调节面板

支持颜色选择器、滑块、下拉菜单等控件

即时反馈效果变化

四、关键技术实现细节
1. WebGPU的优势
相比WebGL，提供更接近原生图形API的性能

支持计算着色器，可用于更复杂的GPU计算

更好的多线程支持和资源管理

2. TSL着色器工作流程
text
输入UV坐标 → Worley噪声生成 → 颜色映射 → 亮度调整 → 输出颜色
在GPU上执行，性能高效

无需编写传统GLSL代码，开发更简单

支持实时编辑和预览

3. 投影灯工作原理
使用阴影相机从灯光视角渲染场景

将深度信息存储在阴影贴图中

在主渲染过程中，将像素位置与阴影贴图比较以确定是否在阴影中

支持聚焦参数调整阴影质量

4. 视频纹理处理
javascript
videoTexture = new THREE.VideoTexture(video);
videoTexture.colorSpace = THREE.SRGBColorSpace;
将HTML5 Video元素转换为Three.js纹理

支持色彩空间转换（sRGB）

实时更新纹理帧以实现视频播放效果

5. 动画系统
javascript
projectorLight.position.x = Math.cos(time) * 2.5;
projectorLight.position.z = Math.sin(time) * 2.5;
基于时间的三角函数实现圆周运动

每帧更新位置，60FPS流畅动画

灯光辅助器同步更新

五、性能优化特性
Mipmap控制：对静态纹理禁用Mipmap生成以节省内存

阴影贴图尺寸：平衡质量与性能的1024×1024分辨率

几何体优化：PLY模型已进行适当简化（100k顶点）

着色器优化：使用TSL生成的着色器经过Three.js优化

六、应用场景
教育演示：展示计算机图形学中的投影和光照技术

艺术创作：动态投影艺术作品的创作工具

产品展示：展示投影灯产品的虚拟演示

技术研究：WebGPU和TSL技术的研究案例

七、技术栈总结
技术组件	用途	特点
Three.js WebGPU	3D渲染引擎	下一代图形API支持
TSL	着色器编程	声明式着色器语言
Worley噪声	程序化纹理	水波纹效果生成
ProjectorLight	投影光源	动态投影效果
PLYLoader	模型加载	3D模型导入
OrbitControls	用户交互	相机控制
Inspector	调试界面	实时参数调节 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js WebGPU投影灯演示 -->
		<title>Three.js WebGPU - 投影灯效果演示</title>
		
		<!-- 字符编码设置：UTF-8支持中文和特殊字符 -->
		<meta charset="utf-8">
		
		<!-- 移动端视口设置 -->
		<!-- width=device-width: 视口宽度等于设备宽度 -->
		<!-- user-scalable=no: 禁止用户手动缩放页面 -->
		<!-- minimum-scale=1.0: 最小缩放比例为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样式表 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 页面信息展示区域 -->
		<div id="info">
			<!-- Three.js官方网站链接，点击跳转 -->
			<!-- target="_blank": 在新标签页中打开 -->
			<!-- rel="noopener": 安全设置，防止新页面访问window.opener -->
			<!-- class="logo-link": 样式类，可能包含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>WebGPU投影灯效果</span>
			</div>

			<!-- 详细功能描述 -->
			<small>
				<!-- 描述内容：展示三种投影灯效果 -->
				本示例演示了Three.js WebGPU中的投影灯功能，包含：
				1. 程序化生成的焦散效果（模拟水波纹）
				2. 视频动态投影
				3. 静态纹理投影
				使用鼠标可以旋转视角，右侧面板可调节参数。
			</small>
		</div>

		<!-- ES模块导入映射配置（Import Maps） -->
		<!-- 允许浏览器识别模块路径的映射关系 -->
		<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>

		<!-- 视频元素：用于视频纹理投影 -->
		<!-- 
			属性说明：
			id="video": 用于JavaScript中获取视频元素
			loop: 视频循环播放
			muted: 静音播放（避免自动播放声音被浏览器阻止）
			crossOrigin="anonymous": 跨域资源共享设置，允许加载跨域资源
			playsinline: 在移动端内联播放（不全屏）
			style="display:none": 隐藏视频元素，不显示在页面上
		-->
		<video id="video" loop muted crossOrigin="anonymous" playsinline style="display:none">
			<!-- 提供多种视频格式以兼容不同浏览器 -->
			<!-- Ogg Theora格式（开源视频编码） -->
			<source src="textures/sintel.ogv" type='video/ogg; codecs="theora, vorbis"'>
			<!-- MP4 H.264格式（广泛支持的格式） -->
			<source src="textures/sintel.mp4" type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
			<!-- 如果浏览器不支持video标签，显示提示信息 -->
			您的浏览器不支持HTML5视频播放。
		</video>

		<!-- JavaScript模块：使用ES6模块化语法 -->
		<script type="module">

			// ==================== 模块导入区域 ====================
			
			// 导入Three.js核心模块的WebGPU版本
			// * as THREE: 将整个模块导入为THREE对象
			import * as THREE from 'three/webgpu';
			
			// 从TSL模块导入特定函数
			// Fn: 创建自定义着色器函数
			// color: 颜色构造函数
			// mx_worley_noise_float: Worley噪声生成函数（用于程序化纹理）
			// time: 时间变量（用于着色器动画）
			import { Fn, color, mx_worley_noise_float, time } from 'three/tsl';
			
			// 导入调试检查器（用于显示调试界面和参数调节）
			import { Inspector } from 'three/addons/inspector/Inspector.js';
			
			// 导入PLY模型加载器（用于加载3D模型文件）
			import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
			
			// 导入轨道控制器（用于鼠标控制相机旋转和缩放）
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ==================== 全局变量声明 ====================
			
			// 渲染器：负责将3D场景渲染到2D画布上
			let renderer;
			
			// 场景：包含所有3D对象的容器
			let scene;
			
			// 相机：定义观察3D场景的视角
			let camera;
			
			// 投影灯：本示例的核心灯光对象
			let projectorLight;
			
			// 灯光辅助器：可视化显示灯光的位置、方向和范围
			let lightHelper;

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

			// ==================== 初始化函数定义 ====================
			function init() {

				// ========== 第一部分：渲染器配置 ==========
				
				// 创建WebGPURenderer实例
				// { antialias: true }: 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置设备像素比
				// window.devicePixelRatio: 获取设备物理像素与CSS像素的比率
				// 在高DPI屏幕上（如Retina显示屏），这个值通常为2
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数
				// animate函数将在每一帧被调用，实现动画效果
				renderer.setAnimationLoop( animate );
				
				// 创建并附加调试检查器到渲染器
				// Inspector用于显示参数调节界面
				renderer.inspector = new Inspector();
				
				// 获取渲染器的DOM元素（canvas画布）并添加到页面body中
				// renderer.domElement: 渲染器对应的HTMLCanvasElement
				document.body.appendChild( renderer.domElement );

				// 启用阴影映射系统
				// 阴影映射是一种计算物体阴影的技术
				renderer.shadowMap.enabled = true;
				
				// 设置阴影类型为PCFSoftShadowMap
				// PCF（Percentage Closer Filtering）软阴影：产生边缘柔和的阴影
				// 其他选项：THREE.BasicShadowMap（基础阴影）、THREE.PCFShadowMap（PCF硬阴影）
				renderer.shadowMap.type = THREE.PCFSoftShadowMap;

				// 设置色调映射（Tone Mapping）
				// 色调映射将HDR（高动态范围）颜色转换为LDR（低动态范围）显示
				renderer.toneMapping = THREE.ACESFilmicToneMapping;
				// ACES Filmic是一种电影工业标准的色调映射算法，能产生电影感的视觉效果
				
				// 设置色调映射曝光值
				// 控制场景的整体亮度，值越大越亮
				renderer.toneMappingExposure = 1;

				// ========== 第二部分：场景创建 ==========
				
				// 创建新的3D场景
				// 场景是所有3D对象（网格、灯光、相机等）的容器
				scene = new THREE.Scene();

				// ========== 第三部分：相机设置 ==========
				
				// 创建透视相机
				// 参数说明：
				// 1. fov (field of view): 视野角度，40度（人眼自然视野）
				// 2. aspect: 宽高比，使用窗口宽高比
				// 3. near: 近裁剪面，0.1单位（相机看不到比这更近的物体）
				// 4. far: 远裁剪面，100单位（相机看不到比这更远的物体）
				camera = new THREE.PerspectiveCamera( 40, window.innerWidth / window.innerHeight, 0.1, 100 );
				
				// 设置相机初始位置 (x, y, z)
				// x=7: 水平方向偏移
				// y=4: 垂直方向高度
				// z=1: 深度方向偏移
				camera.position.set( 7, 4, 1 );

				// ========== 第四部分：控制器设置 ==========
				
				// 创建轨道控制器（OrbitControls）
				// 允许用户通过鼠标拖拽旋转视角，滚轮缩放
				const controls = new OrbitControls( camera, renderer.domElement );
				
				// 设置最小缩放距离：相机不能比这更接近目标点
				controls.minDistance = 2;
				
				// 设置最大缩放距离：相机不能比这更远离目标点
				controls.maxDistance = 10;
				
				// 设置最大极角（polar angle）：限制相机俯仰角度
				// Math.PI / 2 = 90度，限制相机在水平面以上，不能看到地面以下
				controls.maxPolarAngle = Math.PI / 2;
				
				// 设置控制器的目标点（旋转中心点）
				// (0, 1, 0): 场景中心点上方1单位的位置
				controls.target.set( 0, 1, 0 );
				
				// 更新控制器内部状态
				controls.update();

				// ========== 第五部分：纹理加载器 ==========
				
				// 创建纹理加载器实例
				// setPath('textures/'): 设置纹理文件的默认加载路径
				const loader = new THREE.TextureLoader().setPath( 'textures/' );

				// ========== 第六部分：灯光效果定义 ==========
				
				// 创建程序化焦散效果着色器函数
				// Fn: TSL中的函数包装器，用于创建自定义着色器代码
				// ([ projectorUV ]): 函数参数，接收投影UV坐标
				const causticEffect = Fn( ( [ projectorUV ] ) => {
					
					// 使用Worley噪声生成水波纹效果
					// Worley噪声：常用于生成类似细胞、水泡、水波纹的图案
					// projectorUV.mul(10): 将UV坐标放大10倍，增加噪声细节
					// .add(time): 添加时间变量，使噪声随时间变化（动画效果）
					const waterLayer0 = mx_worley_noise_float( projectorUV.mul( 10 ).add( time ) );

					// 创建焦散效果
					// waterLayer0: Worley噪声结果（0-1范围的浮点数）
					// color(0x5abcd8): 将十六进制颜色转换为着色器颜色（青色/蓝色）
					// .mul(2): 乘以2增强亮度
					const caustic = waterLayer0.mul( color( 0x5abcd8 ) ).mul( 2 );

					// 返回最终颜色值
					return caustic;
				} );

				// 添加环境光（半球光）
				// HemisphereLight: 模拟天空和地面的环境光
				// 参数说明：
				// 1. skyColor: 天空颜色（从上方照射的光线颜色）
				// 2. groundColor: 地面颜色（从下方反射的光线颜色）
				// 3. intensity: 光照强度
				const ambient = new THREE.HemisphereLight( 0xffffff, 0x8d8d8d, 0.15 );
				scene.add( ambient );

				// ========== 第七部分：投影灯创建与配置 ==========
				
				// 创建投影灯实例
				// 参数说明：
				// 1. color: 灯光颜色（十六进制）
				// 2. intensity: 灯光强度
				projectorLight = new THREE.ProjectorLight( 0xffffff, 100 );
				
				// 设置投影灯的颜色节点为程序化焦散效果
				// colorNode: 使用TSL着色器节点定义灯光颜色
				projectorLight.colorNode = causticEffect;
				
				// 设置灯光在场景中的位置
				projectorLight.position.set( 2.5, 5, 2.5 );
				
				// 设置灯光锥角（光束扩散角度）
				// Math.PI / 6 = 30度，控制光束的宽度
				projectorLight.angle = Math.PI / 6;
				
				// 设置半影（penumbra）范围
				// 0-1之间的值，控制光束边缘的柔和度
				// 1表示非常柔和的边缘，0表示锐利的边缘
				projectorLight.penumbra = 1;
				
				// 设置衰减系数
				// 控制光线随距离衰减的速度
				// 2是物理正确的衰减值（遵循平方反比定律）
				projectorLight.decay = 2;
				
				// 设置光线距离
				// 0表示无限远（光线不会衰减到0）
				// 如果设为大于0的值，光线会在该距离处衰减为0
				projectorLight.distance = 0;

				// 配置投影灯的阴影属性
				
				// 启用阴影投射：灯光照射的物体会产生阴影
				projectorLight.castShadow = true;
				
				// 设置阴影贴图尺寸
				// 尺寸越大，阴影质量越高，但性能消耗也越大
				projectorLight.shadow.mapSize.width = 1024;  // 宽度1024像素
				projectorLight.shadow.mapSize.height = 1024; // 高度1024像素
				
				// 设置阴影相机参数
				// 阴影映射需要从灯光视角渲染场景
				projectorLight.shadow.camera.near = 1;  // 近裁剪面
				projectorLight.shadow.camera.far = 10;  // 远裁剪面
				
				// 设置阴影聚焦值
				// 控制阴影的清晰度范围，1表示整个阴影区域都清晰
				projectorLight.shadow.focus = 1;
				
				// 设置阴影偏移（bias）
				// 解决阴影痤疮（shadow acne）问题
				// 负值将阴影稍微远离投射物体
				projectorLight.shadow.bias = - .003;
				
				// 将投影灯添加到场景中
				scene.add( projectorLight );

				// 创建并添加灯光辅助器
				// SpotLightHelper: 可视化显示聚光灯/投影灯的位置、方向和范围
				lightHelper = new THREE.SpotLightHelper( projectorLight );
				scene.add( lightHelper );

				// ========== 第八部分：地面创建 ==========
				
				// 创建地面几何体
				// PlaneGeometry: 平面几何体，参数为宽度和高度
				const geometry = new THREE.PlaneGeometry( 200, 200 );
				
				// 创建地面材质
				// MeshLambertMaterial: 兰伯特材质，模拟漫反射表面
				// 对光照敏感，但不产生高光反射
				const material = new THREE.MeshLambertMaterial( { color: 0xbcbcbc } );

				// 创建地面网格对象
				// Mesh: 将几何体和材质组合成可渲染的3D对象
				const mesh = new THREE.Mesh( geometry, material );
				
				// 设置地面位置
				mesh.position.set( 0, - 1, 0 );  // Y轴负方向1单位
				
				// 旋转地面使其水平
				// 默认平面是垂直的，需要绕X轴旋转-90度
				mesh.rotation.x = - Math.PI / 2;
				
				// 启用阴影接收：地面可以接收其他物体投射的阴影
				mesh.receiveShadow = true;
				
				// 将地面添加到场景
				scene.add( mesh );

				// ========== 第九部分：3D模型加载 ==========
				
				// 使用PLYLoader加载Lucy雕像模型
				// PLY（Polygon File Format）：一种3D模型文件格式
				new PLYLoader().load( 
					// 模型文件路径
					'models/ply/binary/Lucy100k.ply', 
					
					// 加载完成后的回调函数
					function ( geometry ) {
						
						// 缩放模型到合适大小
						// Lucy原始模型较大，需要缩小
						geometry.scale( 0.0024, 0.0024, 0.0024 );
						
						// 计算顶点法线
						// 法线用于光照计算，PLY文件可能不包含法线数据
						geometry.computeVertexNormals();

						// 创建模型的材质
						// 使用兰伯特材质，默认白色
						const material = new THREE.MeshLambertMaterial();

						// 创建模型网格对象
						const mesh = new THREE.Mesh( geometry, material );
						
						// 旋转模型：绕Y轴旋转-90度
						mesh.rotation.y = - Math.PI / 2;
						
						// 设置模型高度
						mesh.position.y = 0.8;
						
						// 启用阴影投射：模型可以投射阴影到地面
						mesh.castShadow = true;
						
						// 启用阴影接收：模型可以接收其他物体的阴影
						mesh.receiveShadow = true;
						
						// 将模型添加到场景
						scene.add( mesh );
					} 
				);

				// ========== 第十部分：窗口事件监听 ==========
				
				// 监听窗口大小变化事件
				// 当浏览器窗口大小改变时，调用onWindowResize函数
				window.addEventListener( 'resize', onWindowResize );

				// ========== 第十一部分：GUI调试界面创建 ==========
				
				// 创建参数面板，标题为"Projector Light"
				const gui = renderer.inspector.createParameters( '投影灯参数设置' );

				// 初始化GUI参数对象
				// 这些参数将与GUI控件绑定，修改时会更新对应的灯光属性
				const params = {
					type: 'procedural',  // 投影类型：程序化/视频/纹理
					color: projectorLight.color.getHex(),  // 灯光颜色（十六进制值）
					intensity: projectorLight.intensity,  // 灯光强度
					distance: projectorLight.distance,  // 灯光距离
					angle: projectorLight.angle,  // 灯光锥角（弧度）
					penumbra: projectorLight.penumbra,  // 半影范围
					decay: projectorLight.decay,  // 衰减系数
					focus: projectorLight.shadow.focus,  // 阴影聚焦值
					shadows: true,  // 是否启用阴影系统
				};

				// 纹理变量声明（稍后在GUI回调中使用）
				let videoTexture, mapTexture;

				// ========== 第十二部分：GUI控件配置 ==========
				
				// 1. 投影类型选择控件（下拉菜单）
				gui.add( params, 'type', [ 'procedural', 'video', 'texture' ] )
				   .name('投影类型')  // 控件显示名称
				   .onChange( function ( val ) {
						// 清空当前的投影设置
						projectorLight.colorNode = null;
						projectorLight.map = null;

						if ( val === 'procedural' ) {
							// 选择程序化焦散效果
							projectorLight.colorNode = causticEffect;
							focus.setValue( 1 );  // 设置阴影聚焦值为1

						} else if ( val === 'video' ) {
							// 选择视频投影
							if ( videoTexture === undefined ) {
								// 如果视频纹理未加载，则加载视频
								const video = document.getElementById( 'video' );
								video.play();  // 播放视频

								// 创建视频纹理对象
								videoTexture = new THREE.VideoTexture( video );
								videoTexture.colorSpace = THREE.SRGBColorSpace;  // 设置色彩空间
							}

							projectorLight.map = videoTexture;  // 设置投影纹理为视频
							focus.setValue( .46 );  // 调整阴影聚焦值以获得最佳效果

						} else if ( val === 'texture' ) {
							// 选择静态纹理投影
							mapTexture = loader.load( 'colors.png' );
							
							// 纹理过滤设置
							mapTexture.minFilter = THREE.LinearFilter;  // 缩小过滤器
							mapTexture.magFilter = THREE.LinearFilter;  // 放大过滤器
							mapTexture.generateMipmaps = false;  // 禁用Mipmap生成（纹理尺寸不变）
							mapTexture.colorSpace = THREE.SRGBColorSpace;  // 设置色彩空间

							projectorLight.map = mapTexture;  // 设置投影纹理
							focus.setValue( 1 );  // 设置阴影聚焦值为1
						}
					} );

				// 2. 灯光颜色选择器
				gui.addColor( params, 'color' )
				   .name('灯光颜色')
				   .onChange( function ( val ) {
						// 将颜色选择器的值设置为灯光颜色
						projectorLight.color.setHex( val );
					} );

				// 3. 灯光强度滑块（范围0-500）
				gui.add( params, 'intensity', 0, 500 )
				   .name('灯光强度')
				   .onChange( function ( val ) {
						projectorLight.intensity = val;
					} );

				// 4. 灯光距离滑块（范围0-20）
				gui.add( params, 'distance', 0, 20 )
				   .name('灯光距离')
				   .onChange( function ( val ) {
						projectorLight.distance = val;
					} );

				// 5. 灯光角度滑块（范围0-π/3，即0-60度）
				gui.add( params, 'angle', 0, Math.PI / 3 )
				   .name('灯光角度')
				   .onChange( function ( val ) {
						projectorLight.angle = val;
					} );

				// 6. 半影范围滑块（范围0-1）
				gui.add( params, 'penumbra', 0, 1 )
				   .name('边缘柔和度')
				   .onChange( function ( val ) {
						projectorLight.penumbra = val;
					} );

				// 7. 衰减系数滑块（范围1-2）
				gui.add( params, 'decay', 1, 2 )
				   .name('衰减系数')
				   .onChange( function ( val ) {
						projectorLight.decay = val;
					} );

				// 8. 阴影聚焦滑块（范围0-1）
				// 保存focus控件的引用，以便在其他地方修改它的值
				const focus = gui.add( params, 'focus', 0, 1 )
				   .name('阴影清晰度')
				   .onChange( function ( val ) {
						projectorLight.shadow.focus = val;
					} );

				// 9. 阴影开关
				gui.add( params, 'shadows' )
				   .name('启用阴影')
				   .onChange( function ( val ) {
						// 启用或禁用整个渲染器的阴影映射
						renderer.shadowMap.enabled = val;

						// 遍历场景中的所有对象
						// 当阴影启用状态改变时，需要更新材质
						scene.traverse( function ( child ) {
							if ( child.material ) {
								// 标记材质需要更新
								// 这确保着色器程序重新编译以包含/排除阴影计算
								child.material.needsUpdate = true;
							}
						} );
					} );

			}

			// ==================== 窗口大小变化处理函数 ====================
			function onWindowResize() {
				// 更新相机宽高比以匹配新的窗口尺寸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 必须调用此方法才能使新的宽高比生效
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸以填充整个窗口
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 动画循环函数 ====================
			function animate() {
				// 计算基于时间的动画参数
				// performance.now(): 返回自页面加载以来的毫秒数（高精度）
				// 除以3000：控制动画速度，值越大动画越慢
				const time = performance.now() / 3000;

				// 使投影灯围绕中心点(0,5,0)做圆周运动
				// Math.cos(time)*2.5: X轴位置随时间按余弦函数变化
				// Math.sin(time)*2.5: Z轴位置随时间按正弦函数变化
				// 半径2.5单位，Y轴保持5不变
				projectorLight.position.x = Math.cos( time ) * 2.5;
				projectorLight.position.z = Math.sin( time ) * 2.5;

				// 更新灯光辅助器
				// 由于灯光位置在移动，辅助器需要更新以反映最新位置
				lightHelper.update();

				// 渲染场景
				// 将3D场景通过相机视角渲染到2D画布上
				renderer.render( scene, camera );
			}

		</script>

	</body>

</html>