<!-- Three.js WebGPU 体积云效果演示 - 代码功能与技术点详解
一、项目概述
这是一个基于 Three.js + WebGPU 的实时体积云渲染演示项目，通过3D纹理光线步进技术模拟逼真的云朵效果，具有完整的交互界面和实时参数调节功能。

二、核心功能模块
1. 三维场景构建
WebGPU渲染器：使用下一代图形API，提供卓越的渲染性能

透视相机系统：模拟人眼视角，支持交互式观察

轨道控制器：实现鼠标拖拽、滚轮缩放等交互功能

天空背景：渐变蓝色球体作为环境背景

2. 体积云生成系统
text
云朵生成流程：
1. 噪声生成 → 2. 3D纹理创建 → 3. 光线步进渲染 → 4. 实时显示
3. 交互控制系统
GUI参数面板：实时调节云朵密度、透明度等参数

自动旋转动画：云朵缓慢旋转展示效果

响应式布局：自适应窗口大小变化

三、关键技术实现
1. 3D噪声纹理生成
javascript
// 核心技术：Perlin噪声 + 距离衰减
const d = 1.0 - vector.set(x, y, z)
    .subScalar(size / 2)
    .divideScalar(size)
    .length();
data[i] = (128 + 128 * perlin.noise(...)) * d * d;
Perlin噪声：生成自然的随机云朵纹理

距离衰减：创建球状云朵形状（中心密集，边缘稀疏）

各向异性缩放：x/z轴缩放不同，增加自然感

2. 光线步进算法（核心渲染技术）
glsl
RaymarchingBox(steps, ({ positionRay }) => {
    // 1. 采样3D纹理
    const mapValue = texture.sample(positionRay);
    
    // 2. 阈值处理（创建云朵边界）
    mapValue = smoothstep(threshold-range, threshold+range, mapValue);
    
    // 3. 简单光照计算
    const shading = texture.sample(neighbor1) - texture.sample(neighbor2);
    
    // 4. Alpha混合累积
    finalColor.rgb += (1 - finalColor.a) * mapValue * color;
    finalColor.a += (1 - finalColor.a) * mapValue;
});
3. WebGPU着色器编程（TSL）
javascript
// Three.js着色器语言特有语法
const transparentRaymarchingTexture = Fn(({
    texture,
    range = float(0.1),
    threshold = float(0.25),
    // ... 参数定义
}) => {
    // GPU并行计算逻辑
    // ...
});
四、技术架构解析
1. 渲染管线设计
text
CPU端（JavaScript）              GPU端（WebGPU着色器）
├── 3D纹理数据生成                ├── 光线步进主循环
├── 参数uniform传递               ├── 纹理采样与过滤
├── 场景管理                      ├── 光照计算
└── 交互控制                      └── Alpha混合输出
2. 性能优化策略
提前终止优化：alpha≥0.95时提前结束光线步进

自适应步数：用户可调节步数平衡质量/性能

线性纹理过滤：保证平滑的视觉效果

GPU并行计算：充分利用WebGPU并行能力

3. 视觉特效实现
边缘柔和处理：smoothstep函数创建自然过渡

伪光照模拟：相邻采样差值模拟表面法线

颜色叠加：基础颜色与噪声颜色混合

透明度累积：物理正确的alpha混合

五、创新技术点
1. WebGPU现代渲染
利用新一代图形API，性能远超WebGL

直接GPU内存管理，减少CPU-GPU数据传输

支持更复杂的着色器计算

2. TSL着色器语言
Three.js专属着色器语言，语法更友好

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

与JavaScript更好的集成

3. 动态参数系统
javascript
// Uniform变量实现实时参数更新
const threshold = uniform(0.25);  // 可动态修改
gui.add(threshold, 'value', 0, 1, 0.01).name('密度阈值');
无需重新编译着色器即可更新参数

实时反馈，即时预览效果变化

4. 体积渲染技术
传统方法：使用多个透明面片叠加

