<!-- Three.js WebGPU IES聚光灯演示 - 功能和技术详解
🎯 项目功能概述
这是一个基于Three.js WebGPU后端的真实光照模拟演示，专门展示IES（照明工程学会）标准光照数据在实际3D场景中的应用。项目通过四盏不同颜色的聚光灯，结合真实的IES光照分布文件，模拟专业级照明效果。

🌟 核心功能特性
1. IES真实光照模拟
真实光照分布：使用工业标准IES文件（从灯具制造商获得）

四种不同灯光特性：每盏灯使用不同的IES配置文件

专业级效果：模拟真实灯具的光照强度、角度和衰减特性

2. 动态灯光动画
周期性运动：灯光目标点随时间向中心聚拢和散开

相位偏移：四盏灯动画错开，形成交替效果

平滑过渡：使用线性插值确保动画流畅

3. 完整的3D场景
地面系统：接收阴影的大型平面

中心物体：立方体用于展示光照和阴影效果

阴影系统：启用完整的阴影投射和接收

4. 用户交互系统
相机控制：鼠标拖拽旋转、滚轮缩放

可视化调试：可切换显示的灯光辅助器

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

🔧 主要技术要点
1. WebGPU渲染技术
text
技术栈：Three.js WebGPU后端
优势：
• 相比WebGL更好的性能和现代API支持
• 原生支持GPU计算和高级渲染特性
• 更好的多线程处理和资源管理
2. IES光照系统
javascript
// IES文件加载和解析
const iesLoader = new IESLoader().setPath('./ies/');
// 文件格式：工业标准光照数据格式
// 包含：光强分布、角度数据、衰减曲线
3. IESSpotLight特殊光源
javascript
// 特有属性
IESSpotLight特点：
• iesMap: 应用IES纹理贴图
• 真实衰减：基于IES数据的距离衰减
• 角度分布：真实的光束角度和半影效果
4. 动画系统实现
javascript
// 核心动画算法
const t = (Math.sin((time + i) * (Math.PI / 2)) + 1) / 2;
const x = THREE.MathUtils.lerp(lights[i].position.x, 0, t);
// 技术原理：正弦函数+线性插值
5. 阴影映射技术
text
阴影实现：
1. 灯光启用castShadow
2. 物体设置castShadow/receiveShadow
3. WebGPU渲染器启用shadowMap
4. 实时阴影计算和渲染
6. 模块化架构
javascript
// ES6模块系统
import * as THREE from 'three/webgpu';
import { OrbitControls } from './jsm/controls/OrbitControls.js';
import { IESLoader } from 'three/addons/loaders/IESLoader.js';
// 使用importmap进行路径映射
7. 调试和开发工具
javascript
// Inspector调试系统
renderer.inspector = new Inspector();
// 实时参数调节GUI
// 灯光辅助器可视化
📊 技术架构层次
第一层：核心渲染引擎
Three.js WebGPURenderer：底层渲染接口

GPU管道：WebGPU渲染管线配置

着色器编译：实时着色器代码编译

第二层：资源管理系统
异步加载：Promise.all并行加载IES文件

纹理管理：IES纹理贴图处理

内存管理：GPU资源分配和释放

第三层：光照系统
IES数据处理：解析和转换IES格式

灯光计算：实时光照强度计算

阴影生成：阴影贴图生成算法

第四层：动画和交互系统
时间同步：requestAnimationFrame时间管理

用户输入：鼠标/键盘事件处理

物理模拟：简单的动画插值计算

🎨 视觉效果特点
1. 真实感光照
软阴影：通过penumbra参数实现

颜色混合：四色灯光叠加效果

距离衰减：真实的光照衰减曲线

2. 动态效果
循环动画：无限循环的灯光运动

实时响应：用户交互即时反馈

平滑过渡：所有动画使用插值

3. 专业级表现
工业标准：符合照明行业标准

