<!-- 代码功能和技术点详解
一、整体功能概述
这是一个基于 Three.js WebGPU 的 屏幕空间全局光照（SSGI） 技术演示。它实现了一个完整的3D渲染系统，展示了现代实时图形渲染中的高级光照技术。

核心功能：
实时全局光照 - 在屏幕空间计算间接照明和环境光遮蔽

康奈尔盒子场景 - 经典的光照测试环境

交互式调试 - 实时调整渲染参数

高级后处理 - 包含时域抗锯齿等效果

WebGPU渲染 - 使用新一代图形API

二、主要技术点详解
1. WebGPU渲染技术
javascript
import * as THREE from 'three/webgpu';
下一代图形API：替代WebGL，提供更低的CPU开销和更好的多线程支持

优势：

更好的性能表现

更现代的GPU特性支持

与Vulkan/Metal/DirectX12架构对齐

2. 屏幕空间全局光照（SSGI）
javascript
import { ssgi } from 'three/addons/tsl/display/SSGINode.js';
原理：利用当前帧的屏幕信息（颜色、深度、法线）计算间接光照

关键技术：

射线步进（Ray Marching）：在屏幕空间追踪光线

层次深度缓冲：加速光线与场景的相交测试

时域滤波：减少噪声和闪烁

3. 多渲染目标（MRT）
javascript
scenePass.setMRT(mrt({
  output: output,
  diffuseColor: diffuseColor,
  normal: directionToColor(normalView),
  velocity: velocity
}));
单次渲染，多输出：一次渲染通道输出多个纹理

输出内容：

output：最终颜色

diffuseColor：漫反射颜色（无光照）

normal：法线信息（编码为RGB颜色）

velocity：像素运动向量（用于运动模糊和TAA）

depth：深度缓冲

4. Three.js着色语言（TSL）
javascript
import { pass, mrt, output, normalView, diffuseColor, velocity } from 'three/tsl';
声明式着色编程：简化着色器编写

节点图系统：可视化连接渲染操作

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

5. 时域抗锯齿（TAA）
javascript
import { traa } from 'three/addons/tsl/display/TRAANode.js';
技术原理：混合当前帧与历史帧

优势：

显著减少锯齿

提高图像稳定性

支持亚像素细节

6. 康奈尔盒子场景
javascript
// 经典的光照测试场景配置
// 左墙：红色 | 右墙：绿色 | 其他：白色
用途：评估全局光照算法的准确性

特点：

封闭空间，便于观察颜色反射

简单几何体，便于分析

已知光照条件，便于验证

7. 可调节参数系统
javascript
// GUI控制面板参数
giPass.sliceCount.value = 2;    // 切片数量
giPass.stepCount.value = 8;     // 步进数量
giPass.radius.value = 1;        // 采样半径
giPass.aoIntensity.value = 1;   // AO强度
giPass.giIntensity.value = 1;   // GI强度
实时调节：无需重新编译即可看到效果

调试友好：分离各组件效果观察

三、渲染管线流程
1. 几何渲染阶段
text
场景几何体 → 顶点处理 → 光栅化 → MRT输出
输出：颜色、深度、法线、速度纹理

2. SSGI计算阶段
text
输入纹理 → 射线步进 → 间接光照计算 → AO计算
算法步骤：

屏幕空间光线追踪

寻找相交点

计算间接光照贡献

计算环境光遮蔽

3. 合成阶段
text
直接光照 × AO + 间接光照 × 漫反射颜色
光照模型：Final = Direct×AO + Indirect×Diffuse

4. 后处理阶段
text
当前帧 + 历史帧 → TAA混合 → 最终输出
时域滤波提高图像质量

四、关键技术参数
SSGI核心参数：
参数	作用	典型值
sliceCount	采样切片方向数	2-4
stepCount	每条射线步进次数	8-32
radius	采样搜索半径	1-25像素
thickness	深度测试厚度	0.01-10
aoIntensity	AO强度	0-4
giIntensity	GI强度	0-100
性能优化技术：
带宽优化：使用UnsignedByteType减少纹理内存

