<!-- 代码功能与技术点详解
一、整体功能概述
这是一个基于Three.js WebGPU的体积光照演示应用，展示了矩形区域光源在体积雾环境中的高级渲染效果。应用通过光线步进算法模拟光线在雾/烟介质中的传播，结合后处理技术实现高质量的实时渲染。

主要功能特性：
动态体积雾效果 - 模拟真实世界中的雾、烟等大气介质

物理准确的矩形光源 - 三个彩色矩形区域光源（红、绿、蓝）

实时交互控制 - 可通过GUI调整各项参数

相机轨道控制 - 用户可自由旋转、缩放和平移视角

动态动画 - 光源随时间旋转，雾效自然流动

二、核心技术点详解
1. WebGPU渲染引擎
javascript
// 使用Three.js的WebGPU后端
renderer = new THREE.WebGPURenderer();
现代图形API：相比WebGL，WebGPU提供更底层的GPU控制

并行计算能力：支持计算着色器，适合体积渲染等复杂计算

显存管理：更高效的内存访问模式

跨平台兼容：支持现代浏览器和多种操作系统

2. 体积渲染系统
2.1 光线步进算法（Ray Marching）
javascript
volumetricMaterial.steps = 12;  // 光线采样步数
原理：

从相机发射光线穿过每个像素

沿光线方向等距离采样（本示例12步）

在每个采样点计算雾的密度（基于3D噪声纹理）

累加所有采样点的光学贡献

数学表示：

text
最终颜色 = ∑(i=0 to N) [光照强度 × 雾密度(i) × 衰减因子]
其中N为步进次数，衰减因子考虑光线在介质中的吸收和散射。

2.2 3D噪声纹理生成
javascript
function createTexture3D() {
    // 生成128×128×128的Perlin噪声纹理
    const perlin = new ImprovedNoise();
    const noiseValue = perlin.noise(nx * scale, ny * scale, nz * scale);
}
Perlin噪声：生成连续、自然的随机图案

分形噪声（Fractal Noise）：多尺度叠加增加细节

3D纹理坐标：在三维空间中采样，实现真实的体积感

时间动画：通过时间偏移使噪声"流动"

3. 矩形区域光源技术
3.1 LTC（线性变换余弦）近似
javascript
THREE.RectAreaLightNode.setLTC(RectAreaLightTexturesLib.init());
技术原理：

预计算矩形光源的BRDF积分

使用查找纹理（LTC纹理）加速实时计算

支持物理正确的衰减和软阴影

光照方程：

text
L(p, ω_o) = ∫_A L_i(x, ω_i) f_r(p, ω_i, ω_o) cosθ_i V(x,p) dA
其中：

A为光源面积

V为可见性函数

f_r为双向反射分布函数

3.2 光源属性
javascript
new THREE.RectAreaLight(颜色, 强度, 宽度, 高度);
面积光源：模拟真实世界的面光源（窗户、灯板）

软阴影：产生自然的半影过渡

平方反比衰减：遵循物理规律的光强衰减

4. 后处理渲染管线
4.1 分层渲染架构
javascript
const LAYER_VOLUMETRIC_LIGHTING = 10;
volumetricMesh.layers.enable(LAYER_VOLUMETRIC_LIGHTING);
渲染流程：

text
┌─────────────────────────────────────────────────────┐
│               完整分辨率主场景渲染                    │
│  (包含所有几何体、材质、光照、阴影)                  │
└──────────────────────────┬──────────────────────────┘
                           │ 深度纹理
                           ↓
┌─────────────────────────────────────────────────────┐
│           25%分辨率体积光照渲染（单独层）             │
│  (只渲染体积雾和矩形光源，使用光线步进)              │
└──────────────────────────┬──────────────────────────┘
                           │
                     高斯模糊去噪
                           │
                           ↓
┌─────────────────────────────────────────────────────┐
│                 加法混合到主场景                     │
└──────────────────────────┬──────────────────────────┘
                           │
                           ↓
                     最终输出到屏幕
4.2 高斯模糊去噪
javascript
const blurredVolumetricPass = gaussianBlur(volumetricPass, denoiseStrength);
问题：低分辨率体积渲染会产生噪点
解决方案：使用高斯卷积核平滑噪声

text
G(x,y) = (1/(2πσ²)) × exp(-(x²+y²)/(2σ²))
其中σ控制模糊强度，对应denoiseStrength参数。

5. 性能优化技术
5.1 拜耳抖动（Bayer Dithering）
javascript
volumetricMaterial.offsetNode = bayer16(screenCoordinate);
问题：低步进次数导致条带效应（banding）
解决方案：添加有序抖动图案

