<!-- Three.js WebGPU 自定义雾效背景应用
一、整体功能概述
这是一个基于 Three.js WebGPU 渲染器的 3D可视化演示应用，核心功能是通过后处理技术实现自定义雾效背景。应用展示了一个战损科幻头盔模型，使用HDR环境贴图提供高质量的环境光照和反射，并实现了基于距离的雾效渲染，营造出逼真的空间深度感和氛围效果。

二、主要功能模块
1. 核心渲染系统
WebGPU渲染器：使用下一代图形API，提供更高效的GPU利用率和更现代的特性支持

TSL着色器语言：Three.js自带的着色器语言，用于编写可组合的着色器节点

后处理管线：完整的后期处理流程，将原始渲染结果与雾效等效果合成

2. 视觉特效功能
距离雾效：基于相机距离的雾效计算，物体越远雾越浓

ACES色调映射：电影级色调映射算法，优化HDR到LDR的转换

HDR环境光照：超高动态范围环境贴图，提供真实的光照和反射

抗锯齿：MSAA多采样抗锯齿，平滑3D边缘

3. 交互功能
轨道控制器：鼠标拖拽旋转、滚轮缩放、右键平移的完整3D交互

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

实时渲染：60FPS的流畅动画循环

4. 资源管理系统
模型加载：GLTF格式的3D模型加载和显示

纹理加载：UltraHDR格式的高质量环境贴图

异步加载：所有资源异步加载，避免阻塞主线程

三、关键技术点详解
1. WebGPU渲染架构
javascript
// 核心优势：
- 相比WebGL，提供更底层的GPU控制
- 更好的多线程支持
- 更现代的着色器语言（WGSL）
- 自动内存管理和更少的驱动开销
2. TSL（Three.js Shader Language）
javascript
// 主要特点：
- 声明式的着色器编程
- 可组合的着色器节点
- 实时编译和热重载支持
- 与Three.js材质系统深度集成

// 关键节点：
const fogFactor = rangeFogFactor(2.7, 4)  // 范围雾效节点
const scenePassTM = scenePass.toneMapping() // 色调映射节点
const compose = fogFactor.mix(scenePassTM, fogColor) // 混合节点
3. 后处理管线设计
text
原始渲染 → [场景通道] → [深度提取] → [雾效计算] → [色调映射] → [混合输出]
       ↑               ↑               ↑
   3D场景         深度信息       雾颜色和参数
4. 雾效算法原理
javascript
// 范围雾效计算公式：
fogFactor = (distance - fogNear) / (fogFar - fogNear)
// 其中：
// - distance: 像素到相机的距离
// - fogNear: 雾效开始距离（2.7）
// - fogFar: 雾效完全覆盖距离（4）
// 结果：0（无雾）到1（完全被雾覆盖）的线性插值
5. HDR工作流
text
HDR纹理加载 → 等距柱状映射 → 环境贴图设置 → 物理渲染计算
    ↓
ACES色调映射 → sRGB颜色空间转换 → 屏幕显示
6. 性能优化技术
单次渲染多效应用：通过后处理管线，多个效果在一次绘制中完成

智能资源管理：纹理和模型按需加载和卸载

GPU优化：利用WebGPU的自动批处理和减少状态切换

内存优化：合理的裁剪平面设置，避免渲染不可见物体

四、技术架构特点
1. 模块化设计
javascript
// 清晰的模块分离：
- 渲染核心（WebGPURenderer）
- 着色器逻辑（TSL节点）
- 后处理管理（PostProcessing）
- 资源加载（Loader系统）
- 用户交互（OrbitControls）
2. 可扩展性
效果扩展：可通过添加更多TSL节点扩展后处理效果

模型替换：支持加载不同的GLTF模型

参数调整：雾效参数可实时调整

渲染模式：可切换不同的渲染策略

3. 现代Web标准
ES6模块：使用原生JavaScript模块系统

Import Maps：浏览器原生的模块解析

Promise异步：基于Promise的资源加载

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

五、技术挑战与解决方案
1. WebGPU兼容性
挑战：WebGPU相对较新，浏览器支持仍在完善

方案：提供优雅降级方案或使用WebGL回退

2. HDR渲染流程
挑战：HDR到LDR的正确转换和色调映射

方案：使用行业标准的ACES Filmic色调映射算法

3. 性能平衡
挑战：高质量效果与流畅帧率的平衡

方案：合理的细节层次和渲染优化

