<!-- Three.js WebGPU 计算乒乓纹理演示
🎯 代码功能概述
这是一个基于Three.js和WebGPU的实时GPU计算演示程序，主要展示了：

1. 核心视觉效果
生成动态变化的抽象艺术纹理

实现流体状的色彩流动效果

每秒自动重置生成新的随机图案

持续模糊和增强颜色强度

2. 应用场景
GPU计算能力展示：演示WebGPU在通用计算方面的强大能力

实时图形处理：模拟图像处理流水线

技术原型：展示乒乓缓冲技术在实时渲染中的应用

教育演示：帮助理解GPU并行计算原理

🔧 主要技术点
1. WebGPU架构
javascript
// 核心技术栈
- WebGPU API: 新一代图形和计算API，替代WebGL
- 计算着色器: 专门的GPU计算单元
- 存储纹理: 可在计算着色器中读写的纹理
- 并行计算: 每个像素一个线程，512×512=262,144个并行线程
2. 乒乓缓冲技术（Double Buffering）
javascript
// 核心机制：避免读写冲突
pingTexture ←→ pongTexture
帧1: 读取ping → 处理 → 写入pong
帧2: 读取pong → 处理 → 写入ping
// 优势：无等待、无数据竞争、最大化GPU利用率
3. Three.js TSL（Three.js Shader Language）
javascript
// 声明式着色器编程
const computeShader = wgslFn(`
    fn main() { ... }
`, [dependencies]);

// 特点：
// - 类型安全的WGSL代码
// - 自动绑定管理
// - 与Three.js材质系统集成
4. GPU并行计算模式
text
计算模式：SIMD（单指令多数据）
每个线程执行相同指令，处理不同数据

线程组织：
工作组大小：未知（由驱动优化）
调度：512×512个线程，自动分组
5. 图像处理算法
wgsl
// 1. 随机噪声生成
使用伪随机函数生成Perlin-like噪声

// 2. 卷积模糊滤波
fn blur(image, uv) {
    采样5点X形模式：比9点方形采样快44%
    计算公式：∑(相邻像素)/5
}

// 3. 颜色增强
color * 1.05 // 每帧增强5%，产生"发光"效果
6. 内存管理策略
javascript
// 纹理配置
HDR模式：rgba16float (8字节/像素)
LDR模式：rgba8unorm (4字节/像素)

// 内存使用量：
512×512×8×2 = 4MB (双缓冲)
// 优化：使用半精度浮点，减少带宽需求
7. 动画与同步机制
javascript
// 三重循环结构
1. 计算循环: GPU计算着色器执行
2. 渲染循环: 每帧渲染到屏幕
3. 重置循环: 每秒重新生成纹理

// 时间管理
phase标志: 控制乒乓方向
lastUpdate: 防止重复重置
🚀 性能优化技术
1. 计算优化
最小化纹理采样：只采样5个点而不是9个

使用存储纹理：比传统纹理更快的内存访问

避免分支：着色器中无if语句，最大化并行效率

2. 内存优化
乒乓缓冲：消除同步等待

半精度浮点：减少内存占用和带宽

紧凑的数据布局：RGBA通道高效打包

3. 渲染优化
正交相机：无矩阵变换开销

单一材质：最小化状态切换

直接纹理显示：无后处理开销

🎨 视觉效果原理
1. 初始噪声生成
text
使用两个随机函数的差值创建更自然的噪声：
color = rand2(uv+seed*100) - rand2(uv+seed*300)
效果：产生有组织的随机图案，而非纯噪声
2. 迭代演化过程
text
每帧应用：
1. 模糊：使图案扩散和混合
2. 增强：×1.05倍颜色值
3. 循环：持续迭代

数学上：类似于热扩散方程
∂u/∂t = α∇²u + βu
3. 色彩行为
text
RGB通道独立处理：
- 使用不同的种子偏移
- 产生色彩分离效果
- 随时间演化出现"色溢"现象
📊 技术规格
计算能力需求
text
最低要求：支持WebGPU的现代GPU
推荐：独立显卡，支持计算着色器

线程数量：262,144个并发线程
计算频率：每秒60次计算+渲染
内存带宽：~120MB/s (60fps × 2MB/帧)
浏览器兼容性
text
支持：
- Chrome 113+ (启用Flag)
- Edge 113+
- Firefox Nightly (实验性支持)

要求：
- 启用WebGPU Flag
- 支持WGSL 1.0
- 支持存储纹理
🔍 扩展可能性
1. 技术扩展
javascript
// 可以添加的功能：
- 多级模糊（高斯金字塔）
- 边缘检测算子
- 物理模拟（流体、烟雾）
- 神经网络推理
2. 应用场景扩展
实时视频处理：滤镜和特效

科学可视化：模拟结果渲染

