<!-- Three.js WebGPU 分块照明技术演示 - 详细功能说明
🎯 整体功能概述
这是一个基于WebGPU的实时3D渲染演示，展示了分块照明(Tiled Lighting)技术如何高效处理1000个动态点光源。演示通过先进的光照优化算法，实现了在保持高性能的同时渲染大量动态光源的效果。

🌟 核心功能模块
1. 分块照明系统 (Tiled Lighting)
技术特点：

空间分割：将屏幕分割成32x32像素的瓦片

光源剪裁：每个瓦片只计算影响该区域的有限光源

计算着色器：利用GPU并行计算优势

性能优化：将光照计算复杂度从O(n)降低到接近O(1)

解决的问题：传统前向渲染中，每个像素需要计算所有光源的影响，当光源数量增加时性能急剧下降。

2. WebGPU渲染引擎
技术特点：

下一代图形API：取代WebGL，提供更低开销和更好性能

原生计算着色器支持：分块照明的核心依赖

跨平台兼容：支持Chrome、Edge、Firefox等现代浏览器

现代GPU特性：支持最新的图形硬件功能

3. 动态光源系统
实现效果：

1000个独立点光源：随机颜色和位置

波动动画：每个光源沿正弦波路径运动

实时更新：每帧更新所有光源位置和可视化

实例化渲染：高效绘制光源可视化点

4. 视觉效果系统
包含技术：

材质系统
TSL节点材质：使用Three.js着色器语言

法线贴图：为地板增加细节和质感

纹理平铺：UV坐标缩放，创建重复图案

后处理效果
Bloom泛光：高亮区域产生光晕效果

色调映射：NeutralToneMapping，将HDR转换为显示范围

可调节曝光：曝光值设为5，增强视觉效果

环境效果
雾效(Fog)：线性雾效，增强场景深度感

环境光照：微弱的环境光，补充阴影区域

🔧 关键技术实现细节
1. 性能优化技术
技术	作用	效果
分块照明	减少每像素光照计算量	从1000次/像素 → 约10-20次/像素
实例化渲染	减少Draw Call数量	1000个光源 → 1个Draw Call
WebGPU计算着色器	并行处理光源剪裁	CPU计算 → GPU并行计算
2. 动画系统实现
javascript
// 每个光源的独特动画公式
light.position.x = 初始X + sin(时间×0.7 + 光源ID) × 3
light.position.y = 1 + cos(时间×0.5 + 光源ID) × 0.5
light.position.z = 初始Z + cos(时间×0.3 + 光源ID) × 3
参数化运动：每个光源有不同的频率和相位

平滑过渡：使用三角函数确保运动连续性

3. 渲染管线流程
text
1. 几何处理
   ↓
2. 分块照明计算（计算着色器）
   ↓
3. 前向渲染（每个瓦片独立光照）
   ↓
4. 后处理效果（Bloom、色调映射）
   ↓
5. 调试信息叠加（可选）
   ↓
6. 屏幕输出
4. 调试和可视化功能
瓦片索引可视化：显示分块照明的工作方式

实时参数调节：通过GUI调整效果参数

轨道控制器：交互式相机控制

性能监控：内置的调试信息显示

🚀 技术亮点和创新点
1. 大规模动态光照
挑战：实时渲染1000个动态点光源

解决方案：分块照明 + WebGPU计算着色器

成果：在主流GPU上保持60FPS

2. 现代渲染架构
声明式着色器：使用TSL节点系统

模块化后处理：可组合的渲染效果

可扩展设计：易于添加新光源类型

3. 跨平台兼容性
渐进增强：检测WebGPU支持

优雅降级：提供明确的不支持信息

响应式设计：适应不同屏幕尺寸

4. 教育价值
技术展示：演示现代实时渲染技术

代码清晰：良好注释的结构化代码

交互学习：实时调整参数观察效果变化

📊 性能对比优势
场景	传统前向渲染	分块照明	提升倍数
100光源	100次/像素	~32次/像素	3倍
500光源	500次/像素	~32次/像素	15倍
1000光源	1000次/像素	~32次/像素	30倍
注：实际提升取决于光源分布和瓦片大小

🎨 视觉效果层次
基础层
几何体：地面平面 + 1000个球体

纹理：棋盘格颜色贴图 + 法线贴图

基础光照：环境光 + 1000个点光源

增强层
动态效果：光源波动动画

