<!-- Three.js WebGPU 间接绘制示例
🎯 项目概述
这是一个展示Three.js在WebGPU环境下间接绘制(Indirect Drawing) 技术的高性能图形示例。它通过计算着色器动态控制10万个三角形的渲染，实现了GPU驱动的复杂动画效果。

🚀 核心功能
1. 大规模实例化渲染
渲染对象: 10万个三角形实例

渲染方式: 使用实例化渲染技术，一次绘制调用渲染所有实例

性能优势: 显著减少CPU-GPU通信开销和绘制调用次数

2. 动态实例控制
实时变化: 渲染的实例数量随时间动态变化(100-100,000个)

动画效果: 基于正弦波函数平滑过渡可见实例数量

最少保证: 始终保持至少100个实例可见

3. 复杂3D动画
位置动画: 每个三角形在球面上振荡运动

旋转动画: 使用四元数在起始和结束朝向之间平滑旋转

颜色动画: 基于顶点位置和时间的动态色彩波纹

4. 交互式体验
相机控制: 支持鼠标拖拽旋转、滚轮缩放

自适应布局: 响应式设计，适应不同窗口尺寸

实时渲染: 60FPS流畅动画效果

🔧 主要技术点
1. WebGPU核心技术
间接绘制(Indirect Drawing)
javascript
// 创建间接绘制缓冲区
const drawBuffer = new THREE.IndirectStorageBufferAttribute(new Uint32Array(5), 5);
geometry.setIndirect(drawBuffer);

// 定义绘制参数结构体
const drawBufferStruct = struct({
    vertexCount: 'uint',
    instanceCount: { type: 'uint', atomic: true },  // 原子操作
    firstVertex: 'uint',
    firstInstance: 'uint',
    offset: 'uint'
}, 'DrawBuffer');
工作原理: 将绘制参数存储在GPU缓冲区，渲染时从缓冲区读取而非CPU传递

性能优势: 减少每帧的API调用开销，特别适合动态变化的实例数量

计算着色器(Compute Shaders)
javascript
// 动态更新实例数量的计算着色器
computeDrawBuffer = Fn(() => {
    const halfTime = sin(time.mul(0.5));
    const instanceCount = max(pow(halfTime.add(1), 4.0).mul(instances), 100);
    atomicStore(drawStorage.get('instanceCount'), instanceCount);
})().compute(instances);
并行计算: 利用GPU并行处理能力

动态控制: 每帧重新计算可见实例数量

原子操作: 确保多线程环境下的数据一致性

2. Three.js高级特性
TSL着色器语言
javascript
// 使用TSL声明式着色器编程
const positionFn = Fn(() => {
    const sphereOscilation = offset.mul(oscilationRange).add(position).toVar();
    const orientation = normalize(mix(orientationStart, orientationEnd, halfTime));
    // 四元数旋转计算
    return vcV.mul(orientation.w.mul(2.0))
             .add(crossvcV.mul(2.0).add(sphereOscilation));
})();
类型安全: 编译时类型检查

可组合性: 函数式编程风格

自动优化: Three.js运行时优化着色器代码

节点材质系统
javascript
const material = new THREE.MeshBasicNodeMaterial({
    side: THREE.DoubleSide,
    forceSinglePass: true,
    transparent: true
});
material.positionNode = positionFn;
material.fragmentNode = fragmentFn;
可视化编程: 节点式材质编辑

性能优化: 自动合并渲染通道

灵活扩展: 易于创建复杂材质效果

3. 数学与算法
四元数旋转
javascript
// 四元数旋转公式实现
const vcV = cross(orientation.xyz, sphereOscilation);
const crossvcV = cross(orientation.xyz, vcV);
const rotatedPosition = vcV.mul(orientation.w.mul(2.0))
                          .add(crossvcV.mul(2.0).add(sphereOscilation));
避免万向节锁: 相比欧拉角，四元数没有旋转顺序问题

平滑插值: 在起始和结束旋转之间球面线性插值

高效计算: GPU友好的数学运算

