<!-- Three.js WebGPU 点光源阴影演示 - 详细功能与技术点分析
一、总体功能概述
这是一个基于Three.js WebGPU渲染器的高级3D图形演示程序，主要展示动态点光源的阴影效果和WebGPU渲染技术。程序创建了一个交互式的3D场景，包含两个沿复杂轨迹运动的彩色点光源，这些光源在立方体房间内投射动态阴影，用户可以通过鼠标自由控制视角观察效果。

二、核心功能模块
1. 场景与相机系统
透视相机：45度视野角，1-1000单位的视锥体范围

三维场景：包含环境光、点光源、立方体房间等所有3D元素

交互控制：集成OrbitControls，支持鼠标拖拽旋转、滚轮缩放

2. 光源系统
两个动态点光源：

蓝色光源（0x0088ff）和红色光源（0xff8888）

各自包含复杂的视觉层次：发光核心+半透明外壳

沿三维正弦波轨迹周期性运动

环境光：提供基础照明，创造整体氛围

3. 阴影系统
实时阴影映射：点光源产生的动态阴影

阴影优化：

偏移(bias)设置防止自阴影伪影

模糊半径(radius)实现软阴影效果

可配置的阴影贴图分辨率

4. 视觉效果
立方体房间：作为阴影接收表面，展示阴影投射效果

光源视觉增强：双层球体结构（实体核心+条纹半透明外壳）

条纹透明度贴图：自定义2x2像素纹理创建的光源辉光效果

三、关键技术要点
1. WebGPU渲染技术
下一代图形API：取代WebGL，提供更好的性能和现代GPU特性支持

异步初始化：await renderer.init() 处理WebGPU设备的异步获取

抗锯齿支持：antialias: true 配置实现边缘平滑

2. 阴影映射技术
javascript
// 关键技术配置
light.castShadow = true;                    // 启用阴影
light.shadow.bias = -0.005;                // 阴影偏移（解决自阴影）
light.shadow.mapSize.width = 128;          // 阴影贴图分辨率
light.shadow.radius = 10;                   // 阴影模糊半径
renderer.shadowMap.enabled = true;         // 启用渲染器阴影支持
3. 材质与纹理技术
MeshPhongNodeMaterial：节点化材质系统，支持复杂材质配置

透明度贴图(Alpha Map)：使用Canvas生成的2x2纹理控制透明度

双面渲染：THREE.DoubleSide 使光源外壳内外可见

Alpha测试：alphaTest: 0.5 实现硬性透明度裁切

4. 动画系统
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;
三维Lissajous曲线：不同频率的正弦波创造复杂轨迹

时间偏移：time += 10000 使两个光源运动不同步

连续旋转：光源自身随时间匀速旋转

5. 性能优化技术
Stats.js集成：实时监控帧率(FPS)和渲染性能

自适应分辨率：setPixelRatio(devicePixelRatio) 匹配高DPI屏幕

响应式设计：窗口大小变化时自动调整相机和渲染器

阴影贴图优化：平衡质量与性能的128x128分辨率

6. 自定义纹理生成
javascript
// 动态生成2x2透明度贴图
function generateTexture() {
    const canvas = document.createElement('canvas');
    canvas.width = 2; canvas.height = 2;
    const ctx = canvas.getContext('2d');
    ctx.fillStyle = 'white';
    ctx.fillRect(0, 1, 2, 1); // 填充下半部分像素
    return canvas;
}
极简纹理：最小2x2像素纹理通过重复创建图案

条纹效果：黑白相间产生半透明条纹

Canvas API集成：动态生成纹理数据

四、技术架构特点
1. 模块化设计
ES6模块导入：使用import/export语法组织代码

Import Maps：配置模块路径映射，简化导入语句

函数封装：createLight()函数复用光源创建逻辑

2. 异步编程模型
javascript
async function init() {
    await renderer.init(); // 等待WebGPU设备初始化
    // 其他初始化代码...
}
async/await：处理WebGPU的异步初始化

错误处理：内置异步错误捕获机制