使用16×16拜耳矩阵

在相邻像素添加微小偏移

将量化误差分散到高频噪声中

人眼在运动中会自然平均这些噪声

5.2 自适应分辨率
javascript
volumetricPass.setResolutionScale(.25);  // 使用25%分辨率
权衡策略：

体积效果对分辨率不敏感（模糊特性）

降低分辨率可大幅提升性能

通过去噪补偿质量损失

性能提升：

text
理论计算量减少 = (1 - 0.25²) × 100% = 93.75%
（因为GPU是并行处理，实际提升可能不同）
6. TSL（Three.js Shader Language）
6.1 节点化着色器编程
javascript
// TSL节点系统示例
const density = sampleGrain(.1)
    .mul(sampleGrain(.05, 1))
    .mul(sampleGrain(.02, 2));
优势：

可视化编程：类似UE4材质编辑器

实时编译：动态生成GLSL/HLSL代码

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

性能优化：自动优化节点图

6.2 统一变量（Uniforms）
javascript
const smokeAmount = uniform(2);  // 可在JavaScript中修改
动态控制：运行时调整着色器参数

GUI集成：实时反馈参数变化

动画支持：随时间变化的参数

7. 交互与控制
7.1 轨道控制器（OrbitControls）
javascript
const controls = new OrbitControls(camera, renderer.domElement);
功能：

鼠标左键拖拽：旋转视角

鼠标右键拖拽/滚轮：缩放

中键拖拽：平移场景

触摸支持：移动设备兼容

7.2 实时参数调整GUI
javascript
// 创建光线步进参数面板
rayMarching.add(params, 'resolution', .1, .5).name('分辨率缩放');
可调参数：

体积光照分辨率（0.1-0.5倍）

光线步进步数（2-12步）

去噪强度（0-1）

雾强度（0-2）

烟雾密度（0-3）

三、关键技术应用场景
1. 游戏开发
大气效果：雾、烟、尘埃、体积光

特效系统：法术效果、爆炸烟雾

环境光照：室内体积光照、上帝射线

2. 建筑可视化
室内照明：窗户采光、灯具效果

环境氛围：晨雾、黄昏光线

材质展示：体积光下的材质表现

3. 影视特效
预可视化：实时预览复杂光效

虚拟制作：LED墙体积光照

动态故事板：交互式镜头设计

4. 科学可视化
流体模拟：烟雾、云层可视化

医学成像：体积数据渲染

地质勘探：地下结构可视化

四、性能与质量平衡策略
技术	性能影响	质量影响	适用场景
12步光线步进	高	高	高质量渲染
25%分辨率	低	中	实时应用
高斯去噪	中	高	所有场景
拜耳抖动	低	高	低步数时必需
LTC预计算	低	高	矩形光源
五、代码架构亮点
1. 模块化设计
text
├── 核心模块 (Three.js WebGPU)
├── 体积渲染模块 (VolumeNodeMaterial)
├── 光源模块 (RectAreaLight + LTC)
├── 后处理模块 (PostProcessing)
├── UI模块 (Inspector + Controls)
└── 工具模块 (噪声生成、时间管理)
2. 可扩展性
易于添加新光源类型

支持多种体积材质

可扩展后处理效果链

模块化参数控制系统

3. 跨平台兼容
WebGPU现代浏览器支持

响应式设计适应不同屏幕

触摸和鼠标双控制支持

