<!-- Three.js WebGPU 实例化网格示例 - 详细技术分析
🎯 代码核心功能
主要功能
这是一个展示 Three.js WebGPU 实例化渲染 的交互式3D可视化示例。页面加载后，会在3D空间中显示大量（默认1000个）相同的“Suzanne”（猴子头）模型，每个实例都有独立的位置、旋转和动态颜色，同时它们共享相同的几何体和材质数据。

交互体验
动态效果：所有实例会随时间进行平滑的旋转运动

波浪式旋转：每个实例的旋转基于其在三维网格中的位置，形成波浪传播效果

实时颜色变化：每个实例的颜色基于其法线方向和时间的正弦波动态变化

性能调节：可以通过调试面板实时调整显示的实例数量

URL参数控制：支持通过URL查询参数（如?8）设置实例密度

🔧 主要技术点
1. WebGPU 渲染技术
javascript
import * as THREE from 'three/webgpu';
现代图形API：使用WebGPU替代传统的WebGL

性能优势：更低的CPU开销，更好的多线程支持

异步渲染：await renderer.render() 支持异步操作

GPU实例化：原生支持GPU侧的实例化渲染

2. 实例化渲染（Instanced Rendering）
javascript
mesh = new THREE.InstancedMesh( geometry, material, count );
核心对象：THREE.InstancedMesh 类

共享资源：所有实例共享相同的顶点数据和材质

独立变换：每个实例有自己的4×4变换矩阵

性能优化：减少绘制调用（draw calls），显著提升渲染性能

3. TSL（Three.js Shading Language）
javascript
import { mix, range, normalWorld, oscSine, time } from 'three/tsl';
声明式着色器：使用TSL节点系统编写材质

动态颜色效果：

javascript
material.colorNode = mix( normalWorld, randomColors, oscSine( time.mul( .1 ) ) );
实时计算：颜色基于法线方向和时间的正弦波混合

4. 高效矩阵更新策略
javascript
const dummy = new THREE.Object3D();
// ... 在循环中
dummy.updateMatrix();
mesh.setMatrixAt( i, dummy.matrix );
单对象重用：使用一个临时对象计算所有变换

矩阵缓存：避免频繁创建新对象的内存分配

批量更新：所有实例变换计算完成后一次性更新

