<!-- Three.js WebGPU 材质数组与几何分组示例 - 详细功能与技术点分析
📋 一、代码功能概述
1. 核心演示功能
这是一个Three.js示例，专门展示材质数组（Material Arrays）和几何分组（Geometry Groups）这两个高级3D渲染技术。通过两个不同几何体（平面和立方体）的实体与线框版本，直观展示如何为单个几何体的不同部分分配不同材质。

2. 视觉效果布局
左上角：线框平面（4×4网格）

左下角：实体平面（4×4网格）

右上角：线框立方体

右下角：实体立方体

3. 交互与动态特性
自动旋转的立方体展示动画效果

鼠标控制的轨道摄像机（旋转、缩放、平移）

实时切换WebGPU/WebGL渲染模式

响应式窗口适配

🔧 二、主要技术点详解
1. 几何分组（Geometry Groups）
javascript
// 平面几何体分组：按行分配不同材质
planeGeometry.addGroup(0, 6 * numFacesPerRow, 0);      // 第一行 → 材质0
planeGeometry.addGroup(6 * numFacesPerRow, 6 * numFacesPerRow, 1); // 第二行 → 材质1
planeGeometry.addGroup(12 * numFacesPerRow, 6 * numFacesPerRow, 2); // 第三行 → 材质2

// 立方体几何体分组：按面分配不同材质
boxGeometry.addGroup(0, 6, 0);   // 前面 → 材质0
boxGeometry.addGroup(12, 6, 2);  // 顶面 → 材质2
boxGeometry.addGroup(24, 6, 1);  // 左面 → 材质1
技术要点：

分组原理：将几何体的顶点索引分段，每段对应一个材质

参数含义：addGroup(start, count, materialIndex)

start：起始顶点索引

count：包含的顶点数量

materialIndex：材质数组中的索引

计算规则：每个矩形面由2个三角形组成，每个三角形3个顶点，共6个顶点索引

2. 材质数组（Material Arrays）
javascript
// 创建材质数组
const materials = [
    new THREE.MeshBasicMaterial({ color: 0xff1493, side: THREE.DoubleSide }), // 深粉色
    new THREE.MeshBasicMaterial({ color: 0x0000ff, side: THREE.DoubleSide }), // 蓝色
    new THREE.MeshBasicMaterial({ color: 0x00ff00, side: THREE.DoubleSide }), // 绿色
];

// 将材质数组传递给网格
const mesh = new THREE.Mesh(geometry, materials);
技术要点：

自动映射：Three.js根据几何分组自动将材质索引与材质数组对应

材质复用：同一个材质可以被多个分组使用（如立方体的前后两面使用相同材质）

材质类型：使用MeshBasicMaterial，不受光照影响，始终显示定义的颜色

3. WebGPU与WebGL双渲染支持
javascript
// WebGPU渲染器配置
renderer = new THREE.WebGPURenderer({
    forceWebGL,      // 切换开关：true=强制使用WebGL，false=使用WebGPU
    antialias: true, // 抗锯齿
});

// 运行时切换
gui.add(api, 'webgpu').onChange(() => {
    init(!api.webgpu); // 重新初始化以切换渲染器
});
技术要点：

渐进增强：优先使用WebGPU，若不支持则回退到WebGL

资源管理：切换时正确释放旧渲染器资源

视觉区分：不同渲染模式下使用不同的背景色

4. 线框模式实现
javascript
// 创建线框材质数组（基于实体材质颜色）
const materialsWireframe = [];
for (let index = 0; index < materials.length; index++) {
    const material = new THREE.MeshBasicMaterial({
        color: materials[index].color,
        side: THREE.DoubleSide,
        wireframe: true  // 关键参数：开启线框模式
    });
    materialsWireframe.push(material);
}
技术要点：

参数继承：线框材质继承实体材质的颜色

几何体复用：相同的几何体数据，不同的材质

视觉对比：并排展示实体和线框版本，便于理解几何结构