性能自适应调整 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题和基础元信息 -->
		<title>Three.js WebGPU 体积光照演示 - 矩形区域光源效果</title>
		<meta charset="utf-8">
		<!-- 
			viewport设置：
			width=device-width: 视口宽度等于设备宽度
			user-scalable=no: 禁止用户缩放（保持固定比例）
			minimum-scale=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">
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>

	<body>
		<!-- 页面顶部信息展示区域 -->
		<div id="info">
			<!-- 点击logo跳转到Three.js官网 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link">
				<!-- 这里是Three.js的logo，通过CSS背景图实现 -->
			</a>

			<div class="title-wrapper">
				<!-- 主标题链接到Three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：当前演示的具体功能 -->
				<span>体积光照演示 - 矩形区域光源效果</span>
			</div>

			<!-- 功能描述：说明本演示的核心特性 -->
			<small>使用后处理技术实现矩形区域光源的体积光照和阴影效果，基于WebGPU渲染。</small>
			
		</div>

		<!-- 
			模块导入映射配置表
			作用：将模块名映射到实际的文件路径，简化导入语句
			注意：这里使用相对路径，实际项目中可能需要调整
		-->
		<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>

		<!-- 主应用程序脚本 -->
		<script type="module">

			// ==================== 模块导入区域 ====================
			
			// 导入Three.js WebGPU核心库的所有功能
			// THREE对象包含场景(Scene)、相机(Camera)、几何体(Geometry)、材质(Material)等核心类
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js Shader Language）的关键节点
			// TSL是一种用于构建着色器的节点系统，类似于UE4的材质编辑器
			import { 
				vec3,      // 3维向量节点，用于表示位置、颜色等
				Fn,        // 函数节点，用于创建自定义着色器函数
				time,      // 时间节点，提供当前运行时间（秒）
				texture3D, // 3D纹理采样节点
				screenUV,  // 屏幕UV坐标节点（范围0-1）
				uniform,   // 统一变量节点，可在JavaScript中动态修改
				screenCoordinate, // 屏幕坐标节点（像素坐标）
				pass,      // 渲染通道节点，用于创建渲染管线
				checker,   // 棋盘格图案生成节点
				uv         // UV坐标节点
			} from 'three/tsl';

			// 导入Three.js的扩展功能模块
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';  // 轨道摄像机控制器
			import { ImprovedNoise } from 'three/addons/math/ImprovedNoise.js';      // 改进的Perlin噪声生成器
			import { RectAreaLightTexturesLib } from 'three/addons/lights/RectAreaLightTexturesLib.js';  // 矩形区域光源纹理库

			// 导入调试和UI模块
			import { Inspector } from 'three/addons/inspector/Inspector.js';  // 调试检查器，用于GUI创建

			// 导入TSL专用工具函数
			import { bayer16 } from 'three/addons/tsl/math/Bayer.js';  // 16x16拜耳矩阵，用于有序抖动（减少条带效应）
			import { gaussianBlur } from 'three/addons/tsl/display/GaussianBlurNode.js';  // 高斯模糊后处理节点

			// ==================== 全局变量声明 ====================
			
			// 核心Three.js对象
			let renderer,     // WebGPU渲染器实例
				scene,        // 主场景，包含所有3D对象
				camera;       // 透视相机，用于定义观察视角
			
			// 体积雾相关对象
			let volumetricMesh;  // 体积雾的网格对象，包含体积材质和几何体
			
			// 光源对象
			let rectLight1, rectLight2, rectLight3;  // 三个矩形区域光源（红、绿、蓝）
			
			// 时间和后处理
			let timer;           // 计时器，用于动画和性能监控
			let postProcessing;  // 后处理管理器，负责渲染管线的组合和执行

			// ==================== 函数调用 ====================
			
			// 程序入口：调用初始化函数
			init();

			/**
			 * 创建3D Perlin噪声纹理函数
			 * 
			 * 作用：生成一个128x128x128分辨率的3D噪声纹理，用于模拟体积雾的密度变化
			 * 原理：使用改进的Perlin噪声算法，在三维空间中生成连续的随机值
			 * 应用：作为体积材质的基础噪声，使雾看起来更自然、有机
			 * 
			 * @returns {THREE.Data3DTexture} 返回一个包含3D噪声数据的纹理对象
			 */
			function createTexture3D() {

				let i = 0;  // 数据数组的当前索引

				// 定义纹理尺寸：128x128x128，总共2,097,152个体素
				const size = 128;
				
				// 创建Uint8Array类型的数据数组（8位无符号整数，范围0-255）
				// 这个数组将存储所有体素的噪声值
				const data = new Uint8Array( size * size * size );

				// Perlin噪声参数
				const scale = 10;  // 噪声缩放因子，值越大噪声越细腻
				const perlin = new ImprovedNoise();  // 创建改进的Perlin噪声生成器实例

				// 纹理重复因子：控制噪声在整个纹理中的重复次数
				// 值越大，噪声图案越小，重复次数越多
				const repeatFactor = 5.0;

				// 三重嵌套循环：遍历3D纹理的所有体素
				// z轴循环：深度方向
				for ( let z = 0; z < size; z ++ ) {
					// y轴循环：高度方向
					for ( let y = 0; y < size; y ++ ) {
						// x轴循环：宽度方向
						for ( let x = 0; x < size; x ++ ) {
							
							// 计算归一化坐标（范围0-1）并应用重复因子
							// 这样可以使噪声图案在纹理空间中重复多次
							const nx = ( x / size ) * repeatFactor;
							const ny = ( y / size ) * repeatFactor;
							const nz = ( z / size ) * repeatFactor;

							// 生成Perlin噪声值
							// Perlin.noise()返回[-1, 1]范围内的浮点数
							// 这是连续、平滑的随机值，适合模拟自然现象
							const noiseValue = perlin.noise( 
								nx * scale,   // x坐标乘以缩放因子
								ny * scale,   // y坐标乘以缩放因子
								nz * scale    // z坐标乘以缩放因子
							);

							// 将噪声值从[-1, 1]映射到[0, 255]
							// 公式：128 + 128 * noiseValue
							// 当noiseValue=1时：128+128=256，但Uint8Array自动取模为0
							// 当noiseValue=-1时：128-128=0
							// 当noiseValue=0时：128+0=128
							data[ i ] = ( 128 + 128 * noiseValue );

							i ++;  // 移动到下一个数据位置
						}
					}
				}

				// 创建Three.js的3D数据纹理对象
				const texture = new THREE.Data3DTexture( 
					data,    // 噪声数据数组
					size,    // 纹理宽度（x方向）
					size,    // 纹理高度（y方向）
					size     // 纹理深度（z方向）
				);
				
				// 配置纹理参数
				texture.format = THREE.RedFormat;           // 使用单通道（红色）格式，节省内存
				texture.minFilter = THREE.LinearFilter;     // 缩小过滤：线性插值
				texture.magFilter = THREE.LinearFilter;     // 放大过滤：线性插值
				texture.wrapS = THREE.RepeatWrapping;       // S方向（U坐标）重复包裹
				texture.wrapT = THREE.RepeatWrapping;       // T方向（V坐标）重复包裹
				texture.wrapR = THREE.RepeatWrapping;       // R方向（W坐标）重复包裹
				texture.unpackAlignment = 1;                // 内存对齐：1字节对齐
				texture.needsUpdate = true;                 // 标记纹理需要上传到GPU

				return texture;
			}

			/**
			 * 主初始化函数
			 * 
			 * 作用：初始化整个Three.js应用程序的所有组件
			 * 执行顺序：
			 * 1. 初始化渲染器和场景
			 * 2. 创建相机和控制器
			 * 3. 设置体积雾和光照
			 * 4. 创建后处理管线
			 * 5. 设置GUI和事件监听
			 */
			function init() {

				// ---------- 第1步：初始化矩形区域光照 ----------
				
				// LTC（线性变换余弦）纹理是矩形区域光照的核心
				// 它们预计算了光照的BRDF积分，用于实时渲染
				const ltcTextures = RectAreaLightTexturesLib.init();
				
				// 设置到Three.js的矩形光照节点系统中
				THREE.RectAreaLightNode.setLTC( ltcTextures );

				// ---------- 第2步：定义渲染层 ----------
				
				// 使用层（Layers）系统来分离不同类型的渲染对象
				// 这里定义第10层为体积光照层，只包含需要体积效果的对象
				const LAYER_VOLUMETRIC_LIGHTING = 10;

				// ---------- 第3步：创建计时器 ----------
				
				// THREE.Timer提供高精度时间测量，用于动画和性能监控
				timer = new THREE.Timer();

				// ---------- 第4步：初始化WebGPU渲染器 ----------
				
				// 创建WebGPURenderer实例（Three.js r160+的新功能）
				renderer = new THREE.WebGPURenderer();
				
				// 设置设备像素比，确保在高DPI屏幕上清晰显示
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数（每帧调用animate函数）
				renderer.setAnimationLoop( animate );
				
				// 色调映射设置：将HDR值映射到显示器的LDR范围
				renderer.toneMapping = THREE.NeutralToneMapping;  // 中性色调映射，保持色彩准确
				renderer.toneMappingExposure = 2;                 // 曝光值，控制整体亮度
				
				// 启用阴影映射
				renderer.shadowMap.enabled = true;
				
				// 创建调试检查器（用于GUI）
				renderer.inspector = new Inspector();
				
				// 将渲染器的canvas元素添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ---------- 第5步：创建场景 ----------
				
				// Scene是所有3D对象的容器，包含网格、灯光、相机等
				scene = new THREE.Scene();

				// ---------- 第6步：创建相机 ----------
				
				// 创建透视投影相机
				// 参数：FOV视野角60度，宽高比，近裁剪面0.1，远裁剪面250
				camera = new THREE.PerspectiveCamera( 
					60,                              // 视野角度（度数），越大看到的范围越广
					window.innerWidth / window.innerHeight,  // 宽高比，根据窗口尺寸计算
					0.1,                             // 近裁剪面，距离小于此值的物体不显示
					250                              // 远裁剪面，距离大于此值的物体不显示
				);
				
				// 设置相机初始位置
				camera.position.set( 0, 5, -15 );

				// ==================== 体积雾区域 ====================
				
				// 创建3D噪声纹理（用于体积雾的密度变化）
				const noiseTexture3D = createTexture3D();

				// 创建烟雾数量的统一变量
				// uniform变量可以在着色器外部动态修改，用于GUI控制
				const smokeAmount = uniform( 2 );  // 初始值设为2

				/**
				 * 创建体积节点材质（VolumeNodeMaterial）
				 * 这是一种基于节点的体积材质，使用光线步进（Ray Marching）算法
				 * 光线步进原理：从摄像机发射光线，沿光线方向等距离采样，累加密度值
				 */
				const volumetricMaterial = new THREE.VolumeNodeMaterial();
				
				// 设置光线步进步数：影响渲染质量和性能
				// 步数越多，渲染越精细，但性能开销越大
				volumetricMaterial.steps = 12;
				
				// 设置偏移节点：添加拜耳抖动来减少条带效应
				// 条带效应是光线步进的常见问题，由于采样不足导致的不连续带状图案
				volumetricMaterial.offsetNode = bayer16( screenCoordinate );
				
				/**
				 * 设置散射节点：定义体积雾的密度分布函数
				 * 这个函数在光线步进的每个采样点被调用
				 */
				volumetricMaterial.scatteringNode = Fn( ( { positionRay } ) => {
					// positionRay：当前采样点在光线上的位置（世界坐标）
					
					// 创建随时间变化的偏移向量
					// 使噪声纹理在空间中"流动"，模拟雾的飘动效果
					// time是TSL内置的时间节点，返回程序运行时间（秒）
					const timeScaled = vec3( 
						time,           // x方向随时间变化
						0,              // y方向不变化
						time.mul( .3 )  // z方向以较慢速度变化（0.3倍）
					);

					/**
					 * 定义采样函数：在3D噪声纹理中采样
					 * 采用多尺度采样技术：在不同频率下采样并叠加
					 * 这种技术称为"分形噪声"或"octave噪声"
					 * 
					 * @param {number} scale - 采样尺度，值越小噪声频率越高
					 * @param {number} timeScale - 时间缩放因子，控制动画速度
					 * @returns {TSLNode} 返回采样结果节点
					 */
					const sampleGrain = ( scale, timeScale = 1 ) => {
						// 采样坐标计算：
						// 1. positionRay * scale：应用缩放因子
						// 2. add( timeScaled.mul( timeScale ) )：添加时间动画偏移
						// 3. mod( 1 )：取模1，确保坐标在[0,1]范围内（因为纹理是重复的）
						// 4. texture3D()：在3D纹理中采样，返回单通道值（r分量）
						// 5. add( .5 )：将值从[0,1]映射到[0.5,1.5]，用于后续乘法叠加
						return texture3D( 
							noiseTexture3D,  // 3D噪声纹理
							positionRay
								.add( timeScaled.mul( timeScale ) )  // 添加时间偏移
								.mul( scale )                         // 应用缩放
								.mod( 1 ),                           // 取模确保在纹理范围内
							0                                          // Mipmap级别
						).r.add( .5 );
					};

					// 多尺度噪声叠加（分形噪声）
					// 原理：在不同频率下采样噪声，然后将结果相乘
					// 这样可以创建既包含大尺度结构又包含小尺度细节的复杂图案
					let density = sampleGrain( .1 );               // 低频噪声（大尺度结构）
					density = density.mul( sampleGrain( .05, 1 ) ); // 中频噪声（中等细节）
					density = density.mul( sampleGrain( .02, 2 ) ); // 高频噪声（小尺度细节）

					// 混合烟雾数量参数
					// mix()是线性插值函数：smokeAmount * density + (1-smokeAmount) * 1
					// 当smokeAmount=0时，返回1（最小密度）
					// 当smokeAmount=1时，返回density（原始噪声密度）
					// 当smokeAmount=2时，返回2*density - 1（可能超过1）
					return smokeAmount.mix( 1, density );
				} );

				// 创建体积雾网格对象
				// 使用立方体几何体定义体积雾的边界
				volumetricMesh = new THREE.Mesh( 
					new THREE.BoxGeometry( 50, 40, 50 ),  // 创建50x40x50的立方体
					volumetricMaterial                    // 使用体积节点材质
				);
				
				// 配置网格属性
				volumetricMesh.receiveShadow = true;      // 网格可以接收阴影
				volumetricMesh.position.y = 20;           // 将网格提升到y=20位置
				
				// 配置渲染层：只启用体积光照层
				volumetricMesh.layers.disableAll();       // 先禁用所有层
				volumetricMesh.layers.enable( LAYER_VOLUMETRIC_LIGHTING );  // 只启用第10层
				
				// 将体积雾网格添加到场景
				scene.add( volumetricMesh );

				// ==================== 光照设置 ====================
				
				/**
				 * 创建三个矩形区域光源
				 * 矩形区域光源模拟真实世界中的面光源（如窗户、灯板）
				 * 参数：颜色，强度，宽度，高度
				 */
				
				// 红色矩形光源
				rectLight1 = new THREE.RectAreaLight( 
					0xff0000,  // 红色（十六进制颜色值）
					5,         // 光照强度
					4,         // 光源宽度（单位：世界单位）
					10         // 光源高度
				);
				rectLight1.layers.enable( LAYER_VOLUMETRIC_LIGHTING );  // 启用体积光照层
				rectLight1.position.set( -5, 6, 5 );  // 设置光源位置
				scene.add( rectLight1 );

				// 绿色矩形光源
				rectLight2 = new THREE.RectAreaLight( 0x00ff00, 5, 4, 10 );
				rectLight2.layers.enable( LAYER_VOLUMETRIC_LIGHTING );
				rectLight2.position.set( 0, 6, 5 );
				scene.add( rectLight2 );

				// 蓝色矩形光源
				rectLight3 = new THREE.RectAreaLight( 0x0000ff, 5, 4, 10 );
				rectLight3.layers.enable( LAYER_VOLUMETRIC_LIGHTING );
				rectLight3.position.set( 5, 6, 5 );
				scene.add( rectLight3 );

				/**
				 * 创建矩形光源的可视化网格辅助函数
				 * 
				 * 作用：为每个矩形光源创建两个平面网格
				 * 一个作为发光面（正面），一个作为暗面（背面）
				 * 这样可以让光源在3D场景中可见，而不是仅作为无形光源
				 * 
				 * @param {THREE.RectAreaLight} rectLight - 要添加可视化网格的矩形光源
				 */
				const createRectLightMesh = ( rectLight ) => {

					// 创建平面几何体：大小与光源相同（4x10）
					const geometry = new THREE.PlaneGeometry( 4, 10 );

					// 创建正面材质（发光面）
					// 使用MeshBasicMaterial（基础材质）因为它不受光照影响，始终保持指定颜色
					const frontMaterial = new THREE.MeshBasicMaterial( { 
						color: rectLight.color,  // 使用光源的颜色
						side: THREE.BackSide      // 渲染背面（因为平面默认正面朝+z方向）
					} );

					// 创建背面材质（暗面）
					// 使用MeshStandardMaterial（标准材质）模拟非发光表面
					const backMaterial = new THREE.MeshStandardMaterial( { 
						color: 0x111111  // 深灰色，接近黑色
					} );

					// 创建暗面网格
					const backSide = new THREE.Mesh( geometry, backMaterial );
					backSide.position.set( 0, 0, .08 );  // 沿z轴略微偏移（远离光源中心）

					// 创建发光面网格
					const frontSide = new THREE.Mesh( geometry, frontMaterial );
					frontSide.position.set( 0, 0, .01 );  // 沿z轴略微偏移（靠近光源中心）

					// 将两个网格添加到光源对象中
					// 注意：不是添加到场景，而是添加到光源，这样网格会随光源一起移动旋转
					rectLight.add( backSide );
					rectLight.add( frontSide );
				};

				// 为每个矩形光源创建可视化网格
				createRectLightMesh( rectLight1 );
				createRectLightMesh( rectLight2 );
				createRectLightMesh( rectLight3 );

				// ==================== 场景几何体 ====================
				
				/**
				 * 创建地板
				 * 作用：提供参考平面，展示阴影和反射效果
				 */
				const geoFloor = new THREE.BoxGeometry( 2000, 0.1, 2000 );  // 非常大的薄盒子作为地板
				const matStdFloor = new THREE.MeshStandardMaterial( { 
					color: 0x444444  // 深灰色
				} );
				
				// 为地板材质添加棋盘格粗糙度图案
				// uv().mul( 400 )：将UV坐标放大400倍，使棋盘格更密集
				// checker()：生成棋盘格图案（黑白相间）
				matStdFloor.roughnessNode = checker( uv().mul( 400 ) );
				
				const mshStdFloor = new THREE.Mesh( geoFloor, matStdFloor );
				scene.add( mshStdFloor );

				/**
				 * 创建环面纽结（Torus Knot）
				 * 作用：作为场景中的主要物体，展示光照和阴影效果
				 * Torus Knot是一种复杂的几何形状，适合展示高光反射
				 */
				const geoKnot = new THREE.TorusKnotGeometry( 
					1.5,   // 大半径（环的半径）
					0.5,   // 小半径（管的半径）
					200,   // 管的分段数（圆周方向）
					16     // 环的分段数（径向）
				);
				const matKnot = new THREE.MeshStandardMaterial( { 
					color: 0xffffff,  // 白色
					roughness: 0,      // 粗糙度为0（完全光滑，产生清晰高光）
					metalness: 0       // 金属度为0（非金属材质）
				} );
				const meshKnot = new THREE.Mesh( geoKnot, matKnot );
				meshKnot.position.set( 0, 5.5, 0 );  // 放置在地板上方
				scene.add( meshKnot );

				// ---------- 第7步：创建轨道控制器 ----------
				
				/**
				 * OrbitControls（轨道控制器）
				 * 提供鼠标/触摸交互：旋转、缩放、平移场景
				 */
				const controls = new OrbitControls( camera, renderer.domElement );
				controls.minDistance = 5;     // 最小缩放距离（相机不能比这更近）
				controls.maxDistance = 200;   // 最大缩放距离（相机不能比这更远）
				controls.target.copy( meshKnot.position );  // 设置控制目标点（围绕哪个点旋转）
				controls.update();            // 应用初始设置

				// ==================== 后处理设置 ====================
				
				/**
				 * 后处理（PostProcessing）
				 * 作用：在最终渲染前对图像进行额外处理
				 * 本示例中用于：体积光照渲染、去噪、与主场景混合
				 */
				postProcessing = new THREE.PostProcessing( renderer );

				// 创建体积光照的渲染层对象
				// 这个层只包含需要体积效果的对象（体积雾网格和矩形光源）
				const volumetricLayer = new THREE.Layers();
				volumetricLayer.disableAll();                     // 先禁用所有层
				volumetricLayer.enable( LAYER_VOLUMETRIC_LIGHTING );  // 只启用体积光照层

				// 创建体积光照强度的统一变量
				// 用于控制体积雾的亮度，可在GUI中调整
				const volumetricLightingIntensity = uniform( 1 );

				// ---------- 第8步：创建主场景渲染通道 ----------
				
				/**
				 * 主场景渲染通道
				 * pass()函数创建一个渲染通道节点
				 * 第一个参数：要渲染的场景
				 * 第二个参数：使用的相机
				 * 返回一个包含颜色、深度等纹理的节点
				 */
				const scenePass = pass( scene, camera );
				
				// 从主场景通道获取深度纹理节点
				// 深度纹理存储每个像素的深度值（距离相机的距离）
				const sceneDepth = scenePass.getTextureNode( 'depth' );

				// 将场景深度应用到体积材质
				// 目的：实现正确的遮挡效果（物体后面的体积雾不可见）
				// screenUV：屏幕空间的UV坐标（范围0-1）
				// sample()：在纹理中采样
				volumetricMaterial.depthNode = sceneDepth.sample( screenUV );

				// ---------- 第9步：创建体积光照渲染通道 ----------
				
				/**
				 * 体积光照渲染通道
				 * 这个通道单独渲染体积效果，使用较低的解析度以提高性能
				 * { depthBuffer: false }：不生成深度缓冲区，因为我们使用主场景的深度
				 */
				const volumetricPass = pass( scene, camera, { depthBuffer: false } );
				volumetricPass.setLayers( volumetricLayer );      // 只渲染体积光照层的对象
				volumetricPass.setResolutionScale( .25 );          // 使用25%的分辨率（性能优化）

				// ---------- 第10步：创建去噪强度统一变量 ----------
				
				// 去噪强度：控制高斯模糊的程度
				// 值越大，模糊越强，噪点越少，但细节也越少
				const denoiseStrength = uniform( .6 );

				// 对体积光照通道应用高斯模糊（去噪）
				// 由于体积光照使用低分辨率渲染和光线步进，会产生噪点
				// 高斯模糊可以有效减少这些噪点
				const blurredVolumetricPass = gaussianBlur( volumetricPass, denoiseStrength );

				// ---------- 第11步：混合主场景和体积光照 ----------
				
				/**
				 * 将去噪后的体积光照叠加到主场景
				 * 原理：
				 * 1. scenePass：主场景的渲染结果
				 * 2. add()：将体积光照作为加法混合叠加
				 * 3. mul( volumetricLightingIntensity )：乘以强度系数
				 */
				const scenePassColor = scenePass.add( 
					blurredVolumetricPass.mul( volumetricLightingIntensity ) 
				);

				// 设置后处理的最终输出节点
				postProcessing.outputNode = scenePassColor;

				// ==================== GUI 设置 ====================
				
				/**
				 * 创建GUI参数对象
				 * 这些参数将通过Inspector显示在界面上，供用户实时调整
				 */
				const params = {
					resolution: volumetricPass.getResolutionScale(),  // 体积光照通道的分辨率缩放
					denoise: true  // 是否启用去噪
				};

				// 创建GUI面板（标题为"体积光照"）
				const gui = renderer.inspector.createParameters( '体积光照控制面板' );

				// ---------- 子面板1：光线步进设置 ----------
				const rayMarching = gui.addFolder( '光线步进设置' );
				
				// 分辨率控制滑块
				rayMarching.add( params, 'resolution', .1, .5 )
					.name( '分辨率缩放' )  // 显示名称
					.onChange( ( resolution ) => {
						// 当滑块值改变时，更新体积光照通道的分辨率
						volumetricPass.setResolutionScale( resolution );
					} );
				
				// 步数控制滑块
				rayMarching.add( volumetricMaterial, 'steps', 2, 12 )
					.name( '步进次数' );  // 控制光线步进的采样数量
				
				// 去噪强度控制滑块
				rayMarching.add( denoiseStrength, 'value', 0, 1 )
					.name( '去噪强度' );
				
				// 去噪开关
				rayMarching.add( params, 'denoise' )
					.name( '启用去噪' )
					.onChange( ( denoise ) => {
						// 根据开关状态选择使用哪个体积光照通道
						const volumetric = denoise ? blurredVolumetricPass : volumetricPass;
						
						// 重新创建混合节点
						const scenePassColor = scenePass.add( 
							volumetric.mul( volumetricLightingIntensity ) 
						);
						
						// 更新后处理输出节点
						postProcessing.outputNode = scenePassColor;
						
						// 标记后处理需要更新（重要！）
						postProcessing.needsUpdate = true;
					} );

				// ---------- 子面板2：光照和场景设置 ----------
				const lighting = gui.addFolder( '光照与场景设置' );
				
				// 雾强度控制滑块
				lighting.add( volumetricLightingIntensity, 'value', 0, 2 )
					.name( '雾强度' );
				
				// 烟雾数量控制滑块
				lighting.add( smokeAmount, 'value', 0, 3 )
					.name( '烟雾密度' );

				// ---------- 第12步：窗口大小变化监听 ----------
				
				// 添加窗口大小变化事件监听器
				// 当用户调整浏览器窗口大小时，调用onWindowResize函数
				window.addEventListener( 'resize', onWindowResize );
			}

			/**
			 * 窗口大小变化回调函数
			 * 
			 * 作用：当浏览器窗口大小改变时，调整相机和渲染器的设置
			 * 确保3D场景正确适应新的窗口尺寸
			 */
			function onWindowResize() {
				
				// 更新相机的宽高比
				// 宽高比 = 窗口宽度 / 窗口高度
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 注意：更改相机参数后必须调用updateProjectionMatrix()，否则更改不会生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器的尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			/**
			 * 动画循环函数（每帧调用）
			 * 
			 * 作用：
			 * 1. 更新计时器
			 * 2. 更新场景中的动画（如旋转光源）
			 * 3. 执行后处理渲染
			 * 
			 * 这是Three.js应用的核心循环，通常以60FPS运行
			 */
			function animate() {
				
				// 更新计时器
				// 记录自上一帧以来的时间
				timer.update();
				
				// 获取时间增量（delta time）
				// 这是上一帧到当前帧经过的时间（秒）
				// 使用时间增量可以使动画速度与帧率无关
				const delta = timer.getDelta();
				
				// 旋转三个矩形光源（不同速度和方向）
				// 这创建了一个动态的光照效果
				rectLight1.rotation.y += -delta;      // 向左旋转（逆时针）
				rectLight2.rotation.y += delta * .5;  // 向右慢速旋转（顺时针，一半速度）
				rectLight3.rotation.y += delta;       // 向右旋转（顺时针）
				
				// 执行后处理渲染
				// 这会执行整个渲染管线：
				// 1. 渲染主场景到scenePass
				// 2. 渲染体积光照到volumetricPass
				// 3. 对volumetricPass应用高斯模糊
				// 4. 将模糊后的体积光照叠加到主场景
				// 5. 将最终结果输出到屏幕
				postProcessing.render();
			}

		</script>

	</body>
</html>