<!-- Three.js WebGPU 立方体贴图混合示例 - 功能与技术点详解
📋 整体功能概述
本示例是一个基于 WebGPU 的交互式 3D 可视化应用，核心功能是展示两个立方体贴图的动态混合效果。应用加载一个3D头盔模型，并使用着色器语言实时混合两种不同的环境光照效果，创建出随时间变化的动态反射环境。

🎯 主要功能模块
1. 动态环境混合系统
核心效果：将两个立方体贴图（Pisa HDR 和银河系）进行实时混合

动画机制：使用正弦波函数控制混合比例，实现周期性变化

视觉表现：头盔表面的反射环境会随时间平滑过渡

2. 交互式3D查看器
轨道控制：用户可通过鼠标拖拽旋转、滚轮缩放、右键平移

自适应布局：自动调整相机和渲染器以适应窗口大小变化

模型展示：高清3D头盔模型，展示复杂材质和环境反射

3. 现代图形技术演示
WebGPU 渲染：使用下一代 Web 图形 API

实时着色器编程：通过 TSL 节点系统实现高级视觉效果

HDR 渲染管线：支持高动态范围图像处理

🛠️ 核心技术点详解
1. WebGPU 渲染引擎
javascript
// 关键代码
renderer = new THREE.WebGPURenderer({ antialias: true });
技术优势：

替代传统的 WebGL，提供更接近原生 GPU 的性能

支持多线程渲染和计算着色器

更好的内存管理和资源绑定模型

自动图形管线状态管理

性能特征：

更低的 CPU 开销

更好的并行处理能力

支持更复杂的渲染效果

2. TSL 着色语言系统
javascript
// 核心混合逻辑
scene.environmentNode = mix(
    pmremTexture(cube2Texture),    // 纹理1：银河系
    pmremTexture(cube1Texture),    // 纹理2：Pisa HDR
    oscSine(time.mul(0.1))         // 基于时间的混合因子
);
TSL 节点图架构：
text
时间输入 → [时间×0.1] → [正弦波生成器] → 混合因子
                                      ↓
纹理A(PMREM) → [混合节点] ← 纹理B(PMREM)
                                      ↓
                               动态环境贴图
核心节点功能：
mix(a, b, factor)：线性插值混合

当 factor=0 时输出 a

当 factor=1 时输出 b

中间值实现平滑过渡

oscSine(time)：正弦波振荡器

生成周期性的 -1 到 1 的值

默认周期为 2π 秒

通过 time.mul(0.1) 将周期延长到约 62.8 秒

pmremTexture()：预过滤辐射环境贴图转换

将普通立方体贴图转换为优化格式

预计算不同粗糙度级别的反射

显著提高实时反射渲染性能

3. 立方体贴图处理技术
立方体贴图结构：
text
      +----+----+----+
      |    | PY |    |  ↑ +Y（上）
+----+----+----+----+----+
|    | NX | PZ | PX |    |  ← 展开的立方体
+----+----+----+----+----+
      |    | NY |    |  ↓ -Y（下）
      +----+----+----+
            | NZ |    → +Z（前）
            +----+
纹理处理流程：
加载阶段：

HDR 贴图（Pisa）：保留高动态范围光照信息

JPG 贴图（银河系）：提供星空背景

生成 mipmaps：优化远处渲染质量

转换阶段：

text
原始立方体贴图
     ↓
PMREM 预处理
     ↓
多级mipmap链生成
     ↓
实时着色器采样
4. 环境光照系统
双环境设置：
javascript
// 环境照明（用于物体反射）
scene.environmentNode = ...

// 场景背景（天空盒）
scene.backgroundNode = scene.environmentNode.context({
    getTextureLevel: () => float(0.5)
});
技术特点：
分离渲染：反射环境和背景使用同一纹理但不同细节级别

mipmap 控制：背景使用较低的 mipmap 级别（0.5），减少细节但提高性能

一致性保证：反射和背景视觉上保持一致的环境

5. 资源加载与优化
异步加载策略：
javascript
// 顺序但并行的加载模式
const cube2Texture = await new THREE.CubeTextureLoader().loadAsync(...);
const gltf = await loader.loadAsync('DamagedHelmet.gltf');
性能优化措施：
纹理压缩：为不同格式选择合适的压缩

mipmap 生成：运行时生成，优化内存使用

GPU 上传优化：WebGPU 的显存管理更高效

6. 交互与控制机制
轨道控制器特性：
三轴控制：旋转（左键）、缩放（滚轮）、平移（右键）

物理模拟：惯性滑动、平滑过渡

约束限制：最小/最大距离防止穿模

响应式设计：
实时重计算：窗口大小改变时立即更新投影矩阵