本方案：真正的体积渲染

在3D空间内逐点采样

支持任意观察角度

真实的体积感和光照效果

六、技术难点与解决方案
1. 性能瓶颈问题
问题：光线步进计算量大，实时渲染困难

解决方案：

可调节步数控制精度/性能平衡

提前终止减少无效计算

WebGPU并行计算加速

2. 视觉伪影问题
问题：离散采样导致条带状伪影

解决方案：

使用smoothstep平滑过渡

线性纹理过滤

足够高的采样步数

3. 内存优化问题
问题：3D纹理占用大量显存

解决方案：

使用单通道纹理（RedFormat）

合理控制纹理尺寸（128³）

Uint8Array压缩存储 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：Three.js WebGPU 体积云演示 -->
		<title>Three.js WebGPU - 体积云效果演示</title>
		<!-- 字符编码设置为UTF-8，支持中文和特殊字符 -->
		<meta charset="utf-8">
		<!-- 视口设置：适配设备宽度，禁止用户缩放，最小和最大缩放比例均为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>

		<!-- 页面信息显示区域，包含logo、标题和描述 -->
		<div id="info">
			<!-- Three.js官方网站链接，点击跳转，class用于样式控制 -->
			<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>
				使用3D纹理光线步进技术实现的体积云效果。<br>
				技术特点：基于Perlin噪声生成、WebGPU加速渲染、实时参数调整
			</small>
			
		</div>

		<!-- 模块导入映射配置，定义JavaScript模块的路径别名 -->
		<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模块 -->
		<script type="module">

			// 导入Three.js WebGPU渲染器及相关核心功能
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js着色器语言(TSL)的核心函数和类型
			// float: 浮点数类型，用于着色器中的单精度浮点运算
			// vec3: 三维向量类型，用于表示坐标、颜色等
			// vec4: 四维向量类型，通常用于表示RGBA颜色
			// If, Break: 控制流语句，用于条件判断和循环控制
			// Fn: 函数定义关键字，用于创建着色器函数
			// smoothstep: 平滑插值函数，创建平滑过渡效果
			// texture3D: 3D纹理采样函数
			// uniform: 统一变量声明，用于从CPU传递数据到GPU
			import { float, vec3, vec4, If, Break, Fn, smoothstep, texture3D, uniform } from 'three/tsl';

			// 导入光线步进工具函数，专门用于在立方体内进行光线追踪计算
			import { RaymarchingBox } from 'three/addons/tsl/utils/Raymarching.js';

			// 导入轨道控制器，提供鼠标交互的相机控制（旋转、缩放、平移）
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入改进的Perlin噪声生成器，用于生成自然的随机纹理
			import { ImprovedNoise } from 'three/addons/math/ImprovedNoise.js';

			// 导入调试检查器，提供GUI界面调整参数
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 声明全局变量，用于在多个函数间共享对象引用
			let renderer;  // WebGPU渲染器实例
			let scene;     // 三维场景对象
			let camera;    // 相机对象
			let mesh;      // 云朵的网格对象（Mesh）

			// 调用初始化函数，启动整个应用程序
			init();

			/**
			 * 初始化函数 - 应用程序的入口点
			 * 负责创建所有必要的Three.js对象、设置场景、加载资源等
			 */
			function init() {

				// ========== 1. 创建并配置WebGPU渲染器 ==========
				// 创建新的WebGPURenderer实例，开启抗锯齿功能
				renderer = new THREE.WebGPURenderer({ antialias: true });
				// 设置渲染器的像素比，适配高清屏幕
				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);

				// ========== 2. 创建三维场景 ==========
				// 创建新的场景对象，所有3D对象都将添加到此场景中
				scene = new THREE.Scene();

				// ========== 3. 创建和配置相机 ==========
				// 创建透视相机，模拟人眼视角
				// 参数说明：60度视野角，窗口宽高比，近裁剪面0.1单位，远裁剪面100单位
				camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 100);
				// 设置相机初始位置：x=0, y=0, z=1.5（沿z轴向前1.5个单位）
				camera.position.set(0, 0, 1.5);

				// ========== 4. 创建交互控制器 ==========
				// 创建轨道控制器，允许用户通过鼠标拖拽、滚轮来控制相机
				// 第一个参数：要控制的相机对象
				// 第二个参数：交互的DOM元素（渲染器的canvas）
				new OrbitControls(camera, renderer.domElement);

				// ========== 5. 创建天空背景 ==========
				// 创建一个临时的canvas元素用于生成天空渐变纹理
				const canvas = document.createElement('canvas');
				canvas.width = 1;   // 宽度为1像素（因为只需要垂直渐变）
				canvas.height = 32; // 高度32像素，足够的渐变分辨率
				
				// 获取canvas的2D绘图上下文
				const context = canvas.getContext('2d');
				// 创建线性渐变对象，从上(0)到下(32)渐变
				const gradient = context.createLinearGradient(0, 0, 0, 32);
				// 添加三个渐变颜色停止点，模拟天空颜色变化
				gradient.addColorStop(0.0, '#014a84'); // 顶部：深蓝色
				gradient.addColorStop(0.5, '#0561a0'); // 中部：中蓝色
				gradient.addColorStop(1.0, '#437ab6'); // 底部：浅蓝色
				
				// 设置填充样式为创建的渐变
				context.fillStyle = gradient;
				// 填充整个canvas区域
				context.fillRect(0, 0, 1, 32);

				// 将canvas转换为Three.js纹理对象
				const skyMap = new THREE.CanvasTexture(canvas);
				// 设置纹理颜色空间为sRGB，确保颜色显示正确
				skyMap.colorSpace = THREE.SRGBColorSpace;

				// 创建天空球体网格对象
				const sky = new THREE.Mesh(
					// 几何体：半径为10的球体，足够大以包裹整个场景
					new THREE.SphereGeometry(10),
					// 材质：使用基础节点材质，应用天空渐变纹理
					new THREE.MeshBasicNodeMaterial({ 
						map: skyMap,           // 设置纹理贴图
						side: THREE.BackSide   // 渲染球体内表面（从内部看）
					})
				);
				// 将天空球体添加到场景中
				scene.add(sky);

				// ========== 6. 生成3D云朵纹理数据 ==========
				// 设置3D纹理的尺寸，128x128x128体素
				const size = 128;
				// 创建Uint8Array存储纹理数据，每个体素1字节（0-255）
				const data = new Uint8Array(size * size * size);

				// 用于遍历数组的索引
				let i = 0;
				// Perlin噪声的缩放系数，控制噪声的频率
				const scale = 0.05;
				// 创建Perlin噪声生成器实例
				const perlin = new ImprovedNoise();
				// 临时向量，用于计算距离
				const vector = new THREE.Vector3();

				// 三层嵌套循环，生成3D噪声数据
				for (let z = 0; z < size; z++) {
					for (let y = 0; y < size; y++) {
						for (let x = 0; x < size; x++) {
							// 计算当前体素到纹理中心的归一化距离
							// 步骤：1. 设置坐标 2. 减去中心点 3. 除以尺寸归一化 4. 计算长度
							const d = 1.0 - vector.set(x, y, z)
								.subScalar(size / 2)      // 减去中心点坐标(64,64,64)
								.divideScalar(size)       // 归一化到[-0.5, 0.5]范围
								.length();                // 计算到原点的距离
							
							// 生成最终的体素值：
							// 1. 生成Perlin噪声值（范围[-1,1]）
							// 2. 映射到[0,255]范围（128 + 128 * noise）
							// 3. 乘以距离因子d*d，使中心值大边缘值小（创建球状云朵）
							// 4. x和z轴使用不同的缩放系数（/1.5），创建各向异性效果
							data[i] = (128 + 128 * perlin.noise(
								x * scale / 1.5,   // x轴噪声，缩放较小
								y * scale,         // y轴噪声，正常缩放
								z * scale / 1.5    // z轴噪声，缩放较小
							)) * d * d;  // 距离平方，创建更明显的中心聚集效果
							
							i++; // 移动到下一个数组位置
						}
					}
				}

				// ========== 7. 创建3D纹理对象 ==========
				const texture = new THREE.Data3DTexture(data, size, size, size);
				texture.format = THREE.RedFormat;      // 只使用红色通道（单通道灰度图）
				texture.minFilter = THREE.LinearFilter; // 缩小时的过滤方式：线性过滤
				texture.magFilter = THREE.LinearFilter; // 放大时的过滤方式：线性过滤
				texture.unpackAlignment = 1;           // 内存对齐方式
				texture.needsUpdate = true;            // 标记纹理数据需要上传到GPU

				// ========== 8. 定义光线步进着色器函数 ==========
				/**
				 * 透明光线步进纹理函数
				 * 这是一个着色器函数，将在GPU上执行
				 * @param {Object} params - 函数参数对象
				 * @param {Texture} params.texture - 3D纹理对象
				 * @param {float} params.range - 阈值范围，控制云朵边缘的柔和度
				 * @param {float} params.threshold - 阈值，控制云朵的密度
				 * @param {float} params.opacity - 不透明度，控制云朵的透明度
				 * @param {float} params.steps - 光线步进步数，影响渲染质量和性能
				 * @returns {vec4} 返回最终的颜色（RGBA）
				 */
				const transparentRaymarchingTexture = Fn(({
					texture,
					range = float(0.1),      // 默认阈值范围0.1
					threshold = float(0.25), // 默认阈值0.25
					opacity = float(0.25),   // 默认不透明度0.25
					steps = float(100)       // 默认步数100
				}) => {
					// 声明最终颜色变量，初始化为黑色透明(0,0,0,0)
					const finalColor = vec4(0).toVar();

					// 调用光线步进函数，在立方体内部进行采样
					RaymarchingBox(steps, ({ positionRay }) => {
						// positionRay是光线当前位置，范围[-0.5, 0.5]
						// 采样3D纹理，需要将坐标转换到[0,1]范围
						const mapValue = float(texture.sample(positionRay.add(0.5)).r).toVar();

						// 使用smoothstep函数处理采样值，创建平滑的云朵边缘
						// smoothstep(edge0, edge1, x): 当x<edge0返回0，x>edge1返回1，之间平滑过渡
						mapValue.assign(smoothstep(
							threshold.sub(range), // 下界：阈值-范围
							threshold.add(range), // 上界：阈值+范围
							mapValue              // 输入的采样值
						).mul(opacity));          // 乘以不透明度系数

						// 计算简单的光照效果（法线估计）
						// 通过比较相邻采样点的差异来估计表面法线方向
						const shading = texture.sample(positionRay.add(vec3(-0.01))).r
							.sub(texture.sample(positionRay.add(vec3(0.01))).r);

						// 计算基础颜色，结合光照和位置信息
						const col = shading.mul(3.0)                  // 光照强度增强3倍
							.add(positionRay.x.add(positionRay.y).mul(0.25)) // 添加基于位置的渐变
							.add(0.2);                              // 基础亮度偏移

						// 颜色混合：使用alpha混合公式累加RGB颜色
						// finalColor.rgb += (1 - finalColor.a) * mapValue * col
						finalColor.rgb.addAssign(
							finalColor.a.oneMinus()  // 1 - 当前alpha
							.mul(mapValue)           // 乘以当前采样值
							.mul(col)                // 乘以计算的颜色
						);

						// Alpha混合：累加透明度
						// finalColor.a += (1 - finalColor.a) * mapValue
						finalColor.a.addAssign(
							finalColor.a.oneMinus()  // 1 - 当前alpha
							.mul(mapValue)           // 乘以当前采样值
						);

						// 优化：如果alpha值已经接近不透明（>=0.95），提前终止光线步进
						// 这可以显著提高性能，避免不必要的计算
						If(finalColor.a.greaterThanEqual(0.95), () => {
							Break(); // 跳出光线步进循环
						});
					});

					// 返回最终的累积颜色
					return finalColor;
				});

				// ========== 9. 创建材质参数（可调节） ==========
				// 使用uniform声明变量，这些值可以从JavaScript代码中动态修改
				const baseColor = uniform(new THREE.Color(0x798aa0)); // 云朵基础颜色（灰蓝色）
				const range = uniform(0.1);      // 阈值范围，默认0.1
				const threshold = uniform(0.25); // 密度阈值，默认0.25
				const opacity = uniform(0.25);   // 不透明度，默认0.25
				const steps = uniform(100);      // 光线步进步数，默认100

				// ========== 10. 创建云朵材质 ==========
				// 调用光线步进函数，传入3D纹理和参数
				const cloud3d = transparentRaymarchingTexture({
					texture: texture3D(texture, null, 0), // 将3D纹理转换为着色器可用的格式
					range,        // 阈值范围
					threshold,    // 密度阈值
					opacity,      // 不透明度
					steps         // 步数
				});

				// 将基础颜色添加到云朵颜色中
				// setRGB方法：设置颜色的RGB分量，保持Alpha不变
				const finalCloud = cloud3d.setRGB(cloud3d.rgb.add(baseColor));

				// 创建Three.js节点材质
				const material = new THREE.NodeMaterial();
				material.colorNode = finalCloud;  // 设置颜色节点为光线步进结果
				material.side = THREE.BackSide;   // 渲染背面（从立方体内部看）
				material.transparent = true;      // 启用透明度（重要！）

				// ========== 11. 创建云朵网格对象 ==========
				mesh = new THREE.Mesh(
					// 几何体：1x1x1的立方体，光线步进在这个空间内进行
					new THREE.BoxGeometry(1, 1, 1),
					// 材质：使用上面创建的光线步进材质
					material
				);
				// 将云朵网格添加到场景中
				scene.add(mesh);

				// ========== 12. 创建GUI控制面板 ==========
				// 通过调试检查器创建参数控制面板
				const gui = renderer.inspector.createParameters('云朵参数');
				// 添加阈值控制滑块：范围0-1，步长0.01
				gui.add(threshold, 'value', 0, 1, 0.01).name('密度阈值');
				// 添加不透明度控制滑块：范围0-1，步长0.01
				gui.add(opacity, 'value', 0, 1, 0.01).name('不透明度');
				// 添加范围控制滑块：范围0-1，步长0.01
				gui.add(range, 'value', 0, 1, 0.01).name('边缘柔和度');
				// 添加步数控制滑块：范围0-200，步长1
				gui.add(steps, 'value', 0, 200, 1).name('光线步数');

				// ========== 13. 添加窗口大小变化监听器 ==========
				// 当浏览器窗口大小改变时，调整相机和渲染器
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 窗口大小变化处理函数
			 * 当浏览器窗口大小改变时自动调用，确保渲染正确适配新尺寸
			 */
			function onWindowResize() {
				// 更新相机的宽高比，使用当前窗口的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵（必须调用此方法使更改生效）
				camera.updateProjectionMatrix();
				// 更新渲染器尺寸，匹配新的窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数
			 * 每帧自动调用，用于更新动画状态和渲染场景
			 */
			function animate() {
				// 更新云朵的旋转：基于时间缓慢旋转
				// performance.now()返回页面加载以来的毫秒数
				// 除以7500控制旋转速度（大约每47秒旋转一圈）
				// 负号控制旋转方向（顺时针）
				mesh.rotation.y = -performance.now() / 7500;
				
				// 渲染场景：将3D场景通过相机视角渲染到canvas上
				renderer.render(scene, camera);
			}

		</script>

	</body>
</html>