<!-- Three.js WebGPU Phong光照模型演示
一、项目概述
这是一个基于Three.js和WebGPU的Phong光照模型技术演示应用。项目展示了现代Web图形编程的核心技术，通过三个茶壶模型分别演示不同的光照和材质效果，帮助用户理解计算机图形学中的光照原理。

二、核心功能模块
1. 场景与相机系统
透视相机：模拟人眼视角，支持近大远小的真实视觉效果

场景管理：包含所有3D对象、灯光和雾效的统一容器

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

2. 光照系统演示
四盏动态点光源：

蓝色光源（light1）：仅影响左侧茶壶

白色光源（light2）：仅影响右侧茶壶

绿色光源（light3）：影响所有茶壶

橙色光源（light4）：影响所有茶壶

灯光动画：所有灯光沿复杂的三维正弦轨迹运动，展示动态光照效果

3. 材质效果对比
三个茶壶分别展示不同的材质和光照配置：

茶壶位置	光照配置	材质效果	技术要点
左侧茶壶	仅受蓝色光影响	粗糙度贴图控制高光	选择性光照、贴图采样
中间茶壶	受所有灯光影响	法线贴图增加表面细节	法线映射、默认光照
右侧茶壶	仅受白光影响	棋盘格图案高光	动态纹理生成、选择性光照
4. 交互功能
轨道控制器：支持鼠标拖拽旋转、滚轮缩放

实时调试：集成Three.js Inspector工具

自适应布局：全屏渲染，随窗口大小自动调整

三、主要技术点详解
1. WebGPU渲染管线
javascript
// 使用WebGPU作为渲染后端
renderer = new THREE.WebGPURenderer({ antialias: true });
现代图形API：替代WebGL，提供更好的性能和更低的开销

抗锯齿支持：边缘平滑处理

GPU计算优化：更好的并行处理能力

2. TSL（Three.js Shader Language）节点系统
javascript
import { color, fog, checker, mix, texture, lights, normalMap } from 'three/tsl';
声明式着色器编程：使用节点构建着色器，无需编写GLSL/HLSL代码

可视化着色器逻辑：节点连接表示数据流

类型安全：编译时检查着色器错误

3. Phong光照模型实现
javascript
const material = new THREE.MeshPhongNodeMaterial({ color: 0x555555 });
环境光 + 漫反射 + 镜面反射：完整Phong模型

光泽度控制：shininess参数调节高光大小

法线计算：基于顶点法线的光照计算

4. 选择性光照控制
javascript
// 创建选择性灯光节点
const blueLightsNode = lights([light1]);
const whiteLightsNode = lights([light2]);

// 应用到材质
leftObject.material.lightsNode = blueLightsNode;
灯光分组：灵活控制哪些光源影响特定物体

性能优化：减少不必要的照明计算

5. 纹理与贴图技术
法线贴图：在不增加多边形数量的情况下模拟表面细节

粗糙度贴图：控制表面的微观粗糙度

棋盘格纹理：动态生成的程序化纹理

纹理重复：RepeatWrapping实现平铺效果

6. 雾效实现
javascript
scene.fogNode = fog(color(0xFF00FF), rangeFogFactor(12, 30));
范围雾：基于距离的雾效渐变

颜色雾：紫色雾增强场景氛围

深度提示：增强场景的立体感和距离感

7. 动画系统
javascript
// 基于时间的三角函数动画
light1.position.x = Math.sin(lightTime * 0.7) * 3;
时间驱动：使用performance.now()获取精确时间

三角函数运动：产生平滑的周期性动画

参数化控制：不同频率和幅度产生多样运动

8. 模块化架构
javascript
// ES6模块导入
import * as THREE from 'three/webgpu';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
代码组织：清晰的模块划分

依赖管理：通过importmap配置模块路径

可维护性：便于功能扩展和修改

四、技术亮点
1. 现代图形技术栈
WebGPU + Three.js + TSL节点系统

完全基于现代浏览器标准，无需插件

2. 实时图形效果
60FPS的流畅动画