3. 事件驱动架构
窗口大小监听：resize事件响应浏览器窗口变化

动画循环：setAnimationLoop()替代requestAnimationFrame

用户交互：OrbitControls监听鼠标和触摸事件

五、渲染流程
初始化阶段：创建场景、相机、灯光、材质等基础元素

资源加载：异步初始化WebGPU渲染器，生成纹理

动画循环：

更新时间变量

计算光源新位置和旋转

更新控制器状态

渲染场景到画布

更新性能统计

用户交互：实时响应鼠标控制，更新相机视角 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 文档类型和HTML版本声明，告知浏览器使用HTML5规范解析 -->
		<!DOCTYPE html>
		
		<!-- 设置文档语言为英语 -->
		<html lang="en">
		
		<!-- 页面标题：显示在浏览器标签页上 -->
		<title>Three.js WebGPU技术演示 - 点光源阴影映射效果</title>
		
		<!-- 字符编码设置：使用UTF-8编码支持多语言字符 -->
		<meta charset="utf-8">
		
		<!-- 视口(viewport)设置：确保页面在移动设备上正确显示 -->
		<!-- 
			width=device-width: 宽度等于设备宽度
			user-scalable=no: 禁止用户缩放（为了保持WebGL画布尺寸稳定）
			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="main.css">
	</head>
	<body>
		<!-- 
			信息显示区域：显示项目信息和链接
			id="info"：用于CSS样式和JavaScript操作
		-->
		<div id="info">
			<!-- 
				Three.js官网链接：
				href="https://threejs.org"：目标网址
				target="_blank"：在新标签页打开
				rel="noopener"：安全措施，防止新页面访问原页面的window对象
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - WebGPU渲染技术 - 点光源阴影映射效果展示
			<br>
			<small>使用鼠标拖拽旋转视角，滚轮缩放，体验动态光影效果</small>
		</div>

		<!-- 
			Import Maps：现代JavaScript模块导入映射配置
			作用：定义模块名称与对应文件路径的映射关系
			注意：type="importmap"表示这是一个导入映射配置
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.webgpu.js",
					
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：使用type="module"表示这是ES6模块
			模块化的好处：支持导入导出，避免全局变量污染，更好的代码组织
		-->
		<script type="module">

			// ============ 模块导入部分 ============
			
			// 导入Three.js核心库的所有功能
			// * as THREE：将整个模块重命名为THREE对象，方便访问
			import * as THREE from 'three';

			// 导入性能统计模块
			// Stats：用于显示帧率(FPS)、渲染时间等性能指标
			// 通常显示在页面左上角，绿色表示性能良好，黄色/红色表示性能问题
			import Stats from 'three/addons/libs/stats.module.js';

			// 导入轨道控制器（用于交互式控制相机）
			// OrbitControls：允许用户通过鼠标拖拽、滚轮缩放来控制相机视角
			// 类似于3D建模软件中的视图控制
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ============ 全局变量声明部分 ============
			
			// camera：透视相机，用于定义3D场景的观察视角
			// scene：场景对象，包含所有3D物体、灯光、相机等
			// renderer：WebGPU渲染器，负责将3D场景渲染到2D画布上
			// stats：性能统计器实例
			let camera, scene, renderer, stats;
			
			// pointLight, pointLight2：两个点光源实例
			// 点光源特点：从单个点向所有方向均匀发射光线（类似灯泡）
			let pointLight, pointLight2;

			// ============ 初始化函数调用 ============
			
			// 页面加载完成后立即调用初始化函数
			// 注意：这里调用的是异步函数init()
			init();

			// ============ 异步初始化函数 ============
			
			// async function：异步函数声明，用于处理可能耗时的操作（如WebGPU初始化）
			async function init() {

				// ============ 相机设置 ============
				
				// 创建透视相机(PerspectiveCamera)
				// 参数详解：
				//   1. fov (45): 视野角度（Field of View），单位是度
				//      - 较小的值产生望远镜效果（视角狭窄）
				//      - 较大的值产生广角镜效果（视角宽广）
				//   2. aspect: 宽高比 = 窗口宽度 / 窗口高度
				//      - 确保渲染画面不被拉伸变形
				//   3. near (1): 近裁剪面距离，相机看不到比这更近的物体
				//   4. far (1000): 远裁剪面距离，相机看不到比这更远的物体
				//      - near和far定义相机的可视范围，称为视锥体(frustum)
				camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 1000 );
				
				// 设置相机初始位置：set(x, y, z)
				// x=0: 中心位置
				// y=10: 向上偏移10个单位（俯视场景）
				// z=40: 向后偏移40个单位（拉远视角）
				camera.position.set( 0, 10, 40 );

				// ============ 场景设置 ============
				
				// 创建3D场景：所有物体、灯光、相机的容器
				scene = new THREE.Scene();
				
				// 添加环境光(AmbientLight)：提供均匀的基础照明
				// 参数详解：
				//   1. 颜色(0x111122): 十六进制RGB颜色，深蓝色调
				//      - 0x表示十六进制
				//      - 11: 红色分量（非常低）
				//      - 11: 绿色分量（非常低）
				//      - 22: 蓝色分量（较低）
				//   2. 强度(3): 光照强度，值越大越亮
				// 环境光特点：没有方向，均匀照亮所有物体，不产生阴影
				scene.add( new THREE.AmbientLight( 0x111122, 3 ) );

				// ============ 灯光创建函数 ============
				
				// 函数功能：创建包含视觉表示的点光源
				// 参数color：灯光颜色（十六进制）
				function createLight( color ) {

					// 灯光强度：控制光线亮度
					// 注意：点光源强度需要较高值才能在远距离照亮物体
					const intensity = 200;

					// ===== 创建点光源核心 =====
					
					// 创建点光源(PointLight)
					// 参数详解：
					//   1. color: 灯光颜色
					//   2. intensity: 光照强度
					//   3. distance(20): 光线传播距离，超过此距离光线衰减为0
					const light = new THREE.PointLight( color, intensity, 20 );
					
					// 启用阴影投射：该光源能够产生阴影
					// 注意：启用阴影会显著增加渲染计算量
					light.castShadow = true;
					
					// 设置阴影偏移(bias)：解决自阴影问题
					// 原理：轻微偏移阴影计算位置，避免物体自身的阴影投射到自身上
					// 负值(-0.005)：将阴影向外偏移
					light.shadow.bias = - 0.005;
					
					// 设置阴影贴图尺寸：决定阴影质量
					// 值越大阴影越清晰，但内存占用和计算量也越大
					// 128x128：相对较低的分辨率，产生较柔和的阴影边缘
					light.shadow.mapSize.width = 128;
					
					// 设置阴影模糊半径：控制阴影边缘的模糊程度
					// 值越大阴影边缘越模糊，可以隐藏低分辨率阴影贴图的锯齿
					light.shadow.radius = 10;

					// ===== 创建光源核心视觉表示（内层小球）=====
					
					// 创建球体几何体：表示光源的核心
					// 参数详解：
					//   1. radius(0.3): 球体半径，较小表示光源核心
					//   2. widthSegments(12): 水平分段数，控制球体平滑度
					//   3. heightSegments(6): 垂直分段数，控制球体平滑度
					let geometry = new THREE.SphereGeometry( 0.3, 12, 6 );
					
					// 创建基础材质(MeshBasicMaterial)：不受光照影响的自发光材质
					// 参数：{ color: color } - 设置材质颜色与灯光颜色一致
					let material = new THREE.MeshBasicMaterial( { color: color } );
					
					// 调整材质颜色亮度：乘以强度值，使强光源看起来更亮
					// multiplyScalar()：向量/颜色标量乘法
					material.color.multiplyScalar( intensity );
					
					// 创建网格(Mesh)：将几何体和材质结合成可渲染的物体
					let sphere = new THREE.Mesh( geometry, material );
					
					// 将小球添加到光源对象中
					// 注意：光源对象可以像普通3D对象一样添加子对象
					light.add( sphere );

					// ===== 创建透明度贴图 =====
					
					// 生成2x2像素的Canvas纹理（调用下面定义的generateTexture函数）
					const texture = new THREE.CanvasTexture( generateTexture() );
					
					// 设置纹理放大过滤器：当纹理被放大时如何采样
					// NearestFilter：最近邻过滤，保持像素感，适合低分辨率纹理
					texture.magFilter = THREE.NearestFilter;
					
					// 设置纹理包裹方式：定义纹理坐标超出[0,1]范围时的行为
					// RepeatWrapping：重复纹理，创建平铺效果
					texture.wrapT = THREE.RepeatWrapping; // T方向（垂直/纵向）
					texture.wrapS = THREE.RepeatWrapping; // S方向（水平/横向）
					
					// 设置纹理重复次数：控制纹理的密度
					// set(1, 4.5): 水平不重复，垂直重复4.5次（创建条纹效果）
					texture.repeat.set( 1, 4.5 );

					// ===== 创建光源外层球体（半透明外壳）=====
					
					// 创建更大的球体几何体：作为光源的外层辉光效果
					geometry = new THREE.SphereGeometry( 2, 32, 8 ); // 半径2，更细分更平滑
					
					// 创建冯氏节点材质(MeshPhongNodeMaterial)：受光照影响的材质
					// NodeMaterial：Three.js的节点化材质系统，支持更复杂的材质配置
					material = new THREE.MeshPhongNodeMaterial( {
						side: THREE.DoubleSide,    // 双面渲染：内外表面都渲染
						alphaMap: texture,         // 透明度贴图：控制哪些部分透明
						alphaTest: 0.5             // 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 );

				// ============ 创建场景背景（立方体房间）============
				
				// 创建立方体几何体：作为房间的墙壁
				// 参数详解：
				//   1. width(30): X轴方向宽度
				//   2. height(30): Y轴方向高度
				//   3. depth(30): Z轴方向深度
				const geometry = new THREE.BoxGeometry( 30, 30, 30 );

				// 创建冯氏节点材质：用于房间墙壁
				const material = new THREE.MeshPhongNodeMaterial( {
					color: 0xa0adaf,      // 材质颜色：浅蓝灰色（十六进制）
					shininess: 10,        // 光泽度：控制高光大小，值越小高光越扩散
					specular: 0x111111,   // 镜面反射颜色：深灰色，产生细微高光
					side: THREE.BackSide  // 只渲染背面：使立方体内部可见（从内部看墙壁）
				} );

				// 创建立方体网格
				const mesh = new THREE.Mesh( geometry, material );
				
				// 设置立方体位置：Y轴上移10个单位
				mesh.position.y = 10;
				
				// 启用阴影接收：房间墙壁会接收其他物体的阴影
				mesh.receiveShadow = true;
				
				// 将立方体房间添加到场景
				scene.add( mesh );

				// ============ 创建WebGPU渲染器 ============
				
				// 创建WebGPURenderer：使用现代WebGPU API的渲染器
				// 参数：{ antialias: true } - 启用抗锯齿，平滑边缘锯齿
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置设备像素比：匹配屏幕的物理像素与CSS像素比例
				// 提高高DPI屏幕（如Retina屏）的渲染质量
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸：与浏览器窗口相同大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环函数：每次重绘时调用animate函数
				// 替代传统的requestAnimationFrame
				renderer.setAnimationLoop( animate );
				
				// 启用阴影映射：渲染器支持阴影计算
				renderer.shadowMap.enabled = true;
				
				// 可选：设置阴影映射类型（当前被注释）
				// BasicShadowMap: 基础阴影，无过滤，性能最好但质量最低
				// PCFShadowMap: 软阴影（默认），质量较好
				// PCFSoftShadowMap: 更软的阴影，质量最好但性能消耗最大
				// renderer.shadowMap.type = THREE.BasicShadowMap;
				
				// 异步初始化WebGPU渲染器：WebGPU API需要异步初始化
				await renderer.init();
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ============ 创建交互控制器 ============
				
				// 创建轨道控制器(OrbitControls)
				// 参数：
				//   1. camera: 要控制的相机对象
				//   2. renderer.domElement: 事件监听的DOM元素（canvas画布）
				const controls = new OrbitControls( camera, renderer.domElement );
				
				// 设置控制器目标点：相机围绕旋转的中心点
				// set(0, 10, 0): 场景中心偏上位置
				controls.target.set( 0, 10, 0 );
				
				// 更新控制器内部状态（必须调用）
				controls.update();

				// ============ 创建性能统计器 ============
				
				// 创建Stats实例：用于监控渲染性能
				stats = new Stats();
				
				// 将统计器的DOM元素添加到页面
				// 默认显示帧率(FPS)面板
				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，用于生成条纹透明度贴图
			function generateTexture() {

				// 创建Canvas元素：用于2D绘图
				const canvas = document.createElement( 'canvas' );
				
				// 设置Canvas尺寸：2像素宽 x 2像素高
				// 非常小的纹理，通过重复(repeat)创建图案
				canvas.width = 2;
				canvas.height = 2;

				// 获取2D绘图上下文：用于在Canvas上绘制
				const context = canvas.getContext( '2d' );
				
				// 设置填充颜色：白色（在透明度贴图中，白色表示不透明）
				context.fillStyle = 'white';
				
				// 绘制矩形：创建条纹图案
				// fillRect(x, y, width, height)参数：
				//   x=0: 起始X坐标
				//   y=1: 起始Y坐标（从第二行开始）
				//   width=2: 宽度2像素
				//   height=1: 高度1像素
				// 效果：填充Canvas的下半部分（第2行），上半部分（第1行）保持透明
				// 当纹理垂直重复时，会创建黑白相间的条纹效果
				context.fillRect( 0, 1, 2, 1 );

				// 返回Canvas元素，用于创建纹理
				return canvas;

			}

			// ============ 动画循环函数 ============
			
			// 函数功能：每一帧渲染时调用，更新动画状态并渲染场景
			// 注意：此函数由renderer.setAnimationLoop(animate)自动调用
			function animate() {

				// 获取当前时间：从页面加载开始的秒数
				// performance.now(): 返回高精度时间戳（毫秒）
				// * 0.001: 转换为秒，便于三角函数计算
				let time = performance.now() * 0.001;

				// ===== 更新第一个（蓝色）点光源 =====
				
				// 使用正弦函数创建周期性运动
				// 原理：sin函数产生-1到1的平滑振荡
				// 公式：振幅 * sin(频率 * time) + 偏移量
				
				// X轴位置：以9为振幅，0.6为频率的正弦波
				pointLight.position.x = Math.sin( time * 0.6 ) * 9;
				
				// Y轴位置：以9为振幅，0.7为频率的正弦波，加上6的垂直偏移
				// 不同频率使运动轨迹更复杂
				pointLight.position.y = Math.sin( time * 0.7 ) * 9 + 6;
				
				// Z轴位置：以9为振幅，0.8为频率的正弦波
				pointLight.position.z = Math.sin( time * 0.8 ) * 9;

				// 设置光源自身旋转：随时间匀速旋转
				pointLight.rotation.x = time; // 绕X轴旋转
				pointLight.rotation.z = time; // 绕Z轴旋转

				// ===== 更新第二个（红色）点光源 =====
				
				// 添加时间偏移：使第二个光源与第一个光源运动不同步
				// +10000秒：产生完全不同的运动相位
				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;

				// ===== 渲染场景 =====
				
				// 调用渲染器渲染一帧
				// 参数：
				//   1. scene: 要渲染的场景
				//   2. camera: 使用的相机视角
				renderer.render( scene, camera );

				// ===== 更新性能统计器 =====
				
				// 更新统计器显示：计算并显示当前帧率等性能指标
				stats.update();

			}

		</script>
	</body>
</html>