后处理：Bloom泛光增强视觉冲击

氛围：雾效创造深度感

调试层
技术可视化：显示照明瓦片

参数控制：实时调整效果参数

交互控制：自由视角探索

🔍 应用场景和意义
适用场景
游戏开发：大规模动态光照场景

数据可视化：大量数据点的3D展示

模拟仿真：粒子系统或群集模拟

技术演示：图形编程教学和研究

技术意义
前沿技术展示：WebGPU在实际项目中的应用

性能优化范例：大规模实时渲染的解决方案

教育价值：学习现代图形编程的完整示例

标准参考：Three.js高级功能的使用规范 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：Three.js WebGPU - 分块照明技术演示 -->
		<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官方网站链接，点击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>分块照明技术演示</span>
			</div>

			<!-- 示例描述文字 -->
			<small>
				<!-- 描述内容：这是一个基于GPU计算的自定义分块照明系统 -->
				这是一个基于GPU计算的自定义分块照明系统。可以高效处理大量动态光源。
			</small>

		</div>

		<!-- 模块导入映射配置：定义JavaScript模块的路径别名 -->
		<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模块：类型设置为module，支持ES6模块语法 -->
		<script type="module">

			// ==================== 模块导入区域 ====================
			
			// 导入Three.js WebGPU核心模块，* 表示导入所有导出内容
			import * as THREE from 'three/webgpu';
			
			// 从TSL模块导入特定的着色器节点构建函数：
			// texture - 纹理采样节点
			// uv - UV坐标节点
			// pass - 渲染通道节点
			// normalMap - 法线贴图节点
			// uniform - 统一值节点（可调参数）
			import { texture, uv, pass, normalMap, uniform } from 'three/tsl';
			
			// 导入泛光（Bloom）后处理效果节点
			import { bloom } from 'three/addons/tsl/display/BloomNode.js';

			// 导入分块照明系统核心类
			import { TiledLighting } from 'three/addons/lighting/TiledLighting.js';

			// 导入调试检查器，用于创建实时参数调节界面
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器，实现鼠标交互控制相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入WebGPU能力检测模块，检查浏览器是否支持WebGPU
			import WebGPU from 'three/addons/capabilities/WebGPU.js';

			// ==================== 全局变量声明区域 ====================
			
			// 相机对象：控制观察场景的视角
			let camera;
			
			// 场景对象：包含所有3D物体、灯光、相机等
			let scene;
			
			// 渲染器对象：负责将3D场景渲染到2D画布上
			let renderer;
			
			// 灯光组：包含所有点光源的容器
			let lights;
			
			// 灯光可视化代理：用于显示灯光位置的实例化网格
			let lightDummy;
			
			// 轨道控制器：处理用户鼠标/触摸输入
			let controls;
			
			// 后处理合成相关：
			// compose - 后处理合成节点树
			// tileInfluence - 瓦片索引可视化强度控制参数
			let compose, tileInfluence;
			
			// 分块照明系统实例
			let lighting;
			
			// 场景中的灯光数量
			let count;
			
			// 后处理系统对象
			let postProcessing;

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

			/**
			 * 初始化函数 - 应用程序的入口点
			 * 负责创建场景、相机、渲染器、灯光等所有必要组件
			 */
			function init() {

				// ========== WebGPU兼容性检测 ==========
				
				// 检测当前浏览器是否支持WebGPU
				if ( WebGPU.isAvailable() === false ) {
					// 如果不支持WebGPU，获取错误信息HTML元素
					const errorMessage = WebGPU.getErrorMessage();
					// 将错误信息添加到页面body中
					document.body.appendChild( errorMessage );
					// 抛出错误，停止程序执行
					throw new Error( '当前浏览器不支持WebGPU，请使用最新版本的Chrome、Edge或Firefox浏览器' );
				}

				// ========== 相机设置 ==========
				
				// 创建透视相机（Perspective Camera）
				// 参数说明：
				// 50 - 垂直视野角度（FOV），单位度
				// window.innerWidth / window.innerHeight - 相机纵横比
				// 0.1 - 近裁剪平面距离（小于此距离的物体不渲染）
				// 600 - 远裁剪平面距离（大于此距离的物体不渲染）
				camera = new THREE.PerspectiveCamera( 
					50, 
					window.innerWidth / window.innerHeight, 
					0.1, 
					600 
				);
				
				// 设置相机初始位置
				camera.position.z = 200;  // Z轴向后200单位
				camera.position.y = 30;   // Y轴向上30单位

				// ========== 场景设置 ==========
				
				// 创建3D场景容器
				scene = new THREE.Scene();
				
				// 添加雾效（Fog），增强场景深度感和氛围
				// 参数说明：
				// 0x111111 - 雾的颜色（深灰色）
				// 300 - 雾开始的距离
				// 500 - 雾完全遮挡物体的距离
				scene.fog = new THREE.Fog( 0x111111, 300, 500 );
				
				// 设置场景背景颜色（深灰色）
				scene.background = new THREE.Color( 0x111111 );

				// ========== 灯光系统初始化 ==========
				
				// 设置场景中灯光的数量
				count = 1000;

				// 创建基础材质，用于灯光可视化
				const material = new THREE.MeshBasicMaterial();

				// 创建实例化网格（InstancedMesh）用于高效渲染灯光可视化点
				// 参数说明：
				// new THREE.SphereGeometry( 0.1, 16, 8 ) - 球体几何体，半径0.1，16经度分段，8纬度分段
				// material - 使用的材质
				// count - 实例数量，与灯光数量相同
				lightDummy = new THREE.InstancedMesh( 
					new THREE.SphereGeometry( 0.1, 16, 8 ), 
					material, 
					count 
				);
				
				// 设置实例矩阵的使用方式为动态绘制，便于每帧更新位置
				lightDummy.instanceMatrix.setUsage( THREE.DynamicDrawUsage );
				
				// 将灯光可视化网格添加到场景中
				scene.add( lightDummy );

				// 创建灯光组容器，用于管理所有点光源
				lights = new THREE.Group();
				scene.add( lights );

				/**
				 * 创建点光源的辅助函数
				 * @param {number} hexColor - 光源颜色（十六进制）
				 * @param {number} power - 光源强度，默认10
				 * @param {number} distance - 光源照射距离，默认3
				 * @returns {THREE.PointLight} 创建的点光源对象
				 */
				const addLight = ( hexColor, power = 10, distance = 3 ) => {
					
					// 创建点光源对象
					// 参数说明：
					// hexColor - 光源颜色
					// 1 - 光源强度（后面会通过power属性覆盖）
					// distance - 衰减距离
					const light = new THREE.PointLight( hexColor, 1, distance );
					
					// 随机设置光源的初始位置
					// X轴：-150到150之间的随机值
					// Y轴：固定为1（贴近地面）
					// Z轴：-150到150之间的随机值
					light.position.set( 
						Math.random() * 300 - 150, 
						1, 
						Math.random() * 300 - 150 
					);
					
					// 设置光源的实际功率（亮度）
					light.power = power;
					
					// 保存光源的初始位置，用于动画计算
					// 使用clone()创建副本，避免引用问题
					light.userData.fixedPosition = light.position.clone();
					
					// 将光源添加到灯光组中
					lights.add( light );

					// 返回创建的光源对象
					return light;
				};

				// 创建颜色对象，用于颜色计算
				const color = new THREE.Color();

				// 循环创建指定数量的灯光
				for ( let i = 0; i < count; i ++ ) {
					
					// 生成随机颜色
					// Math.random() * 0xffffff - 生成0到0xffffff之间的随机数
					// + 0x666666 - 确保颜色不会太暗（至少包含0x66的亮度分量）
					const hex = ( Math.random() * 0xffffff ) + 0x666666;

					// 设置实例化网格中每个实例的颜色
					// setColorAt(index, color) - 设置指定索引实例的颜色
					lightDummy.setColorAt( i, color.setHex( hex ) );

					// 创建实际的点光源
					addLight( hex );
				}

				// 添加环境光（Ambient Light）
				// 参数说明：
				// 0xffffff - 白色环境光
				// 0.1 - 环境光强度（较弱）
				const lightAmbient = new THREE.AmbientLight( 0xffffff, .1 );
				scene.add( lightAmbient );

				// ========== 纹理和材质设置 ==========
				
				// 创建纹理加载器
				const textureLoader = new THREE.TextureLoader();

				// 加载地面颜色纹理（棋盘格地板）
				const floorColor = textureLoader.load( 'textures/floors/FloorsCheckerboard_S_Diffuse.jpg' );
				// 设置纹理水平方向重复包裹
				floorColor.wrapS = THREE.RepeatWrapping;
				// 设置纹理垂直方向重复包裹
				floorColor.wrapT = THREE.RepeatWrapping;
				// 设置纹理颜色空间为sRGB（符合人眼感知）
				floorColor.colorSpace = THREE.SRGBColorSpace;

				// 加载地面法线纹理（用于法线贴图）
				const floorNormal = textureLoader.load( 'textures/floors/FloorsCheckerboard_S_Normal.jpg' );
				floorNormal.wrapS = THREE.RepeatWrapping;
				floorNormal.wrapT = THREE.RepeatWrapping;

				// 创建UV坐标缩放节点
				// uv() - 获取默认UV坐标（0-1范围）
				// .mul(50) - 乘以50，使纹理重复50次（创建平铺效果）
				const uvTile = uv().mul( 50 );

				// 创建地面几何体（1000x1000单位的平面）
				const planeGeometry = new THREE.PlaneGeometry( 1000, 1000 );
				
				// 创建Phong节点材质（使用TSL节点系统）
				const planeMaterial = new THREE.MeshPhongNodeMaterial( {
					// 颜色节点：采样地板颜色纹理，使用平铺后的UV坐标
					colorNode: texture( floorColor, uvTile ),
					// 法线节点：法线贴图节点，采样地板法线纹理
					normalNode: normalMap( texture( floorNormal, uvTile ) ),
				} );

				// 创建地面网格对象
				const ground = new THREE.Mesh( planeGeometry, planeMaterial );
				// 旋转平面使其水平（绕X轴旋转-90度）
				ground.rotation.x = - Math.PI / 2;
				// 设置地面Y轴位置为0
				ground.position.y = 0;
				// 允许地面投射阴影
				ground.castShadow = true;
				// 允许地面接收阴影
				ground.receiveShadow = true;
				// 将地面添加到场景中
				scene.add( ground );

				// ========== 渲染器设置 ==========
				
				// 创建分块照明系统实例
				// 参数说明（括号内为默认值）：
				// maxLights = 1024 - 最大支持的灯光数量
				// tileSize = 32 - 每个瓦片的像素大小
				lighting = new TiledLighting(); // ( maxLights = 1024, tileSize = 32 )

				// 创建WebGPU渲染器
				// 参数说明：{ antialias: true } - 开启抗锯齿
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置渲染器像素比（适配高DPI屏幕）
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数（每帧调用animate函数）
				renderer.setAnimationLoop( animate );
				
				// 将分块照明系统附加到渲染器上
				renderer.lighting = lighting;
				
				// 设置色调映射为中性色调映射
				renderer.toneMapping = THREE.NeutralToneMapping;
				
				// 设置色调映射曝光值（5表示较亮的曝光）
				renderer.toneMappingExposure = 5;
				
				// 创建调试检查器并附加到渲染器
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ========== 控制器设置 ==========
				
				// 创建轨道控制器
				// 参数说明：
				// camera - 要控制的相机对象
				// renderer.domElement - 监听事件的DOM元素（canvas）
				controls = new OrbitControls( camera, renderer.domElement );
				
				// 设置相机最大缩放距离（防止相机离场景太远）
				controls.maxDistance = 400;

				// ========== 事件监听器设置 ==========
				
				// 监听窗口大小变化事件，调整渲染器和相机
				window.addEventListener( 'resize', onWindowResize );

				// ========== 后处理设置 ==========
				
				// 创建场景渲染通道节点
				// pass(scene, camera) - 创建一个渲染场景的节点
				const scenePass = pass( scene, camera );
				
				// 创建Bloom（泛光）后处理节点
				// 参数说明：
				// scenePass - 输入的场景渲染结果
				// 3 - Bloom的强度
				// 0.9 - 阈值（亮度高于此值的区域会产生泛光）
				// 0.2 - 平滑度（泛光边缘的柔和程度）
				const bloomPass = bloom( scenePass, 3, .9, .2 );

				// 合成节点：将场景渲染和Bloom效果组合
				compose = scenePass.add( bloomPass );
				
				// 创建统一值节点，用于控制瓦片索引可视化的强度
				// uniform(0) - 创建初始值为0的统一值
				tileInfluence = uniform( 0 );

				// 创建后处理系统
				postProcessing = new THREE.PostProcessing( renderer );

				// 初始化后处理配置
				updatePostProcessing();

				// ========== 调试界面设置 ==========
				
				// 从检查器创建参数面板，标题为"设置"
				const gui = renderer.inspector.createParameters( '设置' );
				
				// 添加滑块控件，控制瓦片索引调试显示强度
				// 参数说明：
				// tileInfluence - 控制的目标对象
				// 'value' - 控制的属性名
				// 0, 1 - 滑块的最小值和最大值
				// 'tile indexes debug' - 控件显示的名称
				gui.add( tileInfluence, 'value', 0, 1 ).name( '瓦片索引调试显示强度' );
			}

			/**
			 * 更新后处理配置函数
			 * 在窗口大小变化或初始化时调用，重新计算后处理节点
			 */
			function updatePostProcessing() {
				
				// 获取分块照明系统的调试节点链：
				// 1. lighting.getNode(scene, camera) - 获取分块照明节点
				// 2. .setSize() - 设置节点尺寸为当前渲染尺寸
				//    window.innerWidth * window.devicePixelRatio - 实际像素宽度
				//    window.innerHeight * window.devicePixelRatio - 实际像素高度
				// 3. .getBlock() - 获取瓦片索引数据块
				// 4. .toColor() - 将数据转换为颜色
				// 5. .div(count * 2) - 除以灯光数量的两倍进行归一化
				const debugBlockIndexes = lighting.getNode( scene, camera )
					.setSize( 
						window.innerWidth * window.devicePixelRatio, 
						window.innerHeight * window.devicePixelRatio 
					)
					.getBlock()
					.toColor()
					.div( count * 2 );

				// 设置后处理系统的输出节点：
				// compose - 基础合成（场景 + Bloom）
				// .add() - 添加调试节点
				// debugBlockIndexes.mul(tileInfluence) - 调试节点乘以影响系数
				//   当tileInfluence为0时，调试效果完全透明
				//   当tileInfluence为1时，调试效果完全显示
				postProcessing.outputNode = compose.add( debugBlockIndexes.mul( tileInfluence ) );
				
				// 标记后处理系统需要更新（节点图发生变化）
				postProcessing.needsUpdate = true;
			}

			/**
			 * 窗口大小变化事件处理函数
			 * 调整相机和渲染器以适应新的窗口尺寸
			 */
			function onWindowResize() {
				
				// 更新相机的纵横比为新的窗口宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵（必须调用，否则渲染会出错）
				camera.updateProjectionMatrix();

				// 更新渲染器的尺寸为新的窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );

				// 更新后处理配置（尺寸变化需要重新计算）
				updatePostProcessing();
			}

			/**
			 * 动画循环函数 - 每帧调用
			 * 负责更新场景中的动画状态和渲染
			 */
			function animate() {
				
				// 获取当前时间（单位：秒）
				// performance.now()返回从页面加载开始的高精度时间戳（毫秒）
				// 除以1000转换为秒
				const time = performance.now() / 1000;

				// 遍历所有灯光，更新它们的位置（创建波动动画效果）
				for ( let i = 0; i < lights.children.length; i ++ ) {
					
					// 获取当前灯光对象
					const light = lights.children[ i ];
					
					// 为每个灯光计算独特的时间偏移
					// time * 0.5 - 整体时间缩放，减慢动画速度
					// + light.id - 使用灯光的唯一ID作为相位偏移，使每个灯光运动不同步
					const lightTime = ( time * 0.5 ) + light.id;

					// 将灯光位置重置到初始位置
					light.position.copy( light.userData.fixedPosition );
					
					// 添加正弦波动动画：
					// X轴：使用sin函数，频率0.7，振幅3
					light.position.x += Math.sin( lightTime * 0.7 ) * 3;
					// Y轴：使用cos函数，频率0.5，振幅0.5
					light.position.y += Math.cos( lightTime * 0.5 ) * .5;
					// Z轴：使用cos函数，频率0.3，振幅3
					light.position.z += Math.cos( lightTime * 0.3 ) * 3;

					// 更新灯光可视化实例的变换矩阵
					// 将灯光的世界变换矩阵设置到实例化网格的对应实例
					lightDummy.setMatrixAt( i, light.matrixWorld );
				}

				// 执行后处理渲染
				// 这会触发整个渲染管线：场景渲染 -> 后处理效果 -> 输出到屏幕
				postProcessing.render();
			}

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