精确测量：基于真实灯具数据

可预测结果：一致的渲染效果

🔄 运行流程
text
启动流程：
1. 加载IES纹理文件（异步并行）
2. 创建3D场景和相机系统
3. 配置WebGPU渲染器
4. 初始化轨道控制器
5. 设置GUI调试界面
6. 启动渲染循环

每帧更新：
1. 计算动画时间
2. 更新灯光目标位置
3. 更新灯光辅助器（如果可见）
4. 执行WebGPU渲染
5. 等待下一帧
💡 应用场景
专业领域应用
建筑可视化：真实建筑照明设计

产品展示：灯具产品效果演示

影视制作：虚拟场景灯光预览

游戏开发：高级光照效果实现

教育培训
光照原理教学：展示真实光照分布

WebGPU技术演示：展示现代图形API

Three.js高级功能：学习插件和扩展使用

🚀 性能优化特性
并行加载：四个IES文件同时加载

GPU加速：WebGPU原生GPU计算

智能更新：只在必要时更新辅助器

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

📈 技术难点解决
难点1：IES数据转换
text
解决方案：
• 使用专门的IESLoader解析器
• 将光度数据转换为纹理贴图
• 在着色器中应用光照分布
难点2：多光源阴影
text
解决方案：
• WebGPU多光源阴影支持
• 合理的阴影距离和分辨率设置
• 性能和质量平衡调节
难点3：跨浏览器兼容
text
解决方案：
• 渐进增强设计
• 功能检测和回退机制
• 明确的浏览器要求提示
🔮 扩展可能性
短期扩展
更多IES文件：扩展灯光库

实时参数调节：强度、颜色、角度调节

环境光支持：添加环境光遮蔽

长期扩展
光线追踪：WebGPU光线追踪支持

体积光效果：光束可见性效果

动态日夜循环：时间变化光照

📋 系统要求
浏览器：支持WebGPU的现代浏览器（Chrome 113+）

硬件：支持WebGPU的GPU

