<!-- Three.js WebGPU 遮罩效果示例 - 功能与技术详解
一、整体功能描述
这个示例展示了一个基于WebGPU的实时动态遮罩效果。核心功能是使用3D几何体（立方体和圆环体）作为动态遮罩，将纹理图像"剪切"到这些几何体的形状中，形成移动的艺术画框效果。

视觉效果特征：
动态遮罩：两个几何体在屏幕上移动旋转，形成不断变化的遮罩形状

纹理映射：在遮罩区域内显示高质量纹理图像（艺术画作和风景照片）

多层合成：基础灰色背景 + 立方体遮罩纹理 + 圆环体遮罩纹理

平滑动画：所有运动都基于三角函数，确保流畅自然的视觉效果

二、主要技术点详解
1. WebGPU渲染器 ⚡
javascript
const renderer = new THREE.WebGPURenderer();
新一代图形API：替代WebGL，提供更接近原生图形API的性能

优势特点：

更好的多线程支持

更高效的GPU命令提交

显式内存管理

支持计算着色器

兼容性：需要现代浏览器支持（Chrome 113+，Edge 113+）

2. 后处理（Post-processing）架构 🎨
javascript
const postProcessing = new THREE.PostProcessing(renderer);
渲染管线：

text
输入 → 渲染各场景 → 提取Alpha通道 → 混合纹理 → 输出
多场景渲染：使用3个独立场景分别渲染不同内容

节点式合成：通过mix()方法连接各个渲染节点

3. TSL（Three.js Shader Language） 🔧
javascript
import { pass, texture } from 'three/tsl';
声明式着色器编程：简化WebGL/WebGPU着色器编写

核心功能：

pass()：创建渲染通道节点

texture()：将纹理转换为着色器节点

.mix()：混合两个输入源（基于遮罩）

实时编译：在运行时生成优化后的着色器代码

4. 遮罩技术实现 🎭
javascript
const sceneMask1 = pass(maskScene1, camera).a;
compose = sceneMask1.mix(compose, texture(texture1));
Alpha通道提取：.a获取渲染结果的透明度信息

混合原理：

text
最终颜色 = 遮罩值 × 纹理颜色 + (1 - 遮罩值) × 底层颜色
遮罩值=1：完全显示纹理

遮罩值=0：完全显示底层

遮罩值=0~1：透明混合

5. 动画系统 🌀
javascript
// 周期性位置变化
box.position.x = Math.cos(time / 1.5) * 2;
box.position.y = Math.sin(time) * 2;

// 持续旋转
box.rotation.x = time;
box.rotation.y = time / 2;
时间驱动：基于performance.now()实现与帧率无关的动画

三角函数运动：使用sin()和cos()产生平滑周期性运动

差异化参数：不同物体使用不同周期参数，避免同步运动

6. 纹理处理优化 📐
javascript
texture1.minFilter = THREE.LinearFilter;
texture1.generateMipmaps = false;
texture1.flipY = false;
texture1.colorSpace = THREE.SRGBColorSpace;
颜色空间：SRGB确保颜色显示准确

过滤优化：LinearFilter提供平滑缩放效果

方向控制：flipY=false保持图像原始方向

性能优化：禁用Mipmap生成，减少内存使用

7. 响应式设计 📱
javascript
window.addEventListener('resize', onWindowResize);
自动适配：窗口大小变化时自动更新渲染尺寸

比例保持：正确更新相机纵横比，防止图像拉伸

高DPI支持：通过devicePixelRatio适配Retina屏幕

8. 调试工具集成 🔍
javascript
renderer.inspector = new Inspector();
可视化调试：实时查看场景结构、材质参数

交互式修改：可直接调整对象属性

性能分析：监控渲染性能指标

三、技术架构图示
text
┌─────────────────────────────────────────────┐
│              WebGPU渲染管线                  │
├─────────────────────────────────────────────┤
│ 1. 渲染基础场景（灰色背景）                  │
│ 2. 渲染遮罩场景1（立方体） → 提取Alpha通道   │
│ 3. 渲染遮罩场景2（圆环体） → 提取Alpha通道   │
│ 4. TSL节点合成：                            │
│    base + (mask1 × texture1) + (mask2 × texture2)│
│ 5. 输出到Canvas                             │
└─────────────────────────────────────────────┘
       ↓
