<!-- Three.js WebGPU 角度切片效果 - 代码功能与技术点详解
🎯 总体功能概述
这是一个基于Three.js WebGPU渲染器的3D可视化演示，实现了动态角度切片效果。该应用加载一个齿轮3D模型，通过自定义着色器在模型上"切割"出一个扇形缺口，用户可以实时调整切片的位置、大小和颜色，所有操作都通过WebGPU在GPU上高效执行。

📊 核心功能模块
1. 3D场景构建
透视相机：模拟人眼视角，支持旋转、缩放和平移

HDR环境光照：使用高质量HDR贴图提供真实的环境反射和背景

定向光源：模拟太阳光，产生动态阴影效果

阴影系统：完整的阴影投射和接收机制

2. 角度切片效果
动态几何切割：在模型表面实时"切割"出扇形区域

双面材质渲染：切割部分显示模型内部，使用不同颜色标记

阴影一致性：切割部分不产生阴影，保持视觉合理性

3. 交互控制系统
轨道控制器：鼠标拖拽旋转、滚轮缩放

实时参数调节：通过GUI控制面板调整切片参数

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

4. 资源管理系统
模型加载：支持GLTF格式和DRACO压缩

纹理加载：HDR环境贴图提供高质量光照

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

🔧 主要技术点详解
1. WebGPU渲染技术
javascript
// 使用Three.js的WebGPU后端
import * as THREE from 'three/webgpu';
const renderer = new THREE.WebGPURenderer({ antialias: true });
现代图形API：替代WebGL，提供更好的性能和特性支持

GPU驱动渲染：所有图形计算在GPU上执行

自动内存管理：Three.js处理WebGPU的复杂内存管理

2. TSL着色器语言
javascript
import { Fn, uniform, positionLocal, discard } from 'three/tsl';
声明式着色器编程：在JavaScript中直接编写GPU着色器代码

类型安全：编译时类型检查，减少运行时错误

与Three.js深度集成：无缝使用Three.js的材质和光照系统

3. 角度切片着色器算法
角度计算原理
javascript
// 关键算法：判断点是否在角度范围内
const angle = atan(position.y, position.x)  // 计算点的角度
            .sub(angleStart)                // 减去起始角度
            .mod(TWO_PI)                   // 取模2π，归一化
            .toVar();                      // 转换为变量
坐标系统转换
模型空间坐标：positionLocal提供顶点在自身坐标系中的位置

角度计算平面：使用XY平面进行角度判断（假设模型沿Z轴对称）

极坐标转换：将笛卡尔坐标转换为极坐标角度

片元丢弃技术
javascript
// 如果点在切片范围内，丢弃该像素
inAngle(positionLocal.xy, sliceStart, sliceArc).discard();
discard指令：在片段着色器中直接丢弃像素，不进行后续渲染

高效裁剪：相比几何修改，着色器裁剪性能更好

4. 双材质系统
javascript
// 条件渲染：正面和背面使用不同颜色
If(frontFacing.not(), () => {
    finalOutput.assign(vec4(sliceColor, 1));  // 背面：自定义颜色
});
frontFacing变量：内置变量，判断当前渲染的是正面还是背面

条件分支优化：TSL的If语句在GPU上高效执行

材质复用：同一材质根据渲染情况动态改变输出

5. 阴影着色器分离
javascript
// 独立的阴影生成着色器
slicedMaterial.castShadowNode = Fn(() => {
    inAngle(positionLocal.xy, sliceStart, sliceArc).discard();
    return vec4(0, 0, 0, 1);
})();
阴影管线分离：阴影生成使用独立的着色器逻辑

性能优化：避免在主着色器中重复计算阴影逻辑

视觉一致性：确保切片部分不产生阴影

6. 实时参数更新系统
javascript
// Uniform变量定义
const sliceStart = uniform(1.75);  // 可以在运行时动态修改

// GUI控制绑定
gui.add(sliceStart, 'value', -Math.PI, Math.PI, 0.001)
   .name('切片起始角度');
Uniform变量：GPU常量，可在渲染时从CPU更新

即时反馈：参数修改立即反映在渲染结果中

范围控制：通过GUI提供直观的参数调节

7. 资源加载优化
javascript
// DRACO压缩模型加载
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('jsm/libs/draco/');