5. 双面渲染配置
javascript
new THREE.MeshBasicMaterial({
    color: 0xff1493,
    side: THREE.DoubleSide, // 关键：启用双面渲染
    wireframe: false/true
});
技术要点：

默认行为：Three.js默认只渲染正面（法线方向）

双面应用：对于透明或从内部可见的物体需要启用

性能影响：双面渲染会增加绘制调用

🎯 三、技术难点与解决方案
1. 顶点索引计算
难点：正确计算几何分组的起始索引和顶点数量
解决方案：

理解几何体的顶点组织结构

平面：4×4分段 = 16个矩形 = 32个三角形 = 96个顶点索引

立方体：6个面 × 2个三角形 = 12个三角形 = 36个顶点索引

2. 材质与分组映射
难点：确保材质索引与分组正确对应
解决方案：

使用清晰的命名和注释

测试每个分组的渲染结果

利用线框模式验证分组边界

3. 渲染器切换
难点：无缝切换WebGPU和WebGL
解决方案：

完整的资源清理（dispose()）

DOM元素的正确移除和添加

状态重置和重新初始化

📊 四、技术应用场景
1. 游戏开发
角色服装的不同部分使用不同材质

地形系统的多材质混合

建筑模型的门窗与墙体材质分离

2. 数据可视化
热力图的不同温度区域着色

地图的不同行政区划颜色

3D图表的多数据系列区分

3. 产品展示
汽车模型（车身、车窗、轮胎不同材质）

电子产品（外壳、屏幕、按键不同材质）

建筑设计（墙体、玻璃、屋顶不同材质）

🚀 五、性能优化建议
1. 几何分组优化
尽量减少分组数量

合并使用相同材质的分组

避免过细的几何划分

2. 材质管理
复用材质实例

使用材质共享

考虑使用材质贴图代替多材质

3. 渲染优化
根据设备能力选择合适的渲染器

合理使用抗锯齿

优化几何体复杂度

🔍 六、调试与开发技巧
1. 调试工具
使用Three.js Inspector检查几何分组

线框模式验证分组边界

控制台输出几何体信息

2. 开发流程
先创建几何体并验证结构

添加分组并测试每个分组

创建材质数组并映射到分组

添加交互和动画效果

优化性能和视觉效果

💡 七、扩展与改进方向
1. 技术扩展
结合纹理贴图使用材质数组

实现动态材质切换

添加光照和阴影效果

2. 功能增强
添加更多几何体类型

实现用户自定义分组

添加材质属性编辑功能

3. 性能提升
实现实例化渲染

添加LOD（细节层次）支持

