<!-- Three.js WebGPU 选择性光照演示 - 功能详解与技术分析
🎯 项目概述
这是一个基于 Three.js WebGPU 和 TSL（Three.js Shading Language） 构建的高级3D图形演示，专门展示选择性光照技术。通过三个相同的茶壶模型，分别演示不同的光照配置方案。

📋 核心功能
1. 选择性光照演示
左侧茶壶（红色区域）：仅受红色点光源影响

中间茶壶（中央区域）：受所有四个点光源的综合影响

右侧茶壶（蓝色区域）：仅受蓝色点光源影响

2. 动态光源系统
四个不同颜色的点光源在3D空间中做复杂圆周运动

每个光源的运动轨迹使用不同的三角函数组合，形成多样化运动模式

光源可视化：每个光源附带一个小球，直观显示光源位置

3. 材质效果展示
法线贴图：中间茶壶使用水的法线贴图模拟表面凹凸细节

PBR材质参数：可实时调整的金属度和粗糙度参数

纹理映射：使用贴图控制材质的粗糙度和金属度属性

4. 场景环境效果
范围雾效：添加紫色雾效，增强场景深度感和氛围

实时交互：支持鼠标控制视角（旋转、缩放、平移）

5. 调试与开发工具
实时参数调节：通过GUI面板调整材质属性

场景检查器：集成Three.js Inspector工具，用于调试和分析

🛠️ 主要技术点
1. WebGPU 渲染器
新一代图形API：取代WebGL，提供更低的CPU开销和更好的多线程支持

GPU计算能力：支持计算着色器、光线追踪等现代图形技术

异步操作：命令缓冲区和管线状态对象的异步创建

2. TSL（Three.js Shading Language）
声明式着色器编程：使用节点连接的方式构建着色器

核心功能模块：

javascript
// 雾效系统
scene.fogNode = fog(color(0xFF00FF), rangeFogFactor(12, 30));

// 选择性光照
const redLightsNode = lights([light1]);  // 只包含红色光源
const blueLightsNode = lights([light2]); // 只包含蓝色光源

// 材质节点
material.normalNode = normalMap(texture(normalMapTexture));
material.roughnessNode = texture(alphaTexture);
3. PBR（基于物理的渲染）材质系统
金属度-粗糙度工作流：行业标准的材质表示方法

能量守恒：确保光照反射的物理准确性

微表面模型：使用GGX分布模拟真实表面散射

4. 选择性光照实现机制
javascript
// 关键技术：为不同材质分配不同的光源节点
leftObject.material.lightsNode = redLightsNode;    // 仅红色光
// 中间对象不设置lightsNode，使用场景所有光源
rightObject.material.lightsNode = blueLightsNode;  // 仅蓝色光
5. 动态动画系统
基于时间的运动：使用performance.now()获取高精度时间戳

三角函数动画：正弦和余弦函数组合创建平滑的周期性运动

参数化运动路径：每个光源有不同的频率、幅度和相位

6. 模块化架构
javascript
// 模块导入
import * as THREE from 'three/webgpu';          // WebGPU核心
import { fog, color, lights } from 'three/tsl'; // 着色器语言
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { Inspector } from 'three/addons/inspector/Inspector.js';
7. 纹理映射技术
法线贴图：在不增加几何复杂度的情况下添加表面细节

粗糙度贴图：控制表面微观粗糙度的空间变化

包裹模式：THREE.RepeatWrapping实现纹理平铺

8. 相机与控制器
透视相机：模拟人眼视角的3D投影

轨道控制器：提供直观的鼠标交互控制

视锥体裁剪：优化渲染性能，只渲染可见区域

9. 响应式设计
窗口大小自适应：监听resize事件，动态调整渲染尺寸

设备像素比适配：在高DPI显示器上保持清晰度

移动端适配：通过viewport元标签控制缩放行为

🔧 关键技术特性对比
特性	WebGL传统方式	本示例的WebGPU+TSL方式
选择性光照	需要自定义着色器	通过lights()节点声明式实现
着色器编写	手写GLSL代码	节点化可视化编程
性能优化	有限的并行处理	更好的多线程支持
开发效率	较低，需要图形学知识	较高，抽象程度更好
跨平台支持	广泛支持	需要现代浏览器支持
🎨 视觉效果层次
基础光照层：点光源提供基础照明