实时光照计算

动态材质更新

3. 教育资源价值
清晰的代码结构和详细注释

分步骤的技术演示

可交互的学习体验

4. 跨平台兼容性
桌面和移动浏览器支持

响应式设计适配不同屏幕

渐进增强的图形功能

五、应用场景
图形学教学：理解Phong光照模型的原理

技术演示：展示WebGPU和Three.js的最新功能

性能测试：评估WebGPU在不同设备上的表现

创意原型：快速构建3D可视化应用的基础框架

六、技术挑战与解决方案
挑战	解决方案
WebGPU兼容性	渐进增强，提供备选方案
复杂着色器逻辑	使用TSL节点简化开发
性能优化	选择性光照，减少计算量
跨平台适配	响应式设计和像素比适配 -->


<!DOCTYPE html>
<!-- HTML5文档声明 -->
<html lang="zh-CN">
	<!-- head部分包含文档的元数据和链接资源 -->
	<head>
		<!-- 页面标题：显示在浏览器标签页上的文本 -->
		<title>Three.js WebGPU - Phong光照模型演示</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">
		<!-- 
			viewport参数详解：
			- width=device-width: 视口宽度等于设备宽度
			- user-scalable=no: 禁止用户手动缩放页面
			- minimum-scale=1.0: 最小缩放比例为1（不缩放）
			- maximum-scale=1.0: 最大缩放比例为1（不缩放）
			这些设置确保页面在移动设备上以固定比例显示，适合WebGL/WebGPU应用
		-->
		
		<!-- 引入外部CSS样式表，用于页面样式和布局 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	
	<!-- body部分包含页面所有可见内容 -->
	<body>

		<!-- 
			id为"info"的信息显示区域
			这个div包含页面的标题、说明文字和链接
			使用了中文内容，更符合中文用户的使用习惯
		-->
		<div id="info">
			<!-- 
				Three.js官方链接，点击跳转到Three.js官网
				class="logo-link"通常用于添加Three.js的logo样式
				target="_blank"：在新标签页打开链接
				rel="noopener"：安全设置，防止新页面访问原页面的window对象
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装容器，用于组织标题内容 -->
			<div class="title-wrapper">
				<!-- 
					主标题链接：点击跳转到Three.js官网
					这里保留了英文"three.js"作为技术标识
				-->
				<a href="https://threejs.org/" target="_blank" rel="noopener">three.js</a>
				<!-- 
					副标题：用中文明确说明演示内容
					"Phong光照模型"是计算机图形学中的经典光照模型
				-->
				<span> - Phong光照模型演示</span>
			</div>

			<!-- 
				详细说明区域，使用<small>标签表示次要信息
				解释场景中三个茶壶的不同光照设置
				使用中文说明，更清晰易懂
			-->
			<small>
				<!-- 
					使用<b>标签加粗重要信息
					使用内联style设置颜色，突出显示不同灯光效果
				-->
				<b style="color:red">左侧茶壶: 仅受蓝色灯光影响</b> - 
				<b>中间茶壶: 受所有灯光影响</b> - 
				<b style="color:blue">右侧茶壶: 仅受白色灯光影响</b>
				<br> <!-- 换行，添加更多说明 -->
				<em>灯光会动态移动，茶壶使用不同的材质和贴图效果</em>
			</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模块，支持import/export语法
			模块代码在严格模式下运行，有自己的作用域
		-->
		<script type="module">

			// ==================== 模块导入区域 ====================
			// 导入Three.js WebGPU核心库的所有功能
			// THREE是一个命名空间对象，包含Three.js的所有类和功能
			import * as THREE from 'three/webgpu';
			
			// 从TSL（Three.js Shader Language）导入着色器节点函数
			// 这些是声明式着色器编程的构建块
			import { 
				color,       // 颜色节点：创建颜色值
				fog,         // 雾效节点：添加场景雾效
				rangeFogFactor, // 范围雾因子：控制雾效的范围
				checker,     // 棋盘格图案生成器：创建棋盘格纹理
				uv,          // UV坐标节点：获取纹理坐标
				mix,         // 混合节点：混合两个值或颜色
				texture,     // 纹理节点：加载和采样纹理
				lights,      // 灯光节点：定义哪些灯光影响材质
				normalMap    // 法线贴图节点：应用法线贴图效果
			} from 'three/tsl';

			// 导入调试检查器，用于开发和调试Three.js应用
			// 可以在运行时检查场景中的对象、材质、灯光等
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器，允许用户用鼠标控制相机旋转、平移和缩放
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入茶壶几何体生成器，茶壶是计算机图形学中的经典测试模型
			import { TeapotGeometry } from 'three/addons/geometries/TeapotGeometry.js';

			// ==================== 全局变量声明 ====================
			// 这些变量在整个模块中共享，存储Three.js的核心对象
			let camera,     // 相机：定义观察者的视角
				scene,      // 场景：包含所有3D对象的容器
				renderer,   // 渲染器：负责将3D场景绘制到2D画布上
				light1, light2, light3, light4,  // 四个点光源对象
				controls;   // 轨道控制器对象

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

			/**
			 * 初始化函数 - Three.js应用的主设置函数
			 * 这个函数执行所有必要的设置步骤：
			 * 1. 创建相机、场景、渲染器
			 * 2. 创建和配置灯光
			 * 3. 创建3D对象并设置材质
			 * 4. 设置用户交互控制
			 * 5. 添加事件监听器
			 */
			function init() {

				// ==================== 相机设置 ====================
				// 创建透视相机（Perspective Camera）
				// 透视相机模拟人眼视角，物体近大远小
				camera = new THREE.PerspectiveCamera(
					50,  // 视野角度（Field of View）：50度，角度越大看到的场景越多
					window.innerWidth / window.innerHeight,  // 宽高比：使用窗口宽高比
					0.01,  // 近裁剪面：相机能看到的最近距离，小于此距离的物体不显示
					100    // 远裁剪面：相机能看到的最远距离，大于此距离的物体不显示
				);
				// 设置相机初始位置：沿Z轴向后移动7个单位
				// Three.js使用右手坐标系：X轴向右，Y轴向上，Z轴朝向观察者
				camera.position.z = 7;

				// ==================== 场景设置 ====================
				// 创建场景对象，所有3D对象（网格、灯光等）都需要添加到场景中
				scene = new THREE.Scene();
				// 设置场景雾效使用TSL节点系统
				// fogNode: 雾效节点，color(0xFF00FF)创建紫色雾，rangeFogFactor(12, 30)控制雾的范围
				scene.fogNode = fog( color( 0xFF00FF ), rangeFogFactor( 12, 30 ) );

				// ==================== 几何体创建 ====================
				// 创建小球几何体，用于可视化灯光的位置
				// SphereGeometry参数：半径(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' );
				// 设置纹理包裹方式：在UV坐标超出[0,1]范围时重复纹理
				normalMapTexture.wrapS = THREE.RepeatWrapping;  // S方向（U坐标，水平方向）
				normalMapTexture.wrapT = THREE.RepeatWrapping;  // T方向（V坐标，垂直方向）

				// 加载粗糙度贴图（这里用作高光贴图）
				// 粗糙度贴图控制表面的粗糙程度，影响高光反射
				const alphaTexture = textureLoader.load( './textures/roughness_map.jpg' );
				alphaTexture.wrapS = THREE.RepeatWrapping;
				alphaTexture.wrapT = THREE.RepeatWrapping;

				// ==================== 灯光创建函数 ====================
				/**
				 * 创建并添加点光源的辅助函数
				 * 点光源从一个点向所有方向发射光线，类似灯泡
				 * 
				 * @param {number} hexColor - 灯光颜色，十六进制格式（如0x0040ff表示蓝色）
				 * @param {number} power - 灯光功率/强度，值越大灯光越亮，默认1700
				 * @param {number} distance - 灯光照射的最大距离，默认100单位
				 * @return {THREE.PointLight} 返回创建的点光源对象
				 */
				const addLight = ( hexColor, power = 1700, distance = 100 ) => {

					// 创建表示灯光位置的可见小球材质
					// 使用MeshPhongNodeMaterial，支持Phong光照模型的节点材质
					const material = new THREE.MeshPhongNodeMaterial();
					// 设置材质颜色节点，颜色与灯光颜色相同
					material.colorNode = color( hexColor );
					// 禁用材质自身的光照计算，让小球看起来是自发光的
					material.lights = false;

					// 创建表示灯光位置的小球网格
					// 网格 = 几何体 + 材质
					const mesh = new THREE.Mesh( sphereGeometry, material );

					// 创建点光源
					// 参数：颜色，强度(1.0)，最大照射距离
					const light = new THREE.PointLight( hexColor, 1, distance );
					// 设置光源的实际功率值，影响光照强度
					light.power = power;
					// 将小球网格添加为灯光的子对象，这样小球会跟随灯光移动
					light.add( mesh );

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

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

				};

				// 创建四个不同颜色的点光源，放置在场景的不同位置
				light1 = addLight( 0x0040ff );  // 深蓝色灯光
				light2 = addLight( 0xffffff );  // 白色灯光
				light3 = addLight( 0x80ff80 );  // 浅绿色灯光
				light4 = addLight( 0xffaa00 );  // 橙色灯光

				// ==================== 灯光节点创建 ====================
				// 创建选择性的灯光节点，用于控制哪些灯光影响特定材质
				// 蓝色灯光节点：只包含蓝色光源，其他光源不影响使用此节点的材质
				const blueLightsNode = lights( [ light1 ] );
				// 白色灯光节点：只包含白色光源
				const whiteLightsNode = lights( [ light2 ] );

				// ==================== 茶壶模型创建 ====================
				// 创建茶壶几何体，茶壶是计算机图形学中的经典测试模型
				// 参数：尺寸(0.8)，细分程度(18)，值越高模型越精细
				const geometryTeapot = new TeapotGeometry( .8, 18 );

				/**
				 * 左侧茶壶：只受蓝色光影响
				 * 演示如何选择性地让材质只受特定灯光影响
				 */
				const leftObject = new THREE.Mesh( 
					geometryTeapot,  // 使用茶壶几何体
					new THREE.MeshPhongNodeMaterial( { color: 0x555555 } )  // 创建Phong节点材质，基础颜色为中灰色
				);
				// 设置材质的光照节点：只使用蓝色灯光节点
				// 这意味着这个茶壶只受蓝色光源(light1)的影响
				leftObject.material.lightsNode = blueLightsNode;
				// 设置高光节点：使用粗糙度贴图作为高光贴图
				// 高光贴图控制表面哪些区域有高光反射
				leftObject.material.specularNode = texture( alphaTexture );
				// 设置茶壶位置：沿X轴向左移动3个单位
				leftObject.position.x = - 3;
				// 将茶壶添加到场景
				scene.add( leftObject );

				/**
				 * 中间茶壶：受所有灯光影响，并添加法线贴图
				 * 演示法线贴图效果和默认光照行为
				 */
				const centerObject = new THREE.Mesh( 
					geometryTeapot, 
					new THREE.MeshPhongNodeMaterial( { color: 0x555555 } ) 
				);
				// 设置法线贴图节点：应用法线贴图来增加表面细节
				// normalMap函数将纹理转换为法线贴图
				centerObject.material.normalNode = normalMap( texture( normalMapTexture ) );
				// 设置材质光泽度：控制高光的大小和强度，值越高高光越小越亮
				centerObject.material.shininess = 80;
				// 添加到场景（默认受所有灯光影响，因为未设置lightsNode）
				scene.add( centerObject );

				/**
				 * 右侧茶壶：只受白光影响，使用棋盘格高光效果
				 * 演示动态生成的高光图案和选择性光照
				 */
				const rightObject = new THREE.Mesh( 
					geometryTeapot, 
					new THREE.MeshPhongNodeMaterial( { color: 0x555555 } ) 
				);
				// 设置材质的光照节点：只使用白色灯光节点
				rightObject.material.lightsNode = whiteLightsNode;
				// 设置高光节点：使用混合节点创建棋盘格高光效果
				// mix函数混合两种颜色，checker函数生成棋盘格图案
				// uv().mul(5)：获取UV坐标并乘以5，使棋盘格图案更密集
				rightObject.material.specularNode = mix( 
					color( 0x0000FF ),  // 颜色1：蓝色
					color( 0xFF0000 ),  // 颜色2：红色
					checker( uv().mul( 5 ) )  // 混合因子：棋盘格图案
				);
				// 设置更高的光泽度，使高光更小更亮
				rightObject.material.shininess = 90;
				// 设置茶壶位置：沿X轴向右移动3个单位
				rightObject.position.x = 3;
				scene.add( rightObject );

				// ==================== 统一设置茶壶属性 ====================
				// 设置所有茶壶的旋转：绕Y轴旋转-90度（顺时针90度）
				// 这样茶壶的壶嘴会朝向观察者
				leftObject.rotation.y = centerObject.rotation.y = rightObject.rotation.y = Math.PI * - 0.5;
				// 设置所有茶壶的高度：沿Y轴向下移动1个单位
				leftObject.position.y = centerObject.position.y = rightObject.position.y = - 1;

				// ==================== 渲染器设置 ====================
				// 创建WebGPU渲染器实例
				// WebGPU是现代图形API，比WebGL更高效，支持更高级的图形功能
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				// 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 );

				// ==================== 控制器设置 ====================
				// 创建轨道控制器，允许用户通过鼠标交互控制相机
				controls = new OrbitControls( camera, renderer.domElement );
				// 设置相机最小缩放距离：不能比3个单位更近
				controls.minDistance = 3;
				// 设置相机最大缩放距离：不能比25个单位更远
				controls.maxDistance = 25;

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

			} // init函数结束

			/**
			 * 窗口大小变化处理函数
			 * 当用户调整浏览器窗口大小时，需要更新相机和渲染器设置
			 * 以保持正确的宽高比和渲染尺寸
			 */
			function onWindowResize() {

				// 更新相机的宽高比为新的窗口宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵，使变化生效
				// 必须调用此方法，否则相机不会使用新的宽高比
				camera.updateProjectionMatrix();

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

			}

			/**
			 * 动画循环函数 - 每帧调用
			 * 这是Three.js应用的核心动画循环
			 * 在每一帧中：
			 * 1. 更新场景中对象的状态（如灯光位置）
			 * 2. 渲染场景到画布
			 * 
			 * @description 使用三角函数创建灯光的圆周运动，使场景更生动
			 */
			function animate() {

				// 获取当前时间（以秒为单位）
				// performance.now()返回从页面加载开始的高精度时间戳（毫秒）
				const time = performance.now() / 1000;
				// 灯光移动的时间因子，比实际时间慢一半，使运动更平缓
				const lightTime = time * 0.5;

				// 更新四个灯光的位置，使用三角函数创建圆周运动
				// 每个灯光的运动参数不同，产生错落有致的运动效果
				
				// 蓝色灯光(light1)的运动
				light1.position.x = Math.sin( lightTime * 0.7 ) * 3;  // X轴：正弦运动，频率0.7，幅度3
				light1.position.y = Math.cos( lightTime * 0.5 ) * 4;  // Y轴：余弦运动，频率0.5，幅度4
				light1.position.z = Math.cos( lightTime * 0.3 ) * 3;  // Z轴：余弦运动，频率0.3，幅度3
				// 不同频率的三角函数组合产生复杂的三维运动轨迹

				// 白色灯光(light2)的运动
				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;

				// 渲染场景：将3D场景绘制到2D画布上
				// 参数：要渲染的场景，使用的相机
				renderer.render( scene, camera );

			} // animate函数结束

		</script>
		<!-- 
			脚本结束标记
			整个Three.js应用从这里开始执行
			模块加载 -> init() -> animate()循环
		-->
	</body>
</html>