<!-- Three.js点光源阴影映射演示 - 功能描述与技术要点
一、项目功能概述
1. 核心功能
这是一个动态点光源阴影映射的Three.js演示项目，主要展示：

两个彩色点光源（蓝色和红色）在3D空间中的动态运动

实时阴影效果：光源照射物体产生的动态阴影

交互式3D场景：用户可通过鼠标控制相机视角

视觉化光源表现：光源本身具有多层可视化效果

2. 场景构成
立方体房间：30x30x30的立方体作为场景容器

两个点光源：蓝色(0x0088ff)和红色(0xff8888)光源

环境光：深蓝色环境光提供基础照明

光源视觉化：每个光源包含核心球体和外层发光球体

3. 交互特性
相机控制：鼠标左键旋转、右键平移、滚轮缩放

自适应布局：窗口大小变化时自动调整渲染尺寸

实时性能监控：显示FPS、渲染时间等性能指标

二、主要技术要点
1. 阴影系统技术
javascript
// 关键阴影配置
light.castShadow = true;                    // 启用阴影投射
light.shadow.bias = -0.005;                 // 阴影偏移，解决自阴影问题
light.shadow.mapSize.width = 128;           // 阴影贴图尺寸
light.shadow.radius = 10;                   // 阴影模糊半径
renderer.shadowMap.enabled = true;          // 渲染器启用阴影
技术解析：

Shadow Bias：微小的负偏移防止物体表面错误地给自己投射阴影

Shadow Map Size：128x128的贴图尺寸，平衡性能与质量

Shadow Radius：PCF软阴影模糊，隐藏低分辨率阴影的锯齿

2. 光源视觉化技术
javascript
// 双层光源结构
1. 核心球体（内层）：半径为0.3，显示光源颜色
2. 发光球体（外层）：半径为2，使用alpha贴图的半透明材质

// Alpha贴图生成
const texture = new THREE.CanvasTexture(generateTexture());
texture.alphaMap: 控制透明度的2x2像素纹理
技术解析：

Alpha测试：alphaTest: 0.5，alpha值小于0.5的像素完全透明

纹理重复：repeat.set(1, 4.5)，垂直方向重复4.5次

Canvas纹理：动态生成2x2像素纹理，上半透明下半不透明

3. 动态动画系统
javascript
// 正弦波运动算法
pointLight.position.x = Math.sin(time * 0.6) * 9;
pointLight.position.y = Math.sin(time * 0.7) * 9 + 6;
pointLight.position.z = Math.sin(time * 0.8) * 9;

// 时间偏移实现异步运动
pointLight2: time += 10000;  // 10秒时间偏移
技术解析：

Lissajous曲线：不同频率的正弦波组合创造复杂3D轨迹

相位差设计：不同坐标轴使用不同频率(0.6, 0.7, 0.8)

异步运动：第二个光源的时间偏移创造非对称运动模式

4. 材质与渲染技术
javascript
// 立方体材质配置
side: THREE.BackSide       // 只渲染背面（房间内部）
shininess: 10              // 高光亮度
specular: 0x111111         // 高光颜色

// 光源外层材质
side: THREE.DoubleSide     // 双面渲染
alphaMap: texture          // 透明度贴图
alphaTest: 0.5             // Alpha测试阈值
技术解析：

背面渲染：立方体作为房间，只需渲染内部表面

冯氏材质：MeshPhongMaterial支持高光和镜面反射

双面渲染：光源球体需要内外表面都可见

5. 性能优化技术
javascript
// 性能相关配置
renderer.setPixelRatio(window.devicePixelRatio);  // 适配高DPI屏幕
stats = new Stats();                              // 性能监控
renderer.setAnimationLoop(animate);              // 现代动画循环
技术解析：

设备像素比适配：确保在高分辨率屏幕上清晰显示

性能监控集成：实时显示帧率、内存使用等信息

高效动画循环：使用setAnimationLoop替代传统requestAnimationFrame