游戏特效：粒子系统、后期处理

AI辅助：在浏览器中运行模型

3. 优化方向
工作组优化：调整线程组大小

共享内存：减少纹理采样

异步计算：重叠计算和渲染

多GPU支持：分布计算负载 -->


<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示应用名称和功能描述 -->
		<title>Three.js WebGPU - 计算乒乓纹理演示</title>
		<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">
			<!-- 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>
				这是一个展示WebGPU计算能力的示例。<br>
				使用乒乓缓冲技术（双缓冲）在GPU上实时处理纹理数据：<br>
				1. 生成随机噪声纹理<br>
				2. 应用模糊滤镜效果<br>
				3. 每秒重置并增强视觉效果<br>
				4. 所有计算都在GPU上并行执行<br>
				<br>
				技术特点：<br>
				- 使用WebGPU计算管线<br>
				- 乒乓纹理避免读写冲突<br>
				- 实时GPU计算与渲染<br>
				- 基于物理的HDR纹理处理
			</small>
		</div>

		<!-- 
			importmap：模块导入映射配置
			作用：将模块名称映射到实际文件路径，简化import语句
			类似于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';
			// 导入TSL（Three.js Shader Language）相关功能
			// storageTexture: 创建存储纹理节点
			// wgslFn: 定义WGSL着色器函数
			// code: 编写着色器代码块
			// instanceIndex: 获取当前计算实例索引（相当于线程ID）
			// uniform: 创建统一变量（可在CPU设置，GPU读取）
			// NodeAccess: 纹理访问权限枚举（READ_ONLY, WRITE_ONLY等）
			import { storageTexture, wgslFn, code, instanceIndex, uniform, NodeAccess } from 'three/tsl';

			// 导入WebGPU兼容性检测工具
			import WebGPU from 'three/addons/capabilities/WebGPU.js';

			// ==================== 全局变量声明 ====================
			// 场景相关变量
			let camera, scene, renderer;
			
			// 计算着色器节点变量
			// computeInitNode: 初始化纹理的计算着色器
			// computeToPing/computeToPong: 乒乓交换的计算着色器
			let computeInitNode, computeToPing, computeToPong;
			
			// 纹理变量：用于乒乓缓冲的双纹理
			let pingTexture, pongTexture;
			
			// 材质变量：用于渲染最终结果
			let material;
			
			// 相位标志：控制当前读写方向
			// true: 从ping读，写入pong
			// false: 从pong读，写入ping
			let phase = true;
			
			// 上次更新时间戳：用于每秒重置纹理
			let lastUpdate = -1;

			// 随机种子：用于生成初始随机纹理
			// 使用uniform包装，可在CPU端更新，GPU端读取
			const seed = uniform(new THREE.Vector2());

			// ==================== 初始化函数调用 ====================
			init();

			// ==================== 主初始化函数 ====================
			async function init() {

				// ---------- 1. WebGPU兼容性检查 ----------
				if (WebGPU.isAvailable() === false) {
					// 如果不支持WebGPU，显示错误信息
					document.body.appendChild(WebGPU.getErrorMessage());
					// 抛出错误，停止执行
					throw new Error('浏览器不支持WebGPU，请使用Chrome 113+、Edge 113+或Firefox Nightly');
				}

				// ---------- 2. 相机设置 ----------
				// 使用正交相机，适合2D渲染
				// 正交相机不会产生透视变形，所有物体大小保持不变
				const aspect = window.innerWidth / window.innerHeight;
				camera = new THREE.OrthographicCamera(-aspect, aspect, 1, -1, 0, 2);
				camera.position.z = 1; // 将相机放置在Z=1位置

				// ---------- 3. 创建场景 ----------
				scene = new THREE.Scene();

				// ---------- 4. 纹理配置 ----------
				const hdr = true; // 使用高动态范围纹理，提供更广的颜色范围和精度
				const width = 512, height = 512; // 纹理分辨率：512x512像素

				// 创建两个存储纹理用于乒乓缓冲
				// 存储纹理是WebGPU特有的纹理类型，支持GPU计算着色器读写
				pingTexture = new THREE.StorageTexture(width, height);
				pongTexture = new THREE.StorageTexture(width, height);

				// 设置纹理数据类型
				if (hdr) {
					// 如果使用HDR，使用16位半精度浮点数，减少内存占用同时保持精度
					pingTexture.type = THREE.HalfFloatType;
					pongTexture.type = THREE.HalfFloatType;
				}

				// 根据HDR设置选择WGSL纹理格式
				// WGSL是WebGPU的着色器语言，需要指定确切的纹理格式
				const wgslFormat = hdr ? 'rgba16float' : 'rgba8unorm';
			
				// 创建纹理访问节点，并设置访问权限
				// 这是TSL的核心概念：将纹理封装为可编程节点
				const readPing = storageTexture(pingTexture).setAccess(NodeAccess.READ_ONLY);
				const writePing = storageTexture(pingTexture).setAccess(NodeAccess.WRITE_ONLY);
				const readPong = storageTexture(pongTexture).setAccess(NodeAccess.READ_ONLY);
				const writePong = storageTexture(pongTexture).setAccess(NodeAccess.WRITE_ONLY);

				// ---------- 5. 着色器代码定义 ----------
				// 定义WGSL辅助函数，这些函数会被多个计算着色器共享
				const rand2 = code(`
					// 伪随机数生成函数
					// 输入：二维向量
					// 输出：0-1之间的随机浮点数
					// 使用三角函数和乘法创建随机性
					fn rand2(n: vec2f) -> f32 {
						return fract(sin(dot(n, vec2f(12.9898, 4.1414))) * 43758.5453);
					}

					// 简单模糊滤波函数
					// 输入：纹理和像素坐标
					// 输出：模糊后的颜色值（5个像素的平均值）
					// 使用X形采样模式，比方形采样更快
					fn blur(image: texture_storage_2d<${wgslFormat}, read>, uv: vec2i) -> vec4f {
						var color = vec4f(0.0);

						// 采样5个像素：四个角+中心
						color += textureLoad(image, uv + vec2i(-1, 1));    // 左上
						color += textureLoad(image, uv + vec2i(-1, -1));   // 左下
						color += textureLoad(image, uv + vec2i(0, 0));     // 中心
						color += textureLoad(image, uv + vec2i(1, -1));    // 右下
						color += textureLoad(image, uv + vec2i(1, 1));     // 右上

						return color / 5.0; // 返回平均值
					}

					// UV坐标计算函数
					// 将像素索引转换为0-1的纹理坐标
					fn getUV(posX: u32, posY: u32) -> vec2f {
						let uv = vec2f(f32(posX) / ${width}.0, f32(posY) / ${height}.0);
						return uv;
					}
				`);

				// ---------- 6. 初始化计算着色器 ----------
				// 这个着色器只执行一次，用于生成初始随机纹理

				// 初始化纹理计算函数
				// 参数：
				// - writeTex: 要写入的纹理
				// - index: 当前线程索引（0 到 width*height-1）
				// - seed: 随机种子，确保每次运行结果不同
				const computeInitWGSL = wgslFn(`
					fn computeInitWGSL(writeTex: texture_storage_2d<${wgslFormat}, write>, index: u32, seed: vec2f) -> void {
						// 将一维索引转换为二维纹理坐标
						let posX = index % ${width};  // 列索引
						let posY = index / ${width};  // 行索引
						let indexUV = vec2u(posX, posY); // 无符号整数坐标
						let uv = getUV(posX, posY);     // 浮点数纹理坐标(0-1范围)

						// 生成随机RGB颜色
						// 使用不同的种子偏移创建颜色变化
						let r = rand2(uv + seed * 100) - rand2(uv + seed * 300);
						let g = rand2(uv + seed * 200) - rand2(uv + seed * 300);
						let b = rand2(uv + seed * 200) - rand2(uv + seed * 100);

						// 将生成的颜色写入纹理
						// vec4(r, g, b, 1): RGB颜色，Alpha固定为1（不透明）
						textureStore(writeTex, indexUV, vec4(r, g, b, 1));
					}
				`, [rand2]); // 传入依赖的辅助函数

				// 创建初始化计算节点
				// 配置参数并指定计算规模（每个像素一个线程）
				computeInitNode = computeInitWGSL({
					writeTex: storageTexture(pingTexture), // 写入ping纹理
					index: instanceIndex,                  // 当前线程索引
					seed                                   // 随机种子
				}).compute(width * height); // 启动width*height个线程

				// ---------- 7. 乒乓交换计算着色器 ----------
				// 这个着色器在每帧执行，应用模糊效果
				// 乒乓交换计算函数
				// 参数：
				// - readTex: 读取的纹理（输入）
				// - writeTex: 写入的纹理（输出）
				// - index: 当前线程索引
				const computePingPongWGSL = wgslFn(`
					fn computePingPongWGSL(readTex: texture_storage_2d<${wgslFormat}, read>, writeTex: texture_storage_2d<${wgslFormat}, write>, index: u32) -> void {
						// 计算像素位置
						let posX = index % ${width};
						let posY = index / ${width};
						let indexUV = vec2i(i32(posX), i32(posY));// 有符号整数坐标

						// 应用模糊效果
						let color = blur(readTex, indexUV).rgb;

						// 轻微增强颜色（乘以1.05）并写入输出纹理
						// 这个增强会导致数值逐渐增加，因此需要每秒重置
						textureStore(writeTex, indexUV, vec4f(color * 1.05, 1));
					}
				`, [rand2]);

				// 创建两个计算节点，实现乒乓交换：
				// computeToPong: 从ping读取，处理后写入pong
				computeToPong = computePingPongWGSL({
					readTex: readPing,    // 输入：ping纹理（只读）
					writeTex: writePong,  // 输出：pong纹理（只写）
					index: instanceIndex  // 线程索引
				}).compute(width * height);

				// computeToPing: 从pong读取，处理后写入ping
				computeToPing = computePingPongWGSL({
					readTex: readPong,    // 输入：pong纹理（只读）
					writeTex: writePing,  // 输出：ping纹理（只写）
					index: instanceIndex  // 线程索引
				}).compute(width * height);

				// ---------- 8. 创建渲染材质和几何体 ----------
				// 使用MeshBasicMaterial，这是一种不受光照影响的基础材质
				material = new THREE.MeshBasicMaterial({
					color: 0xffffff,      // 材质基础颜色（白色）
					map: pongTexture      // 纹理贴图，初始使用pong纹理
				});

				// 创建平面几何体（1x1单位）用于显示纹理
				// 平面位于世界原点，法向量指向Z轴正方向
				const plane = new THREE.Mesh(
					new THREE.PlaneGeometry(1, 1), // 1单位宽高的平面
					material                        // 上面创建的材质
				);
				scene.add(plane); // 将平面添加到场景中

				// ---------- 9. 创建WebGPU渲染器 ----------
				renderer = new THREE.WebGPURenderer({
					antialias: true // 启用抗锯齿，平滑边缘
				});
				// 设置设备像素比，适应高DPI屏幕
				renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器大小为窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 设置动画循环，每帧调用render函数
				renderer.setAnimationLoop(render);
				// 将渲染器的Canvas元素添加到页面中
				document.body.appendChild(renderer.domElement);

				// ---------- 10. 初始化渲染器 ----------
				// 异步初始化WebGPU上下文和资源
				await renderer.init();

				// ---------- 11. 添加窗口大小变化监听 ----------
				window.addEventListener('resize', onWindowResize);

				// ---------- 12. 执行初始计算 ----------
				// 运行初始化计算着色器，生成初始随机纹理
				renderer.compute(computeInitNode);

				console.log('初始化完成：WebGPU计算乒乓纹理演示已启动');
			}

			// ==================== 窗口大小变化处理函数 ====================
			function onWindowResize() {
				// 更新渲染器大小
				renderer.setSize(window.innerWidth, window.innerHeight);

				// 重新计算宽高比
				const aspect = window.innerWidth / window.innerHeight;
				// 计算当前视锥体高度
				const frustumHeight = camera.top - camera.bottom;

				// 调整正交相机的左右边界，保持宽高比
				// 确保内容居中且不变形
				camera.left = -frustumHeight * aspect / 2;
				camera.right = frustumHeight * aspect / 2;

				// 更新相机投影矩阵
				camera.updateProjectionMatrix();
				
				console.log(`窗口大小已调整：${window.innerWidth}x${window.innerHeight}`);
			}

			// ==================== 渲染循环函数 ====================
			// 此函数在每一帧被调用（通常60FPS）
			function render() {
				// 获取当前时间（毫秒）
				const time = performance.now();
				// 转换为秒（向下取整）
				const seconds = Math.floor(time / 1000);

				// ---------- 1. 每秒重置逻辑 ----------
				// 当phase为true且秒数发生变化时执行
				if (phase && seconds !== lastUpdate) {
					// 生成新的随机种子
					// Math.random()返回0-1之间的随机数
					seed.value.set(Math.random(), Math.random());
					
					// 执行初始化计算，重新生成随机纹理
					renderer.compute(computeInitNode);

					// 更新最后重置时间
					lastUpdate = seconds;
					
					console.log(`第${seconds}秒：纹理已重置，新种子: ${seed.value.x.toFixed(3)}, ${seed.value.y.toFixed(3)}`);
				}

				// ---------- 2. 执行计算着色器 ----------
				// 根据当前相位选择计算方向
				// phase = true: ping -> pong
				// phase = false: pong -> ping
				renderer.compute(phase ? computeToPong : computeToPing);

				// ---------- 3. 更新材质纹理 ----------
				// 将当前输出纹理设置为材质的贴图
				// 这里实现"乒乓"显示：总是显示最新的输出纹理
				material.map = phase ? pongTexture : pingTexture;

				// ---------- 4. 切换相位 ----------
				// 为下一帧准备相反的方向
				phase = !phase;

				// ---------- 5. 渲染场景 ----------
				// 使用当前相机渲染整个场景
				// 这会触发WebGPU绘制命令提交
				renderer.render(scene, camera);
			}

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