优化内存使用 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面标题：Three.js WebGPU示例 - 材质数组与几何分组
			描述：展示如何使用Three.js的材质数组和几何组功能
		-->
		<title>Three.js WebGPU示例 - 材质数组与几何分组</title>
		<!-- 字符编码设置为UTF-8，确保中文正常显示 -->
		<meta charset="utf-8">
		<!-- 
			视口设置：
			- 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">
		<!-- 
			引入外部CSS样式表：
			- type="text/css": 指定样式表类型为CSS
			- rel="stylesheet": 定义当前文档与被链接文档的关系为样式表
			- href="example.css": 样式表文件路径
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>

	<body>
		<!-- 
			信息展示区域（id="info"）：
			用于显示页面标题、说明和Three.js链接
		-->
		<div id="info">
			<!-- 
				Three.js官方网站链接：
				- href="https://threejs.org/": 链接到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> - 材质数组示例</span>
			</div>

			<!-- 
				示例描述区域：
				- <small>标签表示较小的文本
				这里描述本示例的核心功能
			-->
			<small>
				本示例演示Three.js中的材质数组与几何分组功能。
				左侧为平面几何体（按行分配不同材质），右侧为立方体几何体（按面分配不同材质）。
				上方为线框模式，下方为实体模式。
			</small>
			

		</div>

		<!-- 
			导入映射（Import Map）配置：
			这是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>

		<!-- 
			主JavaScript模块：
			type="module"表示这是一个ES6模块，支持import/export语法
			模块内的代码在严格模式下运行，有自己的作用域
		-->
		<script type="module">
			// ========== 模块导入部分 ==========
			// 导入Three.js的WebGPU版本核心库
			// * as THREE表示将整个模块导入为THREE对象
			import * as THREE from 'three/webgpu';

			// 导入轨道控制器（OrbitControls）
			// 允许用户用鼠标控制相机旋转、缩放和平移
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入调试检查器（Inspector）
			// 用于创建GUI界面和调试工具
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ========== 全局变量声明 ==========
			// 这些变量将在多个函数中使用，因此声明为全局变量
			let renderer;     // 渲染器：负责将3D场景渲染到2D画布
			let scene;        // 场景：包含所有3D对象的容器
			let camera;       // 相机：定义观察3D场景的视角
			let controls;     // 控制器：处理用户输入，控制相机移动
			
			// 网格对象变量
			let planeMesh;              // 实体平面网格
			let boxMesh;                // 实体立方体网格
			let boxMeshWireframe;       // 线框立方体网格
			let planeMeshWireframe;     // 线框平面网格
			
			let materials;              // 材质数组：包含多个材质对象

			// API配置对象：存储应用程序的配置参数
			// 这些参数可以通过GUI界面修改
			const api = {
				webgpu: true  // 是否使用WebGPU渲染器（true=WebGPU, false=WebGL）
			};

			// ========== 初始化函数调用 ==========
			// 根据api.webgpu的值决定是否强制使用WebGL
			// !api.webgpu：如果webgpu为true，则forceWebGL为false；如果webgpu为false，则forceWebGL为true
			init( !api.webgpu );

			// ========== 函数定义部分 ==========
			
			/**
			 * 初始化函数 - 整个应用程序的入口点
			 * 负责创建和设置所有Three.js核心对象
			 * 
			 * @param {boolean} forceWebGL - 是否强制使用WebGL渲染器
			 *                               true：使用WebGL渲染器
			 *                               false：使用WebGPU渲染器（如果可用）
			 */
			function init( forceWebGL = false ) {
				// ---------- 清理阶段 ----------
				// 检查是否已经存在渲染器实例（用于热重载或重新初始化）
				if ( renderer ) {
					// 释放渲染器占用的所有资源（GPU内存、事件监听器等）
					renderer.dispose();
					
					// 释放控制器资源（移除事件监听器等）
					controls.dispose();
					
					// 从DOM中移除渲染器的画布元素
					// renderer.domElement是Three.js渲染器创建的<canvas>元素
					document.body.removeChild( renderer.domElement );
				}

				// ---------- 1. 创建渲染器 ----------
				/**
				 * 渲染器是Three.js的核心组件，负责将3D场景渲染到HTML画布中
				 * WebGPURenderer是Three.js的WebGPU渲染器实现
				 * 如果forceWebGL为true或浏览器不支持WebGPU，则回退到WebGLRenderer
				 */
				renderer = new THREE.WebGPURenderer( {
					forceWebGL,   // 强制使用WebGL的开关
					antialias: true,  // 开启抗锯齿，使边缘更平滑
				} );
				
				// 设置渲染器的尺寸为整个窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置设备像素比，适应高DPI屏幕（如Retina显示器）
				// window.devicePixelRatio返回物理像素与CSS像素的比值
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置动画循环回调函数
				// animate函数将在每一帧被调用（通常是60次/秒）
				renderer.setAnimationLoop( animate );
				
				// 附加调试器到渲染器，便于调试
				renderer.inspector = new Inspector();
				
				// 将渲染器的画布元素添加到页面body中
				// renderer.domElement是<canvas>元素，所有3D内容将渲染到这个画布上
				document.body.appendChild( renderer.domElement );

				// ---------- 2. 创建场景 ----------
				/**
				 * 场景是所有3D对象的容器
				 * 类似于一个舞台，相机和所有3D对象都在场景中
				 */
				scene = new THREE.Scene();
				
				// 设置场景背景色
				// 根据是否使用WebGL设置不同的背景色（视觉区分）
				scene.background = forceWebGL ? 
					new THREE.Color( 0x000000 ) :   // WebGL模式：纯黑色
					new THREE.Color( 0x222222 );    // WebGPU模式：深灰色

				// ---------- 3. 创建相机 ----------
				/**
				 * PerspectiveCamera（透视相机）模拟人眼的视角
				 * 参数说明：
				 * 1. fov（视野角度）：40度，值越大看到的范围越广
				 * 2. aspect（宽高比）：窗口宽度除以高度
				 * 3. near（近裁剪面）：1，距离相机小于1的物体不会被渲染
				 * 4. far（远裁剪面）：100，距离相机大于100的物体不会被渲染
				 */
				camera = new THREE.PerspectiveCamera( 
					40, 
					window.innerWidth / window.innerHeight, 
					1, 
					100 
				);
				
				// 设置相机位置（x, y, z坐标）
				// 默认放在z轴正方向10个单位的位置，看向原点(0,0,0)
				camera.position.set( 0, 0, 10 );

				// ---------- 4. 创建轨道控制器 ----------
				/**
				 * OrbitControls允许用户通过鼠标控制相机：
				 * - 左键拖拽：旋转视图
				 * - 右键拖拽：平移视图
				 * - 滚轮：缩放视图
				 * 
				 * 参数：
				 * 1. camera：要控制的相机对象
				 * 2. domElement：监听鼠标事件的DOM元素（通常是渲染器的画布）
				 */
				controls = new OrbitControls( camera, renderer.domElement );

				// ---------- 5. 创建材质数组 ----------
				/**
				 * 材质定义了几何体的外观（颜色、纹理、光泽等）
				 * 这里创建三个MeshBasicMaterial（基础网格材质）
				 * MeshBasicMaterial不受光照影响，始终显示定义的颜色
				 */
				materials = [
					// 材质0：深粉色，RGBA: 0xff1493
					new THREE.MeshBasicMaterial( { 
						color: 0xff1493,      // 材质颜色（十六进制）
						side: THREE.DoubleSide // 双面渲染，正反面都可见
					} ),
					
					// 材质1：蓝色，RGBA: 0x0000ff
					new THREE.MeshBasicMaterial( { 
						color: 0x0000ff, 
						side: THREE.DoubleSide 
					} ),
					
					// 材质2：绿色，RGBA: 0x00ff00
					new THREE.MeshBasicMaterial( { 
						color: 0x00ff00, 
						side: THREE.DoubleSide 
					} ),
				];

				// ---------- 6. 创建平面几何体并设置几何组 ----------
				/**
				 * PlaneGeometry创建平面几何体
				 * 参数说明：
				 * 1. width：平面宽度 = 1
				 * 2. height：平面高度 = 1
				 * 3. widthSegments：宽度分段数 = 4（创建4列顶点）
				 * 4. heightSegments：高度分段数 = 4（创建4行顶点）
				 * 
				 * 4x4的分段将平面划分为16个小矩形，每个矩形由2个三角形组成
				 * 总计：16个矩形 × 2个三角形 × 3个顶点 = 96个顶点索引
				 */
				const planeGeometry = new THREE.PlaneGeometry( 1, 1, 4, 4 );
				
				// 清除几何体上可能存在的任何分组
				planeGeometry.clearGroups();
				
				// 计算每行包含的面数（每个面由2个三角形组成）
				// 平面有4行，每行4个矩形，每个矩形2个三角形
				const numFacesPerRow = 4;  // 每行有4个矩形面
				
				/**
				 * geometry.addGroup(start, count, materialIndex)
				 * 为几何体添加一个分组，指定哪些顶点使用哪个材质
				 * 
				 * 参数：
				 * 1. start：起始顶点索引
				 * 2. count：包含的顶点数量
				 * 3. materialIndex：材质数组中的索引
				 * 
				 * 注意：Three.js使用索引缓冲，这里的"顶点"实际上指的是顶点索引
				 * 每个三角形有3个顶点索引，所以6个索引 = 2个三角形 = 1个矩形面
				 */
				
				// 第一行：使用材质0（深粉色）
				// 从索引0开始，包含4个矩形面 × 6个索引 = 24个索引
				planeGeometry.addGroup( 0, 6 * numFacesPerRow, 0 );
				
				// 第二行：使用材质1（蓝色）
				// 从索引24开始，同样包含24个索引
				planeGeometry.addGroup( 6 * numFacesPerRow, 6 * numFacesPerRow, 1 );
				
				// 第三行：使用材质2（绿色）
				// 从索引48开始，同样包含24个索引
				planeGeometry.addGroup( 12 * numFacesPerRow, 6 * numFacesPerRow, 2 );
				
				// 第四行：没有分配分组，将使用材质数组中的第一个材质（材质0）

				// ---------- 7. 创建立方体几何体并设置几何组 ----------
				/**
				 * BoxGeometry创建立方体几何体
				 * 参数说明：
				 * 1. width：立方体宽度 = 0.75
				 * 2. height：立方体高度 = 0.75
				 * 3. depth：立方体深度 = 0.75
				 * 
				 * 立方体有6个面，每个面由2个三角形组成，每个三角形3个顶点
				 * 总计：6个面 × 2个三角形 × 3个顶点 = 36个顶点索引
				 */
				const boxGeometry = new THREE.BoxGeometry( .75, .75, .75 );
				
				// 清除可能存在的分组
				boxGeometry.clearGroups();
				
				/**
				 * 为立方体的每个面分配不同的材质
				 * 每个面有2个三角形，共6个顶点索引
				 * 立方体顶点索引顺序：0-5前面，6-11后面，12-17顶面，18-23底面，24-29左面，30-35右面
				 */
				
				// 前面（索引0-5）：使用材质0（深粉色）
				boxGeometry.addGroup( 0, 6, 0 );
				
				// 后面（索引6-11）：使用材质0（深粉色）
				boxGeometry.addGroup( 6, 6, 0 );
				
				// 顶面（索引12-17）：使用材质2（绿色）
				boxGeometry.addGroup( 12, 6, 2 );
				
				// 底面（索引18-23）：使用材质2（绿色）
				boxGeometry.addGroup( 18, 6, 2 );
				
				// 左面（索引24-29）：使用材质1（蓝色）
				boxGeometry.addGroup( 24, 6, 1 );
				
				// 右面（索引30-35）：使用材质1（蓝色）
				boxGeometry.addGroup( 30, 6, 1 );

				// ---------- 8. 创建线框材质数组 ----------
				/**
				 * 创建与实体材质相同颜色的线框材质
				 * 线框材质将只渲染几何体的边缘
				 */
				const materialsWireframe = [];
				
				// 遍历实体材质数组，为每个颜色创建对应的线框材质
				for ( let index = 0; index < materials.length; index ++ ) {
					// 创建线框材质，继承实体材质的颜色
					const material = new THREE.MeshBasicMaterial( { 
						color: materials[ index ].color,  // 使用相同的颜色
						side: THREE.DoubleSide,           // 双面渲染
						wireframe: true                   // 关键：开启线框模式
					} );
					
					// 将线框材质添加到数组
					materialsWireframe.push( material );
				}

				// ---------- 9. 创建网格对象 ----------
				/**
				 * Mesh是Three.js中的基本3D对象，由几何体和材质组成
				 */
				
				// 实体平面网格：使用平面几何体和材质数组
				// Three.js会根据几何体的分组自动使用对应的材质
				planeMesh = new THREE.Mesh( planeGeometry, materials );
				
				// 线框平面网格：使用相同的几何体但不同的材质数组
				planeMeshWireframe = new THREE.Mesh( planeGeometry, materialsWireframe );
				
				// 线框立方体网格
				boxMeshWireframe = new THREE.Mesh( boxGeometry, materialsWireframe );
				
				// 实体立方体网格
				boxMesh = new THREE.Mesh( boxGeometry, materials );

				// ---------- 10. 设置网格位置和旋转 ----------
				// 将四个网格对象放置在不同的位置，便于观察
				
				// 实体平面网格：放置在左下方
				planeMesh.position.set( -1.5, -1, 0 );
				
				// 实体立方体网格：放置在右下方，并添加一些旋转使其看起来更立体
				boxMesh.position.set( 1.5, -0.75, 0 );
				boxMesh.rotation.set( -Math.PI / 8, Math.PI / 4, Math.PI / 4 );
				
				// 线框平面网格：放置在左上方
				planeMeshWireframe.position.set( -1.5, 1, 0 );
				
				// 线框立方体网格：放置在右上方
				boxMeshWireframe.position.set( 1.5, 1.25, 0 );
				boxMeshWireframe.rotation.set( -Math.PI / 8, Math.PI / 4, Math.PI / 4 );

				// ---------- 11. 将网格添加到场景 ----------
				// 将创建的网格对象添加到场景中，它们才会被渲染
				scene.add( planeMesh, planeMeshWireframe );  // 添加平面网格
				scene.add( boxMesh, boxMeshWireframe );      // 添加立方体网格
			}

			/**
			 * 动画循环函数
			 * 在每一帧渲染之前被调用，用于更新场景状态
			 * 这是游戏和交互式3D应用的核心循环
			 */
			function animate() {
				// 更新实体立方体的旋转角度
				// 每帧绕y轴和x轴旋转0.005弧度，实现持续旋转动画
				boxMesh.rotation.y += 0.005;  // 绕垂直轴旋转
				boxMesh.rotation.x += 0.005;  // 绕水平轴旋转
				
				// 更新线框立方体的旋转角度，与实体立方体同步
				boxMeshWireframe.rotation.y += 0.005;
				boxMeshWireframe.rotation.x += 0.005;
				
				// 调用渲染器渲染当前场景和相机视角
				renderer.render( scene, camera );
			}

			// ========== GUI界面设置 ==========
			/**
			 * 创建图形用户界面，允许用户调整参数
			 * 这里使用Three.js的Inspector创建简单的GUI
			 */
			
			// 创建参数面板，标题为"参数"
			const gui = renderer.inspector.createParameters( '参数' );
			
			// 添加WebGPU/WebGL切换开关
			// 当用户改变这个开关时，会触发onChange回调函数
			gui.add( api, 'webgpu' )
			   .name( '使用WebGPU渲染' )  // 在GUI中显示的标签
			   .onChange( () => {
					// 当开关状态改变时，重新初始化应用程序
					// 如果webgpu为true，则forceWebGL为false，反之亦然
					init( !api.webgpu );
			   } );

			// ========== 事件监听器 ==========
			
			/**
			 * 监听窗口大小变化事件
			 * 当用户调整浏览器窗口大小时，需要更新相机和渲染器的设置
			 */
			window.addEventListener( 'resize', onWindowResize );

			/**
			 * 窗口大小调整处理函数
			 * 确保3D场景始终正确适应窗口尺寸
			 */
			function onWindowResize() {
				// 获取当前窗口的宽度和高度
				const width = window.innerWidth;
				const height = window.innerHeight;

				// 更新相机的宽高比
				// 如果不更新，图像会被拉伸或压缩
				camera.aspect = width / height;
				
				// 更新相机的投影矩阵
				// 修改相机参数后必须调用此方法，否则更改不会生效
				camera.updateProjectionMatrix();

				// 更新渲染器的尺寸
				// 使画布大小与窗口大小一致
				renderer.setSize( width, height );
				
				// 注意：这里不需要调用renderer.render()
				// 因为animate函数会在下一帧自动渲染
			}
		</script>
	</body>
</html>