6. 响应式设计技术
javascript
// 窗口大小变化处理
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();  // 更新相机投影
    renderer.setSize(window.innerWidth, window.innerHeight);
}
技术解析：

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

渲染器尺寸同步：画布尺寸与窗口尺寸保持一致

三、关键技术挑战与解决方案
1. 自阴影问题 (Self-Shadowing)
问题：低精度阴影贴图导致物体表面产生错误阴影
解决方案：shadow.bias = -0.005 微小负偏移

2. 阴影质量与性能平衡
问题：高分辨率阴影贴图性能消耗大
解决方案：

使用128x128低分辨率阴影贴图

通过shadow.radius = 10模糊处理隐藏锯齿

3. 光源视觉表现
问题：点光源本身不可见，需要视觉化表示
解决方案：

内层实体球体表示光源位置

外层半透明球体表示光照范围

4. 动态光照效果
问题：静态光源缺乏视觉吸引力
解决方案：

正弦波轨迹创造自然运动

不同相位创造复杂运动模式

四、应用场景与扩展
1. 实际应用
游戏开发：动态环境光照系统

产品展示：多角度光源展示产品

数据可视化：三维数据的光照强调

建筑渲染：室内光照效果预览

2. 技术扩展方向
添加更多光源类型（聚光灯、平行光）

实现阴影级联（CSM）提升远处阴影质量

集成后期处理（辉光、色彩校正）

添加物理材质（PBR）提升真实感

3. 性能优化建议
阴影贴图缓存：静态物体阴影预计算

视锥体裁剪：只渲染可见区域的光源

