<!-- 代码功能与技术点详解
一、核心功能概述
1. 主要功能
这是一个使用Three.js WebGPU版本实现的深度纹理可视化示例。程序将3D场景的深度信息（物体到相机的距离）渲染成纹理，然后以灰度图像的形式显示在屏幕上。

2. 功能流程
text
场景3D对象 → 第一遍渲染 → 深度纹理生成 → 第二遍渲染 → 屏幕显示
     ↑                              ↓
相机视角控制                     深度值转换为灰度
二、详细功能描述
1. 3D场景创建
创建一个包含50个随机分布的环面扭结（Torus Knot）的场景

所有物体呈球形分布，具有随机位置和旋转

场景使用统一的节点材质，便于后续深度信息提取

2. 深度信息捕获
将整个3D场景渲染到离屏缓冲区（Render Target）

在此过程中自动生成深度纹理，记录每个像素的深度值

深度值范围：近裁剪面（1）到远裁剪面（20）

3. 深度可视化
将深度纹理作为颜色纹理应用到全屏四边形

通过灰度映射显示深度信息：近处亮，远处暗

用户可以直观看到场景的深度分布

4. 交互功能
鼠标拖拽：旋转相机视角

鼠标滚轮：缩放场景

触摸屏支持：平移和缩放操作

三、主要技术点
1. WebGPU渲染技术
javascript
// WebGPU是下一代Web图形API
const renderer = new THREE.WebGPURenderer({ antialias: true });
优势：相比WebGL有更好的并行计算能力

特性：支持计算着色器、更好的内存管理

兼容性：现代浏览器支持（Chrome、Edge等）

2. 深度纹理技术
javascript
const depthTexture = new THREE.DepthTexture();
depthTexture.type = THREE.FloatType;
存储格式：使用FloatType提高精度

生成方式：在渲染目标中自动生成

数据内容：每个像素存储一个浮点深度值

3. 两遍渲染（Two-pass Rendering）
javascript
// 第一遍：渲染到离屏缓冲区
renderer.setRenderTarget(renderTarget);
renderer.render(scene, camera);

// 第二遍：渲染到屏幕
renderer.setRenderTarget(null);
quad.render(renderer);
第一遍：生成场景的深度信息

第二遍：处理深度信息并显示

优势：分离渲染逻辑，便于后处理

4. TSL（Three.js Shading Language）
javascript
import { texture } from 'three/tsl';
materialFX.colorNode = texture(depthTexture);
节点化材质系统：可视化方式构建着色器

实时编译：TSL代码在运行时编译为GLSL/WGSL

灵活性：便于创建复杂的材质效果

5. 渲染目标（Render Target）
javascript
const renderTarget = new THREE.RenderTarget(width, height);
renderTarget.depthTexture = depthTexture;
离屏渲染：不直接输出到屏幕

纹理附件：可以附加颜色、深度、模板纹理

复用性：渲染结果可以多次使用

6. 相机与投影系统
javascript
const camera = new THREE.PerspectiveCamera(70, aspect, 1, 20);
透视投影：模拟人眼视觉效果

视锥体裁剪：只渲染近裁剪面和远裁剪面之间的物体

相机控制：通过OrbitControls实现交互

7. 几何体分布算法
javascript
// 球面坐标分布算法
const zScale = Math.sqrt(1.0 - z * z) * scale;
球面坐标转换：在球面上均匀分布物体

随机性控制：确保物体不重叠且有自然分布

数学原理：球面坐标到笛卡尔坐标的转换

8. 响应式设计
javascript
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    renderer.setSize(window.innerWidth, window.innerHeight);
}
窗口自适应：自动调整渲染尺寸

设备像素比：支持高DPI显示

相机参数更新：保持正确的宽高比

四、技术架构
1. 模块化设计
text
three.js核心模块
    ├── WebGPU渲染器
    ├── 相机系统
    ├── 几何体系统
    ├── 材质系统
    └── 场景图
