<!-- 代码功能和技术点详解
一、核心功能概述
这是一个基于 Three.js WebGPU 版本的体积渲染示例，通过光线步进技术在立方体内渲染三维柏林噪声纹理，模拟出逼真的体积云/烟雾效果。

主要功能特性：
体积渲染效果：在立方体内部渲染出有机的云状体积效果

实时交互：支持鼠标拖拽旋转、滚轮缩放视图

参数调节：可实时调整渲染阈值和光线步数

响应式设计：自动适应窗口大小变化

二、主要技术点详解
1. WebGPU 渲染器
javascript
renderer = new THREE.WebGPURenderer({ antialias: true });
现代图形API：替代WebGL，提供更好的性能和更低的开销

原生GPU访问：更直接的硬件控制，支持计算着色器等高级特性

并行处理优势：更适合大规模并行计算（如体积渲染）

2. 体积渲染技术
这是最核心的技术，实现了从3D密度场到2D图像的转换：

光线步进算法原理：
text
对于屏幕上的每个像素：
  1. 从相机位置发射一条光线
  2. 沿着光线方向逐步前进（Raymarching）
  3. 在每个步进点采样3D纹理获取密度值
  4. 当密度超过阈值时，视为"命中"表面
  5. 根据命中点的位置和法线计算颜色
关键实现：
javascript
RaymarchingBox(steps, ({ positionRay }) => {
  const mapValue = texture.sample(positionRay.add(0.5)).r.toVar();
  If(mapValue.greaterThan(threshold), () => {
    // 命中表面，计算颜色并停止步进
    Break();
  });
});
3. 柏林噪声生成
javascript
const perlin = new ImprovedNoise();
const d = perlin.noise(x * 6.5, y * 6.5, z * 6.5);
技术特点：
连续性：相邻点之间平滑过渡，适合自然形态

多频叠加：通过频率参数(6.5)控制细节层次

3D扩展：在三维空间中生成，形成体积数据

数据存储：
javascript
// 128×128×128 个体素，每个体素1字节
const data = new Uint8Array(size * size * size);
// 映射到[0,255]范围，存储为灰度值
data[i] = d * 128 + 128;
4. TSL（Three.js Shader Language）
声明式着色器编程：
javascript
// 传统GLSL vs TSL对比：
// GLSL: if(mapValue > threshold) { ... }
// TSL: If(mapValue.greaterThan(threshold), () => { ... })
主要优势：
类型安全：vec3、vec4等强类型

模块化：通过Fn()创建可复用着色器函数

易读性：类似JavaScript的语法

节点连接：便于构建复杂的材质网络

5. 3D纹理采样与法线计算
javascript
// 采样3D纹理
const mapValue = texture.sample(positionRay.add(0.5)).r;

// 计算法线（基于中心差分法）
texture.normal(p) // 在p点计算梯度作为法线
法线计算原理：
text
对于3D纹理中的点(x,y,z)：
  法线 = normalize(vec3(
    density(x+Δ,y,z) - density(x-Δ,y,z),  // x方向梯度
    density(x,y+Δ,z) - density(x,y-Δ,z),  // y方向梯度  
    density(x,y,z+Δ) - density(x,y,z-Δ)   // z方向梯度
  ))
6. 优化策略
提前终止优化：
javascript
If(mapValue.greaterThan(threshold), () => {
  // 一旦找到表面就停止步进
  Break(); // 显著减少计算量
});
步数控制：
javascript
const steps = uniform(200); // 最大步数，平衡质量和性能
// 步数越多：质量越高，渲染越慢
// 步数越少：性能越好，可能出现走样
7. 交互系统
轨道控制器：
旋转：左键拖拽

平移：右键拖拽或中键拖拽

缩放：滚轮或双指触摸