LOD系统：根据距离调整阴影质量 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示为"Three.js点光源阴影映射演示" -->
		<title>Three.js点光源阴影映射演示</title>
		<!-- 字符编码：UTF-8支持中文 -->
		<meta charset="utf-8">
		<!-- 
			视口设置：确保在移动设备上正确显示
			width=device-width: 宽度等于设备宽度
			user-scalable=no: 禁止用户缩放页面
			minimum-scale=1.0: 最小缩放比例为1
			maximum-scale=1.0: 最大缩放比例为1
		-->
		<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="main.css">
	</head>
	<body>
		<!-- 
			信息显示区域：显示页面标题和相关信息
			id="info": 用于CSS样式和JavaScript操作
		-->
		<div id="info">
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - 点光源阴影映射技术演示
		</div>

		<!-- 
			模块导入映射(Import Map)
			现代浏览器模块系统配置，用于指定模块导入路径
			type="importmap": 声明这是导入映射配置
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript代码模块
			type="module": 声明这是一个ES6模块，支持import/export语法
		-->
		<script type="module">
			// 导入Three.js核心库的所有功能
			// THREE是Three.js的主要命名空间
			import * as THREE from 'three';

			// 导入性能监视器模块
			// Stats用于显示帧率等性能指标，方便性能优化和调试
			import Stats from 'three/addons/libs/stats.module.js';

			// 导入轨道控制器模块
			// OrbitControls允许用户用鼠标和触摸屏控制相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 全局变量声明
			// camera: 相机对象，决定观察场景的视角
			// scene: 场景对象，包含所有3D对象、灯光和相机
			// renderer: 渲染器对象，负责将3D场景渲染到2D画布
			// stats: 性能统计对象，用于监控渲染性能
			// pointLight, pointLight2: 两个点光源对象
			let camera, scene, renderer, stats;
			let pointLight, pointLight2;

			// 调用初始化函数，启动应用
			init();

			/**
			 * 初始化函数
			 * 这是整个Three.js应用的入口点，负责创建和设置所有必要的组件
			 * 包括场景、相机、灯光、几何体、材质、渲染器等
			 * 注意：这是一个立即调用的函数
			 */
			function init() {
				// 创建透视相机(PerspectiveCamera)
				// 参数说明：
				// 45: 视野角度(Field of View, FOV)，单位是度，45度接近人眼视野
				// window.innerWidth/window.innerHeight: 宽高比，确保渲染不拉伸
				// 1: 近裁剪面(near clipping plane)，距离相机小于1的对象不显示
				// 1000: 远裁剪面(far clipping plane)，距离相机大于1000的对象不显示
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 1, 1000);
				
				// 设置相机在三维空间中的位置(x, y, z坐标)
				// 这里将相机放置在(0, 10, 40)的位置
				// x=0: 水平居中，y=10: 高度为10，z=40: 距离场景40个单位
				camera.position.set(0, 10, 40);

				// 创建场景对象
				// 场景是所有3D对象的容器，包括网格、灯光、相机等
				scene = new THREE.Scene();
				
				// 添加环境光(AmbientLight)
				// 参数说明：
				// 0x111122: 环境光颜色，这里是深蓝色调的暗色
				// 3: 环境光强度，数值越大光照越强
				// 环境光没有方向，会给所有物体均匀照明，减少阴影中的死黑区域
				scene.add(new THREE.AmbientLight(0x111122, 3));

				// ==================== 灯光创建部分 ====================
				
				/**
				 * 创建点光源的工厂函数
				 * 这个函数封装了点光源的创建和配置过程，便于重复使用
				 * @param {number} color - 光源的颜色，使用十六进制表示(如0x0088ff)
				 * @returns {THREE.PointLight} 返回配置好的点光源对象
				 */
				function createLight(color) {
					// 光源强度，决定光照的亮度
					const intensity = 200;

					// 创建点光源(PointLight)
					// 参数说明：
					// color: 光源颜色
					// intensity: 光源强度
					// 20: 光源衰减距离，超过此距离光照强度降为0
					const light = new THREE.PointLight(color, intensity, 20);
					
					// 启用阴影投射：这个光源可以产生阴影
					light.castShadow = true;
					
					// 阴影偏移(shadow bias)
					// -0.005: 微小的负偏移，可以减少自阴影(self-shadowing)问题
					// 自阴影是当物体自身表面错误地投射阴影到自己上的问题
					light.shadow.bias = -0.005;
					
					// 阴影贴图尺寸：决定阴影的质量
					// 较大的尺寸会产生更清晰的阴影，但消耗更多内存和性能
					light.shadow.mapSize.width = 128;
					
					// 阴影模糊半径：控制阴影边缘的模糊程度
					// 值越大阴影越模糊，可以隐藏低分辨率阴影贴图的锯齿
					light.shadow.radius = 10;

					// ====== 创建光源的视觉表示 ======
					
					// 创建一个小球体作为光源核心的视觉表示
					// SphereGeometry参数：半径0.3，宽度分段数12，高度分段数6
					let geometry = new THREE.SphereGeometry(0.3, 12, 6);
					
					// 创建基本材质，不受光照影响，始终显示指定颜色
					let material = new THREE.MeshBasicMaterial({ color: color });
					
					// 增强材质亮度，使其视觉上匹配光源的实际亮度
					// multiplyScalar将颜色的每个分量乘以标量值
					material.color.multiplyScalar(intensity);
					
					// 创建网格(Mesh)：几何体和材质的组合
					let sphere = new THREE.Mesh(geometry, material);
					
					// 将小球添加到光源中，使其成为光源的子对象
					// 这样小球会随着光源一起移动和旋转
					light.add(sphere);

					// ====== 创建光源的外层发光效果 ======
					
					// 调用generateTexture函数创建自定义透明纹理
					const texture = new THREE.CanvasTexture(generateTexture());
					
					// 设置纹理的放大过滤器为最近邻过滤
					// NearestFilter在纹理放大时保持像素清晰，不进行插值
					texture.magFilter = THREE.NearestFilter;
					
					// 设置纹理在T方向(垂直方向)的包裹方式为重复包裹
					// RepeatWrapping允许纹理在超出范围时重复平铺
					texture.wrapT = THREE.RepeatWrapping;
					
					// 设置纹理在S方向(水平方向)的包裹方式为重复包裹
					texture.wrapS = THREE.RepeatWrapping;
					
					// 设置纹理的重复次数：水平方向1次，垂直方向4.5次
					// 这会影响纹理在球体表面的分布
					texture.repeat.set(1, 4.5);

					// 创建外层球体几何体，半径2，分段数较高以获得平滑外观
					geometry = new THREE.SphereGeometry(2, 32, 8);
					
					// 创建冯氏(Phong)材质，受光照影响，有高光效果
					material = new THREE.MeshPhongMaterial({
						side: THREE.DoubleSide,  // 双面渲染：内外表面都渲染
						alphaMap: texture,       // 透明度贴图：控制哪些部分透明
						alphaTest: 0.5           // Alpha测试阈值：alpha值小于0.5的像素不渲染
					});

					// 创建外层球体网格
					sphere = new THREE.Mesh(geometry, material);
					
					// 启用阴影投射和接收
					// 外层球体既能投射阴影，也能接收其他物体的阴影
					sphere.castShadow = true;
					sphere.receiveShadow = true;
					
					// 将外层球体添加到光源中
					light.add(sphere);

					// 返回完整配置的光源对象
					return light;
				}

				// 创建蓝色点光源并添加到场景中
				// 0x0088ff是蓝色，表示冷色调光源
				pointLight = createLight(0x0088ff);
				scene.add(pointLight);

				// 创建红色点光源并添加到场景中
				// 0xff8888是红色，表示暖色调光源
				pointLight2 = createLight(0xff8888);
				scene.add(pointLight2);

				// ==================== 场景几何体创建部分 ====================
				
				// 创建立方体几何体，作为场景的"房间"或"容器"
				// 参数：宽度30，高度30，深度30
				const geometry = new THREE.BoxGeometry(30, 30, 30);

				// 创建冯氏材质，具有高光效果
				const material = new THREE.MeshPhongMaterial({
					color: 0xa0adaf,       // 材质基础颜色，浅灰蓝色
					shininess: 10,         // 高光亮度，值越大高光点越小越亮
					specular: 0x111111,    // 高光颜色，深灰色
					side: THREE.BackSide   // 只渲染背面（使立方体内部可见）
				});

				// 创建立方体网格
				const mesh = new THREE.Mesh(geometry, material);
				
				// 将立方体向上移动10个单位，使其处于合适的位置
				mesh.position.y = 10;
				
				// 启用阴影接收：立方体可以接收其他物体投射的阴影
				mesh.receiveShadow = true;
				
				// 将立方体添加到场景中
				scene.add(mesh);

				// ==================== 渲染器创建和配置部分 ====================
				
				// 创建WebGL渲染器
				// { antialias: true }: 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGLRenderer({ antialias: true });
				
				// 设置设备像素比，确保在高DPI屏幕上清晰显示
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为整个浏览器窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环，animate函数将被持续调用
				// 这是Three.js的推荐做法，替代传统的requestAnimationFrame
				renderer.setAnimationLoop(animate);
				
				// 启用阴影贴图功能
				renderer.shadowMap.enabled = true;
				
				// 可选：设置阴影贴图类型
				// BasicShadowMap: 基本阴影贴图，无滤镜，性能好但质量低
				// PCFShadowMap: 默认值，使用百分比渐进滤镜，质量较好
				// PCFSoftShadowMap: 软阴影，质量最好但性能消耗大
				// 这里注释掉了，使用Three.js的默认设置
				// renderer.shadowMap.type = THREE.BasicShadowMap;
				
				// 将渲染器的DOM元素(Canvas画布)添加到页面body中
				document.body.appendChild(renderer.domElement);

				// ==================== 用户交互控制部分 ====================
				
				// 创建轨道控制器
				// 参数：要控制的相机，交互的DOM元素
				const controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置控制器的目标点，即相机围绕哪个点旋转
				controls.target.set(0, 10, 0);
				
				// 更新控制器状态
				controls.update();

				// ==================== 性能监控部分 ====================
				
				// 创建性能监视器
				stats = new Stats();
				
				// 将性能监视器的DOM元素添加到页面中
				// 默认显示FPS(帧率)、MS(渲染时间)、MB(内存使用)
				document.body.appendChild(stats.dom);

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

			/**
			 * 窗口大小变化事件处理函数
			 * 当浏览器窗口大小改变时，确保渲染正确适应新尺寸
			 */
			function onWindowResize() {
				// 更新相机的宽高比，防止图像拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机参数改变后，必须调用此方法使更改生效
				camera.updateProjectionMatrix();

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

			/**
			 * 生成自定义纹理的函数
			 * 创建一个简单的2x2像素的Canvas纹理，用于alpha贴图
			 * 这个纹理决定外层球体哪些部分透明，哪些部分不透明
			 * 纹理样式：上半部分透明，下半部分不透明
			 * 
			 * @returns {HTMLCanvasElement} 包含生成纹理的Canvas元素
			 */
			function generateTexture() {
				// 创建一个新的Canvas元素
				const canvas = document.createElement('canvas');
				
				// 设置Canvas尺寸为2x2像素
				// 小尺寸纹理可以节省内存，并通过重复平铺覆盖整个球体
				canvas.width = 2;
				canvas.height = 2;

				// 获取2D渲染上下文
				const context = canvas.getContext('2d');
				
				// 设置填充颜色为白色（不透明）
				context.fillStyle = 'white';
				
				// 填充Canvas的一部分（从(0,1)位置开始，填充2x1的区域）
				// 这会使Canvas的下半部分为白色，上半部分为透明
				// 当用作alpha贴图时，白色部分不透明，透明部分透明
				context.fillRect(0, 1, 2, 1);

				// 返回Canvas元素
				return canvas;
			}

			/**
			 * 动画循环函数
			 * 这是Three.js应用的核心，每帧都会被调用
			 * 负责更新动画状态和渲染场景
			 * 使用performance.now()获取高精度时间戳
			 */
			function animate() {
				// 获取当前时间并转换为秒
				// performance.now()返回页面加载以来的毫秒数
				// 乘以0.001转换为秒，便于在三角函数中使用
				let time = performance.now() * 0.001;

				// ====== 更新第一个点光源(蓝色)的位置和旋转 ======
				
				// 使用正弦函数创建周期性运动
				// Math.sin(time * 频率) * 振幅
				// 不同坐标轴使用不同频率，创造复杂的3D运动轨迹
				pointLight.position.x = Math.sin(time * 0.6) * 9;  // X轴：频率0.6，振幅9
				pointLight.position.y = Math.sin(time * 0.7) * 9 + 6;  // Y轴：频率0.7，振幅9，偏移+6
				pointLight.position.z = Math.sin(time * 0.8) * 9;  // Z轴：频率0.8，振幅9
				
				// 更新光源的旋转
				// 随时间线性增加旋转角度
				pointLight.rotation.x = time;  // X轴旋转
				pointLight.rotation.z = time;  // Z轴旋转

				// 为第二个光源添加时间偏移，使其运动与第一个光源不同步
				// 这样两个光源不会完全同步移动，产生更丰富的视觉效果
				time += 10000;

				// ====== 更新第二个点光源(红色)的位置和旋转 ======
				
				// 使用相同的运动公式，但基于偏移后的时间
				pointLight2.position.x = Math.sin(time * 0.6) * 9;
				pointLight2.position.y = Math.sin(time * 0.7) * 9 + 6;
				pointLight2.position.z = Math.sin(time * 0.8) * 9;
				
				// 更新光源的旋转
				pointLight2.rotation.x = time;
				pointLight2.rotation.z = time;

				// ====== 渲染场景 ======
				
				// 调用渲染器的render方法，将3D场景渲染到2D画布
				// 参数：要渲染的场景，要使用的相机
				renderer.render(scene, camera);

				// 更新性能监视器
				// 必须在每帧调用，以更新显示的性能数据
				stats.update();
			}
		</script>
	</body>
</html>