2. 渲染管线
text
用户交互 → 相机更新 → 第一遍渲染 → 深度纹理生成
                                ↓
                    第二遍渲染 → 屏幕显示
3. 内存管理
纹理内存：深度纹理存储在GPU内存

几何体实例化：多个物体共享同一几何体数据

资源清理：自动管理WebGPU资源

五、应用场景
1. 教育用途
学习深度缓冲原理

理解3D渲染管线

掌握WebGPU基础知识

2. 开发调试
可视化深度信息，调试渲染问题

测试相机裁剪设置

验证几何体位置关系

3. 技术演示
展示WebGPU性能

演示后处理效果

展示Three.js高级特性

4. 算法验证
深度相关算法测试

空间分布算法验证

渲染优化技术验证

六、性能特点
1. GPU友好
利用WebGPU的并行计算能力

减少CPU到GPU的数据传输

高效的纹理采样

2. 内存效率
几何体实例化减少内存占用

深度纹理使用合适的精度

及时的资源释放

3. 渲染优化
两遍渲染避免冗余计算

合理的批次处理

自动的视锥体裁剪 -->


<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示页面核心功能 -->
		<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">
		<!-- 外部样式表链接：引入页面样式 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 页面信息展示区域：包含logo、标题和描述 -->
		<div id="info" class="invert">
			<!-- 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" title="访问Three.js官方网站">Three.js</a>
				<!-- 副标题：当前示例名称 -->
				<span>深度纹理渲染示例</span>
			</div>

			<!-- 页面描述：简要说明示例功能 -->
			<small>将场景深度信息渲染为纹理，并进行后期处理可视化</small>
			<!-- 额外说明：解释深度纹理的作用 -->
			<small style="display:block;margin-top:20px;">深度纹理记录了每个像素到相机的距离，常用于后处理效果</small>
		</div>

		<!-- ES模块导入映射配置：定义模块路径别名 -->
		<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逻辑代码 -->
		<script type="module">

			// 导入Three.js WebGPU核心模块
			// WebGPU是新一代图形API，相比WebGL性能更高，功能更强大
			import * as THREE from 'three/webgpu';
			
			// 从TSL模块导入texture函数
			// TSL（Three.js Shading Language）是Three.js的着色语言
			// texture函数用于在节点材质中创建纹理采样节点
			import { texture } from 'three/tsl';
			
			// 导入轨道控制器模块
			// OrbitControls提供鼠标拖拽、缩放、旋转等相机控制功能
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 全局变量声明区域
			let camera;        // 相机对象：定义观察者的视角和投影方式
			let scene;         // 场景对象：包含所有3D对象（网格、光源等）
			let controls;      // 控制器对象：处理用户交互输入
			let renderer;      // 渲染器对象：负责将3D场景渲染到2D画布
			let quad;          // 全屏四边形：用于后处理效果的全屏渲染
			let renderTarget;  // 渲染目标：离屏渲染缓冲区，用于中间渲染结果
			
			// 获取设备像素比
			// 设备像素比表示物理像素与CSS像素的比率，高DPI屏幕需要更高的渲染分辨率
			const dpr = window.devicePixelRatio;

			// 初始化函数调用：页面加载完成后执行
			// 这是整个Three.js应用的入口点
			init();

			/**
			 * 初始化函数：设置Three.js场景、相机、渲染器和所有必要组件
			 * 这是整个应用程序的启动函数，只执行一次
			 */
			function init() {

				// ============ 1. 相机创建与配置 ============
				// 创建透视相机（PerspectiveCamera）
				// 参数说明：
				//   70 - 视野角度（Field of View），单位是度，影响可见范围
				//   window.innerWidth / window.innerHeight - 宽高比，保持图像不变形
				//   1 - 近裁剪面距离，相机看不到比这更近的物体
				//   20 - 远裁剪面距离，相机看不到比这更远的物体
				camera = new THREE.PerspectiveCamera( 70, window.innerWidth / window.innerHeight, 1, 20 );
				// 设置相机初始位置：沿Z轴正方向移动4个单位
				camera.position.z = 4;

				// ============ 2. 场景创建与配置 ============
				// 创建3D场景容器
				scene = new THREE.Scene();
				// 设置场景背景颜色：深灰色（十六进制颜色值）
				scene.background = new THREE.Color( 0x222222 );
				
				// 设置场景的覆盖材质
				// overrideMaterial会强制场景中所有物体使用相同的材质
				// MeshBasicNodeMaterial是节点化基础材质，支持TSL着色语言
				// 这里使用节点材质是为了后续处理深度纹理
				scene.overrideMaterial = new THREE.MeshBasicNodeMaterial();

				// ============ 3. 几何体和网格对象创建 ============
				// 创建环面扭结几何体（TorusKnotGeometry）
				// 参数说明：
				//   1 - 主半径，决定环面的大小
				//   0.3 - 管道半径，决定扭结的粗细
				//   128 - 径向分段数，影响环面圆周的细分程度
				//   64 - 管道分段数，影响管道截面的细分程度
				const geometry = new THREE.TorusKnotGeometry( 1, 0.3, 128, 64 );

				// 创建多个网格对象并添加到场景中
				const count = 50;     // 要创建的网格对象数量
				const scale = 5;      // 分布范围的缩放因子
				
				// 循环创建count个网格对象
				for ( let i = 0; i < count; i ++ ) {

					// 生成随机球面坐标
					// 球面坐标系统：用半径r、极角θ和方位角φ表示3D空间中的点
					const r = Math.random() * 2.0 * Math.PI;  // 随机方位角（0到2π）
					const z = ( Math.random() * 2.0 ) - 1.0;  // 随机z值（-1到1），用于计算极角
					
					// 计算球面上的缩放因子
					// 公式：sqrt(1 - z^2) 确保点在单位球面上
					const zScale = Math.sqrt( 1.0 - z * z ) * scale;

					// 创建网格对象：几何体 + 材质 = 可渲染的3D对象
					// 这里使用默认材质，因为后面会被场景的overrideMaterial覆盖
					const mesh = new THREE.Mesh( geometry );
					
					// 将球面坐标转换为笛卡尔坐标（直角坐标系）
					// 球面坐标转笛卡尔坐标公式：
					//   x = cos(φ) * sin(θ) * 半径
					//   y = sin(φ) * sin(θ) * 半径
					//   z = cos(θ) * 半径
					mesh.position.set(
						Math.cos( r ) * zScale,    // X坐标：方位角的余弦值乘以缩放
						Math.sin( r ) * zScale,    // Y坐标：方位角的正弦值乘以缩放
						z * scale                   // Z坐标：直接使用z值乘以缩放
					);
					
					// 设置随机旋转：每个网格对象随机旋转，增加视觉效果多样性
					// set方法参数：绕X轴旋转，绕Y轴旋转，绕Z轴旋转（弧度制）
					mesh.rotation.set( Math.random(), Math.random(), Math.random() );
					
					// 将网格对象添加到场景中
					scene.add( mesh );
				}

				// ============ 4. 渲染器创建与配置 ============
				// 创建WebGPU渲染器实例
				// 配置参数：{ antialias: true } 启用多重采样抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置渲染器的设备像素比
				// 在高DPI屏幕上，设置更高的像素比可以获得更清晰的图像
				renderer.setPixelRatio( dpr );
				
				// 设置渲染器尺寸为窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数
				// setAnimationLoop会持续调用animate函数，通常每秒60次
				renderer.setAnimationLoop( animate );
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ============ 5. 深度纹理和渲染目标创建 ============
				// 创建深度纹理（DepthTexture）
				// 深度纹理是一种特殊纹理，存储每个像素的深度值（到相机的距离）
				const depthTexture = new THREE.DepthTexture();
				// 设置深度纹理的数据类型为浮点型
				// FloatType提供更高的精度，适合存储深度值
				depthTexture.type = THREE.FloatType;

				// 创建渲染目标（RenderTarget）
				// 渲染目标是一个离屏渲染缓冲区，可以将场景渲染到这个缓冲区而不是屏幕
				// 尺寸需要考虑设备像素比，确保在高DPI屏幕上纹理足够清晰
				renderTarget = new THREE.RenderTarget( 
					window.innerWidth * dpr,    // 宽度：窗口宽度乘以设备像素比
					window.innerHeight * dpr    // 高度：窗口高度乘以设备像素比
				);
				// 将深度纹理附加到渲染目标
				// 这样渲染场景时，深度信息会保存到depthTexture中
				renderTarget.depthTexture = depthTexture;

				// ============ 6. 事件监听器设置 ============
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，调用onWindowResize函数
				window.addEventListener( 'resize', onWindowResize );

				// ============ 7. 后处理效果设置 ============
				// 创建后处理材质（MeshBasicNodeMaterial）
				// 这个材质将用于渲染深度纹理到全屏四边形
				const materialFX = new THREE.MeshBasicNodeMaterial();
				
				// 设置材质颜色节点为深度纹理
				// texture(depthTexture) 创建一个纹理采样节点
				// 这意味着材质的颜色将由深度纹理的值决定
				materialFX.colorNode = texture( depthTexture );

				// 创建全屏四边形（QuadMesh）
				// QuadMesh是一个覆盖整个屏幕的平面，用于后处理效果
				// 它将使用上面创建的materialFX材质
				quad = new THREE.QuadMesh( materialFX );

				// ============ 8. 交互控制设置 ============
				// 创建轨道控制器（OrbitControls）
				// 参数：要控制的相机，和用于接收输入的DOM元素
				controls = new OrbitControls( camera, renderer.domElement );
				
				// 启用阻尼效果
				// 阻尼效果使相机移动有惯性，更加平滑自然
				controls.enableDamping = true;

			}

			/**
			 * 窗口大小变化回调函数
			 * 当浏览器窗口大小改变时，重新调整相机、渲染器和渲染目标的尺寸
			 */
			function onWindowResize() {

				// 更新相机的宽高比
				// 宽高比 = 窗口宽度 / 窗口高度
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机参数改变后，必须调用此方法使更改生效
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸为新的窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 更新渲染目标尺寸
				// 同样需要考虑设备像素比，保持纹理清晰度
				renderTarget.setSize( window.innerWidth * dpr, window.innerHeight * dpr );

			}

			/**
			 * 动画循环函数
			 * 每帧自动调用，负责渲染场景和更新状态
			 * 这是整个应用程序的核心循环
			 */
			function animate() {

				// ============ 第一遍渲染：场景到渲染目标 ============
				// 设置当前渲染目标为自定义的renderTarget
				// 这样渲染结果不会直接显示到屏幕，而是保存到渲染目标的纹理中
				renderer.setRenderTarget( renderTarget );
				
				// 渲染场景到渲染目标
				// 参数：要渲染的场景，使用的相机
				// 这次渲染会生成颜色缓冲区和深度缓冲区
				renderer.render( scene, camera );

				// ============ 第二遍渲染：深度纹理到屏幕 ============
				// 设置渲染目标为null，表示渲染到默认帧缓冲区（即屏幕）
				renderer.setRenderTarget( null );
				
				// 渲染全屏四边形到屏幕
				// quad.render() 会绘制一个覆盖整个屏幕的四边形
				// 这个四边形使用materialFX材质，该材质显示深度纹理
				// 结果就是深度信息的可视化：近处物体颜色浅，远处物体颜色深
				quad.render( renderer );

			}

		</script>
	</body>
</html>