振荡动画算法
javascript
// 球面振荡计算
const oscilationRange = max(abs(halfTime.mul(2.0).add(1.0)), 0.5);
const sphereOscilation = offset.mul(oscilationRange).add(position);
周期性运动: 基于正弦函数的振荡

范围控制: 确保最小振荡幅度

可调节参数: 易于调整动画速度和幅度

4. 性能优化技术
实例化缓冲区
javascript
// 实例属性使用InstancedBufferAttribute
geometry.setAttribute('offset', new THREE.InstancedBufferAttribute(
    new Float32Array(offsets), 3
));
内存效率: 共享顶点数据，减少内存占用

渲染效率: 减少状态切换和绘制调用

存储缓冲区优化
javascript
// 创建存储缓冲区用于GPU计算
const drawStorage = storage(drawBuffer, drawBufferStruct, drawBuffer.count);
GPU内存: 数据驻留在GPU内存，减少传输延迟

高速访问: 计算着色器直接读写，无CPU干预

5. 交互与用户体验
轨道控制器
javascript
const controls = new OrbitControls(camera, renderer.domElement);
直观控制: 鼠标拖拽旋转、滚轮缩放

平滑动画: 惯性效果和动画过渡

边界控制: 防止相机进入无效区域

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

保持比例: 正确计算宽高比，避免图像拉伸

实时响应: 即时更新无需刷新页面

📊 性能特点
CPU负载极低
所有动画计算在GPU上完成

CPU仅负责事件处理和简单的状态管理

主线程几乎不会被阻塞

GPU高效利用
并行处理10万个实例的变换计算

计算着色器与渲染着色器流水线协作

充分利用现代GPU的计算能力

内存使用优化
实例数据一次性上传到GPU

共享几何数据减少重复存储

动态缓冲区更新无需重新分配内存

🎨 视觉效果特色
色彩系统
随机颜色: 每个实例有独特的RGBA颜色

动态波纹: 基于位置的色彩变化

透明度混合: 支持半透明效果，创建深度感

运动效果
复合动画: 位置振荡 + 旋转 + 颜色变化

自然过渡: 所有动画基于连续数学函数

协调运动: 实例间运动有节奏感但不完全同步

场景氛围
深色背景: 突出显示彩色三角形

透视景深: 远近距离不同的模糊效果

动态光照: 虽然没有光源，但通过颜色变化模拟光照效果

🔍 技术实现亮点
创新的架构模式
text
CPU (控制逻辑) → WebGPU API → GPU (计算+渲染)
     ↓                           ↑
    事件处理               间接绘制缓冲区
     ↓                           ↑
    相机控制                存储缓冲区
高效的渲染流水线
初始化阶段: 创建几何数据和缓冲区

计算阶段: GPU计算着色器更新实例参数

渲染阶段: 间接绘制调用渲染所有可见实例

后处理: 可扩展添加后期效果

模块化设计
数据层: 几何体、缓冲区、属性管理

计算层: 计算着色器、动画逻辑

渲染层: 材质、着色器、渲染器