// HDR环境贴图
const hdrLoader = new UltraHDRLoader();
hdrLoader.load('textures/...', (environmentMap) => {
    scene.environment = environmentMap;
});
模型压缩：使用DRACO减少模型文件大小70-90%

渐进式加载：纹理和模型异步加载

HDR照明：高动态范围贴图提供真实光照

🚀 技术架构亮点
1. 模块化设计
清晰分离：初始化、渲染、交互逻辑分离

可扩展性：易于添加新的3D对象或效果

维护性：代码结构清晰，便于调试和修改

2. 性能优化策略
GPU并行计算：角度判断在GPU上并行执行所有像素

批处理渲染：Three.js自动批处理相同材质的对象

动态LOD：根据距离自动调整渲染细节

3. 跨平台兼容
WebGPU支持：现代浏览器支持（Chrome、Edge等）

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

触摸支持：移动设备友好的交互控制 -->


<!DOCTYPE html>
<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">
		
		<!-- 样式表链接：引入外部CSS文件用于页面样式 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 页面信息区域：包含标题、链接和说明信息 -->
		<div id="info">
			<!-- Three.js 官方链接 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link">
				<!-- 这里通常会放置Three.js的logo图片 -->
			</a>

			<!-- 标题包装器：包含主标题和副标题 -->
			<div class="title-wrapper">
				<!-- 主标题链接 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题：当前示例的名称 -->
				<span>角度切片效果演示</span>
			</div>

			<!-- 小字说明区域 -->
			<small>
				<!-- 说明文字和教程来源链接 -->
				本示例基于 <a href="https://threejs-journey.com/lessons/sliced-model-shader" target="_blank" rel="noopener">Three.js Journey</a> 课程中的切片模型着色器教程。
				<br>
				<!-- 额外说明：描述示例的功能 -->
				展示如何使用着色器技术在3D模型上实现角度切片效果，可实时调整切片参数。
			</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>

		<script type="module">

			// ========== 模块导入部分 ==========
			
			// 导入Three.js的核心功能，使用WebGPU渲染后端
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js着色器语言（TSL）的功能：
			// - If: 条件语句
			// - TWO_PI: 2π常量（约6.283）
			// - atan: 反正切函数（计算角度）
			// - color: 颜色处理函数
			// - frontFacing: 判断当前片元是否为正面
			// - output: 着色器输出变量
			// - positionLocal: 局部空间位置坐标
			// - Fn: 定义着色器函数
			// - uniform: 定义着色器统一变量（可从外部控制）
			// - vec4: 四维向量（通常用于颜色和位置）
			import { If, TWO_PI, atan, color, frontFacing, output, positionLocal, Fn, uniform, vec4 } from 'three/tsl';

			// 导入调试检查器工具，用于创建参数控制面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入模型加载器：DRACO用于压缩模型，GLTF用于加载glTF格式
			import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			
			// 导入HDR图像加载器，用于高质量环境贴图
			import { UltraHDRLoader } from 'three/addons/loaders/UltraHDRLoader.js';
			
			// 导入轨道控制器，用于鼠标/触摸控制相机旋转和缩放
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ========== 全局变量声明 ==========
			
			// camera: 场景相机，控制观察视角
			// scene: 场景容器，包含所有3D对象
			// renderer: 渲染器，负责将3D场景绘制到2D画布
			// controls: 用户交互控制器
			let camera, scene, renderer, controls;

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

			// ========== 初始化函数定义 ==========
			
			/**
			 * 初始化整个3D应用程序
			 * 1. 创建相机、场景、灯光
			 * 2. 设置着色器材质
			 * 3. 加载3D模型
			 * 4. 创建渲染器和控制器
			 * 5. 设置事件监听和调试界面
			 */
			function init() {

				// ---------- 相机设置 ----------
				
				// 创建透视投影相机：
				// - 35: 视野角度（FOV），单位度，控制可见范围大小
				// - window.innerWidth / window.innerHeight: 宽高比，保持画面比例正确
				// - 0.1: 近裁剪平面，距离相机0.1单位以内的物体不渲染
				// - 100: 远裁剪平面，距离相机100单位以外的物体不渲染
				camera = new THREE.PerspectiveCamera( 35, window.innerWidth / window.innerHeight, 0.1, 100 );
				
				// 设置相机初始位置：(x, y, z)坐标
				// - x: -5（左侧）
				// - y: 5（上方）
				// - z: 12（前方）
				camera.position.set( -5, 5, 12 );

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

				// ---------- 环境贴图设置 ----------
				
				// 创建HDR加载器实例
				const hdrLoader = new UltraHDRLoader();
				
				// 加载HDR环境贴图文件
				hdrLoader.load( 
					// HDR贴图文件路径
					'textures/equirectangular/royal_esplanade_2k.hdr.jpg',
					
					// 加载完成后的回调函数
					( environmentMap ) => {

						// 设置贴图映射方式为等距圆柱投影（类似世界地图展开方式）
						environmentMap.mapping = THREE.EquirectangularReflectionMapping;

						// 将环境贴图设置为场景背景
						scene.background = environmentMap;
						
						// 将环境贴图设置为场景的环境光，影响所有物体的反射和折射
						scene.environment = environmentMap;

					}
				);

				// ---------- 灯光设置 ----------
				
				// 创建平行光（模拟太阳光）：
				// - '#ffffff': 白色光
				// - 4: 光照强度
				const directionalLight = new THREE.DirectionalLight( '#ffffff', 4 );
				
				// 设置灯光位置
				directionalLight.position.set( 6.25, 3, 4 );
				
				// 启用此灯光的阴影投射功能
				directionalLight.castShadow = true;
				
				// 设置阴影贴图的分辨率：更高的分辨率=更清晰的阴影边缘
				directionalLight.shadow.mapSize.set( 2048, 2048 );
				
				// 设置阴影相机的参数（定义哪些物体会投射阴影）：
				directionalLight.shadow.camera.near = 0.1;   // 近裁剪面
				directionalLight.shadow.camera.far = 30;     // 远裁剪面
				directionalLight.shadow.camera.top = 8;      // 上边界
				directionalLight.shadow.camera.right = 8;    // 右边界
				directionalLight.shadow.camera.bottom = -8;  // 下边界
				directionalLight.shadow.camera.left = -8;    // 左边界
				
				// 设置法线偏移，减少阴影的"彼得潘"效应（阴影与物体分离）
				directionalLight.shadow.normalBias = 0.05;
				
				// 将灯光添加到场景中
				scene.add( directionalLight );

				// ---------- TSL着色器函数定义 ----------
				
				/**
				 * inAngle函数：判断一个点是否在指定的角度范围内
				 * @param {vec2} position - 点的2D坐标（通常在xy平面）
				 * @param {float} angleStart - 角度范围的起始角度（弧度）
				 * @param {float} angleArc - 角度范围的大小（弧度）
				 * @returns {bool} - 返回true表示点在角度范围内，false表示不在
				 */
				const inAngle = Fn( ( [ position, angleStart, angleArc ] ) => {

					// 计算点的角度（使用atan2函数，考虑四个象限）：
					// 1. atan(position.y, position.x): 计算点相对于原点的角度
					// 2. .sub(angleStart): 减去起始角度，得到相对于起始角度的偏移
					// 3. .mod(TWO_PI): 对2π取模，确保角度在[0, 2π)范围内
					// 4. .toVar(): 将计算结果转换为变量，便于后续操作
					const angle = atan( position.y, position.x )
						.sub( angleStart )
						.mod( TWO_PI )
						.toVar();
					
					// 判断角度是否在指定范围内：
					// - angle.greaterThan(0): 角度大于0
					// - .and(angle.lessThan(angleArc)): 且角度小于角度范围
					// 返回布尔值，表示点是否在角度切片内
					return angle.greaterThan( 0 ).and( angle.lessThan( angleArc ) );

				} );

				// ---------- 材质创建 ----------
				
				// 创建默认物理材质（用于模型的大部分部分）：
				const defaultMaterial = new THREE.MeshPhysicalNodeMaterial( {
					metalness: 0.5,         // 金属度：0=非金属，1=金属
					roughness: 0.25,        // 粗糙度：0=完全光滑，1=完全粗糙
					envMapIntensity: 0.5,   // 环境贴图反射强度
					color: '#858080'        // 基础颜色（灰色）
				} );

				// 创建切片材质（用于需要切片效果的部分）：
				const slicedMaterial = new THREE.MeshPhysicalNodeMaterial( {
					metalness: 0.5,
					roughness: 0.25,
					envMapIntensity: 0.5,
					color: '#858080',
					side: THREE.DoubleSide  // 双面渲染：因为切片会暴露内部，需要渲染背面
				} );

				// ---------- 着色器Uniform变量定义 ----------
				
				// 这些Uniform变量可以从JavaScript代码中动态控制
				
				// sliceStart: 切片起始角度（弧度），初始值1.75（约100度）
				const sliceStart = uniform( 1.75 );
				
				// sliceArc: 切片的角度范围（弧度），初始值1.25（约71.6度）
				const sliceArc = uniform( 1.25 );
				
				// sliceColor: 切片内部显示的颜色，初始为深红色
				const sliceColor = uniform( color( '#b62f58' ) );

				// ---------- 设置切片材质的主着色器 ----------
				
				/**
				 * 主着色器函数：控制模型表面的外观
				 * 此函数在GPU上对每个像素（片元）执行
				 */
				slicedMaterial.outputNode = Fn( () => {

					// 第一步：丢弃切片区域内的片元
					// 如果当前片元的局部坐标在切片角度范围内，则丢弃（不渲染）
					// 这会在模型上"切掉"一个扇形区域
					inAngle( positionLocal.xy, sliceStart, sliceArc ).discard();

					// 第二步：获取默认的输出颜色
					// output变量包含材质原本的计算结果（考虑光照、反射等）
					const finalOutput = output;
					
					// 第三步：处理背面（切口的内部）
					// 使用条件语句：如果不是正面（即背面或内部表面）
					If( frontFacing.not(), () => {
						// 将输出颜色设置为自定义的切片颜色
						// vec4(sliceColor, 1): 将颜色转换为四维向量，1表示完全不透明
						finalOutput.assign( vec4( sliceColor, 1 ) );
					} );
			
					// 返回最终的着色器输出
					return finalOutput;
			
				} )(); // 立即执行函数，返回着色器节点

				// ---------- 设置切片材质的阴影着色器 ----------
				
				/**
				 * 阴影着色器函数：控制阴影的生成
				 * 此函数决定哪些部分会投射阴影
				 */
				slicedMaterial.castShadowNode = Fn( () => {

					// 同样丢弃切片区域内的片元
					// 这样切片部分就不会产生阴影，与视觉效果一致
					inAngle( positionLocal.xy, sliceStart, sliceArc ).discard();

					// 返回阴影颜色
					// vec4(0, 0, 0, 1): 黑色完全不透明（实际阴影颜色由灯光和材质决定）
					return vec4( 0, 0, 0, 1 );
			
				} )();

				// ---------- 3D模型加载 ----------
				
				// 创建DRACO加载器（用于加载压缩的3D模型）
				const dracoLoader = new DRACOLoader();
				// 设置DRACO解码器的路径
				dracoLoader.setDecoderPath( 'jsm/libs/draco/' );

				// 创建GLTF加载器
				const gltfLoader = new GLTFLoader();
				// 配置GLTF加载器使用DRACO解码器
				gltfLoader.setDRACOLoader( dracoLoader );

				// 加载齿轮模型文件
				gltfLoader.load(
					// 模型文件路径
					'./models/gltf/gears.glb',
					
					// 加载成功回调函数
					( gltf ) => {

						// 获取模型的根场景
						const model = gltf.scene;

						// 遍历模型的所有子对象
						model.traverse( ( child ) => {

							// 检查是否是网格对象（3D模型中的几何体）
							if ( child.isMesh ) {

								// 根据网格名称分配不同材质
								if ( child.name === 'outerHull' )
									// 外壳部分使用切片材质
									child.material = slicedMaterial;
								else
									// 其他部分使用默认材质
									child.material = defaultMaterial;

								// 启用此网格的阴影功能
								child.castShadow = true;     // 投射阴影
								child.receiveShadow = true;  // 接收阴影（显示其他物体的阴影）
			
							}

						} );

						// 将整个模型添加到场景中
						scene.add( model );
			
					}
				);

				// ---------- 创建地面平面 ----------
				
				// 创建平面几何体：宽度10，高度10，分段数10x10
				const plane = new THREE.Mesh(
					new THREE.PlaneGeometry( 10, 10, 10 ),
					// 使用标准材质
					new THREE.MeshStandardMaterial( { color: '#aaaaaa' } )
				);
				
				// 地面可以接收其他物体投射的阴影
				plane.receiveShadow = true;
				
				// 设置地面位置
				plane.position.set( -4, -3, -4 );
				
				// 使地平面朝向原点（使地面倾斜，更有层次感）
				plane.lookAt( new THREE.Vector3( 0, 0, 0 ) );
				
				// 将地面添加到场景
				scene.add( plane );

				// ---------- 创建渲染器 ----------
				
				// 创建WebGPU渲染器实例
				renderer = new THREE.WebGPURenderer( { antialias: true } ); // 开启抗锯齿
				
				// 设置色调映射算法：ACESFilmic提供更真实的颜色响应
				renderer.toneMapping = THREE.ACESFilmicToneMapping;
				
				// 设置曝光值：1表示标准曝光
				renderer.toneMappingExposure = 1;
				
				// 启用阴影映射
				renderer.shadowMap.enabled = true;
				
				// 创建调试检查器实例
				renderer.inspector = new Inspector();
				
				// 设置渲染器的像素比，匹配设备屏幕
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数（每帧调用animate函数）
				renderer.setAnimationLoop( animate );
				
				// 将渲染器的canvas元素添加到页面body中
				document.body.appendChild( renderer.domElement );

				// ---------- 创建用户交互控制器 ----------
				
				// 创建轨道控制器，绑定到相机和渲染器的DOM元素
				controls = new OrbitControls( camera, renderer.domElement );
				
				// 启用阻尼效果（惯性），使控制更平滑
				controls.enableDamping = true;
				
				// 设置相机可缩放的最小距离
				controls.minDistance = 0.1;
				
				// 设置相机可缩放的最大距离
				controls.maxDistance = 50;

				// ---------- 事件监听器设置 ----------
				
				// 监听窗口大小变化事件
				window.addEventListener( 'resize', onWindowResize );

				// ---------- 调试界面创建 ----------
				
				// 从检查器创建参数控制面板
				const gui = renderer.inspector.createParameters( '参数控制' );
				
				// 添加切片起始角度控制滑块：
				// - sliceStart: 控制的变量
				// - 'value': 变量属性名
				// - -Math.PI 到 Math.PI: 取值范围（-π到π，完整圆周）
				// - 0.001: 滑块步长
				// - 'sliceStart': 在面板中显示的名称
				gui.add( sliceStart, 'value', -Math.PI, Math.PI, 0.001 ).name( '切片起始角度' );
				
				// 添加切片角度范围控制滑块：
				// 取值范围0到2π，表示0到360度
				gui.add( sliceArc, 'value', 0, Math.PI * 2, 0.001 ).name( '切片角度范围' );
				
				// 添加切片颜色选择器：
				// - 创建临时对象包含颜色值
				// - 颜色格式为16进制字符串
				// - 当颜色改变时，更新sliceColor变量的值
				gui.addColor( 
					{ 
						color: sliceColor.value.getHexString( THREE.SRGBColorSpace ) 
					}, 
					'color' 
				).name( '切片内部颜色' ).onChange( value => sliceColor.value.set( value ) );

			}

			// ========== 窗口大小变化处理函数 ==========
			
			/**
			 * 当浏览器窗口大小改变时调用
			 * 调整相机和渲染器以适应新窗口尺寸
			 */
			function onWindowResize() {

				// 更新相机的宽高比，防止图像拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 通知相机投影矩阵已更改，需要重新计算
				camera.updateProjectionMatrix();

				// 调整渲染器尺寸以匹配新窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );

			}

			// ========== 动画循环函数 ==========
			
			/**
			 * 每一帧调用的动画循环函数
			 * 这是Three.js应用的核心循环
			 */
			async function animate() {
			
				// 更新控制器状态（处理用户输入）
				// 如果启用了阻尼，这里会计算平滑的相机运动
				controls.update();

				// 执行渲染：将3D场景绘制到2D画布上
				// 参数1: 要渲染的场景
				// 参数2: 使用的相机
				renderer.render( scene, camera );

			}

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