实时参数调节：
javascript
gui.add(threshold, 'value', 0, 1, 0.01).name('表面阈值');
// 阈值控制：决定哪些密度区域可见
// 值越小：更多区域可见（云更"稀薄"）
// 值越大：只有高密度区域可见（云更"厚重"）
8. 渲染流程架构
text
初始化阶段
  ├─ 创建WebGPU渲染器
  ├─ 生成柏林噪声3D纹理
  ├─ 编译TSL着色器代码
  ├─ 创建立方体网格和材质
  └─ 设置交互控制器

渲染循环（每帧）
  ├─ 处理用户输入（轨道控制器）
  ├─ 执行光线步进计算（GPU）
  │    ├─ 从相机发射光线
  │    ├─ 在立方体内步进采样
  │    ├─ 与3D密度场求交
  │    └─ 计算着色和光照
  └─ 输出到屏幕
三、性能考虑
计算复杂度：
text
总计算量 = 屏幕像素数 × 光线步数 × 纹理采样数
示例：1920×1080分辨率 × 200步 ≈ 4.1亿次采样/帧
优化手段：
Early Exit：提前终止光线步进

自适应步长：根据密度变化调整步长

层次结构：使用空间划分加速结构

降采样渲染：动态调整渲染分辨率

四、扩展可能性
技术增强：
多重散射：模拟光线在体积内的多次反弹

动态噪声：添加时间维度，创建动画效果

彩色体积：使用多通道纹理支持颜色变化

阴影支持：体积阴影和自阴影效果

应用场景：
科学可视化：医学CT数据、气象云图

游戏特效：烟雾、爆炸、魔法效果

艺术创作：抽象体积艺术、数据雕塑

教育演示：物理现象的可视化