早期深度测试：减少无效片段处理

层级采样：根据距离调整采样密度

时域重用：复用历史帧信息

五、技术优势
1. 实时性能
在主流GPU上可达到60FPS

适合实时应用和游戏

2. 视觉质量
动态间接光照

准确的环境光遮蔽

自然的颜色反射

3. 灵活性
可调节的质量/性能平衡

易于集成到现有渲染管线

支持各种材质类型 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面元数据设置：
			- title: 页面标题，显示在浏览器标签页上
			- charset: 字符编码，utf-8支持中文等多国语言
			- viewport: 移动端适配，禁止缩放保证显示一致性
		-->
		<title>Three.js WebGPU - 屏幕空间全局光照演示</title>
		<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>
		<!-- 
			信息展示区域：包含logo、标题和技术说明
			id="info"：用于CSS样式选择和JavaScript操作
		-->
		<div id="info">
			<!-- 
				three.js官网链接：
				- target="_blank"：在新标签页打开
				- rel="noopener"：安全设置，防止新页面访问原页面
				- class="logo-link"：CSS样式类，通常用于添加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>标签：次要内容，通常显示为较小字体
				- 内容：说明本演示使用的核心技术原理
			-->
			<small>使用屏幕空间信息实现实时间接照明和环境光遮蔽。</small>
			

		</div>
		
		<!-- 
			Import Map（导入映射表）：
			- type="importmap"：HTML5新特性，定义模块导入路径
			- 作用：将模块名称映射到具体的文件路径
			- 好处：简化导入语句，便于管理和维护
		-->
		<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模块
			- 支持现代JavaScript特性如import/export
			- 在模块作用域中运行，避免全局变量污染
		-->
		<script type="module">
			// ==================== 模块导入区域 ====================
			
			// 导入Three.js核心库的WebGPU版本
			// WebGPU是新一代图形API，比WebGL性能更好，功能更强大
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js着色语言（TSL）的核心功能
			// TSL是Three.js的着色器编程接口，简化了着色器编写
			import { 
				pass,          // 创建渲染通道，用于组织渲染流程
				mrt,           // 多渲染目标，单次渲染输出多个纹理
				output,        // 输出节点，表示最终的渲染输出
				normalView,    // 视图空间法线，用于光照计算
				diffuseColor,  // 漫反射颜色，物体的基础颜色
				velocity,      // 像素速度/运动向量，用于运动模糊和TAA
				add,           // 向量/颜色加法运算
				vec3,          // 创建三维向量
				vec4,          // 创建四维向量（RGBA）
				directionToColor, // 将方向向量编码为颜色值（用于存储）
				colorToDirection, // 将颜色值解码为方向向量
				sample         // 纹理采样函数
			} from 'three/tsl';
			
			// 导入后处理特效节点
			// SSGI：屏幕空间全局光照，模拟间接照明和AO
			import { ssgi } from 'three/addons/tsl/display/SSGINode.js';
			// TRA：时域抗锯齿，利用历史帧信息提高图像质量
			import { traa } from 'three/addons/tsl/display/TRAANode.js';
			
			// 导入控制器和调试工具
			// OrbitControls：轨道控制器，实现鼠标拖拽、缩放等相机控制
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// Inspector：调试检查器，可视化调试和参数调整
			import { Inspector } from 'three/addons/inspector/Inspector.js';
			
			// ==================== 全局变量声明 ====================
			// 这些变量在整个应用中使用，在多个函数间共享
			let camera;      // 3D场景相机，决定观察视角
			let scene;       // 3D场景容器，包含所有3D对象
			let renderer;    // 渲染器，负责将3D场景绘制到2D屏幕
			let postProcessing; // 后处理管理器，处理各种屏幕后效
			let controls;    // 用户交互控制器
			
			// ==================== 初始化函数调用 ====================
			// 程序入口点，启动整个3D应用
			init();
			
			// ==================== 异步初始化函数 ====================
			// async关键字：函数内部可以使用await进行异步操作
			async function init() {
				// ---------- 1. 相机设置 ----------
				// 创建透视投影相机（模拟人眼视角）
				// 参数：视野角度、宽高比、近裁剪面、远裁剪面
				camera = new THREE.PerspectiveCamera(40, window.innerWidth / window.innerHeight, 0.1, 100);
				// 设置相机初始位置（X, Y, Z坐标）
				camera.position.set(0, 10, 30);
				
				// ---------- 2. 场景设置 ----------
				// 创建3D场景，所有3D对象的容器
				scene = new THREE.Scene();
				// 设置场景背景颜色（浅灰色）
				scene.background = new THREE.Color(0xaaaaaa);
				
				// ---------- 3. 渲染器设置 ----------
				// 创建WebGPU渲染器实例
				renderer = new THREE.WebGPURenderer();
				// 注释：像素比设置，通常用于视网膜屏优化，但可能性能开销大
				// renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 设置动画循环回调函数（每帧调用animate函数）
				renderer.setAnimationLoop(animate);
				// 启用阴影映射功能
				renderer.shadowMap.enabled = true;
				// 初始化调试检查器，用于可视化调试
				renderer.inspector = new Inspector();
				// 将渲染器的Canvas元素添加到网页body中
				document.body.appendChild(renderer.domElement);
				
				// ---------- 4. 控制器设置 ----------
				// 创建轨道控制器，连接相机和渲染器的Canvas
				controls = new OrbitControls(camera, renderer.domElement);
				// 设置控制器的目标点（相机围绕此点旋转）
				controls.target.set(0, 7, 0);
				// 启用平移功能（鼠标右键拖拽）
				controls.enablePan = true;
				// 设置相机与目标点的最小距离
				controls.minDistance = 1;
				// 设置相机与目标点的最大距离
				controls.maxDistance = 100;
				// 更新控制器内部状态
				controls.update();
				
				// ---------- 5. 后处理系统初始化 ----------
				// 创建后处理管理器，管理各种后处理效果
				postProcessing = new THREE.PostProcessing(renderer);
				
				// ---------- 6. 创建主场景渲染通道 ----------
				// pass函数：创建一个渲染通道，将场景渲染到纹理
				const scenePass = pass(scene, camera);
				// 设置多渲染目标（MRT），一次渲染输出多个纹理
				scenePass.setMRT(mrt({
					output: output,                     // 通道1：最终颜色输出
					diffuseColor: diffuseColor,         // 通道2：漫反射颜色（无光照影响）
					normal: directionToColor(normalView), // 通道3：法线信息（编码为颜色存储）
					velocity: velocity                  // 通道4：像素运动速度
				}));
				
				// ---------- 7. 获取渲染纹理节点 ----------
				// 这些节点可以在后续的着色器计算中使用
				const scenePassColor = scenePass.getTextureNode('output');
				// toInspector：将节点添加到调试检查器，便于观察
				const scenePassDiffuse = scenePass.getTextureNode('diffuseColor').toInspector('漫反射颜色');
				const scenePassDepth = scenePass.getTextureNode('depth').toInspector('深度缓冲', () => {
					// 回调函数：将深度值转换为线性深度，便于可视化
					return scenePass.getLinearDepthNode();
				});
				const scenePassNormal = scenePass.getTextureNode('normal').toInspector('法线信息');
				const scenePassVelocity = scenePass.getTextureNode('velocity').toInspector('运动向量');
				
				// ---------- 8. 带宽优化 ----------
				// 减少纹理内存占用，提高性能
				const diffuseTexture = scenePass.getTexture('diffuseColor');
				// 使用8位无符号字节类型（0-255），而非默认的浮点数
				diffuseTexture.type = THREE.UnsignedByteType;
				const normalTexture = scenePass.getTexture('normal');
				normalTexture.type = THREE.UnsignedByteType;
				
				// ---------- 9. 法线解码 ----------
				// 将颜色编码的法线纹理解码回方向向量
				const sceneNormal = sample((uv) => {
					// 采样法线纹理，然后解码
					return colorToDirection(scenePassNormal.sample(uv));
				});
				
				// ---------- 10. SSGI处理 ----------
				// 创建SSGI效果，计算间接光照和环境光遮蔽
				// 参数：场景颜色、深度、法线、相机
				const giPass = ssgi(scenePassColor, scenePassDepth, sceneNormal, camera);
				// 配置SSGI参数
				giPass.sliceCount.value = 2;   // 切片数量：影响采样方向多样性
				giPass.stepCount.value = 8;    // 步进数量：影响光线步进精度
				
				// 获取SSGI的输出分量
				const gi = giPass.rgb.toInspector('SSGI输出');  // RGB：间接光照颜色
				const ao = giPass.a.toInspector('环境光遮蔽');    // A：环境光遮蔽强度
				
				// ---------- 11. 最终合成 ----------
				// 将直接光照、间接光照、AO组合成最终图像
				// 公式：最终颜色 = 直接颜色 × AO + 漫反射颜色 × 间接光照
				const compositePass = vec4(
					add(
						scenePassColor.rgb.mul(ao),     // 直接光照部分（受AO影响）
						scenePassDiffuse.rgb.mul(gi)    // 间接光照部分（颜色反射）
					),
					scenePassColor.a  // 保持原始透明度
				);
				// 为节点命名，便于调试识别
				compositePass.name = '合成输出';
				
				// ---------- 12. 时域抗锯齿 ----------
				// 应用TAA减少锯齿和闪烁
				// 参数：当前帧颜色、深度、运动向量、相机
				const traaPass = traa(compositePass, scenePassDepth, scenePassVelocity, camera);
				// 设置后处理的最终输出节点
				postProcessing.outputNode = traaPass;
				
				// ==================== 场景构建 ====================
				// 创建康奈尔盒子场景（经典的光照测试场景）
				
				// ---------- 13. 墙面几何体 ----------
				// 创建基础平面几何体（1x1单位）
				const wallGeometry = new THREE.PlaneGeometry(1, 1);
				
				// ---------- 14. 左墙（红色） ----------
				const redWallMaterial = new THREE.MeshPhysicalMaterial({ 
					color: '#ff0000'  // 纯红色
				});
				const leftWall = new THREE.Mesh(wallGeometry, redWallMaterial);
				leftWall.scale.set(20, 15, 1);      // 缩放：宽20，高15
				leftWall.rotation.y = Math.PI * 0.5; // 旋转90度（弧度制）
				leftWall.position.set(-10, 7.5, 0);  // 位置：左边
				leftWall.receiveShadow = true;       // 可以接收阴影
				scene.add(leftWall);                 // 添加到场景
				
				// ---------- 15. 右墙（绿色） ----------
				const greenWallMaterial = new THREE.MeshPhysicalMaterial({ 
					color: '#00ff00'  // 纯绿色
				});
				const rightWall = new THREE.Mesh(wallGeometry, greenWallMaterial);
				rightWall.scale.set(20, 15, 1);
				rightWall.rotation.y = Math.PI * -0.5; // 旋转-90度
				rightWall.position.set(10, 7.5, 0);    // 位置：右边
				rightWall.receiveShadow = true;
				scene.add(rightWall);
				
				// ---------- 16. 白色材质（共享） ----------
				const whiteMaterial = new THREE.MeshPhysicalMaterial({ 
					color: '#fff'  // 纯白色
				});
				
				// ---------- 17. 地板 ----------
				const floor = new THREE.Mesh(wallGeometry, whiteMaterial);
				floor.scale.set(20, 20, 1);
				floor.rotation.x = Math.PI * -0.5;  // 旋转-90度，使其水平
				floor.receiveShadow = true;
				scene.add(floor);
				
				// ---------- 18. 后墙 ----------
				const backWall = new THREE.Mesh(wallGeometry, whiteMaterial);
				backWall.scale.set(15, 20, 1);
				backWall.rotation.z = Math.PI * -0.5;  // 旋转-90度
				backWall.position.set(0, 7.5, -10);    // 位置：后方
				backWall.receiveShadow = true;
				scene.add(backWall);
				
				// ---------- 19. 天花板 ----------
				const ceiling = new THREE.Mesh(wallGeometry, whiteMaterial);
				ceiling.scale.set(20, 20, 1);
				ceiling.rotation.x = Math.PI * 0.5;   // 旋转90度
				ceiling.position.set(0, 15, 0);       // 位置：顶部
				ceiling.receiveShadow = true;
				scene.add(ceiling);
				
				// ---------- 20. 高盒子 ----------
				const tallBoxGeometry = new THREE.BoxGeometry(5, 7, 5);
				const tallBox = new THREE.Mesh(tallBoxGeometry, whiteMaterial);
				tallBox.rotation.y = Math.PI * 0.25;   // 旋转45度
				tallBox.position.set(-3, 3.5, -2);     // 位置：左前
				tallBox.castShadow = true;            // 可以投射阴影
				tallBox.receiveShadow = true;         // 可以接收阴影
				scene.add(tallBox);
				
				// ---------- 21. 矮盒子 ----------
				const shortBoxGeometry = new THREE.BoxGeometry(4, 4, 4);
				const shortBox = new THREE.Mesh(shortBoxGeometry, whiteMaterial);
				shortBox.rotation.y = Math.PI * -0.1;  // 旋转-18度
				shortBox.position.set(4, 2, 4);        // 位置：右后
				shortBox.castShadow = true;
				shortBox.receiveShadow = true;
				scene.add(shortBox);
				
				// ---------- 22. 光源可视化几何体 ----------
				// 创建一个圆柱体代表光源位置（仅用于可视化）
				const lightSourceGeometry = new THREE.CylinderGeometry(2.5, 2.5, 1, 64);
				const lightSourceMaterial = new THREE.MeshBasicMaterial();
				const lightSource = new THREE.Mesh(lightSourceGeometry, lightSourceMaterial);
				lightSource.position.y = 15;  // 位置：顶部中央
				scene.add(lightSource);
				
				// ---------- 23. 点光源 ----------
				// 创建主要光源
				const pointLight = new THREE.PointLight('#ffffff', 100);
				pointLight.position.set(0, 13, 0);      // 光源位置
				pointLight.distance = 100;             // 光源影响距离
				pointLight.castShadow = true;          // 启用阴影
				pointLight.shadow.mapSize.width = 1024;  // 阴影贴图分辨率
				pointLight.shadow.mapSize.height = 1024;
				pointLight.shadow.bias = -0.0025;      // 阴影偏移，防止阴影失真
				scene.add(pointLight);
				
				// ---------- 24. 环境光 ----------
				// 添加微弱的环境光，防止完全黑暗的区域
				const ambientLight = new THREE.AmbientLight('#0c0c0c');
				scene.add(ambientLight);
				
				// ---------- 25. 窗口大小变化监听 ----------
				// 当浏览器窗口大小改变时，调整渲染器尺寸
				window.addEventListener('resize', onWindowResize);
				
				// ==================== GUI控制面板 ====================
				// 创建参数对象，存储GUI的当前状态
				const params = {
					output: 0  // 默认显示合成结果
				};
				
				// 输出类型枚举，对应不同的显示模式
				const types = { 
					Combined: 0,  // 合成模式：直接光照+间接光照+AO
					Direct: 3,    // 仅直接光照
					AO: 1,        // 仅环境光遮蔽
					GI: 2         // 仅全局光照
				};
				
				// 创建GUI控制面板
				const gui = renderer.inspector.createParameters('SSGI设置');
				
				// 添加各种控制参数
				// 输出模式选择下拉框
				gui.add(params, 'output', types)
				   .name('显示模式')
				   .onChange(updatePostprocessing);
				
				// SSGI参数调节
				gui.add(giPass.sliceCount, 'value', 1, 4, 1)
				   .name('切片数量')
				   .step(1);  // 整数步进
				
				gui.add(giPass.stepCount, 'value', 1, 32, 1)
				   .name('步进数量')
				   .step(1);
				
				gui.add(giPass.radius, 'value', 1, 25)
				   .name('采样半径');
				
				gui.add(giPass.expFactor, 'value', 1, 3)
				   .name('指数因子');
				
				gui.add(giPass.thickness, 'value', 0.01, 10)
				   .name('厚度参数');
				
				gui.add(giPass.backfaceLighting, 'value', 0, 1)
				   .name('背面照明');
				
				gui.add(giPass.aoIntensity, 'value', 0, 4)
				   .name('AO强度');
				
				gui.add(giPass.giIntensity, 'value', 0, 100)
				   .name('GI强度');
				
				gui.add(giPass.useLinearThickness, 'value')
				   .name('使用线性厚度');
				
				gui.add(giPass.useScreenSpaceSampling, 'value')
				   .name('屏幕空间采样');
				
				gui.add(giPass, 'useTemporalFiltering')
				   .name('时域滤波')
				   .onChange(updatePostprocessing);
				
				// ==================== 后处理更新函数 ====================
				/**
				 * 根据选择的显示模式更新后处理输出
				 * @param {number} value - 显示模式枚举值
				 */
				function updatePostprocessing(value) {
					// 根据选择的模式设置不同的输出节点
					if (value === 1) {
						// 模式1：仅显示AO（环境光遮蔽）
						// 将AO的灰度值复制到RGB三个通道
						postProcessing.outputNode = vec4(vec3(ao), 1);
					} else if (value === 2) {
						// 模式2：仅显示GI（全局光照）
						postProcessing.outputNode = vec4(gi, 1);
					} else if (value === 3) {
						// 模式3：仅显示直接光照
						postProcessing.outputNode = scenePassColor;
					} else {
						// 模式0（默认）：显示合成结果
						// 根据是否启用时域滤波选择不同的输出
						postProcessing.outputNode = giPass.useTemporalFiltering ? traaPass : compositePass;
					}
					// 标记后处理需要更新
					postProcessing.needsUpdate = true;
				}
			}
			
			// ==================== 窗口大小变化处理函数 ====================
			/**
			 * 响应浏览器窗口大小变化
			 * 重新调整相机和渲染器的尺寸
			 */
			function onWindowResize() {
				// 获取当前窗口的宽度和高度
				const width = window.innerWidth;
				const height = window.innerHeight;
				
				// 更新相机的宽高比
				camera.aspect = width / height;
				// 通知相机投影矩阵已更改，需要重新计算
				camera.updateProjectionMatrix();
				
				// 更新渲染器尺寸，匹配窗口大小
				renderer.setSize(width, height);
			}
			
			// ==================== 动画循环函数 ====================
			/**
			 * 每一帧执行的主渲染循环
			 * 1. 更新控制器状态
			 * 2. 执行后处理渲染
			 */
			function animate() {
				// 更新轨道控制器（处理鼠标/触摸输入）
				controls.update();
				// 执行后处理渲染链
				postProcessing.render();
			}
			// 注意：没有使用传统的requestAnimationFrame循环
			// 因为WebGPURenderer.setAnimationLoop已经处理了循环
		</script>
	</body>
</html>