网络：需要加载IES纹理文件 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：Three.js WebGPU - IES聚光灯演示 -->
		<title>Three.js WebGPU - IES聚光灯演示</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>

		<!-- 页面信息展示区域，id为info用于CSS样式定位 -->
		<div id="info">
			<!-- Three.js官网链接，点击跳转到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> - IES聚光灯技术演示</span>
			</div>

			<!-- 页面描述文本，使用small标签表示次要信息 -->
			<small>
				演示使用真实IES光照数据文件的聚光灯效果。
				<br>IES（照明工程学会）文件包含真实灯光的光照强度分布数据。
				<br>四盏聚光灯使用不同的IES配置文件，展示真实世界的光照效果。
			</small>
			
		</div>

		<!-- 
			导入映射(Import Map)配置：
			现代浏览器中用于控制JavaScript模块导入的映射关系
			允许开发者使用简短的模块名代替完整的URL路径
		-->
		<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';

			// 导入轨道控制器（OrbitControls）
			// 用于实现通过鼠标控制相机旋转、缩放和平移的功能
			import { OrbitControls } from './jsm/controls/OrbitControls.js';

			// 导入IES加载器（IESLoader）
			// 专门用于加载和解析IES光照数据文件
			// IES文件是照明行业的标准化格式，描述灯光的光照分布
			import { IESLoader } from 'three/addons/loaders/IESLoader.js';

			// 导入调试检查器（Inspector）
			// 提供可视化界面用于调整场景参数，类似于Three.js编辑器
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ==================== 全局变量声明 ====================
			
			// 渲染器：负责将3D场景渲染到2D画布上
			let renderer;
			// 场景：所有3D对象的容器，包括灯光、模型、相机等
			let scene;
			// 相机：决定用户看到场景的哪个部分和视角
			let camera;
			// 灯光数组：存储场景中的所有聚光灯对象，便于统一管理
			let lights;

			// ==================== 主初始化函数 ====================
			
			/**
			 * 异步初始化函数
			 * async关键字表示这个函数包含异步操作
			 * 使用async/await语法处理异步加载
			 */
			async function init() {

				// ---------- IES文件加载部分 ----------
				
				/**
				 * 创建IESLoader实例并配置
				 * IESLoader是专门用于加载IES文件的加载器
				 * IES文件包含真实世界灯光的光照强度分布数据
				 */
				const iesLoader = new IESLoader().setPath( './ies/' );
				// 可选：设置IES纹理类型为无符号字节类型（LDR模式）
				//iesLoader.type = THREE.UnsignedByteType; // LDR（低动态范围）
				
				/**
				 * 并行加载4个不同的IES文件
				 * Promise.all()确保所有文件都加载完成后再继续执行
				 * 每个IES文件代表不同类型灯光的光照分布
				 * 这些文件通常从真实灯具制造商处获得
				 */
				const [ iesTexture1, iesTexture2, iesTexture3, iesTexture4 ] = await Promise.all( [
					// 加载第一个IES文件（红色灯光使用）
					iesLoader.loadAsync( '007cfb11e343e2f42e3b476be4ab684e.ies' ),
					// 加载第二个IES文件（绿色灯光使用）
					iesLoader.loadAsync( '06b4cfdc8805709e767b5e2e904be8ad.ies' ),
					// 加载第三个IES文件（蓝色灯光使用）
					iesLoader.loadAsync( '02a7562c650498ebb301153dbbf59207.ies' ),
					// 加载第四个IES文件（白色灯光使用）
					iesLoader.loadAsync( '1a936937a49c63374e6d4fbed9252b29.ies' )
				] );

				// ---------- 场景创建 ----------
				
				/**
				 * 创建主场景对象
				 * Scene是所有3D对象的容器，相当于一个虚拟的3D空间
				 * 可以设置背景色、雾效、环境光等全局属性
				 */
				scene = new THREE.Scene();

				// ---------- 创建聚光灯（红色） ----------
				
				/**
				 * IESSpotLight类：特殊的聚光灯，支持IES光照贴图
				 * 参数1：灯光颜色（十六进制，0xff0000表示红色）
				 * 参数2：灯光强度（数值越大越亮）
				 */
				const spotLight = new THREE.IESSpotLight( 0xff0000, 500 );
				// 设置灯光在3D空间中的位置（X, Y, Z坐标）
				// 这里设置在右上角位置
				spotLight.position.set( 6.5, 3, 6.5 );
				// 设置灯光的锥形角度（单位：弧度）
				// Math.PI / 8 约等于22.5度
				spotLight.angle = Math.PI / 8;
				// 设置半影大小（0到1之间）
				// 值越大，光线边缘越柔和
				spotLight.penumbra = 0.7;
				// 设置灯光照射的最大距离
				// 超过这个距离，光线强度衰减为0
				spotLight.distance = 20;
				// 启用阴影投射功能
				// 灯光照射的物体会产生阴影
				spotLight.castShadow = true;
				// 应用之前加载的IES纹理贴图
				// 这会使灯光的光照分布符合真实灯具的特性
				spotLight.iesMap = iesTexture1;
				// 创建灯光辅助器并存储到userData中
				// SpotLightHelper可以直观显示灯光的锥形范围和方向
				spotLight.userData.helper = new THREE.SpotLightHelper( spotLight );
				// 将灯光添加到场景中
				scene.add( spotLight );
				// 将灯光目标点添加到场景中
				// 聚光灯的方向始终指向其target对象
				scene.add( spotLight.target );
				// 将灯光辅助器添加到场景中（默认可能隐藏）
				scene.add( spotLight.userData.helper );

				// ---------- 创建聚光灯（绿色） ----------
				
				/**
				 * 第二盏聚光灯，设置与第一盏类似
				 * 颜色：绿色（0x00ff00）
				 * 位置：左上角
				 * 使用不同的IES纹理文件
				 */
				const spotLight2 = new THREE.IESSpotLight( 0x00ff00, 500 );
				spotLight2.position.set( -6.5, 3, 6.5 );
				spotLight2.angle = Math.PI / 8;
				spotLight2.penumbra = 0.7;
				spotLight2.distance = 20;
				spotLight2.castShadow = true;
				spotLight2.iesMap = iesTexture2;
				spotLight2.userData.helper = new THREE.SpotLightHelper( spotLight2 );
				scene.add( spotLight2 );
				scene.add( spotLight2.target );
				scene.add( spotLight2.userData.helper );

				// ---------- 创建聚光灯（蓝色） ----------
				
				/**
				 * 第三盏聚光灯
				 * 颜色：蓝色（0x0000ff）
				 * 位置：左下角
				 */
				const spotLight3 = new THREE.IESSpotLight( 0x0000ff, 500 );
				spotLight3.position.set( -6.5, 3, -6.5 );
				spotLight3.angle = Math.PI / 8;
				spotLight3.penumbra = 0.7;
				spotLight3.distance = 20;
				spotLight3.castShadow = true;
				spotLight3.iesMap = iesTexture3;
				spotLight3.userData.helper = new THREE.SpotLightHelper( spotLight3 );
				scene.add( spotLight3 );
				scene.add( spotLight3.target );
				scene.add( spotLight3.userData.helper );

				// ---------- 创建聚光灯（白色） ----------
				
				/**
				 * 第四盏聚光灯
				 * 颜色：白色（0xffffff）
				 * 位置：右下角
				 */
				const spotLight4 = new THREE.IESSpotLight( 0xffffff, 500 );
				spotLight4.position.set( 6.5, 3, -6.5 );
				spotLight4.angle = Math.PI / 8;
				spotLight4.penumbra = 0.7;
				spotLight4.distance = 20;
				spotLight4.castShadow = true;
				spotLight4.iesMap = iesTexture4;
				spotLight4.userData.helper = new THREE.SpotLightHelper( spotLight4 );
				scene.add( spotLight4 );
				scene.add( spotLight4.target );
				scene.add( spotLight4.userData.helper );

				// ---------- 灯光数组管理 ----------
				
				/**
				 * 将所有灯光对象存入数组
				 * 便于批量操作和管理
				 * 例如：统一更新、统一显示/隐藏辅助器等
				 */
				lights = [ spotLight, spotLight2, spotLight3, spotLight4 ];

				// ---------- 创建地面 ----------
				
				/**
				 * 创建Phong材质
				 * Phong材质是一种经典的光照模型材质
				 * 支持高光反射和光滑表面效果
				 */
				const material = new THREE.MeshPhongMaterial( { 
					color: 0x999999  // 材质颜色：中等灰色
					/*, dithering: true*/  // 可选：启用颜色抖动，减少低精度颜色显示的条带效应
				} );

				/**
				 * 创建平面几何体作为地面
				 * 参数：宽度200，高度200
				 */
				const geometry = new THREE.PlaneGeometry( 200, 200 );

				/**
				 * 创建网格（Mesh）对象
				 * Mesh是几何体（Geometry）和材质（Material）的组合
				 */
				const mesh = new THREE.Mesh( geometry, material );
				// 将平面绕X轴旋转-90度，使其从垂直变为水平
				// Math.PI * 0.5 = 90度，负号表示顺时针旋转
				mesh.rotation.x = - Math.PI * 0.5;
				// 启用阴影接收，地面可以接收其他物体投射的阴影
				mesh.receiveShadow = true;
				// 将地面添加到场景
				scene.add( mesh );

				// ---------- 创建立方体 ----------
				
				/**
				 * 创建立方体几何体
				 * 参数：宽度2，高度2，深度2
				 */
				const geometry2 = new THREE.BoxGeometry( 2, 2, 2 );
				// 可选：使用二十面体几何体
				// 参数：半径1，细分级别5
				//const geometry2 = new THREE.IcosahedronGeometry( 1, 5 );

				/**
				 * 创建立方体网格
				 * 使用与地面相同的材质
				 */
				const mesh2 = new THREE.Mesh( geometry2, material );
				// 将立方体放置在Y轴1单位高的位置（地面之上）
				mesh2.position.y = 1;
				// 启用阴影投射，立方体会投射阴影到地面
				mesh2.castShadow = true;
				// 将立方体添加到场景
				scene.add( mesh2 );

				// ---------- 创建渲染器 ----------
				
				/**
				 * 创建WebGPU渲染器
				 * WebGPURenderer是Three.js的WebGPU后端渲染器
				 * 相比传统的WebGLRenderer，WebGPU提供更好的性能和更现代的API
				 */
				renderer = new THREE.WebGPURenderer( { 
					antialias: true  // 启用抗锯齿，使边缘更平滑
				} );
				// 设置设备像素比，适应高DPI屏幕（如Retina显示屏）
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器尺寸为浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 设置动画循环回调函数
				// setAnimationLoop替代了旧的requestAnimationFrame方式
				// render函数会在每一帧被调用
				renderer.setAnimationLoop( render );
				// 启用阴影映射系统
				renderer.shadowMap.enabled = true;
				// 创建并附加调试检查器到渲染器
				// Inspector提供可视化界面用于调节场景参数
				renderer.inspector = new Inspector();
				// 将渲染器的canvas元素添加到页面body中
				// domElement是渲染器对应的HTMLCanvasElement
				document.body.appendChild( renderer.domElement );

				// ---------- 创建相机 ----------
				
				/**
				 * 创建透视相机（PerspectiveCamera）
				 * 透视相机模拟人眼视角，近大远小
				 * 参数：
				 *   1. 视野角度（FOV）：35度
				 *   2. 纵横比：窗口宽度/高度
				 *   3. 近裁剪面：0.1（离相机0.1单位以内的物体不显示）
				 *   4. 远裁剪面：100（离相机100单位以外的物体不显示）
				 */
				camera = new THREE.PerspectiveCamera( 
					35, 
					window.innerWidth / window.innerHeight, 
					0.1, 
					100 
				);
				// 设置相机初始位置（X, Y, Z坐标）
				camera.position.set( 16, 4, 1 );

				// ---------- 创建轨道控制器 ----------
				
				/**
				 * 创建轨道控制器（OrbitControls）
				 * 将相机和渲染器的canvas元素关联
				 * 用户可以通过鼠标控制相机视角
				 */
				const controls = new OrbitControls( camera, renderer.domElement );
				// 设置最小缩放距离，相机不能比这更靠近目标
				controls.minDistance = 2;
				// 设置最大缩放距离，相机不能比这更远离目标
				controls.maxDistance = 50;
				// 禁用平移功能，只允许旋转和缩放
				controls.enablePan = false;

				// ---------- 辅助函数：控制灯光辅助器显示 ----------
				
				/**
				 * 设置所有灯光辅助器的可见性
				 * @param {boolean} value - true显示辅助器，false隐藏辅助器
				 */
				function setHelperVisible( value ) {
					// 遍历所有灯光
					for ( let i = 0; i < lights.length; i ++ ) {
						// 设置每个灯光的辅助器可见性
						// userData是Three.js对象上的自定义数据存储
						lights[ i ].userData.helper.visible = value;
					}
				}

				// 初始化时隐藏所有灯光辅助器
				setHelperVisible( false );

				// ---------- 创建GUI控制面板 ----------
				
				/**
				 * 使用Inspector创建参数控制面板
				 * 这里创建名为"Settings"的参数组
				 */
				const gui = renderer.inspector.createParameters( 'Settings' );
				/**
				 * 添加"helper"控制项
				 * 参数1：包含helper属性的对象，初始值为false
				 * 参数2：'helper'表示要控制的属性名
				 * onChange：当值改变时的回调函数
				 */
				gui.add( { helper: false }, 'helper' ).onChange( ( v ) => setHelperVisible( v ) );

				// ---------- 窗口大小变化监听 ----------
				
				/**
				 * 监听窗口大小变化事件
				 * 当浏览器窗口大小改变时，调用onWindowResize函数
				 * 确保3D场景始终正确适配窗口尺寸
				 */
				window.addEventListener( 'resize', onWindowResize );

			}

			// ==================== 窗口大小变化处理函数 ====================
			
			/**
			 * 处理浏览器窗口大小变化的函数
			 * 当用户调整浏览器窗口大小时自动调用
			 */
			function onWindowResize() {
				// 更新相机的纵横比（aspect ratio）
				// 相机纵横比应该始终与窗口宽高比一致，避免图像拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵
				// 在修改相机参数后必须调用此方法
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸，使其与窗口新尺寸一致
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 渲染循环函数 ====================
			
			/**
			 * 主渲染循环函数
			 * 由renderer.setAnimationLoop()调用，每帧执行一次
			 * @param {number} time - 从页面加载开始经过的时间（毫秒）
			 */
			function render( time ) {
				// 将毫秒时间转换为秒，便于计算
				// 使用秒作为单位可以使动画速度与真实时间一致
				time = time / 1000;

				// ---------- 更新灯光目标位置动画 ----------
				
				/**
				 * 遍历所有灯光，更新它们的目标位置
				 * 创建灯光目标点从初始位置向中心(0,0)移动的动画
				 */
				for ( let i = 0; i < lights.length; i ++ ) {
					/**
					 * 计算插值因子t
					 * 使用正弦函数创建周期性动画
					 * (time + i)：为每个灯光添加相位偏移，使动画不同步
					 * Math.PI / 2：控制动画速度
					 * Math.sin() + 1：将正弦值从[-1,1]映射到[0,2]
					 * / 2：进一步映射到[0,1]范围
					 * t的值在0到1之间周期性变化
					 */
					const t = ( Math.sin( ( time + i ) * ( Math.PI / 2 ) ) + 1 ) / 2;

					/**
					 * 使用线性插值（Lerp）计算目标位置的X和Z坐标
					 * THREE.MathUtils.lerp(a, b, t)：在a和b之间线性插值
					 * 当t=0时返回a，当t=1时返回b
					 * 这里使灯光目标点从初始位置逐渐移动到中心(0,0)
					 */
					const x = THREE.MathUtils.lerp( lights[ i ].position.x, 0, t );
					const z = THREE.MathUtils.lerp( lights[ i ].position.z, 0, t );

					// 设置灯光目标点的X和Z坐标
					// Y坐标保持不变
					lights[ i ].target.position.x = x;
					lights[ i ].target.position.z = z;
					
					// 如果灯光有辅助器，则更新辅助器的显示
					// 辅助器需要手动更新以反映灯光属性的变化
					if ( lights[ i ].userData.helper ) {
						lights[ i ].userData.helper.update();
					}
				}

				// ---------- 执行渲染 ----------
				
				/**
				 * 调用渲染器的render方法
				 * 将3D场景通过相机视角渲染到画布上
				 * 这是整个3D渲染流程的最后一步
				 * @param {THREE.Scene} scene - 要渲染的场景
				 * @param {THREE.Camera} camera - 使用的相机
				 */
				renderer.render( scene, camera );
			}

			// ==================== 启动初始化 ====================
			
			/**
			 * 调用初始化函数启动应用
			 * 这是整个程序的入口点
			 * init()函数是异步的，内部会处理所有资源加载
			 */
			init();

		</script>

	</body>

</html>