交互层: 控制器、事件处理 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 
			页面元数据设置
			- title: 页面标题，显示在浏览器标签页上
			- charset: 字符编码设置为UTF-8，支持中文和特殊字符
			- viewport: 视口设置，控制移动端显示和缩放行为
		-->
		<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">
		<!-- 引入CSS样式文件，用于页面布局和样式控制 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			页面信息显示区域
			id="info": 用于CSS样式选择器和JavaScript操作
			这个区域显示示例的基本信息和相关链接
		-->
		<div id="info">
			<!-- 
				three.js官方logo链接
				- href: 链接到three.js官方网站
				- target="_blank": 在新标签页中打开链接
				- rel="noopener": 安全属性，防止新页面访问原页面的window对象
				- 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>WebGPU间接绘制演示</span>
			</div>

			<!-- 示例描述信息 -->
			<small>
				使用结构体(struct)和间接绘制(indirect draw)技术，通过计算着色器动态控制10万个实例的渲染。
				展示WebGPU高性能计算与渲染的结合应用。
			</small>
			<!-- 技术要点说明 -->
			<div class="tech-points" style="margin-top: 40px;">
				<small>
					<strong>技术要点：</strong>
					<br>• 间接绘制(Indirect Drawing) - 减少CPU-GPU通信
					<br>• 计算着色器(Compute Shader) - 动态更新实例参数
					<br>• 原子操作(Atomic Operations) - 线程安全的缓冲区更新
					<br>• 实例化渲染(Instanced Rendering) - 高效绘制大量相似对象
					<br>• TSL着色器语言 - Three.js的声明式着色器编程
				</small>
			</div>
		</div>

		<!-- 
			导入映射(Import Maps)配置
			作用：将模块标识符映射到实际文件路径
			允许在代码中使用简化的导入语句
			现代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>

		<!-- 
			主JavaScript模块
			type="module": 标识这是一个ES6模块，支持模块化导入导出
			模块中的代码在严格模式下运行，有独立的作用域
		-->
		<script type="module">

			// ==================== 模块导入区域 ====================
			
			// 导入Three.js WebGPU版本的核心功能
			// 使用import * as语法将整个模块导入为一个对象
			import * as THREE from 'three/webgpu';
			
			// 从TSL(Three.js Shading Language)库导入着色器函数和类型
			// struct: 定义着色器中的结构体类型，用于组织相关数据
			// storage: 创建存储缓冲区(storage buffer)，用于GPU计算和着色器数据共享
			// sin, cross, normalize, abs, mix: 数学函数，用于向量和标量计算
			// Fn: 函数定义器，用于创建可重用的着色器函数
			// vec4, uint: 数据类型构造器，创建4维向量和无符号整数
			// time: 时间统一变量，提供着色器中的时间信息
			// varyingProperty: 定义varying变量，用于顶点着色器和片元着色器之间的数据传递
			// attribute: 定义顶点属性，每个顶点或实例特有的数据
			// atomicStore: 原子存储操作，确保多线程环境下的数据一致性
			import { 
				struct, storage, sin, cross, normalize, 
				abs, mix, Fn, vec4, max, pow, time, 
				varyingProperty, attribute, uint, atomicStore 
			} from 'three/tsl';
			
			// 导入轨道控制器，用于鼠标/触摸控制相机旋转、缩放和平移
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入WebGPU能力检测模块，检查浏览器是否支持WebGPU
			import WebGPU from 'three/addons/capabilities/WebGPU.js';

			// ==================== WebGPU兼容性检查 ====================
			
			// 检测当前浏览器环境是否支持WebGPU
			if ( WebGPU.isAvailable() === false ) {
				// 如果不支持WebGPU，获取错误信息HTML元素
				const errorMessage = WebGPU.getErrorMessage();
				// 将错误信息添加到页面body中，提示用户
				document.body.appendChild( errorMessage );
				// 抛出错误，停止JavaScript执行
				throw new Error( '当前浏览器不支持WebGPU，请使用Chrome 113+、Edge 113+或Safari 16.4+' );
			}

			// ==================== 渲染器初始化 ====================
			
			// 创建WebGPU渲染器实例
			// antialias: true 启用抗锯齿，使边缘更平滑
			const renderer = new THREE.WebGPURenderer( { antialias: true } );
			
			// 设置渲染器输出颜色空间为sRGB
			// sRGB是标准的颜色空间，能正确显示颜色渐变
			renderer.outputColorSpace = THREE.SRGBColorSpace;
			
			// 设置设备像素比，匹配显示器的物理像素和CSS像素比例
			// 提高高DPI显示器的渲染质量
			renderer.setPixelRatio( window.devicePixelRatio );
			
			// 设置渲染器画布尺寸为整个浏览器窗口大小
			renderer.setSize( window.innerWidth, window.innerHeight );
			
			// 设置清除颜色为黑色(十六进制表示)
			// 每次渲染前会用这个颜色清除画布
			renderer.setClearColor( 0x000000 );
			
			// 设置清除透明度为0(完全透明)
			// 与clearColor一起定义背景的透明状态
			renderer.setClearAlpha( 0 );
			
			// 将渲染器的DOM元素(Canvas画布)添加到页面body中
			// 这样画布才能显示在网页上
			document.body.appendChild( renderer.domElement );

			// ==================== 场景和相机设置 ====================
			
			// 计算窗口的宽高比，用于相机投影矩阵
			// 宽高比 = 宽度 / 高度
			const aspect = window.innerWidth / window.innerHeight;

			// 创建透视相机(PerspectiveCamera)
			// 参数说明：
			// 50.0 - 视野角度(Field of View)，单位是度，控制相机能看到的多大范围
			// aspect - 宽高比，确保渲染内容不被拉伸
			// 0.1 - 近裁剪面(Near Plane)，距离相机多近的物体开始被渲染
			// 10000 - 远裁剪面(Far Plane)，距离相机多远的物体不再被渲染
			const camera = new THREE.PerspectiveCamera( 50.0, aspect, 0.1, 10000 );
			
			// 创建场景(Scene)，所有3D对象的容器
			// 场景管理着渲染对象、光源、相机等
			const scene = new THREE.Scene();

			// 设置场景背景颜色为深蓝色
			// 0x00001f是十六进制颜色表示，RGB分量分别为0, 0, 31
			scene.background = new THREE.Color( 0x00001f );
			
			// 设置相机初始位置
			// 三个参数分别对应X、Y、Z坐标
			// (1, 1, 1)表示在三维空间的原点右上前方
			camera.position.set( 1, 1, 1 );
			
			// 创建轨道控制器(OrbitControls)
			// 将相机和渲染器的DOM元素传递给控制器
			// 用户可以通过鼠标拖拽、滚轮缩放来交互控制相机
			const controls = new OrbitControls( camera, renderer.domElement );

			// ==================== 全局变量声明 ====================
			
			// 计算着色器引用变量
			// computeDrawBuffer: 用于动态更新绘制缓冲区中的实例数量
			// computeInitDrawBuffer: 用于初始化绘制缓冲区参数
			// 使用let声明，因为这些变量在init函数中才会被赋值
			let computeDrawBuffer, computeInitDrawBuffer;

			// ==================== 初始化函数调用 ====================
			
			// 调用初始化函数，开始设置场景
			init();

			// ==================== 异步初始化函数 ====================
			
			/**
			 * 异步初始化函数
			 * 负责创建所有3D对象、设置材质、配置着色器
			 * async关键字表示函数内部可以使用await进行异步操作
			 */
			async function init() {

				// 等待渲染器完全初始化
				// WebGPU渲染器初始化是异步的，需要等待设备、上下文等资源准备就绪
				await renderer.init();

				// ==================== 几何体数据准备 ====================
				
				// 创建临时向量对象，用于四元数计算
				// Vector4表示四维向量，用于存储四元数(x, y, z, w)
				const vector = new THREE.Vector4();

				// 定义实例数量：10万个三角形实例
				// 实例化渲染允许用一次绘制调用渲染大量相似对象
				const instances = 100000;

				// 数据数组声明：
				// positions: 存储单个三角形的3个顶点位置
				// offsets: 存储每个实例的位置偏移量
				// colors: 存储每个实例的颜色(RGBA)
				// orientationsStart: 存储每个实例的起始旋转四元数
				// orientationsEnd: 存储每个实例的结束旋转四元数
				const positions = [];
				const offsets = [];
				const colors = [];
				const orientationsStart = [];
				const orientationsEnd = [];

				// 定义基础三角形的位置数据
				// 这是一个小三角形，三个顶点在3D空间中的坐标
				// 每个实例都会以这个三角形为基础，通过变换显示在不同位置
				positions.push( 0.025, - 0.025, 0 );  // 顶点1: 右下
				positions.push( - 0.025, 0.025, 0 );   // 顶点2: 左上
				positions.push( 0, 0, 0.025 );         // 顶点3: 正前方稍微突出

				// ==================== 生成实例属性数据 ====================
				
				// 循环生成10万个实例的属性数据
				for ( let i = 0; i < instances; i ++ ) {

					// 生成随机偏移量
					// Math.random()返回0-1的随机数，减去0.5得到-0.5到0.5的范围
					// 这样实例会分布在原点周围的立方体区域内
					offsets.push( 
						Math.random() - 0.5,  // X轴偏移
						Math.random() - 0.5,  // Y轴偏移
						Math.random() - 0.5   // Z轴偏移
					);

					// 生成随机颜色
					// 四个分量分别对应红、绿、蓝和透明度
					// 透明度也随机，创建半透明效果
					colors.push( 
						Math.random(),  // 红色分量
						Math.random(),  // 绿色分量
						Math.random(),  // 蓝色分量
						Math.random()   // 透明度
					);

					// 生成随机起始朝向四元数
					// 四元数用于表示3D旋转，比欧拉角没有万向节锁问题
					// 生成四个-1到1的随机分量
					vector.set( 
						Math.random() * 2 - 1,  // X分量
						Math.random() * 2 - 1,  // Y分量
						Math.random() * 2 - 1,  // Z分量
						Math.random() * 2 - 1   // W分量
					);
					// 归一化四元数，确保其表示有效的旋转
					vector.normalize();
					// 将归一化后的四元数分量添加到数组
					orientationsStart.push( vector.x, vector.y, vector.z, vector.w );

					// 生成随机结束朝向四元数
					// 与起始朝向类似，但使用不同的随机值
					vector.set( 
						Math.random() * 2 - 1,
						Math.random() * 2 - 1,
						Math.random() * 2 - 1,
						Math.random() * 2 - 1
					);
					vector.normalize();
					orientationsEnd.push( vector.x, vector.y, vector.z, vector.w );

				}

				// ==================== 创建实例化几何体 ====================
				
				// 创建InstancedBufferGeometry实例
				// 这是Three.js中用于实例化渲染的特殊几何体类型
				const geometry = new THREE.InstancedBufferGeometry();
				
				// 设置实例数量
				// WebGPU渲染器会根据这个值决定绘制多少次实例
				geometry.instanceCount = instances;

				// 设置顶点位置属性
				// Float32BufferAttribute: 32位浮点数缓冲区属性
				// 参数：Float32Array数据, 每个顶点的分量数(3表示xyz)
				geometry.setAttribute( 'position', 
					new THREE.Float32BufferAttribute( positions, 3 ) 
				);
				
				// 设置实例偏移量属性
				// InstancedBufferAttribute: 实例化缓冲区属性
				// 与普通属性的区别：每个实例有独立的值，而不是每个顶点
				geometry.setAttribute( 'offset', 
					new THREE.InstancedBufferAttribute( new Float32Array( offsets ), 3 ) 
				);
				
				// 设置实例颜色属性(RGBA，4个分量)
				geometry.setAttribute( 'color', 
					new THREE.InstancedBufferAttribute( new Float32Array( colors ), 4 ) 
				);
				
				// 设置实例起始朝向属性(四元数，4个分量)
				geometry.setAttribute( 'orientationStart', 
					new THREE.InstancedBufferAttribute( new Float32Array( orientationsStart ), 4 ) 
				);
				
				// 设置实例结束朝向属性(四元数，4个分量)
				geometry.setAttribute( 'orientationEnd', 
					new THREE.InstancedBufferAttribute( new Float32Array( orientationsEnd ), 4 ) 
				);

				// ==================== 间接绘制缓冲区设置 ====================
				
				// 创建间接绘制缓冲区属性
				// IndirectStorageBufferAttribute: 专为间接绘制设计的缓冲区属性
				// 参数：Uint32Array(5个元素), 每个元素的大小(5表示有5个参数)
				// 5个参数对应WebGPU drawIndirect调用的参数：
				// [vertexCount, instanceCount, firstVertex, firstInstance, offset]
				const drawBuffer = new THREE.IndirectStorageBufferAttribute( 
					new Uint32Array( 5 ), 5 
				);
				
				// 将间接绘制缓冲区设置为几何体的间接绘制参数源
				// 这样渲染时WebGPU会从这个缓冲区读取绘制参数，而不是从CPU传递
				geometry.setIndirect( drawBuffer );

				// ==================== 定义间接绘制结构体 ====================
				
				// 使用TSL的struct函数定义绘制缓冲区的结构
				// 这个结构体对应WebGPU的间接绘制参数
				const drawBufferStruct = struct( {
					// 顶点数量：要绘制的顶点总数
					vertexCount: 'uint',
					
					// 实例数量：要绘制的实例总数
					// atomic: true 表示这个字段支持原子操作
					// 原子操作确保在多线程(计算着色器)环境下修改的安全性
					instanceCount: { type: 'uint', atomic: true },
					
					// 第一个顶点：顶点缓冲区中的起始索引
					firstVertex: 'uint',
					
					// 第一个实例：实例缓冲区中的起始索引
					firstInstance: 'uint',
					
					// 偏移量：在实例数据中的字节偏移
					offset: 'uint'
				}, 'DrawBuffer' );  // 结构体名称，用于调试和引用

				// 创建存储缓冲区视图
				// storage函数将普通的缓冲区属性包装为可在着色器中访问的存储缓冲区
				// 参数：原始缓冲区，结构体定义，元素数量
				const drawStorage = storage( drawBuffer, drawBufferStruct, drawBuffer.count );

				// ==================== 创建计算着色器：更新实例数量 ====================
				
				/**
				 * computeDrawBuffer计算着色器
				 * 作用：根据时间动态更新要渲染的实例数量
				 * 实现实例数量的动画效果：随时间正弦波动
				 */
				computeDrawBuffer = Fn( () => {
					
					// 计算基于时间的正弦值
					// time.mul(0.5): 将时间乘以0.5，减慢变化速度
					// sin(): 计算正弦值，范围[-1, 1]
					const halfTime = sin( time.mul( 0.5 ) );
					
					// 计算动态实例数量：
					// 1. halfTime.add(1): 将正弦值从[-1,1]映射到[0,2]
					// 2. pow(..., 4.0): 取4次方，创建更陡峭的变化曲线
					// 3. .mul(instances): 乘以总实例数，得到实际实例数
					// 4. max(..., 100): 与100取最大值，确保最少渲染100个实例
					// 5. .toVar('instanceCount'): 转换为变量并命名，便于调试
					const instanceCount = max( 
						( pow( halfTime.add( 1 ), 4.0 ) ).mul( instances ), 
						100 
					).toVar( 'instanceCount' );
					
					// 使用原子操作将计算出的实例数量存储到绘制缓冲区
					// atomicStore: 原子存储操作，确保多线程安全
					// drawStorage.get('instanceCount'): 获取结构体中的instanceCount字段
					atomicStore( drawStorage.get( 'instanceCount' ), instanceCount );
					
				} )().compute( instances );  // 执行计算着色器，指定并行度为instances(10万)
				
				// ==================== 创建计算着色器：初始化绘制参数 ====================
				
				/**
				 * computeInitDrawBuffer计算着色器
				 * 作用：初始化间接绘制缓冲区的所有参数
				 * 在每帧渲染前调用，确保绘制参数处于已知状态
				 */
				computeInitDrawBuffer = Fn( () => {
					
					// 获取绘制缓冲区的引用
					const drawInfo = drawStorage;
					
					// 设置顶点数量为3(三角形有3个顶点)
					drawInfo.get( 'vertexCount' ).assign( 3 );
					
					// 原子操作设置实例数量为0
					// 注意：这个0会被computeDrawBuffer覆盖
					atomicStore( drawInfo.get( 'instanceCount' ), uint( 0 ) );
					
					// 设置第一个顶点索引为0(从顶点缓冲区的开头开始)
					drawInfo.get( 'firstVertex' ).assign( 0 );
					
					// 设置第一个实例索引为0(从实例缓冲区的开头开始)
					drawInfo.get( 'firstInstance' ).assign( 0 );
					
					// 设置偏移量为0(无额外偏移)
					drawInfo.get( 'offset' ).assign( 0 );

				} )().compute( 1 );  // 执行计算着色器，并行度为1(只需要一个线程执行)
			
				// ==================== 定义着色器中的传递变量 ====================
				
				/**
				 * 在顶点着色器和片元着色器之间传递数据的变量
				 * varyingProperty: 定义varying变量
				 * 参数：数据类型，变量名
				 */
				
				// vPosition: 传递变换后的顶点位置
				// 用于在片元着色器中计算基于位置的视觉效果
				const vPosition = varyingProperty( 'vec3', 'vPosition' );
				
				// vColor: 传递顶点颜色
				// 从顶点着色器传递到片元着色器进行插值
				const vColor = varyingProperty( 'vec4', 'vColor' );

				// ==================== 顶点着色器参数定义 ====================
				
				/**
				 * 顶点着色器的输入参数
				 * attribute: 表示这些是每个顶点或实例特有的数据
				 * 这些参数在GPU中作为缓冲区提供
				 */
				const positionShaderParams = {
					position: attribute( 'position' ),            // 基础顶点位置(每个三角形相同)
					offset: attribute( 'offset' ),                // 实例位置偏移(每个实例不同)
					color: attribute( 'color' ),                  // 实例颜色(每个实例不同)
					orientationStart: attribute( 'orientationStart' ),  // 起始旋转四元数
					orientationEnd: attribute( 'orientationEnd' ),      // 结束旋转四元数
					time: time                                     // 统一时间变量(所有实例相同)
				};
			
				// ==================== 定义顶点着色器函数 ====================
				
				/**
				 * positionFn - 顶点着色器主函数
				 * 作用：计算每个顶点的最终位置
				 * 包含位置偏移、旋转动画等复杂变换
				 */
				const positionFn = Fn( () => {

					// 从参数对象中解构出需要的属性
					// 这些是顶点着色器的输入
					const { position, offset, color, orientationStart, orientationEnd } = positionShaderParams;

					// 计算基于时间的正弦值，用于控制动画
					// 与computeDrawBuffer中的计算保持一致
					const halfTime = sin( time.mul( 0.5 ) );

					// 计算振荡范围因子
					// 将正弦值范围(-1到1)映射到更复杂的范围：
					// 1. halfTime.mul(2.0).add(1.0): 映射到[0, 2]
					// 2. abs(): 取绝对值，范围[0, 2]
					// 3. max(..., 0.5): 与0.5取最大值，确保最小值是0.5
					// 最终范围：[0.5, 2.0]
					const oscilationRange = max( abs( halfTime.mul( 2.0 ).add( 1.0 ) ), 0.5 );

					// 计算球面振荡位置
					// 1. offset.mul(oscilationRange): 将偏移量乘以振荡范围
					// 2. .add(position): 加上基础顶点位置
					// 3. .toVar(): 转换为变量，便于后续使用
					// 效果：实例位置随时间在球面上振荡
					const sphereOscilation = offset.mul( oscilationRange ).add( position ).toVar();

					// 计算当前旋转四元数
					// 1. mix(orientationStart, orientationEnd, halfTime): 
					//    在起始和结束旋转之间插值，halfTime作为插值因子
					// 2. normalize(): 归一化四元数，确保是有效的旋转
					// 效果：实例在起始和结束朝向之间平滑旋转
					const orientation = normalize( mix( orientationStart, orientationEnd, halfTime ) );
					
					// 使用四元数旋转计算：
					// 四元数旋转公式：v' = v + 2.0 * w * (q.xyz × v) + 2.0 * (q.xyz × (q.xyz × v))
					// 其中v是要旋转的向量，q是四元数(q.xyz是向量部分，q.w是标量部分)
					
					// 第一次叉积：q.xyz × sphereOscilation
					const vcV = cross( orientation.xyz, sphereOscilation );
					
					// 第二次叉积：q.xyz × vcV
					const crossvcV = cross( orientation.xyz, vcV );

					// 应用四元数旋转公式：
					// 1. vcV.mul(orientation.w.mul(2.0)): 2.0 * w * (q.xyz × v)
					// 2. crossvcV.mul(2.0).add(sphereOscilation): 2.0 * (q.xyz × (q.xyz × v)) + v
					// 3. 将两部分相加得到旋转后的位置
					vPosition.assign( 
						vcV.mul( orientation.w.mul( 2.0 ) )
						   .add( crossvcV.mul( 2.0 ).add( sphereOscilation ) ) 
					);
					
					// 将颜色传递给片元着色器
					// 颜色在顶点之间会进行插值
					vColor.assign( color );

					// 返回最终计算出的顶点位置
					// 这是顶点着色器必须返回的值
					return vPosition;

				} )();

				// ==================== 定义片元着色器函数 ====================
				
				/**
				 * fragmentFn - 片元着色器主函数
				 * 作用：计算每个像素的最终颜色
				 * 可以基于位置、时间等添加视觉效果
				 */
				const fragmentFn = Fn( () => {

					// 获取从顶点着色器传递来的颜色
					// vec4(vColor): 确保是四维向量
					// .toVar(): 转换为变量，便于修改
					const color = vec4( vColor ).toVar();

					// 添加基于位置和时间的动态效果：
					// 1. vPosition.x.mul(10.0): 将X坐标乘以10，增加波纹频率
					// 2. .add(time): 加上时间，使波纹动画随时间移动
					// 3. sin(...): 计算正弦值，范围[-1, 1]
					// 4. .mul(0.5): 乘以0.5，范围[-0.5, 0.5]
					// 5. color.r.addAssign(...): 将结果加到红色分量上
					// 效果：创建红色的波纹动画，增强视觉效果
					color.r.addAssign( sin( vPosition.x.mul( 10.0 ).add( time ) ).mul( 0.5 ) );

					// 返回最终计算的颜色
					// 这是片元着色器必须返回的值
					return color;

				} )();

				// ==================== 创建材质 ====================
				
				/**
				 * 使用MeshBasicNodeMaterial，这是Three.js的节点材质系统
				 * 节点材质允许通过连接节点来创建复杂的着色器
				 */
				const material = new THREE.MeshBasicNodeMaterial( {
					side: THREE.DoubleSide,      // 双面渲染：三角形的两面都渲染
					forceSinglePass: true,       // 强制单通道渲染：优化透明物体渲染性能
					transparent: true            // 启用透明度：支持alpha混合
				} );

				// 设置顶点着色器节点
				// 将我们定义的positionFn函数赋值给材质
				material.positionNode = positionFn;
				
				// 设置片元着色器节点
				// 将我们定义的fragmentFn函数赋值给材质
				material.fragmentNode = fragmentFn;

				// ==================== 创建网格对象 ====================
				
				// 创建Mesh(网格)对象
				// 网格是Three.js中的基本渲染对象，包含几何体和材质
				const mesh = new THREE.Mesh( geometry, material );
				
				// 将网格添加到场景中
				// 只有添加到场景中的对象才会被渲染
				scene.add( mesh );

				// ==================== 设置渲染循环 ====================
				
				// 设置动画循环回调函数
				// setAnimationLoop会以显示器的刷新率(通常是60Hz)调用render函数
				renderer.setAnimationLoop( render );

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

			}

			// ==================== 渲染循环函数 ====================
			
			/**
			 * render - 每帧调用的渲染函数
			 * 负责更新控制器、渲染场景和执行计算着色器
			 * 这个函数会在显示器的刷新率下被调用(通常60次/秒)
			 */
			function render() {

				// 更新轨道控制器
				// 处理用户的鼠标/触摸输入，更新相机位置和朝向
				controls.update();

				// 渲染场景
				// 将3D场景从相机的视角渲染到画布上
				renderer.render( scene, camera );

				// 执行计算着色器：
				// 计算着色器在GPU上并行执行，不阻塞主线程
				
				// 1. 首先初始化绘制缓冲区
				// 将绘制参数重置为初始状态
				renderer.compute( computeInitDrawBuffer );
				
				// 2. 然后更新实例数量
				// 根据时间动态计算并更新要渲染的实例数量
				renderer.compute( computeDrawBuffer );

			}

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

				// 更新相机的宽高比
				// 确保渲染内容不会因窗口形状变化而拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 投影矩阵定义了3D空间如何映射到2D屏幕
				// 当相机参数改变时，必须调用此方法更新内部矩阵
				camera.updateProjectionMatrix();
				
				// 更新渲染器尺寸
				// 使渲染画布的大小与窗口大小保持一致
				renderer.setSize( window.innerWidth, window.innerHeight );

			}

		</script>

	</body>
</html>