4. 跨平台一致性
挑战：不同设备和浏览器的渲染一致性

方案：使用标准的WebGPU特性和测试覆盖

六、应用场景和扩展方向
1. 适用场景
产品展示：高质量的3D产品可视化

游戏开发：作为游戏引擎的渲染演示

建筑设计：建筑场景的雾效和氛围渲染

教育演示：计算机图形学教学示例

2. 可扩展功能
实时雾效调整：GUI控制雾效参数

多模型支持：场景中加载多个3D模型

动态光照：实时变化的灯光效果

天气系统：雨、雪等天气效果集成

VR/AR支持：虚拟现实和增强现实适配

七、性能指标和技术要求
1. 硬件要求
支持WebGPU的现代GPU

至少2GB显存（用于HDR纹理和模型）

现代浏览器（Chrome 113+，Edge 113+）

2. 性能目标
目标帧率：60 FPS

加载时间：< 5秒（模型+HDR纹理）

内存使用：< 500MB

响应时间：交互延迟 < 100ms

3. 最佳实践
使用压缩纹理格式

实现模型的LOD（细节层次）

添加加载状态指示器

提供性能统计面板 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<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>

		<!-- 信息展示区域：包含Logo、标题、描述和版权信息 -->
		<div id="info">
			<!-- Three.js官方Logo链接：点击跳转到Three.js官网 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link" title="访问Three.js官网"></a>

			<!-- 标题包装器：包含主标题和副标题 -->
			<div class="title-wrapper">
				<!-- 主标题链接：Three.js官方网站链接 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：当前示例的具体名称 -->
				<span>自定义雾效背景演示</span>
			</div>

			<!-- 详细描述和版权信息区域 -->
			<small>
				<!-- 主要技术说明：通过后处理技术实现的自定义雾效背景效果 -->
				通过后处理技术实现的自定义雾效背景效果。<br/>
				
				<!-- 3D模型来源信息：战损科幻头盔模型的创作者 -->
				战损科幻头盔模型由 <a href="https://sketchfab.com/theblueturtle_" target="_blank" rel="noopener">theblueturtle_</a> 创作。
				
				<!-- HDR环境贴图来源信息：皇家广场HDR环境贴图 -->
				<a href="https://hdrihaven.com/hdri/?h=royal_esplanade" target="_blank" rel="noopener">皇家广场</a> HDR环境贴图由 
				<a href="https://hdrihaven.com/" target="_blank" rel="noopener">HDRI Haven</a> 提供。
				
				<!-- 技术特点说明 -->
				<br/>技术特点：基于WebGPU渲染、TSL着色器语言、后处理管线。
			</small>
		</div>

		<!-- 导入映射配置（Import Maps）：现代浏览器中的模块解析机制 -->
		<!-- 作用：将模块标识符映射到实际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模块：包含Three.js应用的完整逻辑 -->
		<!-- type="module" 表示这是一个ES6模块，支持模块化导入 -->
		<script type="module">

			// ==================== 模块导入区域 ====================
			
			// 导入Three.js核心库（WebGPU版本）
			// THREE对象包含Three.js的所有核心类和方法
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js Shader Language）着色器节点
			// pass: 创建渲染通道节点
			// color: 创建颜色节点
			// rangeFogFactor: 创建范围雾效因子节点
			import { pass, color, rangeFogFactor } from 'three/tsl';

			// 导入附加组件（addons）
			// UltraHDRLoader: 用于加载超高动态范围（HDR）图像
			import { UltraHDRLoader } from 'three/addons/loaders/UltraHDRLoader.js';
			
			// OrbitControls: 轨道控制器，提供鼠标/触摸交互控制
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// GLTFLoader: GLTF格式3D模型加载器
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

			// ==================== 全局变量声明 ====================
			
			// 核心Three.js对象
			let camera;     // 相机：定义观察者的视角和投影方式
			let scene;      // 场景：包含所有要渲染的3D对象、灯光等
			let renderer;   // 渲染器：负责将3D场景渲染到2D画布上
			
			// 后处理对象：管理后处理效果管线
			let postProcessing;

			// ==================== 初始化调用 ====================
			
			// 页面加载完成后立即调用初始化函数
			// 这是整个应用的入口点
			init();

			/**
			 * 初始化函数 - 整个Three.js应用的基础设置
			 * 
			 * 主要任务：
			 * 1. 创建并配置相机、场景、渲染器
			 * 2. 设置后处理效果管线
			 * 3. 加载3D模型和纹理资源
			 * 4. 设置用户交互控制
			 * 5. 绑定窗口事件监听器
			 * 
			 * 此函数只会在页面加载时执行一次
			 */
			function init() {

				// ============ 1. 相机创建与配置 ============
				
				// 创建透视相机（PerspectiveCamera）
				// 参数说明：
				// 45 - 视野角度（Field of View），单位：度，影响可视范围大小
				// window.innerWidth / window.innerHeight - 宽高比，根据窗口尺寸计算
				// 0.25 - 近裁剪平面（Near clipping plane），比这个距离近的物体不被渲染
				// 20 - 远裁剪平面（Far clipping plane），比这个距离远的物体不被渲染
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.25, 20);
				
				// 设置相机初始位置（X, Y, Z坐标）
				// X轴：水平方向，负值表示向左
				// Y轴：垂直方向，正值表示向上
				// Z轴：深度方向，正值表示向屏幕外（观察者方向）
				camera.position.set(-1.8, 0.6, 2.7);

				// ============ 2. 场景创建 ============
				
				// 创建3D场景容器
				// 场景是所有3D对象（网格、灯光、相机等）的容器
				scene = new THREE.Scene();

				// ============ 3. 渲染器创建与配置 ============
				
				// 创建WebGPU渲染器实例
				// { antialias: true } 开启抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer({ antialias: true });
				
				// 设置设备像素比
				// window.devicePixelRatio 获取设备的物理像素与CSS像素的比率
				// 这有助于在高DPI屏幕上获得更清晰的渲染效果
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为当前浏览器窗口的尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// animate函数将在每一帧被调用（通常每秒60次）
				renderer.setAnimationLoop(animate);
				
				// 禁用渲染器内置的色调映射（Tone Mapping）
				// 我们将通过后处理管线应用更精细的色调映射控制
				renderer.toneMapping = THREE.NoToneMapping;
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				// 这样3D场景就可以显示在网页上了
				document.body.appendChild(renderer.domElement);

				// ============ 4. 后处理效果管线设置 ============
				
				// 4.1 创建场景渲染通道
				// pass()函数创建一个渲染通道节点，它将渲染指定的场景和相机
				const scenePass = pass(scene, camera);
				
				// 获取场景通道的视图深度（View Z）节点
				// 视图深度表示每个像素到相机的距离，是计算雾效的关键数据
				const scenePassViewZ = scenePass.getViewZNode();

				// 4.2 定义雾的颜色
				// color(0x4080cc) 创建一个颜色节点，参数是十六进制颜色值
				// 0x4080cc 表示浅蓝色（RGB: 64, 128, 204）
				// 这个颜色是在sRGB色彩空间中定义的
				const fogColor = color(0x4080cc);

				// 4.3 计算雾效混合因子
				// rangeFogFactor(2.7, 4) 创建范围雾效因子
				// 参数说明：
				// 2.7 - 雾效开始的距离（从相机位置算起）
				// 4 - 雾效完全覆盖的距离，超过这个距离物体完全被雾遮挡
				// .context({ getViewZ: () => scenePassViewZ }) 提供上下文信息
				// 这相当于传统的：scene.fog = new THREE.Fog(0x4080cc, 2.7, 4);
				const fogFactor = rangeFogFactor(2.7, 4).context({ getViewZ: () => scenePassViewZ });

				// 4.4 对场景通道应用色调映射
				// toneMapping()方法应用指定的色调映射算法
				// THREE.ACESFilmicToneMapping - ACES电影级色调映射算法
				// 1 - 色调映射强度参数
				// 色调映射将高动态范围（HDR）颜色转换为低动态范围（LDR）显示
				const scenePassTM = scenePass.toneMapping(THREE.ACESFilmicToneMapping, 1);

				// 4.5 混合雾效和色调映射后的场景
				// fogFactor.mix() 使用雾效因子混合两个输入
				// 参数1：scenePassTM - 色调映射后的场景（前景）
				// 参数2：fogColor - 雾颜色（背景）
				// 根据雾效因子（0到1之间）线性插值混合前景和背景
				const compose = fogFactor.mix(scenePassTM, fogColor);

				// 4.6 创建后处理管理器
				// PostProcessing类管理整个后处理管线
				postProcessing = new THREE.PostProcessing(renderer);
				
				// 只应用默认的颜色空间转换，不应用额外的色调映射
				// 因为我们已经在前面的步骤中应用了色调映射
				postProcessing.outputColorTransform = true;
				
				// 设置后处理管线的最终输出节点
				// 整个后处理的结果将由compose节点定义
				postProcessing.outputNode = compose;

				// ============ 5. 3D资源和纹理加载 ============
				
				// 5.1 加载HDR环境贴图
				// 创建UltraHDRLoader实例
				new UltraHDRLoader()
					// 设置纹理文件的基础路径
					.setPath('textures/equirectangular/')
					
					// 加载指定的HDR图像文件
					// 参数1：文件名
					// 参数2：加载完成后的回调函数
					.load('royal_esplanade_2k.hdr.jpg', function (texture) {
						// 设置纹理映射方式为等距柱状反射映射
						// 这种映射方式将2D图像包裹在球体上，用于环境反射
						texture.mapping = THREE.EquirectangularReflectionMapping;
						
						// 将加载的纹理设置为场景的环境贴图
						// 环境贴图为场景中的所有物体提供环境光照和反射
						scene.environment = texture;

						// 5.2 加载GLTF 3D模型
						// 创建GLTFLoader实例并设置模型文件路径
						const loader = new GLTFLoader().setPath('models/gltf/DamagedHelmet/glTF/');
						
						// 加载GLTF模型文件
						loader.load('DamagedHelmet.gltf', function (gltf) {
							// 将加载的模型添加到场景中
							// gltf.scene包含模型的所有网格、材质、动画等
							scene.add(gltf.scene);
							
							// 可选：可以在这里添加模型加载后的处理逻辑
							// 例如：调整模型位置、缩放、旋转，或设置动画
						});
					});

				// ============ 6. 用户交互控制设置 ============
				
				// 创建轨道控制器（OrbitControls）
				// 允许用户通过鼠标/触摸与3D场景交互
				const controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置相机与目标点的最小距离（限制缩放）
				controls.minDistance = 2;
				
				// 设置相机与目标点的最大距离（限制缩放）
				controls.maxDistance = 5;
				
				// 设置控制器的目标点（相机围绕旋转的中心点）
				controls.target.set(0, -0.1, -0.2);
				
				// 更新控制器内部状态
				controls.update();

				// ============ 7. 窗口事件监听器 ============
				
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，自动更新相机和渲染器
				window.addEventListener('resize', onWindowResize);
				
				// 可选：可以添加更多事件监听器
				// 例如：键盘事件、全屏切换、性能监控等

			}

			/**
			 * 窗口大小变化处理函数
			 * 
			 * 当浏览器窗口大小改变时，此函数被调用
			 * 主要任务：
			 * 1. 更新相机的宽高比以适应新窗口尺寸
			 * 2. 更新渲染器的尺寸以填充新窗口
			 * 
			 * @event resize - 浏览器窗口大小变化事件
			 */
			function onWindowResize() {
				// 更新相机宽高比为新的窗口宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机参数（如宽高比）改变后，必须调用此方法更新内部矩阵
				camera.updateProjectionMatrix();

				// 更新渲染器的尺寸为新窗口尺寸
				// 这确保3D场景正确填充整个浏览器窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 注意：后处理管线的尺寸通常会自动更新
				// 如果遇到渲染问题，可能需要手动更新后处理尺寸
			}

			/**
			 * 动画循环函数
			 * 
			 * 这是Three.js应用的核心循环函数
			 * 每帧（通常每秒60帧）都会被调用一次
			 * 
			 * 主要任务：
			 * 1. 更新控制器状态（处理用户输入）
			 * 2. 更新场景中的动画（如果有）
			 * 3. 执行后处理渲染
			 * 
			 * 注意：这里使用后处理渲染而不是标准的renderer.render()
			 */
			function animate() {
				// 使用后处理管理器进行渲染
				// postProcessing.render()会执行整个后处理管线：
				// 1. 渲染原始场景到纹理
				// 2. 应用所有后处理效果（雾效、色调映射等）
				// 3. 将最终结果输出到屏幕
				postProcessing.render();
				
				// 注意：OrbitControls通常会自动更新，不需要手动调用update()
				// 但如果需要更新其他动画（如模型旋转、粒子效果等），可以在这里添加
			}

			// ==================== 可选功能扩展区域 ====================
			
			// 这里可以添加更多的功能函数，例如：
			// - 性能监控和统计显示
			// - 场景切换功能
			// - 雾效参数动态调整
			// - 全屏切换功能
			// - 截图保存功能
			// - VR/AR模式支持

		</script>

	</body>
</html>