五、技术栈总结
技术层次	使用的技术	作用
图形API	WebGPU	底层图形接口，高性能渲染
3D框架	Three.js	高级3D图形抽象，场景管理
着色语言	TSL	声明式着色器编程，材质定义
噪声算法	Perlin Noise	生成自然、连续的随机图案
渲染算法	Raymarching	体积渲染核心算法
交互	OrbitControls	3D视图导航控制
调试	Inspector	实时参数调节界面 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示网页在浏览器标签页上的名称 -->
		<title>Three.js WebGPU 体积渲染示例 - 柏林噪声体积云</title>
		<!-- 字符编码声明：指定文档使用 UTF-8 字符编码，支持多语言字符显示 -->
		<meta charset="utf-8">
		<!-- 
			视口设置（viewport）：控制移动设备上的显示方式
			width=device-width：让页面宽度等于设备宽度
			user-scalable=no：禁止用户手动缩放页面（保持固定比例）
			minimum-scale=1.0, maximum-scale=1.0：锁定缩放比例为1
		-->
		<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 官方徽标链接：
				- href：指向Three.js官方网站
				- target="_blank"：在新标签页中打开链接
				- rel="noopener"：安全措施，防止新页面访问原页面的window对象
				- class="logo-link"：CSS类名，通常用于设置背景图片显示徽标
			-->
			<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）：现代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 渲染器及相关核心功能
			import * as THREE from 'three/webgpu';
			
			// 导入 TSL（Three.js Shader Language）的核心构建块：
			// - Break: 用于在着色器中实现break语句功能
			// - If: 条件语句构建块
			// - vec3, vec4: 三维和四维向量类型
			// - texture3D: 三维纹理采样器
			// - uniform: 声明uniform变量（在着色器中不变，由CPU传递）
			// - Fn: 定义着色器函数
			import { Break, If, vec3, vec4, texture3D, uniform, Fn } 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';

			// 导入检查器/调试面板：提供可视化参数调节界面
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ==================== 全局变量声明 ====================
			// 声明将在整个模块中使用的变量（未使用var/let/const声明，需要在函数中赋值）
			let renderer, // Three.js 渲染器实例（WebGPURenderer）
				scene,    // Three.js 场景对象，包含所有3D对象、灯光、相机等
				camera;   // 相机对象，定义观察者的视角
			let mesh;    // 网格对象，包含几何体和材质，是主要的渲染对象

			// ==================== 初始化函数调用 ====================
			// 立即调用初始化函数，开始设置Three.js应用
			init();

			// ==================== 初始化函数定义 ====================
			/**
			 * 初始化函数：Three.js应用的主要设置入口
			 * 职责：创建渲染器、场景、相机、几何体、材质、灯光等所有必要组件
			 * 并设置用户交互和事件监听器
			 */
			function init() {

				// ---------- 1. 创建WebGPU渲染器 ----------
				// 创建Three.js的WebGPU渲染器实例
				// { antialias: true }：启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置渲染器的像素比率，匹配设备物理像素与CSS像素的比例
				// 在高DPI设备（如Retina显示屏）上提供更清晰的图像
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器画布大小为整个浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数，浏览器每帧调用animate函数进行渲染
				renderer.setAnimationLoop( animate );
				
				// 创建并附加检查器/调试面板到渲染器
				// 这将提供实时调节参数的功能（如阈值、步数等）
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到网页body中
				// 这样Three.js渲染的内容才能显示在页面上
				document.body.appendChild( renderer.domElement );

				// ---------- 2. 创建场景 ----------
				// 创建Three.js场景对象，作为所有3D对象的容器
				// 场景包含网格、灯光、相机等，是渲染的根容器
				scene = new THREE.Scene();

				// ---------- 3. 创建相机 ----------
				// 创建透视相机，模拟人眼视角（近大远小）：
				// - 参数1: 视野角度（Field of View）60度
				// - 参数2: 宽高比，根据窗口尺寸计算
				// - 参数3: 近裁剪面0.1，比这个距离更近的物体不显示
				// - 参数4: 远裁剪面100，比这个距离更远的物体不显示
				camera = new THREE.PerspectiveCamera( 60, window.innerWidth / window.innerHeight, 0.1, 100 );
				
				// 设置相机初始位置：在z轴上向后移动2个单位
				// 这样相机位于(0,0,2)，看向原点(0,0,0)
				camera.position.set( 0, 0, 2 );

				// ---------- 4. 创建轨道控制器 ----------
				// 创建轨道控制器，将相机和渲染器的canvas绑定
				// 用户可以通过鼠标拖拽、滚轮缩放来与3D场景交互
				// 不需要将控制器赋值给变量，因为它会自动管理自身状态
				new OrbitControls( camera, renderer.domElement );

				// ==================== 创建3D柏林噪声纹理 ====================
				// 这个纹理将用于体积渲染，模拟云、烟雾等自然效果
				
				// 定义3D纹理的尺寸：128x128x128个体素（voxels）
				// 这个尺寸是性能（内存和计算）和质量（细节）之间的权衡
				const size = 128;
				
				// 创建Uint8Array类型数组存储纹理数据
				// 每个体素用1个字节（0-255）表示，总共128^3 = 2,097,152个体素
				const data = new Uint8Array( size * size * size );

				// 变量初始化
				let i = 0; // 数据数组的当前索引
				
				// 创建柏林噪声生成器实例
				// Perlin噪声具有连续性、平滑过渡的特点，适合生成自然形状
				const perlin = new ImprovedNoise();
				
				// 创建临时三维向量，用于计算每个体素的归一化坐标
				const vector = new THREE.Vector3();

				// 三重嵌套循环：遍历3D纹理的所有体素
				// 顺序：从z轴最外层开始，然后是y轴，最后是x轴最内层
				// 这种顺序确保数据在内存中按正确布局存储
				for ( let z = 0; z < size; z ++ ) {
					for ( let y = 0; y < size; y ++ ) {
						for ( let x = 0; x < size; x ++ ) {
							// 将体素坐标(x,y,z)从[0,127]范围映射到[0,1]范围
							// 这是纹理坐标的标准表示方式
							vector.set( x, y, z ).divideScalar( size );
							
							// 计算该位置的柏林噪声值
							// 参数乘以6.5增加噪声频率，创建更多细节
							// 返回值范围大约在[-1, 1]之间
							const d = perlin.noise( vector.x * 6.5, vector.y * 6.5, vector.z * 6.5 );
							
							// 将噪声值从[-1,1]映射到[0,255]并存入数组
							// d * 128：将范围映射到[-128, 128]
							// + 128：将范围平移到[0, 256]
							// 最终截断到[0,255]（Uint8Array自动处理）
							data[ i ++ ] = d * 128 + 128;
						}
					}
				}

				// 使用生成的数据创建Three.js的3D纹理对象
				// 参数：数据数组、宽度、高度、深度
				const texture = new THREE.Data3DTexture( data, size, size, size );
				
				// 设置纹理格式为单通道（红色通道）
				// 因为我们的噪声数据是单值的，不需要RGB或RGBA
				texture.format = THREE.RedFormat;
				
				// 设置纹理缩小过滤为线性过滤
				// 当纹理被缩小时（观察距离变远），使用线性插值平滑过渡
				texture.minFilter = THREE.LinearFilter;
				
				// 设置纹理放大过滤为线性过滤
				// 当纹理被放大时（观察距离变近），使用线性插值避免像素化
				texture.magFilter = THREE.LinearFilter;
				
				// 设置内存对齐方式为1字节对齐
				// 这是纹理数据在内存中的布局方式，影响性能和兼容性
				texture.unpackAlignment = 1;
				
				// 标记纹理需要更新
				// 这通知Three.js将我们的数据上传到GPU显存
				texture.needsUpdate = true;

				// ==================== 创建着色器函数（使用TSL） ====================
				/**
				 * 不透明体积光线步进函数
				 * 这是一个TSL函数，将在着色器中执行
				 * 
				 * @param {Object} params 函数参数
				 * @param {texture3D} params.texture 三维噪声纹理
				 * @param {uniform} params.steps 光线步进的最大步数（控制质量）
				 * @param {uniform} params.threshold 表面阈值（决定哪些部分可见）
				 * @returns {vec4} 最终计算的颜色（RGBA）
				 */
				const opaqueRaymarchingTexture = Fn( ( { texture, steps, threshold } ) => {

					// 声明最终颜色变量，初始化为透明黑色(0,0,0,0)
					// toVar()将常量转换为变量，允许在函数内部修改
					const finalColor = vec4( 0 ).toVar();

					/**
					 * 调用光线步进辅助函数
					 * 在单位立方体[-0.5,0.5]范围内沿视线方向逐步前进
					 * 
					 * @param {number} steps 最大步进次数
					 * @param {Function} callback 每步调用的回调函数
					 *        接收包含 positionRay（当前步进位置）的对象
					 */
					RaymarchingBox( steps, ( { positionRay } ) => {
						
						// 从3D纹理中采样当前位置的噪声值
						// positionRay在[-0.5,0.5]范围内，需要+0.5转换到[0,1]纹理坐标范围
						// .r 只获取红色通道值（因为纹理是单通道格式）
						// .toVar() 转换为变量，后续可以在If语句中引用
						const mapValue = texture.sample( positionRay.add( 0.5 ) ).r.toVar();

						// 条件判断：如果采样值大于阈值
						// 这意味着我们"命中"了体积表面（密度足够高的区域）
						If( mapValue.greaterThan( threshold ), () => {
							
							// 计算用于着色的纹理坐标（[0,1]范围）
							const p = vec3( positionRay ).add( 0.5 );
							
							// 计算最终颜色：
							// 1. texture.normal(p)：计算纹理在p点的法线（基于梯度）
							//    这模拟了光照效果，使体积有立体感
							// 2. .mul(0.5)：将法线值减半，减弱对比度
							// 3. positionRay.mul(1.5).add(0.25)：基于位置添加颜色变化
							//    这创建从中心到边缘的渐变效果
							// 4. 两者相加得到最终RGB颜色
							finalColor.rgb.assign( 
								texture.normal( p )
									.mul( 0.5 )
									.add( positionRay.mul( 1.5 ).add( 0.25 ) ) 
							);
							
							// 设置完全不透明（alpha = 1）
							// 因为我们已经"命中"表面，不需要透明度
							finalColor.a.assign( 1 );
							
							// 跳出光线步进循环
							// 一旦找到表面，就不需要继续步进了，提高性能
							Break();
						} );
					} );

					// 返回计算得到的颜色
					// 如果没有命中任何表面，将返回初始的透明黑色
					return finalColor;
				} );

				// ==================== 创建材质和网格 ====================
				
				// 创建uniform变量：这些值可以在着色器外部动态修改
				// 这些变量在GPU着色器程序中是只读的常量
				const threshold = uniform( 0.6 ); // 初始阈值0.6，控制哪些密度区域可见
				const steps = uniform( 200 );     // 初始步数200，控制光线步进精度

				// 创建Three.js节点材质
				// 节点材质使用TSL构建着色器，提供更直观的材质定义方式
				const material = new THREE.NodeMaterial();
				
				// 设置材质的颜色节点为我们定义的光线步进函数
				// 这意味着每个像素的颜色将由我们的体积渲染函数计算
				material.colorNode = opaqueRaymarchingTexture( {
					// 将Three.js纹理对象转换为TSL纹理节点
					// 参数1: texture - Three.js纹理对象
					// 参数2: null - UV变换（这里不需要）
					// 参数3: 0 - 纹理单元索引
					texture: texture3D( texture, null, 0 ),
					steps: steps,      // 传递步数uniform变量
					threshold: threshold // 传递阈值uniform变量
				} );
				
				// 设置材质渲染立方体的背面
				// 因为相机在立方体内部观察，我们看到的是内表面
				material.side = THREE.BackSide;
				
				// 启用透明度支持
				// 虽然我们的体积渲染函数通常返回不透明颜色，但保持透明选项更灵活
				material.transparent = true;

				// 创建立方体网格
				// 使用单位立方体几何体（1x1x1）和我们创建的体积材质
				mesh = new THREE.Mesh( new THREE.BoxGeometry( 1, 1, 1 ), material );
				
				// 将网格添加到场景中
				// 现在这个立方体将成为我们体积渲染的"容器"
				scene.add( mesh );

				// ==================== 创建调试GUI ====================
				// 使用检查器创建参数调节面板
				// 'Parameters'是面板的标题
				const gui = renderer.inspector.createParameters( '参数调节' );
				
				// 添加阈值调节滑块：
				// - threshold: uniform变量对象
				// - 'value': 调节的属性名
				// - 0, 1: 最小值和最大值
				// - 0.01: 步进值（每次拖动的变化量）
				// - .name('阈值'): 在GUI中显示的标签
				gui.add( threshold, 'value', 0, 1, 0.01 ).name( '表面阈值' );
				
				// 添加步数调节滑块：
				// 控制光线步进的精度，影响渲染质量和性能
				gui.add( steps, 'value', 0, 300, 1 ).name( '光线步数' );

				// ==================== 事件监听器设置 ====================
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，调整渲染器和相机
				window.addEventListener( 'resize', onWindowResize );
			}

			// ==================== 窗口大小变化处理函数 ====================
			/**
			 * 处理浏览器窗口大小变化
			 * 确保渲染器尺寸和相机比例始终匹配窗口尺寸
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// 窗口大小变化后，需要重新计算宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机参数（如aspect）改变时，必须调用此方法更新内部矩阵
				camera.updateProjectionMatrix();
				
				// 更新渲染器大小，使其填充整个窗口
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 动画循环函数 ====================
			/**
			 * 动画循环函数
			 * 在每一帧被渲染器调用（通常每秒60次）
			 * 这里是Three.js应用的核心渲染循环
			 */
			function animate() {
				// 执行渲染：将场景和相机传递给渲染器
				// 渲染器将计算3D场景的2D投影并绘制到canvas上
				renderer.render( scene, camera );
				
				// 注意：这个简单示例中没有动画更新逻辑
				// 复杂的示例可能会在这里更新对象位置、旋转、材质属性等
				// 例如：mesh.rotation.y += 0.01; // 让立方体旋转
			}

		</script>

	</body>
</html>