<!-- Three.js WebGPU 聚光灯效果演示 - 功能与技术点分析
一、整体功能概述
这是一个基于Three.js WebGPU渲染器的高级3D图形演示，展示聚光灯投影纹理和实时动态阴影的完整实现。主要功能包括：

1. 核心视觉效果
纹理投影聚光灯：聚光灯可以投射不同的纹理图案到3D场景中

动态阴影系统：实现物体间的实时阴影投射和接收

灯光动画：聚光灯自动围绕场景做圆周运动

交互式3D场景：包含3D模型（Lucy雕像）和地面平面

2. 用户交互功能
鼠标轨道控制：旋转、缩放、平移视角

实时参数调节：通过GUI面板调整灯光和阴影的所有参数

辅助工具切换：可视化显示灯光方向和阴影计算范围

二、主要技术点详解
1. WebGPU渲染技术
javascript
// 使用WebGPU而非传统的WebGL渲染器
renderer = new THREE.WebGPURenderer({ antialias: true });
性能优势：WebGPU是下一代Web图形API，相比WebGL提供更直接的GPU访问

现代特性：支持计算着色器、更高效的并行处理

多平台：在Chrome、Edge、Safari等现代浏览器中可用

2. 聚光灯系统
javascript
spotLight = new THREE.SpotLight(0xffffff, 100);
关键参数：
纹理投影：spotLight.map = texture - 将2D纹理作为投影图案

锥角控制：angle参数定义光束扩散范围（30度）

边缘柔和：penumbra参数控制光束边缘的软硬度

物理衰减：decay=2遵循真实世界的光衰减规律

3. 阴影映射技术
javascript
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
阴影实现机制：
阴影贴图：从灯光视角渲染深度图（1024x1024分辨率）

PCF软阴影：使用Percentage-Closer Filtering产生柔和阴影边缘

阴影相机：每个投射阴影的灯光都有对应的阴影相机

深度偏移：shadow.bias = -0.003解决阴影痤疮问题

4. 色调映射与色彩管理
javascript
renderer.toneMapping = THREE.NeutralToneMapping;
renderer.toneMappingExposure = 1;
texture.colorSpace = THREE.SRGBColorSpace;
色调映射：将HDR（高动态范围）颜色转换为显示器的LDR范围

色彩空间：sRGB确保颜色在不同设备上的一致性

曝光控制：调节场景整体亮度

5. 异步资源加载
javascript
// 纹理异步加载
const texture = loader.load(filename);

// 3D模型异步加载
new PLYLoader().load('models/ply/binary/Lucy100k.ply', callback);
纹理加载：支持JPG、PNG等多种格式，自动处理颜色空间

模型加载：PLY格式（多边形文件格式），常用于3D扫描数据

资源管理：所有资源异步加载，避免阻塞主线程

6. 动画与交互系统
javascript
// 动画循环（WebGPU版本）
renderer.setAnimationLoop(animate);

// 轨道控制器
const controls = new OrbitControls(camera, renderer.domElement);
动画机制：
基于时间的动画：使用performance.now()确保动画速度与时间同步

圆周运动算法：x = cos(time)*r, z = sin(time)*r

实时更新：灯光辅助工具每帧更新以匹配灯光位置

交互控制：
最小/最大距离限制：防止相机过近或过远

俯仰角限制：防止相机翻转

目标点锁定：相机围绕固定点旋转

7. 调试与参数调节系统
javascript
const gui = renderer.inspector.createParameters('灯光设置');
GUI面板功能：
实时调节：所有参数修改立即生效

范围验证：滑块设置合理的数值范围

辅助工具：可视化显示灯光参数效果

辅助工具：
聚光灯辅助器：显示灯光方向、角度和范围

阴影相机辅助器：显示阴影计算的范围（视锥体）

8. 响应式布局
javascript
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
}
自适应分辨率：根据窗口大小调整渲染尺寸

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

设备像素比：考虑高DPI显示器的清晰度

三、技术架构特点
1. 模块化设计
ES6模块导入：使用浏览器原生模块系统

清晰的依赖管理：通过importmap定义模块路径

分离的关注点：初始化、动画、事件处理逻辑分离

2. 性能优化
Mipmaps禁用：投影纹理不需要多级渐远纹理

线性过滤：平衡性能和质量

适当的阴影分辨率：1024x1024提供足够质量

3. 错误处理
异步加载回调：模型加载完成后再进行设置

参数范围限制：GUI滑块防止无效值输入

兼容性检查：依赖现代浏览器功能

四、适用场景
3D图形学习：理解灯光、阴影、材质的基础概念