像素比适配：适配高DPI显示器（Retina等）

性能保持：大小变化时维持渲染性能

🔬 技术架构亮点
1. 模块化设计
javascript
// 清晰的模块分离
- 核心 Three.js（WebGPU 版本）
- TSL 着色语言模块
- 加载器模块（纹理、模型）
- 控制器模块
- 工具模块（检查器）
2. 现代JavaScript特性
ES6 模块：明确的依赖关系，避免全局污染

异步/等待：清晰的异步代码流程

导入映射：灵活的模块路径配置

3. 渲染管线优化
text
CPU端：资源准备 → GPU端：渲染执行
     ↓                       ↓
资源加载               顶点处理
纹理处理               光栅化
场景更新               像素着色
                    后处理
🎨 视觉效果实现原理
1. 动态混合算法
text
混合公式：result = texture1 × (1 - factor) + texture2 × factor

其中 factor = (sin(time × 0.1) + 1) / 2

时间轴变化：
time=0s: factor=0.5 → 均匀混合
time=15.7s: factor≈1 → 主要显示texture2
time=31.4s: factor=0.5 → 均匀混合
time=47.1s: factor≈0 → 主要显示texture1
周期循环...
2. 材质反射模拟
环境映射：使用立方体贴图模拟真实世界反射

能量守恒：HDR 贴图保持光照能量正确

粗糙度变化：PMREM 预计算不同粗糙度的反射

3. 色调映射处理
javascript
renderer.toneMapping = THREE.LinearToneMapping;
目的：将 HDR 颜色值映射到显示器的 LDR 范围

线性映射：简单但有效的映射方式

视觉保护：避免过曝和颜色失真

📊 性能考量
1. 内存使用优化
纹理复用：同一个纹理用于环境和背景

智能加载：按需加载和释放资源

mipmap 策略：根据距离动态选择细节级别

2. 渲染性能
WebGPU 优势：更少的驱动开销

预计算：PMREM 减少实时计算量

批次优化：Three.js 自动合并绘制调用

3. 扩展性设计
模块化：易于添加新功能

配置化：通过参数调整效果

可维护：清晰的代码结构和注释

🚀 应用场景与扩展
适用场景：
产品展示：动态环境下的产品可视化

艺术创作：随时间变化的数字艺术

教育演示：实时图形编程教学

技术验证：WebGPU 和 TSL 技术测试

可能的扩展方向：
更多混合模式：添加不同的插值函数

用户交互控制：允许手动调整混合参数

实时录制：导出混合动画为视频

多模型支持：展示不同模型在相同环境下的表现