┌─────────────────────────────────────────────┐
│            每帧更新（60fps）                 │
│  1. 更新几何体位置/旋转                      │
│  2. 重新计算遮罩形状                         │
│  3. 执行合成渲染                            │
└─────────────────────────────────────────────┘
四、应用场景扩展
这个技术可以扩展应用于：

UI/UX设计：动态形状的图片展示

游戏开发：特殊效果、技能范围显示

数据可视化：通过形状突出显示数据区域

艺术创作：交互式数字艺术装置

广告展示：吸引眼球的动态广告效果

五、性能优化建议
纹理优化：

使用适当的分辨率（避免过大纹理）

启用纹理压缩（如果目标平台支持）

考虑使用纹理图集

几何体优化：

调整几何体分段数（平衡效果和性能）

使用实例化渲染（如果有多个相同遮罩）

渲染优化：

根据设备性能动态调整后处理质量

实现细节层次（LOD）系统

使用WebGPU的compute shader进行预处理 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			title标签：定义网页标题，显示在浏览器标签页上
			这里展示的是一个使用Three.js WebGPU实现遮罩效果的示例
		-->
		<title>Three.js WebGPU - 遮罩效果演示</title>
		<!-- 
			meta charset：定义文档字符编码
			utf-8支持包括中文在内的多种语言字符
		-->
		<meta charset="utf-8">
		<!-- 
			viewport：响应式设计的关键元标签，控制移动设备上的视口行为
			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">
		<!-- 
			link标签：引入外部CSS样式表
			rel="stylesheet"：指定资源为样式表
			href="example.css"：样式表文件路径
			这个CSS文件可能包含页面布局、颜色、字体等样式规则
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			id="info"：为这个div元素设置唯一标识符
			class="invert"：应用CSS类，可能包含颜色反转或其他样式效果
			这个div包含页面的标题、logo和描述信息
		-->
		<div id="info" class="invert">
			<!-- 
				logo链接：点击可以跳转到Three.js官方网站
				target="_blank"：在新标签页打开链接
				rel="noopener"：安全措施，防止新页面访问原页面的window.opener属性
				class="logo-link"：CSS类，可能设置Three.js的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>通过后处理技术实现的动态遮罩效果</small>
		</div>

		<!-- 
			importmap：JavaScript模块导入映射
			允许浏览器理解非标准模块标识符
			这是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>

		<!-- 
			type="module"：表示这是一个ES模块
			ES模块支持import/export语法，具有自己的作用域
			浏览器会自动延迟(defer)执行模块脚本
		-->
		<script type="module">

			// ==================== 模块导入部分 ====================
			// 导入Three.js WebGPU版本的所有导出内容
			// * 表示导入所有导出，as THREE表示将其命名为THREE对象
			import * as THREE from 'three/webgpu';
			
			// 从three/tsl导入特定的函数
			// pass函数：用于创建渲染通道，是后处理的核心
			// texture函数：用于将普通纹理转换为TSL可用的纹理节点
			import { pass, texture } from 'three/tsl';
			
			// 导入调试检查器
			// Inspector是一个可视化调试工具，可以查看场景、材质等信息
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ==================== 全局变量声明 ====================
			// 这些变量将在多个函数中共享使用
			let camera;          // 相机：定义观察3D场景的视角
			let postProcessing;  // 后处理：管理和执行后处理效果
			let renderer;        // 渲染器：负责将3D场景绘制到2D画布上
			let box;             // 立方体网格：第一个遮罩对象
			let torus;           // 圆环体网格：第二个遮罩对象

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

			// ==================== 初始化函数定义 ====================
			/**
			 * init函数：整个应用的主初始化函数
			 * 负责创建场景、相机、渲染器、加载资源、设置后处理流程
			 * 这是整个应用的起点
			 */
			function init() {

				// ---------- 场景创建部分 ----------
				// 场景(Scene)是Three.js中所有3D对象的容器

				// 1. 创建基础场景 - 作为背景层
				// 这个场景只包含纯色背景，没有3D对象
				const baseScene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色
				// 0xe0e0e0是十六进制颜色值，对应RGB(224, 224, 224)
				baseScene.background = new THREE.Color( 0xe0e0e0 );

				// 2. 创建第一个遮罩场景 - 包含立方体
				// 这个场景的渲染结果将用作遮罩
				const maskScene1 = new THREE.Scene();
				// 创建立方体网格(Mesh)
				// BoxGeometry：创建立方体几何体，参数为宽、高、深
				box = new THREE.Mesh( new THREE.BoxGeometry( 4, 4, 4 ) );
				// 将立方体添加到第一个遮罩场景
				maskScene1.add( box );

				// 3. 创建第二个遮罩场景 - 包含圆环体
				const maskScene2 = new THREE.Scene();
				// 创建圆环体网格
				// TorusGeometry：创建圆环几何体
				// 参数依次为：半径(3)、管径(1)、径向分段数(16)、管状分段数(32)
				torus = new THREE.Mesh( new THREE.TorusGeometry( 3, 1, 16, 32 ) );
				// 将圆环体添加到第二个遮罩场景
				maskScene2.add( torus );

				// ---------- 相机设置部分 ----------
				// 相机定义了如何观察3D场景
				// PerspectiveCamera：透视相机，模拟人眼视角，有近大远小的效果
				// 参数依次为：
				//   - 50：垂直视野角度(degrees)
				//   - window.innerWidth / window.innerHeight：纵横比
				//   - 1：近裁剪面距离，比这个距离近的对象不渲染
				//   - 1000：远裁剪面距离，比这个距离远的对象不渲染
				camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 1, 1000 );
				// 设置相机位置：沿Z轴正方向移动10个单位
				// Three.js使用右手坐标系：X轴向右，Y轴向上，Z轴向屏幕外
				camera.position.z = 10;

				// ---------- 纹理加载部分 ----------
				// 纹理是贴在3D对象表面的2D图像

				// 1. 加载第一个纹理 - 水果篮图片（卡拉瓦乔的画作）
				// TextureLoader：纹理加载器，用于从URL加载图像文件
				const texture1 = new THREE.TextureLoader().load( 
					'textures/758px-Canestra_di_frutta_(Caravaggio).jpg' 
				);
				// 设置颜色空间为SRGB，这会影响颜色计算方式
				// SRGB颜色空间更接近人眼感知，用于彩色图像
				texture1.colorSpace = THREE.SRGBColorSpace;
				// 设置纹理缩小过滤器为线性过滤
				// 当纹理被渲染得比原始尺寸小时使用
				texture1.minFilter = THREE.LinearFilter;
				// 禁用mipmap生成
				// Mipmap是一系列预先缩小的纹理副本，可以提高渲染性能
				// 这里禁用可能是因为纹理大小固定或性能考虑
				texture1.generateMipmaps = false;
				// 禁用Y轴翻转
				// 通常情况下纹理在Three.js中会上下翻转，这里保持原方向
				texture1.flipY = false;

				// 2. 加载第二个纹理 - 风景图片
				const texture2 = new THREE.TextureLoader().load( 
					'textures/2294472375_24a3b8ef46_o.jpg' 
				);
				// 同样设置为SRGB颜色空间
				texture2.colorSpace = THREE.SRGBColorSpace;
				// 同样禁用Y轴翻转，保持纹理原方向
				texture2.flipY = false;

				// ---------- 渲染器设置部分 ----------
				// WebGPURenderer：使用WebGPU API的渲染器
				// WebGPU是新一代图形API，比WebGL更高效
				renderer = new THREE.WebGPURenderer();
				// 设置设备像素比
				// window.devicePixelRatio获取设备的物理像素与CSS像素比
				// 在高DPI屏幕上（如Retina显示屏），这可以提高渲染清晰度
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 设置动画循环函数
				// animate函数将在每一帧被调用，实现动画效果
				renderer.setAnimationLoop( animate );
				// 启用调试检查器
				// Inspector提供可视化界面，可以查看和修改场景中的对象
				renderer.inspector = new Inspector();
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				// 这样渲染结果才能显示在网页上
				document.body.appendChild( renderer.domElement );

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

				// ---------- 后处理设置部分 ----------
				// 后处理(Post-processing)：在场景渲染完成后应用额外效果

				// 1. 创建各个场景的渲染通道
				// pass()函数：创建一个渲染通道节点
				// 参数：要渲染的场景和使用的相机
				
				// 基础场景通道：只包含灰色背景
				const base = pass( baseScene, camera );
				
				// 第一个遮罩场景通道，并提取alpha通道(.a)
				// maskScene1的渲染结果中，alpha通道表示遮罩形状
				// 立方体所在位置alpha值为1，其他位置为0
				const sceneMask1 = pass( maskScene1, camera ).a;
				
				// 第二个遮罩场景通道，同样提取alpha通道
				const sceneMask2 = pass( maskScene2, camera ).a;

				// 2. 合成渲染节点
				// 使用链式混合操作构建最终效果
				let compose = base;  // 从基础场景开始
				
				// 第一次混合：将第一个纹理应用到第一个遮罩区域
				// sceneMask1.mix()：混合函数
				// 参数1(compose)：当前合成结果
				// 参数2(texture(texture1))：第一个纹理
				// 效果：在立方体遮罩区域显示纹理1，其他区域保持原样
				compose = sceneMask1.mix( compose, texture( texture1 ) );
				
				// 第二次混合：将第二个纹理应用到第二个遮罩区域
				// 在之前的结果上，再叠加圆环体遮罩区域的纹理2
				compose = sceneMask2.mix( compose, texture( texture2 ) );

				// 3. 创建后处理实例
				// PostProcessing类管理后处理流程
				postProcessing = new THREE.PostProcessing( renderer );
				// 设置输出节点为最终合成的结果
				// 这个节点定义了整个渲染管线的最终输出
				postProcessing.outputNode = compose;

				// 初始化完成，接下来animate函数将开始执行
			}

			// ==================== 窗口大小调整函数 ====================
			/**
			 * onWindowResize函数：响应窗口大小变化
			 * 当浏览器窗口大小改变时，需要更新相机和渲染器设置
			 */
			function onWindowResize() {

				// 获取当前窗口的宽度和高度
				const width = window.innerWidth;
				const height = window.innerHeight;

				// 更新相机纵横比
				// 纵横比 = 宽度 / 高度，确保渲染不会拉伸变形
				camera.aspect = width / height;
				// 必须调用updateProjectionMatrix()使新的纵横比生效
				// 这个方法重新计算相机的投影矩阵
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				// 使渲染器的画布大小与窗口大小保持一致
				renderer.setSize( width, height );

			}

			// ==================== 动画循环函数 ====================
			/**
			 * animate函数：每帧执行的动画函数
			 * 这是实现动态效果的核心，由setAnimationLoop自动循环调用
			 * 通常每秒调用60次（取决于屏幕刷新率）
			 */
			function animate() {

				// 计算当前时间（单位：秒）
				// performance.now()返回页面加载以来的毫秒数
				// * 0.001转换为秒
				// + 6000：添加偏移量，确保动画开始时角度合适
				// 避免sin/cos函数在时间接近0时产生不自然的剧烈变化
				const time = performance.now() * 0.001 + 6000;

				// ---------- 更新立方体（第一个遮罩） ----------
				// 位置动画：让立方体在XY平面上做周期性运动
				// Math.cos()和Math.sin()产生平滑的周期性变化
				box.position.x = Math.cos( time / 1.5 ) * 2;  // X轴：每1.5秒完成一次周期
				box.position.y = Math.sin( time ) * 2;        // Y轴：每秒完成一次周期
				
				// 旋转动画：让立方体持续旋转
				box.rotation.x = time;      // 绕X轴旋转，每秒1弧度
				box.rotation.y = time / 2;  // 绕Y轴旋转，每秒0.5弧度（较慢）

				// ---------- 更新圆环体（第二个遮罩） ----------
				// 使用不同的周期参数，让两个物体运动不同步
				torus.position.x = Math.cos( time ) * 2;      // X轴：每秒一次周期
				torus.position.y = Math.sin( time / 1.5 ) * 2;  // Y轴：每1.5秒一次周期
				
				// 旋转动画
				torus.rotation.x = time;      // 绕X轴旋转，每秒1弧度
				torus.rotation.y = time / 2;  // 绕Y轴旋转，每秒0.5弧度

				// ---------- 执行渲染 ----------
				// 调用后处理的render()方法
				// 这将执行整个渲染管线：渲染所有场景，应用遮罩混合，输出最终结果
				postProcessing.render();

			}

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