5. 三维网格布局算法
javascript
const offset = ( amount - 1 ) / 2;
for ( let x = 0; x < amount; x ++ ) {
    for ( let y = 0; y < amount; y ++ ) {
        for ( let z = 0; z < amount; z ++ ) {
            dummy.position.set( offset - x, offset - y, offset - z );
立方体排列：在三维空间中均匀分布实例

中心对齐：通过offset计算使网格以原点为中心

位置计算：每个实例的坐标基于其在网格中的索引

6. 动态旋转效果
javascript
dummy.rotation.y = ( Math.sin( x / 4 + time ) + 
                     Math.sin( y / 4 + time ) + 
                     Math.sin( z / 4 + time ) );
坐标相关：旋转角度基于实例的x、y、z坐标

时间驱动：随时间变化产生动画效果

波浪传播：不同位置的实例有相位差，形成波浪效果

7. 性能优化技巧
javascript
mesh.instanceMatrix.setUsage( THREE.DynamicDrawUsage );
mesh.instanceMatrix.needsUpdate = true;
使用提示：DynamicDrawUsage 告诉渲染器该数据会频繁更新

最小化更新：设置needsUpdate标志，避免不必要的GPU上传

内存优化：共享几何体和材质数据

8. 调试与交互
javascript
import { Inspector } from 'three/addons/inspector/Inspector.js';
gui.add( mesh, 'count', 1, count, 1 ).name( '实例数量' );
实时调试：内置Inspector工具

参数调节：可通过GUI滑块动态调整实例数量

性能监控：方便测试不同实例数量下的性能表现

📊 技术架构
数据流
加载阶段：加载Suzanne模型几何体 → 创建实例化网格 → 设置初始位置

动画循环：计算时间 → 更新整体旋转 → 遍历所有实例更新变换 → 渲染

渲染阶段：Three.js将实例数据传递给WebGPU → GPU执行实例化绘制

性能特点
CPU负担低：大部分计算在着色器中完成

内存效率高：几何体和材质只存储一次

渲染效率高：单次绘制调用渲染所有实例

可扩展性强：轻松支持成千上万个实例

🚀 应用场景
适用场景
大规模粒子系统：雨雪、火焰、星空效果

植被渲染：草地、森林等大量重复的自然元素

建筑可视化：城市模型中的大量窗户、树木等

数据可视化：三维散点图、分子模型等

游戏开发：人群、军队、群集动物等

技术限制
实例必须共享几何体：所有实例的顶点结构必须相同

变换方式有限：主要通过矩阵变换，复杂的变形需要其他技术

WebGPU兼容性：需要较新的浏览器版本支持

内存考虑：大量实例的变换矩阵仍然需要存储

💡 学习价值
这个示例展示了：

现代Web图形编程的最佳实践

Three.js高级特性的实际应用

性能优化技巧在实时图形中的重要性

声明式着色器编程的优势

WebGPU API的实际使用方式 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示这是一个使用WebGPU和实例化渲染的Three.js示例 -->
		<title>three.js WebGPU 实例化网格演示</title>
		<!-- 字符编码：确保中文字符正确显示 -->
		<meta charset="utf-8">
		<!-- 移动端视口设置：
			 width=device-width: 宽度等于设备宽度
			 user-scalable=no: 禁止用户缩放
			 minimum-scale=1.0, maximum-scale=1.0: 固定缩放比例为1 -->
		<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>

		<!-- 页面顶部信息展示区域 -->
		<div id="info">
			<!-- Three.js官方链接：点击跳转到Three.js官网 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link">
				<!-- 通常这里会有Three.js的logo图片，通过CSS设置背景图 -->
			</a>

			<!-- 标题包装器：包含主标题和子标题 -->
			<div class="title-wrapper">
				<!-- 主标题链接：点击跳转到Three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">three.js</a>
				<!-- 子标题：显示当前示例的主题 -->
				<span>实例化渲染演示</span>
			</div>

			<!-- 详细描述信息 -->
			<small>
				通过InstancedMesh实现高效实例化渲染。<br>
				每个实例都有独立的位置和旋转，共享相同的几何体和材质。<br>
				实例数量：<span id="instance-count">1000</span>个（10×10×10排列）<br>
				使用WebGPU渲染器，支持GPU实例化渲染。
			</small>
			
			<!-- 操作提示 -->
			<div class="tips" style="margin-top: 110px;">
				<small>
					提示：<br>
					1. 可通过URL参数调整实例数量（如?5表示5×5×5=125个实例）<br>
					2. 右侧调试面板可实时调整实例数量<br>
					3. 实例颜色基于法线方向和时间的正弦波动态变化
				</small>
			</div>
		</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>

		<!-- 主JavaScript模块：包含所有3D渲染逻辑 -->
		<script type="module">

			// 导入Three.js WebGPU模块
			// WebGPU是新一代图形API，相比WebGL有更好的性能和特性支持
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js着色器语言）函数：
			// mix: 线性插值函数，用于混合两个值
			// range: 生成颜色范围
			// normalWorld: 获取世界空间中的法线向量
			// oscSine: 正弦波振荡器
			// time: 时间变量
			import { mix, range, normalWorld, oscSine, time } from 'three/tsl';
			
			// 导入调试器，用于创建实时调试面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ========== 全局变量声明 ==========
			
			// Three.js核心对象：
			let camera;      // 相机：定义观察场景的视角
			let scene;       // 场景：包含所有3D对象的容器
			let renderer;    // 渲染器：负责将3D场景渲染到2D画布上
			
			// 实例化网格对象：
			let mesh;        // 包含所有实例的网格对象
			
			// 实例数量配置：
			// 从URL查询参数获取实例密度，例如"?8"表示8×8×8排列
			// 如果没有参数则使用默认值10
			const amount = parseInt( window.location.search.slice( 1 ) ) || 10;
			
			// 计算总实例数：立方体排列，所以是amount的立方
			const count = Math.pow( amount, 3 );
			
			// 临时对象：用于计算每个实例的变换矩阵
			// 避免为每个实例都创建新的Object3D对象，提高性能
			const dummy = new THREE.Object3D();

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

			/**
			 * 初始化函数 - 整个应用的入口点
			 * 功能：创建场景、相机、渲染器，加载模型，设置事件监听
			 */
			function init() {

				// ========== 创建相机 ==========
				// 透视相机参数：
				// 60: 视野角度（FOV），单位度
				// window.innerWidth / window.innerHeight: 宽高比
				// 0.1: 近裁剪面，距离相机小于此值的物体不被渲染
				// 100: 远裁剪面，距离相机大于此值的物体不被渲染
				camera = new THREE.PerspectiveCamera( 60, window.innerWidth / window.innerHeight, 0.1, 100 );
				
				// 设置相机位置：根据实例数量动态调整，确保能看到所有实例
				camera.position.set( amount * 0.9, amount * 0.9, amount * 0.9 );
				
				// 相机看向场景原点（0,0,0）
				camera.lookAt( 0, 0, 0 );

				// ========== 创建场景 ==========
				// 场景是所有3D对象的容器，包括网格、灯光、相机等
				scene = new THREE.Scene();

				// ========== 创建材质 ==========
				// 使用基础材质，不响应光照，适合演示实例化渲染
				const material = new THREE.MeshBasicMaterial();

				// ========== 创建动态颜色效果 ==========
				// 使用TSL创建颜色范围：从纯黑色(0x000000)到纯白色(0xFFFFFF)
				const randomColors = range( new THREE.Color( 0x000000 ), new THREE.Color( 0xFFFFFF ) );

				// 设置材质颜色节点：使用TSL节点系统创建动态着色效果
				// 1. normalWorld: 获取当前像素在世界空间中的法线方向
				// 2. oscSine(time.mul(.1)): 创建基于时间的正弦波振荡
				//    - time.mul(.1): 将时间乘以0.1，减慢振荡速度
				//    - oscSine: 正弦波振荡器，输出在[-1,1]之间振荡
				// 3. mix(normalWorld, randomColors, ...): 混合函数
				//    - 将法线向量和随机颜色混合
				//    - 第三个参数是混合因子，使用正弦波振荡值
				// 最终效果：每个实例的颜色会基于其法线方向和时间的正弦波动态变化
				material.colorNode = mix( normalWorld, randomColors, oscSine( time.mul( .1 ) ) );

				// ========== 加载几何体 ==========
				// BufferGeometryLoader用于加载预处理的几何体数据
				const loader = new THREE.BufferGeometryLoader();
				
				// 加载Suzanne模型（猴子头，Three.js的经典示例模型）
				loader.load( 'models/json/suzanne_buffergeometry.json', function ( geometry ) {

					// 计算顶点法线：用于光照计算和法线贴图
					// Suzanne模型可能已经有法线数据，这里确保计算一次
					geometry.computeVertexNormals();
					
					// 缩放几何体：将原始模型缩小一半
					geometry.scale( 0.5, 0.5, 0.5 );

					// ========== 创建实例化网格 ==========
					// InstancedMesh参数：
					// 1. geometry: 共享的几何体数据
					// 2. material: 共享的材质
					// 3. count: 实例数量
					mesh = new THREE.InstancedMesh( geometry, material, count );
					
					// 设置实例矩阵的使用方式：
					// DynamicDrawUsage: 动态绘制使用，表示实例矩阵会频繁更新
					// 这告诉Three.js优化内存布局，提高更新性能
					mesh.instanceMatrix.setUsage( THREE.DynamicDrawUsage );

					// 将实例化网格添加到场景中
					scene.add( mesh );

					// ========== 创建调试界面 ==========
					// 创建"Settings"调试面板
					const gui = renderer.inspector.createParameters( 'Settings' );
					
					// 添加控制实例数量的滑块：
					// 参数1: 要控制的对象属性（mesh.count）
					// 参数2: 最小值（1个实例）
					// 参数3: 最大值（所有实例）
					// 参数4: 步长（每次调整1个实例）
					// .name(): 设置控件显示名称
					gui.add( mesh, 'count', 1, count, 1 ).name( '实例数量' );

				} );

				// ========== 创建渲染器 ==========
				// 创建WebGPU渲染器：
				// { antialias: true }: 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer( { antialias: true } );
				
				// 设置设备像素比：适配高DPI屏幕（如Retina显示器）
				// window.devicePixelRatio: 物理像素与CSS像素的比值
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环：每帧调用animate函数
				renderer.setAnimationLoop( animate );
				
				// 附加调试器到渲染器：启用实时调试功能
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild( renderer.domElement );

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

			}

			/**
			 * 窗口大小变化处理函数
			 * 当用户调整浏览器窗口大小时自动调用
			 */
			function onWindowResize() {

				// 更新相机的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵：必须调用此方法才能使新的宽高比生效
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸：使3D场景填充整个窗口
				renderer.setSize( window.innerWidth, window.innerHeight );

			}

			/**
			 * 动画循环函数
			 * 每一帧由渲染器自动调用
			 */
			function animate() {

				// 调用渲染函数
				render();

			}

			/**
			 * 渲染函数
			 * 更新所有实例的变换，然后渲染整个场景
			 * 使用async/await确保渲染完成
			 */
			async function render() {

				// 检查网格是否已加载完成
				if ( mesh ) {

					// 获取当前时间（秒）
					// Date.now()返回毫秒，乘以0.001转换为秒
					const time = Date.now() * 0.001;

					// ========== 更新整体网格旋转 ==========
					// 使用正弦函数创建平滑的旋转动画
					// time/4和time/2使不同轴的旋转速度不同，创建更复杂的运动
					mesh.rotation.x = Math.sin( time / 4 );
					mesh.rotation.y = Math.sin( time / 2 );

					// ========== 更新每个实例的变换 ==========
					
					let i = 0;  // 实例索引，从0开始
					
					// 计算偏移量：使所有实例以场景原点为中心对称排列
					// 例如amount=10时，offset=4.5，实例位置从-4.5到4.5
					const offset = ( amount - 1 ) / 2;

					// 三层嵌套循环：创建立方体排列
					for ( let x = 0; x < amount; x ++ ) {
						for ( let y = 0; y < amount; y ++ ) {
							for ( let z = 0; z < amount; z ++ ) {

								// 设置临时对象的位置
								// offset - x/y/z：使实例在x、y、z轴上对称分布
								dummy.position.set( offset - x, offset - y, offset - z );
								
								// 设置临时对象的旋转：
								// 基于实例的坐标(x,y,z)和当前时间计算旋转角度
								// 每个坐标分量都参与计算，创建波纹效果
								dummy.rotation.y = (
									Math.sin( x / 4 + time ) +  // x坐标的影响
									Math.sin( y / 4 + time ) +  // y坐标的影响
									Math.sin( z / 4 + time )    // z坐标的影响
								);
								
								// z轴旋转是y轴的两倍，创建更复杂的旋转
								dummy.rotation.z = dummy.rotation.y * 2;

								// 更新临时对象的变换矩阵
								// 将位置、旋转、缩放等信息组合成4x4矩阵
								dummy.updateMatrix();

								// 将计算好的矩阵设置到实例化网格中
								// setMatrixAt(索引, 矩阵): 设置指定实例的变换矩阵
								mesh.setMatrixAt( i ++, dummy.matrix );

							}
						}
					}
					
					// 更新实例矩阵：
					// 当修改了实例矩阵后，需要通知Three.js数据已更新
					// 这会触发GPU缓冲区的更新
					mesh.instanceMatrix.needsUpdate = true;

				}

				// ========== 执行渲染 ==========
				// 异步渲染场景和相机
				// WebGPU渲染是异步操作，使用await确保渲染完成
				await renderer.render( scene, camera );

			}

		</script>

	</body>
</html>