产品展示：展示产品在特定灯光下的效果

游戏开发：学习实时阴影和动态灯光技术

艺术创作：利用纹理投影创建特殊视觉效果

技术演示：展示WebGPU的图形处理能力

五、技术亮点总结
前沿的WebGPU技术：展示下一代Web图形标准的应用

完整的阴影系统：从基础阴影映射到高级PCF软阴影

交互式参数调节：实时可视化参数调整效果

物理正确的光照：遵循真实世界的光学原理

专业级的调试工具：内置完善的辅助和调试功能 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示在浏览器标签页上 -->
		<title>Three.js WebGPU - 聚光灯效果演示</title>
		<!-- 字符编码设置：UTF-8支持中文显示 -->
		<meta charset="utf-8">
		<!-- 视口设置：针对移动设备优化，禁止用户手动缩放 -->
		<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官网链接，点击跳转到官网 -->
			<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>聚光灯效果演示</span>
			</div>

			<!-- 场景详细描述 -->
			<small>此示例展示使用WebGPU渲染器实现的聚光灯效果，包含纹理投射和动态阴影功能。</small>
			<br>
			<small style="margin-top: 20px;">功能说明：聚光灯可投射纹理到3D模型上，灯光围绕场景做圆周运动，支持实时参数调整。</small>
			<br>
			<small style="margin-top: 40px;">交互操作：使用鼠标左键旋转视图，滚轮缩放，右键平移；右侧面板可调整灯光参数。</small>
		</div>

		<!-- 导入映射配置：定义模块导入的路径映射关系 -->
		<!-- importmap是浏览器原生模块导入的配置方式，用于指定模块名称对应的实际文件路径 -->
		<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版本的所有功能
			// THREE对象包含了Three.js的所有核心类和方法
			import * as THREE from 'three/webgpu';

			// 导入调试检查器：用于创建参数调整面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入PLY模型加载器：用于加载.ply格式的3D模型文件
			// PLY是一种常用的3D模型文件格式，常用于存储3D扫描数据
			import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
			
			// 导入轨道控制器：用于实现鼠标控制相机旋转、缩放和平移
			// 这是Three.js中最常用的相机控制器之一
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ========== 全局变量声明 ==========
			let renderer;  // WebGPU渲染器实例，负责将3D场景渲染到画布上
			let scene;     // 场景对象，包含所有的3D对象（网格、灯光、相机等）
			let camera;    // 透视相机，定义了观察3D场景的视角
			let spotLight; // 聚光灯对象，本示例的核心光源

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

			// ========== 初始化函数定义 ==========
			// 这个函数负责创建和设置所有的Three.js对象
			function init() {

				// ---------- 1. 渲染器设置 ----------
				// 创建WebGPURenderer实例，开启抗锯齿以获得更平滑的边缘
				// WebGPU是新一代图形API，相比WebGL有更好的性能和特性支持
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置设备像素比：确保在高DPI屏幕上清晰显示
				// window.devicePixelRatio获取设备的物理像素与CSS像素的比例
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为整个浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数：animate函数会在每一帧被调用
				// 这是实现动画效果的关键，替代了传统的requestAnimationFrame
				renderer.setAnimationLoop( animate );
				
				// 将渲染器的DOM元素（canvas画布）添加到网页body中
				// 这样3D场景就会显示在网页上
				document.body.appendChild( renderer.domElement );

				// 创建调试检查器实例并附加到渲染器
				// Inspector提供图形化界面用于调试和参数调整
				renderer.inspector = new Inspector();

				// 色调映射设置：用于将HDR颜色值映射到显示器的LDR范围
				// NeutralToneMapping是一种中性的色调映射算法，保持颜色相对自然
				renderer.toneMapping = THREE.NeutralToneMapping;
				
				// 设置曝光度：控制场景的整体亮度
				// 1.0表示标准曝光，大于1会增亮，小于1会变暗
				renderer.toneMappingExposure = 1;

				// 阴影系统设置
				renderer.shadowMap.enabled = true;  // 启用阴影映射功能
				renderer.shadowMap.type = THREE.PCFSoftShadowMap;  // 使用PCF软阴影算法
				// PCF（Percentage-Closer Filtering）软阴影会产生更自然的柔和阴影边缘

				// ---------- 2. 场景创建 ----------
				// 创建场景对象，所有3D对象都需要添加到场景中才能被渲染
				scene = new THREE.Scene();
				// 场景是Three.js的容器对象，管理所有要渲染的物体、灯光和相机

				// ---------- 3. 相机设置 ----------
				// 创建透视相机：模拟人眼的观察方式，近大远小
				// 参数说明：40-垂直视野角度（FOV），宽高比，0.1-近裁剪面，100-远裁剪面
				// 近裁剪面和远裁剪面定义了相机的可见范围，之外的物体不会被渲染
				camera = new THREE.PerspectiveCamera( 
					40,  // 视野角度（度）
					window.innerWidth / window.innerHeight,  // 宽高比
					0.1, // 近裁剪面：相机能看到的最近距离
					100  // 远裁剪面：相机能看到的最远距离
				);
				
				// 设置相机初始位置：x=7, y=4, z=1
				// 这样相机位于场景的右上方，可以俯瞰整个场景
				camera.position.set( 7, 4, 1 );

				// ---------- 4. 轨道控制器设置 ----------
				// 创建轨道控制器，连接相机和渲染器的DOM元素
				// 这样用户就可以用鼠标控制相机了
				const controls = new OrbitControls( camera, renderer.domElement );
				
				// 设置相机控制限制
				controls.minDistance = 2;  // 最小缩放距离：相机不能比这个更接近目标
				controls.maxDistance = 10; // 最大缩放距离：相机不能比这个更远离目标
				controls.maxPolarAngle = Math.PI / 2;  // 最大俯仰角：防止相机翻转到底部
				// Math.PI/2 = 90度，这意味着相机不能看到地面以下
				
				// 设置控制器的目标点：相机总是围绕这个点旋转
				controls.target.set( 0, 1, 0 );
				
				// 更新控制器状态
				controls.update();

				// ---------- 5. 纹理加载 ----------
				// 创建纹理加载器实例，并设置纹理文件的基路径
				const loader = new THREE.TextureLoader().setPath( 'textures/' );
				
				// 定义要加载的纹理文件名数组
				// 这些纹理将用于聚光灯的投影效果
				const filenames = [ 
					'disturb.jpg',      // 扰动纹理：产生波动光效
					'colors.png',       // 彩色纹理：产生彩色光效
					'uv_grid_opengl.jpg' // UV网格纹理：用于测试和调试
				];

				// 创建纹理对象容器，初始包含一个"none"选项（无纹理）
				const textures = { none: null };

				// 循环加载所有纹理文件
				for ( let i = 0; i < filenames.length; i ++ ) {

					const filename = filenames[ i ];  // 获取当前文件名

					// 加载纹理文件
					// 纹理是图像数据，可以应用到3D物体表面或作为灯光投影
					const texture = loader.load( filename );
					
					// 设置纹理过滤参数
					texture.minFilter = THREE.LinearFilter;  // 缩小过滤器：纹理缩小时的采样方式
					texture.magFilter = THREE.LinearFilter;  // 放大过滤器：纹理放大时的采样方式
					// LinearFilter使用线性插值，效果比NearestFilter平滑
					
					texture.generateMipmaps = false;  // 不生成Mipmaps链
					// Mipmaps是预计算的不同分辨率的纹理副本，用于优化远距离渲染
					// 这里禁用是因为投影纹理通常不需要
					
					texture.colorSpace = THREE.SRGBColorSpace;  // 设置颜色空间为sRGB
					// sRGB是标准的颜色空间，确保颜色在不同设备上显示一致

					// 将加载好的纹理存储到textures对象中，使用文件名作为键
					textures[ filename ] = texture;

				}

				// ---------- 6. 灯光系统设置 ----------
				// 6.1 环境光/半球光
				// 创建半球光：模拟天空和地面的环境光照
				// 参数：天空颜色，地面颜色，光照强度
				const ambient = new THREE.HemisphereLight( 
					0xffffff,  // 天空颜色：白色
					0x8d8d8d,  // 地面颜色：浅灰色
					0.25       // 光照强度：0.25（较弱的环境光）
				);
				scene.add( ambient );  // 将环境光添加到场景

				// 6.2 聚光灯（本示例的核心）
				// 创建聚光灯：产生锥形光束，可以投射纹理和阴影
				// 参数：灯光颜色（白色），光照强度（100）
				spotLight = new THREE.SpotLight( 0xffffff, 100 );
				spotLight.name = 'spotLight';  // 设置灯光名称，便于调试识别
				spotLight.map = textures[ 'disturb.jpg' ];  // 设置投影纹理：初始使用扰动纹理
				spotLight.position.set( 2.5, 5, 2.5 );  // 设置灯光位置：场景右上方
				spotLight.angle = Math.PI / 6;  // 设置锥角：30度（Math.PI/6弧度）
				// 锥角定义了聚光灯光束的扩散角度
				
				spotLight.penumbra = 1;  // 设置半影：1表示完全软边缘
				// 半影控制光束边缘的柔和度，0为硬边缘，1为最柔和
				
				spotLight.decay = 2;  // 设置衰减指数：光线随距离衰减的速度
				// 物理正确衰减，2表示符合真实世界的光衰减规律
				
				spotLight.distance = 0;  // 设置光照距离：0表示无限远
				// 如果设为正值，光线在超过该距离后完全消失

				// 6.3 聚光灯阴影设置
				spotLight.castShadow = true;  // 启用阴影投射
				// 这意味着聚光灯照射的物体会产生阴影
				
				spotLight.shadow.mapSize.width = 1024;  // 阴影贴图宽度：分辨率越高阴影越清晰
				spotLight.shadow.mapSize.height = 1024; // 阴影贴图高度
				// 阴影贴图是渲染到纹理的深度图，用于计算阴影
				
				spotLight.shadow.camera.near = 2;  // 阴影相机近平面：阴影计算的最小距离
				spotLight.shadow.camera.far = 10;  // 阴影相机远平面：阴影计算的最大距离
				// 阴影相机是灯光视角的相机，用于生成阴影贴图
				
				spotLight.shadow.focus = 1;  // 阴影聚焦：控制阴影边缘的清晰度
				spotLight.shadow.bias = - .003;  // 阴影偏移：解决阴影悬浮问题（阴影痤疮）
				// 负的bias值可以避免物体表面出现自阴影的虚假阴影
				
				spotLight.shadow.intensity = 1;  // 阴影强度：1表示完全强度的阴影
				scene.add( spotLight );  // 将聚光灯添加到场景

				// 6.4 聚光灯辅助工具
				// 创建聚光灯辅助工具：可视化显示灯光的方向和锥角
				spotLight.lightHelper = new THREE.SpotLightHelper( spotLight );
				spotLight.lightHelper.visible = false;  // 默认隐藏，可通过GUI显示
				scene.add( spotLight.lightHelper );  // 将辅助工具添加到场景

				// 创建阴影相机辅助工具：显示阴影相机的视锥体
				// 帮助理解阴影计算的范围和视角
				spotLight.shadowCameraHelper = new THREE.CameraHelper( spotLight.shadow.camera );
				spotLight.shadowCameraHelper.visible = false;  // 默认隐藏
				scene.add( spotLight.shadowCameraHelper );

				// ---------- 7. 地面创建 ----------
				// 创建平面几何体作为地面：宽10单位，高10单位
				const geometry = new THREE.PlaneGeometry( 10, 10 );
				
				// 创建朗伯特材质：对光照有反应的基本材质
				// 颜色设为浅灰色（0xbcbcbc）
				const material = new THREE.MeshLambertMaterial( { color: 0xbcbcbc } );

				// 创建网格对象：组合几何体和材质
				const mesh = new THREE.Mesh( geometry, material );
				mesh.position.set( 0, - 1, 0 );  // 设置地面位置：y轴-1处
				mesh.rotation.x = - Math.PI / 2;  // 旋转平面：使其水平放置
				// -Math.PI/2表示绕x轴旋转-90度
				
				mesh.receiveShadow = true;  // 启用阴影接收：地面可以显示其他物体的阴影
				scene.add( mesh );  // 将地面添加到场景

				// ---------- 8. 3D模型加载 ----------
				// 使用PLYLoader异步加载Lucy模型
				// Lucy是计算机图形学中常用的测试模型
				new PLYLoader().load( 
					'models/ply/binary/Lucy100k.ply',  // 模型文件路径
					function ( geometry ) {  // 加载完成后的回调函数
						// 回调参数geometry是加载的几何体数据

						// 缩放几何体：原始模型较大，缩小到合适尺寸
						geometry.scale( 0.0024, 0.0024, 0.0024 );
						
						// 计算顶点法线：几何体需要法线信息才能正确显示光照效果
						// 法线是垂直于表面的向量，用于计算光照方向
						geometry.computeVertexNormals();

						// 创建朗伯特材质：使用默认参数
						const material = new THREE.MeshLambertMaterial();

						// 创建网格对象
						const mesh = new THREE.Mesh( geometry, material );
						mesh.rotation.y = - Math.PI / 2;  // 旋转模型：调整朝向
						mesh.position.y = 0.8;  // 设置模型高度：稍微高于地面
						mesh.castShadow = true;  // 启用阴影投射：模型会产生阴影
						mesh.receiveShadow = true;  // 启用阴影接收：模型表面可以显示阴影
						scene.add( mesh );  // 将模型添加到场景

					}
				);

				// ---------- 9. 窗口大小变化事件监听 ----------
				// 当浏览器窗口大小改变时，调整渲染器和相机
				window.addEventListener( 'resize', onWindowResize );

				// ---------- 10. GUI调试面板创建 ----------
				// 使用Inspector创建参数调整面板
				const gui = renderer.inspector.createParameters( '灯光设置' );

				// 定义GUI参数对象，初始值与聚光灯属性同步
				const params = {
					map: textures[ 'disturb.jpg' ],  // 当前投影纹理
					color: spotLight.color.getHex(),  // 灯光颜色（16进制值）
					intensity: spotLight.intensity,   // 灯光强度
					distance: spotLight.distance,     // 光照距离
					angle: spotLight.angle,           // 光束锥角
					penumbra: spotLight.penumbra,     // 边缘半影
					decay: spotLight.decay,           // 衰减指数
					focus: spotLight.shadow.focus,    // 阴影聚焦
					shadowIntensity: spotLight.shadow.intensity,  // 阴影强度
					helpers: false  // 辅助工具显示状态
				};

				// 10.1 纹理选择下拉菜单
				gui.add( params, 'map', textures )
				   .name('投影纹理')  // 设置显示名称
				   .onChange( function ( val ) {
						// 当选择改变时，更新聚光灯的投影纹理
						spotLight.map = val;
					} );

				// 10.2 颜色选择器
				gui.addColor( params, 'color' )
				   .name('灯光颜色')
				   .onChange( function ( val ) {
						// 将16进制颜色值设置到聚光灯
						spotLight.color.setHex( val );
					} );

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

				// 10.4 距离滑块：范围0-20
				gui.add( params, 'distance', 0, 20 )
				   .name('光照距离')
				   .onChange( function ( val ) {
						spotLight.distance = val;
					} );

				// 10.5 角度滑块：范围0-π/3（0-60度）
				gui.add( params, 'angle', 0, Math.PI / 3 )
				   .name('光束角度')
				   .onChange( function ( val ) {
						spotLight.angle = val;
					} );

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

				// 10.7 衰减滑块：范围1-2
				gui.add( params, 'decay', 1, 2 )
				   .name('衰减指数')
				   .onChange( function ( val ) {
						spotLight.decay = val;
					} );

				// 10.8 阴影聚焦滑块：范围0-1
				gui.add( params, 'focus', 0, 1 )
				   .name('阴影聚焦')
				   .onChange( function ( val ) {
						spotLight.shadow.focus = val;
					} );

				// 10.9 阴影强度滑块：范围0-1
				gui.add( params, 'shadowIntensity', 0, 1 )
				   .name('阴影强度')
				   .onChange( function ( val ) {
						spotLight.shadow.intensity = val;
					} );

				// 10.10 辅助工具开关
				gui.add( params, 'helpers' )
				   .name('显示辅助工具')
				   .onChange( function ( val ) {
						// 同时控制灯光辅助工具和阴影相机辅助工具的显示状态
						spotLight.lightHelper.visible = val;
						spotLight.shadowCameraHelper.visible = val;
					} );

			} // init函数结束

			// ========== 窗口大小变化处理函数 ==========
			function onWindowResize() {

				// 更新相机的宽高比：使用窗口的新宽高比
				// 这确保渲染内容不会变形
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机参数改变后，必须调用此方法更新内部矩阵
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸：适应新的窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );

			}

			// ========== 动画循环函数 ==========
			// 这个函数会在每一帧被调用（通常是每秒60次）
			// 负责更新动画状态和渲染场景
			function animate() {

				// 计算当前时间：从页面加载到现在的秒数
				// performance.now()返回高精度时间戳（毫秒）
				// 除以3000使动画速度适中
				const time = performance.now() / 3000;

				// 更新聚光灯位置：让灯光围绕原点做圆周运动
				// Math.cos(time)和Math.sin(time)产生圆周运动
				// 乘以2.5控制圆周半径
				spotLight.position.x = Math.cos( time ) * 2.5;
				spotLight.position.z = Math.sin( time ) * 2.5;
				// y坐标保持不变，所以灯光在水平面做圆周运动

				// 更新灯光辅助工具：确保辅助工具显示正确的位置和方向
				spotLight.lightHelper.update();

				// 渲染场景：将3D场景绘制到画布上
				// 这是整个Three.js管线的最后一步
				renderer.render( scene, camera );

			} // animate函数结束

		</script>

	</body>

</html>