选择性过滤层：TSL节点过滤特定光源

材质细节层：法线贴图和PBR参数

环境效果层：雾效和后期处理

交互反馈层：实时参数调整和视角控制

📈 技术栈总结
核心框架：Three.js r158+

图形API：WebGPU（现代浏览器支持）

着色器语言：TSL（Three.js Shading Language）

材质系统：PBR金属度-粗糙度工作流

交互控制：OrbitControls + Inspector

开发范式：ES6模块 + 声明式编程

🚀 应用场景
技术演示：展示Three.js WebGPU和TSL的最新功能

教学工具：学习PBR材质和选择性光照的概念

性能测试：评估WebGPU在复杂光照场景下的表现

原型开发：快速验证3D渲染方案的技术可行性 -->


<!DOCTYPE html>
<!-- HTML5文档声明 -->
<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链接，点击跳转到three.js官网 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link">
				<!-- 这里通常会有CSS背景图片显示three.js logo -->
			</a>

			<!-- 标题包装容器，用于组织主标题和副标题 -->
			<div class="title-wrapper">
				<!-- 主标题链接：点击跳转到three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：当前示例的名称 -->
				<span>选择性光照技术演示</span>
			</div>

			<!-- 示例详细说明区域，使用small标签表示辅助信息 -->
			<small>
				<!-- 第一行说明：描述三个茶壶模型各自受哪些光源影响 -->
				<b style="color:red">左侧茶壶：仅受红色光源影响</b> - 
				<b>中间茶壶：受所有四个光源影响</b> - 
				<b style="color:blue">右侧茶壶：仅受蓝色光源影响</b>
				<!-- 换行符 -->
				<br>
				<!-- 第二行说明：交互操作提示 -->
				<em>使用鼠标左键拖拽旋转视角，滚轮缩放，右键拖拽平移</em>
				<br>
				<!-- 第三行说明：技术特性说明 -->
				<em>演示Three.js TSL（着色器语言）的选择性光照功能，四个点光源在场景中动态移动</em>
			</small>
		</div>

		<!-- Import Maps配置部分：定义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模块，type="module"表示这是一个ES6模块 -->
		<script type="module">

			// ========== 模块导入部分 ==========
			
			// 导入Three.js WebGPU核心库的所有功能
			// WebGPU是新一代图形API，比WebGL更高效，支持更多现代GPU特性
			import * as THREE from 'three/webgpu';
			
			// 从TSL模块导入特定的着色器节点函数：
			// fog - 创建雾效着色器节点
			// rangeFogFactor - 创建范围雾效因子节点
			// color - 创建颜色节点
			// lights - 创建光源节点（用于选择性光照）
			// texture - 创建纹理采样节点
			// normalMap - 创建法线贴图节点
			import { fog, rangeFogFactor, color, lights, texture, normalMap } from 'three/tsl';

			// 导入调试检查器工具，用于实时查看和修改场景参数
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器，提供鼠标交互控制相机视角的功能
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入茶壶几何体生成器，茶壶是计算机图形学中的经典测试模型
			import { TeapotGeometry } from 'three/addons/geometries/TeapotGeometry.js';

			// ========== 全局变量声明 ==========
			
			// camera - 透视相机，定义观察场景的视角和投影方式
			// scene - 场景对象，包含所有3D对象、灯光和效果
			// renderer - WebGPU渲染器，负责将3D场景渲染到2D画布
			let camera, scene, renderer;
			
			// 四个点光源变量，将用于创建动态移动的光源
			// light1 - 红色光源
			// light2 - 蓝色光源
			// light3 - 绿色光源
			// light4 - 橙色光源
			let light1, light2, light3, light4;
			
			// controls - 轨道控制器实例，用于用户与场景交互
			let controls;

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

			// ========== 初始化函数定义 ==========
			function init() {

				// ---------- 相机设置 ----------
				// 创建透视相机，模拟人眼视角
				// 参数说明：
				// 50 - 垂直视野角度（度数），值越大看到的范围越广
				// window.innerWidth / window.innerHeight - 宽高比，根据窗口尺寸计算
				// 0.01 - 近裁剪平面距离，比这个距离近的对象不会被渲染
				// 100 - 远裁剪平面距离，比这个距离远的对象不会被渲染
				camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.01, 100 );
				// 设置相机在Z轴上的初始位置，即沿视线方向向后移动7个单位
				camera.position.z = 7;

				// ---------- 场景设置 ----------
				// 创建3D场景容器，所有对象都将添加到这个场景中
				scene = new THREE.Scene();
				// 使用TSL节点设置场景雾效，增强场景的深度感和氛围
				// fog() - 创建雾效节点
				// color(0xFF00FF) - 创建紫色（红色+蓝色）颜色节点
				// rangeFogFactor(12, 30) - 创建雾效范围因子，12单位开始有雾，30单位完全被雾遮挡
				scene.fogNode = fog( color( 0xFF00FF ), rangeFogFactor( 12, 30 ) );

				// ---------- 几何体创建 ----------
				// 创建小球几何体，用于可视化光源位置
				// 参数说明：
				// 0.1 - 球体半径
				// 16 - 水平分段数（经线），值越高球体越光滑
				// 8 - 垂直分段数（纬线），值越高球体越光滑
				const sphereGeometry = new THREE.SphereGeometry( 0.1, 16, 8 );

				// ---------- 纹理加载 ----------
				// 创建纹理加载器实例，用于从URL加载图像文件作为纹理
				const textureLoader = new THREE.TextureLoader();

				// 加载法线贴图纹理
				// 法线贴图是一种用于模拟表面细节而不增加几何复杂度的技术
				// 它通过修改表面法线方向来创造凹凸不平的视觉效果
				const normalMapTexture = textureLoader.load( './textures/water/Water_1_M_Normal.jpg' );
				// 设置纹理包裹方式为重复，这样小纹理可以平铺覆盖大表面
				normalMapTexture.wrapS = THREE.RepeatWrapping;  // S方向（U方向，水平）
				normalMapTexture.wrapT = THREE.RepeatWrapping;  // T方向（V方向，垂直）

				// 加载粗糙度贴图纹理（这里命名为alphaTexture，但实际用作粗糙度贴图）
				// 粗糙度贴图控制材质表面的微观粗糙程度，影响高光反射的扩散范围
				const alphaTexture = textureLoader.load( './textures/roughness_map.jpg' );
				// 同样设置重复包裹模式
				alphaTexture.wrapS = THREE.RepeatWrapping;
				alphaTexture.wrapT = THREE.RepeatWrapping;

				// ---------- 光源创建函数 ----------
				// 定义一个可重用的函数来创建点光源及其可视化标记
				// 参数说明：
				// hexColor - 光源颜色的十六进制值
				// power - 光源功率/强度，默认1700流明
				// distance - 光源衰减距离，默认100单位
				const addLight = ( hexColor, power = 1700, distance = 100 ) => {

					// 创建标准节点材质，用于光源的可视化小球
					const material = new THREE.MeshStandardNodeMaterial();
					// 设置材质颜色节点，使用传入的十六进制颜色值
					material.colorNode = color( hexColor );
					// 禁用此材质的光照计算，因为小球只是标记，不需要被场景光照影响
					material.lights = false;

					// 创建小球网格对象，将几何体和材质组合
					const mesh = new THREE.Mesh( sphereGeometry, material );

					// 创建点光源对象
					// 参数说明：
					// hexColor - 光源颜色
					// 1 - 光源强度（这里设为1，后面会用power属性覆盖）
					// distance - 衰减距离，超过此距离光照强度降为0
					const light = new THREE.PointLight( hexColor, 1, distance );
					// 设置光源的实际功率（流明值），影响光照强度
					light.power = power;
					// 将可视化小球添加为光源的子对象，这样小球会跟随光源移动
					light.add( mesh );

					// 将光源（包含其子对象小球）添加到场景中
					scene.add( light );

					// 返回创建的光源对象，以便后续操作
					return light;

				};

				// 使用addLight函数创建四个不同颜色的点光源
				// 每个光源有不同的颜色，但使用相同的功率和衰减距离
				light1 = addLight( 0xff0040 );  // 鲜艳的红色光源
				light2 = addLight( 0x0040ff );  // 鲜艳的蓝色光源
				light3 = addLight( 0x80ff80 );  // 淡绿色光源
				light4 = addLight( 0xffaa00 );  // 橙黄色光源

				// ---------- 选择性光照节点创建 ----------
				// 使用TSL的lights()函数创建选择性光照节点
				// 这是本示例的核心功能：不同物体可以只受特定光源影响
				
				// 创建红色光源节点，只包含light1（红色光源）
				// 这个节点可以赋给材质，使该材质只受红色光源影响
				const redLightsNode = lights( [ light1 ] );
				
				// 创建蓝色光源节点，只包含light2（蓝色光源）
				// 这个节点可以赋给材质，使该材质只受蓝色光源影响
				const blueLightsNode = lights( [ light2 ] );

				// ---------- 茶壶模型创建 ----------
				// 创建茶壶几何体，这是计算机图形学的经典测试模型
				// 参数说明：
				// .8 - 茶壶的尺寸/半径
				// 18 - 细分等级，值越高茶壶表面越光滑
				const geometryTeapot = new TeapotGeometry( .8, 18 );

				// 创建左侧茶壶（只受红色光源影响）
				// 创建网格对象，包含茶壶几何体和标准节点材质
				const leftObject = new THREE.Mesh( geometryTeapot, new THREE.MeshStandardNodeMaterial( { color: 0x555555 } ) );
				// 设置材质的光照节点为红色光源节点，实现选择性光照
				leftObject.material.lightsNode = redLightsNode;
				// 设置粗糙度节点为纹理节点，使用alphaTexture控制粗糙度
				leftObject.material.roughnessNode = texture( alphaTexture );
				// 设置金属度为0，表示这是一个非金属材质（电介质）
				leftObject.material.metalness = 0;
				// 将茶壶放置在X轴负方向3个单位处（左侧）
				leftObject.position.x = - 3;
				// 将茶壶添加到场景中
				scene.add( leftObject );

				// 创建中间茶壶（受所有四个光源影响）
				// 使用默认的标准节点材质，不特别设置lightsNode，因此受场景所有光源影响
				const centerObject = new THREE.Mesh( geometryTeapot, new THREE.MeshStandardNodeMaterial( { color: 0x555555 } ) );
				// 设置法线贴图节点，为茶壶表面添加细节
				// normalMap()函数将2D法线贴图纹理转换为法线向量
				centerObject.material.normalNode = normalMap( texture( normalMapTexture ) );
				// 设置金属度为0.5，表示这是一个半金属材质
				centerObject.material.metalness = .5;
				// 设置粗糙度为0.5，中等粗糙度表面
				centerObject.material.roughness = .5;
				// 添加到场景中（默认位置在原点）
				scene.add( centerObject );

				// 创建右侧茶壶（只受蓝色光源影响）
				const rightObject = new THREE.Mesh( geometryTeapot, new THREE.MeshStandardNodeMaterial( { color: 0x555555 } ) );
				// 设置材质的光照节点为蓝色光源节点
				rightObject.material.lightsNode = blueLightsNode;
				// 设置金属度节点为纹理节点，使用alphaTexture控制金属度
				// 注意：这里将粗糙度贴图用作金属度贴图，实际应用中应使用专门的金属度贴图
				rightObject.material.metalnessNode = texture( alphaTexture );
				// 将茶壶放置在X轴正方向3个单位处（右侧）
				rightObject.position.x = 3;
				// 添加到场景中
				scene.add( rightObject );

				// 统一调整三个茶壶的旋转和垂直位置
				// 将所有茶壶绕Y轴旋转-90度（-π/2弧度），使茶壶嘴朝右
				leftObject.rotation.y = centerObject.rotation.y = rightObject.rotation.y = Math.PI * - 0.5;
				// 将所有茶壶向下移动1个单位，使它们不在场景正中心
				leftObject.position.y = centerObject.position.y = rightObject.position.y = - 1;

				// ---------- 渲染器设置 ----------
				// 创建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.inspector = new Inspector();
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ---------- 控制器设置 ----------
				// 创建轨道控制器，连接相机和渲染器的DOM元素
				// 这使得用户可以通过鼠标与场景交互
				controls = new OrbitControls( camera, renderer.domElement );
				// 设置最小缩放距离，防止相机离物体太近
				controls.minDistance = 3;
				// 设置最大缩放距离，防止相机离物体太远
				controls.maxDistance = 25;

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

				// ---------- 图形用户界面（GUI）设置 ----------
				// 从渲染器的检查器创建参数面板，标题为'Material'
				const gui = renderer.inspector.createParameters( 'Material' );

				// 在GUI中添加控制中间茶壶粗糙度的滑块
				// 参数说明：
				// centerObject.material - 要控制的对象
				// 'roughness' - 要控制的属性名
				// 0 - 最小值
				// 1 - 最大值
				// 0.01 - 步进值
				gui.add( centerObject.material, 'roughness', 0, 1, 0.01 );
				
				// 在GUI中添加控制中间茶壶金属度的滑块
				gui.add( centerObject.material, 'metalness', 0, 1, 0.01 );

			} // init函数结束

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

				// 更新相机的宽高比，使用新的窗口尺寸计算
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵，这是必要的步骤，否则渲染会变形
				camera.updateProjectionMatrix();

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

			}

			// ========== 动画循环函数 ==========
			// 这个函数会在每一帧被调用（通常每秒60次）
			function animate() {

				// 获取当前时间（从页面加载开始计算的秒数）
				// performance.now()返回以毫秒为单位的高精度时间戳
				const time = performance.now() / 1000;
				// 使用较慢的时间系数控制光源运动速度
				const lightTime = time * 0.5;

				// ---------- 光源动画 ----------
				// 为每个光源设置周期性运动路径
				// 使用三角函数（sin, cos）创建圆周/椭圆运动
				// 每个光源使用不同的频率和幅度组合，创造多样化运动
				
				// 红色光源（light1）的运动路径
				// X轴：sin(lightTime*0.7)*3，频率0.7，幅度3
				// Y轴：cos(lightTime*0.5)*4，频率0.5，幅度4
				// Z轴：cos(lightTime*0.3)*3，频率0.3，幅度3
				light1.position.x = Math.sin( lightTime * 0.7 ) * 3;
				light1.position.y = Math.cos( lightTime * 0.5 ) * 4;
				light1.position.z = Math.cos( lightTime * 0.3 ) * 3;

				// 蓝色光源（light2）的运动路径
				// 使用不同的三角函数组合，与light1形成对比运动
				light2.position.x = Math.cos( lightTime * 0.3 ) * 3;
				light2.position.y = Math.sin( lightTime * 0.5 ) * 4;
				light2.position.z = Math.sin( lightTime * 0.7 ) * 3;

				// 绿色光源（light3）的运动路径
				light3.position.x = Math.sin( lightTime * 0.7 ) * 3;
				light3.position.y = Math.cos( lightTime * 0.3 ) * 4;
				light3.position.z = Math.sin( lightTime * 0.5 ) * 3;

				// 橙色光源（light4）的运动路径
				light4.position.x = Math.sin( lightTime * 0.3 ) * 3;
				light4.position.y = Math.cos( lightTime * 0.7 ) * 4;
				light4.position.z = Math.sin( lightTime * 0.5 ) * 3;

				/*
				注释掉的代码段：原本用于测试动态光源添加功能
				
				设计目的：在特定时间点将光源逐个添加到场景中
				当前状态：由于TSL（Three.js Shading Language）的限制，
				          动态更改场景中的光源目前不可用
				未来计划：Three.js团队可能会在未来版本中支持此功能
				
				逻辑说明：
				- 当时间超过2.0秒且light1不在场景中时，将light1添加到场景
				- 当时间超过2.5秒且light2不在场景中时，将light2添加到场景
				- 当时间超过3.0秒且light3不在场景中时，将light3添加到场景
				- 当时间超过3.5秒且light4不在场景中时，将light4添加到场景
				
				代码原型：
				if ( time > 2.0 && light1.parent === null ) scene.add( light1 );
				if ( time > 2.5 && light2.parent === null ) scene.add( light2 );
				if ( time > 3.0 && light3.parent === null ) scene.add( light3 );
				if ( time > 3.5 && light4.parent === null ) scene.add( light4 );
				*/

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

			} // animate函数结束

		</script>
		<!-- 脚本结束 -->
	</body>
	<!-- 文档主体结束 -->
</html>
<!-- HTML文档结束 -->