AR/VR 集成：支持沉浸式观看体验 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示示例的主要功能 -->
		<title>Three.js WebGPU示例 - 立方体贴图混合效果</title>
		<!-- 字符编码设置：UTF-8确保中文和其他字符正确显示 -->
		<meta charset="utf-8">
		<!-- 
			视口设置：
			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">
		<!-- 外部CSS样式表链接：控制页面布局和样式 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			信息显示区域：包含示例的标题、描述和版权信息
			id="info": 用于CSS样式定位和JavaScript操作
		-->
		<div id="info">
			<!-- 
				Three.js官方Logo链接：
				target="_blank": 在新标签页打开链接
				rel="noopener": 安全特性，防止新页面访问原页面的window对象
				class="logo-link": CSS类，通常用于设置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>
				<!-- 主要功能描述：使用正弦波函数动态混合两个立方体贴图 -->
				本示例演示了两个立方体贴图（Cube Map）的动态混合效果。<br/>
				<!-- 技术说明：使用Three.js的TSL着色语言实现基于时间的动画混合 -->
				通过TSL（Three.js Shading Language）的正弦波函数随时间混合环境贴图。<br/><br/>
				
				<!-- 模型版权信息 -->
				示例中使用模型：<br/>
				<b>「战斗损坏的科幻头盔」</b><br/>
				<!-- 模型作者信息 -->
				模型作者：
				<a href="https://sketchfab.com/theblueturtle_" target="_blank" rel="noopener">theblueturtle_</a><br/>
				
				<!-- 使用说明 -->
				<br/>使用说明：<br/>
				• 鼠标拖拽：旋转视角<br/>
				• 鼠标滚轮：缩放场景<br/>
				• 右键拖拽：平移视角<br/>
				
				<!-- 技术特性说明 -->
				<br/>技术特性：<br/>
				• 使用WebGPU渲染器<br/>
				• 基于时间的环境贴图动画混合<br/>
				• HDR高动态范围贴图支持<br/>
				• PMREM预过滤辐射环境贴图<br/>
				• 实时正弦波混合效果
			</small>
		</div>

		<!-- 
			导入映射（Import Map）配置：
			现代JavaScript模块系统特性，用于定义模块路径别名
			使import语句中的模块引用更简洁
		-->
		<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版本的核心功能
			// * as THREE：将所有导出内容打包到THREE对象中
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js Shading Language）的着色器节点函数：
			// mix()：混合函数，根据第三个参数混合前两个参数
			// oscSine()：正弦波振荡器，生成基于时间的正弦波值
			// time：时间节点，提供着色器中的时间信息
			// pmremTexture()：将立方体贴图转换为PMREM（预过滤辐射环境贴图）
			// float()：创建浮点数节点
			import { mix, oscSine, time, pmremTexture, float } from 'three/tsl';

			// 导入HDR立方体贴图加载器（专门用于加载HDR格式的立方体贴图）
			import { HDRCubeTextureLoader } from 'three/addons/loaders/HDRCubeTextureLoader.js';

			// 导入轨道控制器：提供鼠标/触摸交互控制相机旋转、缩放和平移
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入GLTF加载器：用于加载GLTF/GLB格式的3D模型
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

			// 导入检查器工具：用于调试和检查Three.js场景
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ============================ 全局变量声明 ============================
			// 声明将在多个函数中使用的变量
			let camera;      // 相机对象：定义观察3D场景的视角
			let scene;       // 场景对象：包含所有3D对象、灯光等
			let renderer;    // 渲染器对象：负责将3D场景绘制到2D画布

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

			// ============================ 初始化函数 ============================
			// async关键字：这是一个异步函数，可以内部使用await等待异步操作完成
			async function init() {
				// 注意：此函数中的代码按顺序执行，但某些操作（如纹理加载）是异步的

				// ---------- 1. 创建并设置相机 ----------
				// PerspectiveCamera参数说明：
				// 参数1：视野角度(FOV) - 45度，控制可见范围
				// 参数2：宽高比 - 使用窗口宽高比，确保正确比例
				// 参数3：近裁剪面 - 0.25，距离相机小于此值的物体不渲染
				// 参数4：远裁剪面 - 20，距离相机大于此值的物体不渲染
				camera = new THREE.PerspectiveCamera(
					45, 
					window.innerWidth / window.innerHeight, 
					0.25, 
					20
				);
				// 设置相机初始位置：x, y, z坐标
				// 调整这些值可以改变初始视角
				camera.position.set(-1.8, 0.6, 2.7);

				// ---------- 2. 创建场景 ----------
				// Scene是3D对象的容器，所有要渲染的对象都添加到场景中
				scene = new THREE.Scene();

				// ---------- 3. 加载第一个HDR立方体贴图 ----------
				// 定义立方体贴图六个面的文件名（顺序重要）：
				// 顺序：正x, 负x, 正y, 负y, 正z, 负z
				const hdrUrls = [
					'px.hdr',  // 正X面（右）
					'nx.hdr',  // 负X面（左）
					'py.hdr',  // 正Y面（上）
					'ny.hdr',  // 负Y面（下）
					'pz.hdr',  // 正Z面（前）
					'nz.hdr'   // 负Z面（后）
				];
				
				// 创建HDR立方体贴图加载器实例
				const cube1Texture = new HDRCubeTextureLoader()
					.setPath('./textures/cube/pisaHDR/')  // 设置纹理文件所在目录
					.load(hdrUrls);  // 加载所有六个面的纹理
				
				// 配置纹理参数以优化渲染质量：
				cube1Texture.generateMipmaps = true;  // 生成mipmaps（多级纹理金字塔）
				cube1Texture.minFilter = THREE.LinearMipmapLinearFilter;  // 使用线性mipmap过滤，提高远处纹理质量

				// ---------- 4. 加载第二个立方体贴图（银河系） ----------
				// 定义第二个立方体贴图的六个面
				const cube2Urls = [
					'dark-s_px.jpg',  // 正X面
					'dark-s_nx.jpg',  // 负X面
					'dark-s_py.jpg',  // 正Y面
					'dark-s_ny.jpg',  // 负Y面
					'dark-s_pz.jpg',  // 正Z面
					'dark-s_nz.jpg'   // 负Z面
				];
				
				// 使用标准的CubeTextureLoader加载JPG格式的立方体贴图
				// 使用await等待异步加载完成
				const cube2Texture = await new THREE.CubeTextureLoader()
					.setPath('./textures/cube/MilkyWay/')
					.loadAsync(cube2Urls);  // loadAsync返回Promise，可用await等待
				
				// 配置第二个纹理
				cube2Texture.generateMipmaps = true;
				cube2Texture.minFilter = THREE.LinearMipmapLinearFilter;

				// ---------- 5. 创建动态环境混合效果 ----------
				// 使用TSL着色语言创建节点图：
				// 效果：银河系贴图和Pisa贴图随时间正弦波动画混合
				// time.mul(0.1)：将时间乘以0.1，降低动画速度（周期变为10倍）
				// oscSine()：基于时间生成-1到1之间的正弦波值
				// pmremTexture()：将立方体贴图转换为PMREM，优化实时渲染性能
				// mix()：根据第三个参数（混合因子）混合前两个纹理
				//   混合因子为0时完全使用cube2Texture，为1时完全使用cube1Texture
				scene.environmentNode = mix(
					pmremTexture(cube2Texture),    // 第一个纹理：银河系环境
					pmremTexture(cube1Texture),    // 第二个纹理：Pisa HDR环境
					oscSine(time.mul(0.1))         // 混合因子：基于时间的正弦波值
				);

				// ---------- 6. 设置场景背景 ----------
				// 使用相同的环境贴图作为场景背景，但使用不同的mipmap级别
				// context()：创建节点上下文，可以覆盖节点的某些参数
				// getTextureLevel: () => float(0.5)：设置纹理级别为0.5
				// 纹理级别控制mipmap的细节级别，0.5表示中等细节
				scene.backgroundNode = scene.environmentNode.context({
					getTextureLevel: () => float(0.5)
				});

				// ---------- 7. 加载并添加3D模型 ----------
				// 创建GLTF加载器实例并设置模型路径
				const loader = new GLTFLoader().setPath('models/gltf/DamagedHelmet/glTF/');
				// 异步加载模型文件
				const gltf = await loader.loadAsync('DamagedHelmet.gltf');
				// 将加载的模型添加到场景中
				// gltf.scene包含模型的所有网格、材质等
				scene.add(gltf.scene);

				// ---------- 8. 创建WebGPU渲染器 ----------
				// WebGPURenderer：Three.js的WebGPU后端渲染器
				// { antialias: true }：启用抗锯齿，平滑边缘
				renderer = new THREE.WebGPURenderer({ antialias: true });

				// 设置渲染器参数：
				renderer.setPixelRatio(window.devicePixelRatio);  // 匹配设备像素比，确保清晰度
				renderer.setSize(window.innerWidth, window.innerHeight);  // 设置渲染尺寸为窗口大小
				renderer.toneMapping = THREE.LinearToneMapping;  // 设置线性色调映射，处理HDR颜色

				// ---------- 9. 添加调试工具 ----------
				// 将检查器附加到渲染器，按特定快捷键（通常是Ctrl+Shift+I）可打开调试面板
				renderer.inspector = new Inspector();

				// ---------- 10. 设置动画循环 ----------
				// setAnimationLoop：设置渲染循环，每帧调用指定函数
				// 类似requestAnimationFrame，但由Three.js管理
				renderer.setAnimationLoop(render);

				// ---------- 11. 将渲染器添加到DOM ----------
				// renderer.domElement是canvas元素，包含渲染结果
				document.body.appendChild(renderer.domElement);

				// ---------- 12. 创建用户交互控制器 ----------
				// OrbitControls：轨道控制器，允许用户通过鼠标/触摸控制相机
				// 参数1：要控制的相机对象
				// 参数2：交互的DOM元素（通常是渲染器的canvas）
				const controls = new OrbitControls(camera, renderer.domElement);
				controls.minDistance = 2;   // 相机与目标点的最小距离（缩放限制）
				controls.maxDistance = 10;  // 相机与目标点的最大距离（缩放限制）

				// ---------- 13. 添加窗口大小变化监听器 ----------
				// 当窗口大小改变时，调整相机和渲染器以适应新尺寸
				window.addEventListener('resize', onWindowResize);
			}

			// ============================ 窗口大小变化处理函数 ============================
			/**
			 * 处理浏览器窗口大小变化事件
			 * 确保3D场景正确适应新的窗口尺寸
			 */
			function onWindowResize() {
				// 1. 更新相机的宽高比（重要！否则图像会拉伸变形）
				camera.aspect = window.innerWidth / window.innerHeight;
				// 2. 更新相机的投影矩阵（应用新的宽高比）
				camera.updateProjectionMatrix();
				// 3. 更新渲染器大小以匹配新窗口尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			// ============================ 渲染函数 ============================
			/**
			 * 每帧调用的渲染函数
			 * 这是动画循环的核心，负责将3D场景绘制到2D画布
			 * 注意：此函数每秒调用60次（取决于浏览器刷新率）
			 */
			function render() {
				// 执行渲染：将场景从相机视角渲染到画布
				// 参数1：要渲染的场景
				// 参数2：用于渲染的相机
				renderer.render(scene, camera);
			}

		</script>

	</body>
</html>