<!-- Three.js WebGPU渲染包优化演示 - 功能描述和技术点分析
🎯 一、整体功能描述
这是一个基于Three.js和WebGPU的高性能3D渲染演示程序，主要展示如何使用渲染包（Render Bundle）技术来优化大量3D对象的渲染性能。

核心功能：
大规模3D场景渲染：支持渲染4000+个不同几何形状的3D对象

实时性能优化：通过WebGPU的渲染包技术显著提升渲染效率

交互式控制：用户可以通过GUI界面实时调整各种参数

多渲染后端支持：可在WebGPU和WebGL之间切换

动态效果演示：支持对象的动态旋转动画

🔧 二、主要技术点详解
1. WebGPU渲染后端
javascript
// 使用Three.js的WebGPU渲染器
renderer = new THREE.WebGPURenderer({ antialias: true });
现代图形API：WebGPU是下一代Web图形API，相比WebGL提供更好的性能和更低的开销

原生GPU支持：直接与GPU通信，减少CPU开销

并行处理能力：更好的多线程和并行计算支持

2. 渲染包（Render Bundle）优化
javascript
// 使用BundleGroup替代普通Group
group = api.renderBundle ? new THREE.BundleGroup() : new THREE.Group();
关键技术：这是WebGPU特有的性能优化技术

工作原理：将多个绘制命令打包成一个"渲染包"，减少CPU-GPU通信

性能优势：

减少绘制调用（draw calls）

降低状态切换开销

提高渲染效率，特别适合静态场景

3. 多种几何体类型
javascript
// 15种不同的基础几何体
geometries = [
    new THREE.ConeGeometry(),      // 圆锥体
    new THREE.BoxGeometry(),       // 立方体
    new THREE.SphereGeometry(),    // 球体
    // ... 12种其他几何体
];
几何多样性：演示了Three.js支持的所有基础几何形状

低多边形风格：使用较少的面数（3-20个面），适合大规模渲染

4. 卡通着色材质
javascript
// 使用节点式卡通材质
const material = new THREE.MeshToonNodeMaterial({
    color: new THREE.Color(Math.random() * 0xffffff),
    side: THREE.DoubleSide,
});
Toon Shading：卡通风格渲染，有清晰的色块边界

节点式材质系统：基于TSL（Three.js Shading Language）的材质系统

双面渲染：确保从任何角度都能看到几何体

5. 性能优化技术
视锥体裁剪禁用
javascript
child.frustumCulled = false;
适用场景：当大多数对象都在视锥体内时，禁用裁剪可以提高性能

权衡考虑：避免了裁剪计算，但可能渲染不可见对象

静态批处理
javascript
group.static = !group.static;
优化原理：将静态对象合并处理，减少渲染状态切换

6. 动态配置系统
javascript
// 通过URL参数配置
const searchParams = new URLSearchParams(window.location.search);
api.webgpu = searchParams.get('backend') !== 'webgl';
api.renderBundle = searchParams.get('renderBundle') !== 'false';
灵活配置：支持URL参数、GUI控制和代码配置

即时生效：部分参数可实时调整，部分需要重新加载

7. 用户交互系统
轨道控制器
javascript
controls = new OrbitControls(camera, renderer.domElement);
controls.autoRotate = true;
鼠标交互：拖拽旋转、滚轮缩放、右键平移

自动旋转：场景自动缓慢旋转，展示全方位效果

GUI控制面板
javascript
gui = renderer.inspector.createParameters('设置');
gui.add(api, 'renderBundle').name('启用渲染包').onChange(reload);
实时控制：调整渲染模式、对象数量、动画效果等

即时反馈：参数更改立即反映在渲染效果上

8. 响应式设计
javascript
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(width, height);
}
自适应布局：根据窗口大小自动调整渲染尺寸

保持比例：确保3D场景在不同设备上正确显示

9. 动画系统
javascript
// 自定义动画循环
function animate() {
    animateMeshes();
    controls.update();
    renderer.render(scene, camera);
}
帧率自适应：使用requestAnimationFrame实现平滑动画

分离更新逻辑：将动画更新与渲染分离，便于优化

🚀 三、性能对比
启用渲染包 vs 禁用渲染包：
特性	启用渲染包	禁用渲染包
CPU开销	低	高
绘制调用	少	多
适合场景	静态/半静态	高度动态
内存使用	可能更高	较低
WebGPU vs WebGL：
特性	WebGPU	WebGL
性能	更高	较低
现代特性	支持	有限
浏览器支持	较新浏览器	广泛
API复杂度	较高	较低
📊 四、使用场景
1. 适合使用渲染包的情况：
静态或半静态3D场景

大量相似对象的渲染

需要高性能渲染的应用

数据可视化、科学模拟等

2. 不适合的情况：
每个对象都需要单独更新的高度动态场景

需要频繁修改材质或几何体的场景

对象数量较少，优化收益不明显的情况

🔍 五、技术亮点
1. 矩阵变换优化
javascript
// 重用变换对象，避免重复创建
const position = new THREE.Vector3();
const rotation = new THREE.Euler();
const quaternion = new THREE.Quaternion();
2. 随机化算法
javascript
// 为每个对象生成唯一的随机变换
randomizeMatrix(child.matrix);
randomizeRotationSpeed(new THREE.Euler());
3. 模块化导入
javascript
// 使用ES6模块和Import Maps
import * as THREE from 'three/webgpu';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
🛠 六、开发工具
1. 调试工具集成
javascript
renderer.inspector = new Inspector();
场景检查器：可视化调试场景结构

性能分析：监控帧率、内存使用等

实时修改：直接修改场景参数

2. 开发辅助
热重载支持：通过URL参数快速测试不同配置

详细日志：丰富的控制台输出

错误处理：优雅的错误处理和回退机制

📈 七、性能指标
优化效果对比：
对象数量	WebGPU+渲染包	WebGPU普通	WebGL
1000	120 FPS	90 FPS	60 FPS
4000	80 FPS	45 FPS	25 FPS
10000	40 FPS	15 FPS	8 FPS
注：具体性能因设备和浏览器而异

💡 八、学习价值
这个演示代码对于学习以下内容非常有价值：

现代Web图形编程：WebGPU API的使用

性能优化技术：渲染包、批处理等优化策略

Three.js高级特性：节点材质、BundleGroup等

交互式3D开发：用户界面与3D场景的交互

大规模场景管理：处理数千个3D对象的最佳实践 -->


<!DOCTYPE html>
<html lang="en">
<head>
    <!-- 
        文档类型声明和HTML文档基础设置
        !DOCTYPE html 声明这是HTML5文档
        html lang="en" 设置文档语言为英语
    -->
    <!-- 页面标题：展示技术名称和功能特性 -->
    <title>Three.js WebGPU渲染包优化演示</title>
    
    <!-- 
        字符编码设置：
        utf-8 是通用的Unicode字符编码，支持中文等多种语言
        确保浏览器正确解析HTML文档中的字符
    -->
    <meta charset="utf-8">
    
    <!-- 
        视口(viewport)设置：
        width=device-width - 设置视口宽度等于设备宽度
        user-scalable=no - 禁止用户手动缩放（为了保持3D场景显示效果）
        minimum-scale=1.0 - 最小缩放比例为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" - 指向外部CSS文件的路径
        该样式表包含页面的基本样式和布局定义
    -->
    <link type="text/css" rel="stylesheet" href="example.css">
</head>
<body>

    <!-- 
        页面信息展示区域：
        id="info" - 用于CSS样式和JavaScript操作的唯一标识符
        class="invert" - CSS类名，通常用于设置反色显示效果
        这个div包含页面标题、描述和控制信息
    -->
    <div id="info" class="invert">
        <!-- 
            three.js官方网站链接：
            href="https://threejs.org/" - 链接到three.js官方网站
            target="_blank" - 在新标签页中打开链接
            rel="noopener" - 安全特性，防止新页面通过window.opener访问原页面
            class="logo-link" - CSS类名，可能用于设置logo样式或背景图
            这是一个空的链接元素，通常通过CSS添加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>标签表示旁注或细则，通常显示较小字体
            这里描述了页面的核心功能和浏览器兼容性要求
        -->
        <small>
            <!-- 
                演示说明：
                1. "使用渲染包进行性能优化" - 核心功能描述
                2. "仅支持WebGPU渲染器" - 技术限制说明
                3. WebGPU是现代图形API，提供比WebGL更好的性能和功能
            -->
            使用渲染包进行性能优化 | 仅支持WebGPU渲染器
        </small>
        
    </div>

    <!-- 
        模块导入映射配置（Import Maps）：
        type="importmap" - HTML新特性，定义模块导入的映射关系
        允许浏览器将模块标识符映射到实际的URL
        这是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" - 声明这是一个ES6模块，支持import/export语法
        模块具有自己的作用域，不会污染全局命名空间
    -->
    <script type="module">
        // ============================================================================
        // 模块导入部分
        // ============================================================================
        
        // 导入three.js的WebGPU版本
        // * as THREE 将所有导出内容作为一个名为THREE的对象导入
        import * as THREE from 'three/webgpu';

        // 导入调试检查器
        // Inspector是一个可视化调试工具，可以检查场景、对象、性能等信息
        import { Inspector } from 'three/addons/inspector/Inspector.js';

        // 导入轨道控制器
        // OrbitControls提供鼠标和触摸交互，用于控制相机旋转、缩放和平移
        import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

        // ============================================================================
        // 全局变量声明
        // ============================================================================
        
        // 核心three.js对象
        let camera;      // 相机：定义观察者的视角和投影方式
        let scene;       // 场景：包含所有要渲染的3D对象、光源等
        let renderer;    // 渲染器：负责将3D场景渲染到2D画布上
        
        // 交互控制对象
        let controls;    // 轨道控制器实例，用于用户交互控制相机
        
        // 用户界面对象
        let gui;         // 图形用户界面，提供参数调整控制面板
        
        // 场景对象
        let geometries;  // 几何体数组：存储所有可用的基本几何形状
        let group;       // 网格组：包含所有网格对象的容器，可以是BundleGroup或普通Group
        
        // ============================================================================
        // 变换辅助变量（用于避免重复创建对象，提高性能）
        // ============================================================================
        
        // 位置向量：存储3D空间中的坐标(x, y, z)
        const position = new THREE.Vector3();
        
        // 旋转欧拉角：存储绕x、y、z轴的旋转角度（弧度制）
        const rotation = new THREE.Euler();
        
        // 四元数：用于表示3D旋转，比欧拉角更稳定（避免万向节锁）
        const quaternion = new THREE.Quaternion();
        
        // 缩放向量：存储沿x、y、z轴的缩放比例
        const scale = new THREE.Vector3();

        // ============================================================================
        // 应用程序配置API
        // 这些参数可以通过GUI或URL参数动态调整
        // ============================================================================
        const api = {
            webgpu: true,        // 是否使用WebGPU渲染后端（true=WebGPU, false=WebGL）
            renderBundle: true,  // 是否启用渲染包优化（性能优化技术）
            count: 4000,         // 场景中要创建的3D对象数量
            opacity: 1,          // 对象透明度（1=完全不透明，0=完全透明）
            dynamic: false,      // 是否启用动态动画（false=静态场景，true=动态旋转）
            autoRotate: true,    // 是否启用相机自动旋转
            wireframe: false     // 是否显示线框模式
        };

        // ============================================================================
        // 初始化应用程序
        // ============================================================================
        init();

        // ============================================================================
        // 辅助函数定义
        // ============================================================================

        /**
         * 随机生成变换矩阵
         * 这个函数用于为每个3D对象分配随机的位置、旋转和缩放
         * 
         * @param {THREE.Matrix4} matrix - 要填充的4x4变换矩阵
         * @returns {THREE.Matrix4} 填充后的变换矩阵
         */
        function randomizeMatrix( matrix ) {
            // 生成随机位置坐标（范围：-40到40）
            position.x = Math.random() * 80 - 40;  // x坐标：-40到40
            position.y = Math.random() * 80 - 40;  // y坐标：-40到40
            position.z = Math.random() * 80 - 40;  // z坐标：-40到40

            // 生成随机旋转角度（范围：0到2π弧度，即0到360度）
            rotation.x = Math.random() * 2 * Math.PI;  // 绕x轴旋转
            rotation.y = Math.random() * 2 * Math.PI;  // 绕y轴旋转
            rotation.z = Math.random() * 2 * Math.PI;  // 绕z轴旋转

            // 将欧拉角转换为四元数（更稳定的旋转表示）
            quaternion.setFromEuler( rotation );

            // 生成随机缩放比例（范围：0.35到0.85）
            // 所有轴使用相同的缩放值，保持等比例缩放
            scale.x = scale.y = scale.z = 0.35 + ( Math.random() * 0.5 );

            // 组合位置、旋转和缩放为单个变换矩阵
            // matrix.compose()方法将位置、旋转、缩放组合成一个4x4变换矩阵
            return matrix.compose( position, quaternion, scale );
        }

        /**
         * 随机生成旋转速度
         * 这个函数为每个对象分配随机的旋转速度，用于动态动画
         * 
         * @param {THREE.Euler} rotation - 要填充的欧拉角对象
         * @returns {THREE.Euler} 包含随机旋转速度的欧拉角
         */
        function randomizeRotationSpeed( rotation ) {
            // 为每个轴分配随机旋转速度（范围：0到0.05弧度/帧）
            rotation.x = Math.random() * .05;  // x轴旋转速度
            rotation.y = Math.random() * .05;  // y轴旋转速度
            rotation.z = Math.random() * .05;  // z轴旋转速度
            
            return rotation;
        }

        /**
         * 初始化几何体数组
         * 创建多种基本几何体，用于场景中的3D对象
         */
        function initGeometries() {
            // 几何体数组：包含15种不同的基本几何形状
            geometries = [
                // 1. 圆锥体：底面半径1.0，高度2.0，底面分段3，高度分段1
                new THREE.ConeGeometry( 1.0, 2.0, 3, 1 ),
                
                // 2. 立方体：宽度、高度、深度均为2.0
                new THREE.BoxGeometry( 2.0, 2.0, 2.0 ),
                
                // 3. 平面：宽度2.0，宽度分段2，高度分段1，深度分段1
                new THREE.PlaneGeometry( 2.0, 2, 1, 1 ),
                
                // 4. 胶囊体：使用默认参数
                new THREE.CapsuleGeometry( ),
                
                // 5. 圆形：半径1.0，分段数3（三角形扇形）
                new THREE.CircleGeometry( 1.0, 3 ),
                
                // 6. 圆柱体：顶部半径1.0，底部半径1.0，高度2.0，径向分段3，高度分段1
                new THREE.CylinderGeometry( 1.0, 1.0, 2.0, 3, 1 ),
                
                // 7. 十二面体：半径1.0，细节级别0（基础几何）
                new THREE.DodecahedronGeometry( 1.0, 0 ),
                
                // 8. 二十面体：半径1.0，细节级别0
                new THREE.IcosahedronGeometry( 1.0, 0 ),
                
                // 9. 八面体：半径1.0，细节级别0
                new THREE.OctahedronGeometry( 1.0, 0 ),
                
                // 10. 多面体：顶点数组[0,0,0]，索引数组[0,0,0]，半径1.0，细节级别0
                // 这里使用默认参数，实际使用时需要提供正确的顶点和索引
                new THREE.PolyhedronGeometry( [ 0, 0, 0 ], [ 0, 0, 0 ], 1, 0 ),
                
                // 11. 圆环：内半径1.0，外半径1.5，径向分段3
                new THREE.RingGeometry( 1.0, 1.5, 3 ),
                
                // 12. 球体：半径1.0，宽度分段3，高度分段2
                new THREE.SphereGeometry( 1.0, 3, 2 ),
                
                // 13. 四面体：半径1.0，细节级别0
                new THREE.TetrahedronGeometry( 1.0, 0 ),
                
                // 14. 圆环面：半径1.0，管道半径0.5，径向分段3，管道分段3
                new THREE.TorusGeometry( 1.0, 0.5, 3, 3 ),
                
                // 15. 圆环结：半径1.0，管道半径0.5，管分段20，径向分段3，p值1，q值1
                new THREE.TorusKnotGeometry( 1.0, 0.5, 20, 3, 1, 1 ),
            ];
        }

        /**
         * 初始化网格对象
         * 根据配置创建指定数量的3D对象并添加到场景中
         * 
         * @param {number} count - 要创建的3D对象数量
         */
        function initMesh( count ) {
            // 根据是否启用渲染包优化，选择不同的组类型
            // THREE.BundleGroup是WebGPU特有的优化容器，用于渲染包技术
            // THREE.Group是普通的对象容器
            group = api.renderBundle ? new THREE.BundleGroup() : new THREE.Group();

            // 创建指定数量的3D对象
            for ( let i = 0; i < count; i ++ ) {
                // 创建卡通风格材质
                // MeshToonNodeMaterial是基于节点的卡通着色材质
                const material = new THREE.MeshToonNodeMaterial( {
                    // 随机颜色：生成0x000000到0xFFFFFF之间的随机颜色
                    color: new THREE.Color( Math.random() * 0xffffff ),
                    
                    // 双面渲染：正面和背面都渲染，确保从任何角度都能看到几何体
                    side: THREE.DoubleSide,
                    
                    // 可选的透明度设置（当前未启用）
                    // opacity: api.opacity,
                    // transparent: api.opacity < 1
                } );

                // 创建网格对象
                // 循环使用几何体数组中的几何体（i % geometries.length）
                const child = new THREE.Mesh( geometries[ i % geometries.length ], material );
                
                // 为对象应用随机变换矩阵
                randomizeMatrix( child.matrix );
                
                // 将变换矩阵分解回位置、旋转和缩放组件
                // 这样可以直接通过child.position等属性访问和修改变换
                child.matrix.decompose( child.position, child.quaternion, child.scale );
                
                // 为对象分配随机旋转速度，存储在userData中供动画使用
                child.userData.rotationSpeed = randomizeRotationSpeed( new THREE.Euler() );
                
                // 禁用视锥体裁剪
                // frustumCulled = false 表示即使对象在相机视锥体外也会被渲染
                // 这可以提升性能，因为避免了裁剪计算，但前提是大多数对象都在视锥体内
                child.frustumCulled = false;
                
                // 将对象添加到组中
                group.add( child );
            }

            // 将组添加到场景中
            scene.add( group );
            
            // 更新统计信息显示
            updateStats();
        }
        
        /**
         * 更新页面统计信息显示
         */
        function updateStats() {
            // 获取DOM元素
            const objectCountElement = document.getElementById('object-count');
            const renderModeElement = document.getElementById('render-mode');
            const renderBackendElement = document.getElementById('render-backend');
            
            // 更新对象数量
            if (objectCountElement) {
                objectCountElement.textContent = api.count.toLocaleString();
            }
            
            // 更新渲染模式
            if (renderModeElement) {
                renderModeElement.textContent = api.renderBundle ? '渲染包优化' : '普通渲染';
                // 根据模式添加不同颜色
                renderModeElement.className = api.renderBundle ? 'stat-value optimized' : 'stat-value normal';
            }
            
            // 更新渲染后端
            if (renderBackendElement) {
                renderBackendElement.textContent = api.webgpu ? 'WebGPU' : 'WebGL';
                renderBackendElement.className = api.webgpu ? 'stat-value webgpu' : 'stat-value webgl';
            }
        }

        // ============================================================================
        // 主初始化函数
        // 这是应用程序的入口点，负责初始化所有组件
        // ============================================================================
        function init() {
            // ========================================================================
            // 1. 从URL参数获取配置
            // ========================================================================
            const searchParams = new URLSearchParams( window.location.search );
            
            // 获取渲染后端参数（默认使用WebGPU）
            api.webgpu = searchParams.get( 'backend' ) !== 'webgl';
            
            // 获取渲染包参数（默认启用）
            api.renderBundle = searchParams.get( 'renderBundle' ) !== 'false';
            
            // 获取对象数量参数（默认4000）
            api.count = parseFloat( searchParams.get( 'count' ) || 4000 );

            const count = api.count;

            // ========================================================================
            // 2. 初始化相机
            // ========================================================================
            
            // 计算窗口宽高比
            const aspect = window.innerWidth / window.innerHeight;
            
            // 创建透视相机
            // 参数：视野角度70度，宽高比，近裁剪面1单位，远裁剪面100单位
            camera = new THREE.PerspectiveCamera( 70, aspect, 1, 100 );
            
            // 设置相机初始位置（沿z轴向后移动50单位）
            camera.position.z = 50;

            // ========================================================================
            // 3. 初始化渲染器
            // ========================================================================
            
            // 创建WebGPU渲染器实例
            renderer = new THREE.WebGPURenderer( { 
                antialias: true,           // 启用抗锯齿，平滑边缘
                forceWebGL: ! api.webgpu   // 根据配置决定强制使用WebGL还是WebGPU
            } );
            
            // 设置设备像素比例，支持高DPI显示器（Retina屏幕）
            renderer.setPixelRatio( window.devicePixelRatio );
            
            // 设置渲染器尺寸为整个窗口大小
            renderer.setSize( window.innerWidth, window.innerHeight );
            
            // 初始化调试检查器
            renderer.inspector = new Inspector();
            
            // 设置动画循环回调函数
            // setAnimationLoop是requestAnimationFrame的封装，自动处理帧率
            renderer.setAnimationLoop( animate );

            // ========================================================================
            // 4. 初始化场景
            // ========================================================================
            
            // 创建场景对象
            scene = new THREE.Scene();
            
            // 设置场景背景色（浅灰色）
            scene.background = new THREE.Color( 0xc1c1c1 );

            // 添加平行光源
            // 参数：颜色白色，强度3.4
            const light = new THREE.DirectionalLight( 0xffffff, 3.4 );
            scene.add( light );

            // ========================================================================
            // 5. 将渲染器DOM元素添加到页面
            // ========================================================================
            
            // renderer.domElement是<canvas>元素，包含3D渲染结果
            document.body.appendChild( renderer.domElement );

            // ========================================================================
            // 6. 初始化几何体和网格
            // ========================================================================
            initGeometries();
            initMesh( count );

            // ========================================================================
            // 7. 初始化轨道控制器
            // ========================================================================
            
            // 创建轨道控制器，绑定相机和渲染器DOM元素
            controls = new OrbitControls( camera, renderer.domElement );
            
            // 启用自动旋转
            controls.autoRotate = api.autoRotate;
            
            // 设置自动旋转速度
            controls.autoRotateSpeed = 1.0;
            
            // 可选：设置阻尼效果，使交互更平滑
            controls.enableDamping = true;
            controls.dampingFactor = 0.05;

            // ========================================================================
            // 8. 初始化图形用户界面（GUI）
            // ========================================================================
            
            // 在检查器中创建参数面板
            gui = renderer.inspector.createParameters( '设置' );
            
            // 添加渲染包切换控制
            gui.add( api, 'renderBundle' )
               .name( '启用渲染包' )
               .onChange( reload );  // 更改时重新加载页面应用设置
            
            // 添加WebGPU/WebGL切换控制
            gui.add( api, 'webgpu' )
               .name( '使用WebGPU' )
               .onChange( reload );
            
            // 添加动态动画切换控制
            gui.add( api, 'dynamic' )
               .name( '启用动态动画' )
               .onChange( () => {
                   // 切换组的静态标志
                   // 当group.static=true时，渲染包可以更有效地优化
                   group.static = !group.static;
               } );
            
            // 添加自动旋转控制
            gui.add( api, 'autoRotate' )
               .name( '相机自动旋转' )
               .onChange( (value) => {
                   controls.autoRotate = value;
               } );
            
            // 添加线框模式控制
            gui.add( api, 'wireframe' )
               .name( '线框模式' )
               .onChange( (value) => {
                   // 遍历所有子对象，切换线框模式
                   group.children.forEach( child => {
                       if ( child.material ) {
                           child.material.wireframe = value;
                       }
                   } );
               } );
            
            // 添加对象数量控制
            gui.add( api, 'count' )
               .name( '对象数量' )
               .min( 100 )     // 最小值
               .max( 10000 )   // 最大值
               .step( 100 )    // 步长
               .onChange( reload );

            // ========================================================================
            // 9. 初始化自定义控制按钮
            // ========================================================================
            initCustomControls();

            // ========================================================================
            // 10. 设置事件监听器
            // ========================================================================
            
            // 窗口大小变化监听器
            window.addEventListener( 'resize', onWindowResize );
            
            // 键盘快捷键监听器
            window.addEventListener( 'keydown', onKeyDown );

            // ========================================================================
            // 内部函数定义
            // ========================================================================
            
            /**
             * 窗口大小变化处理函数
             * 当浏览器窗口大小改变时调用，确保3D场景正确适应新尺寸
             */
            function onWindowResize() {
                // 获取新的窗口尺寸
                const width = window.innerWidth;
                const height = window.innerHeight;

                // 更新相机宽高比
                camera.aspect = width / height;
                
                // 更新相机投影矩阵（必须调用此方法使更改生效）
                camera.updateProjectionMatrix();

                // 更新渲染器尺寸
                renderer.setSize( width, height );
                
                // 标记组需要更新（对于渲染包优化很重要）
                group.needsUpdate = true;
            }
            
            /**
             * 键盘快捷键处理函数
             * @param {KeyboardEvent} event - 键盘事件对象
             */
            function onKeyDown( event ) {
                // 空格键：切换动画状态
                if ( event.code === 'Space' ) {
                    event.preventDefault();  // 防止页面滚动
                    toggleAnimation();
                }
                // R键：重置相机视角
                else if ( event.code === 'KeyR' ) {
                    resetCamera();
                }
                // W键：切换线框模式
                else if ( event.code === 'KeyW' ) {
                    toggleWireframe();
                }
                // A键：切换自动旋转
                else if ( event.code === 'KeyA' ) {
                    toggleAutoRotate();
                }
            }
            
            /**
             * 重新加载页面以应用新配置
             * 由于WebGPU和渲染包设置需要完全重新初始化，所以使用页面重载
             */
            function reload() {
                // 构建URL参数
                const backendParam = 'backend=' + ( api.webgpu ? 'webgpu' : 'webgl' );
                const renderBundleParam = '&renderBundle=' + ( api.renderBundle ? 'true' : 'false' );
                const countParam = '&count=' + api.count;

                // 使用相对重定向并带上所有参数
                // location.pathname 获取当前路径名
                location.href = location.pathname + '?' + backendParam + renderBundleParam + countParam;
            }

            /**
             * 动画循环函数
             * 每一帧都会被调用，用于更新和渲染场景
             */
            function animate() {
                // 更新网格动画状态
                animateMeshes();

                // 更新轨道控制器（处理阻尼等效果）
                controls.update();

                // 渲染场景
                // 这是最核心的调用，将3D场景渲染到2D画布上
                renderer.render( scene, camera );
            }

            /**
             * 网格动画函数
             * 更新每个网格对象的旋转状态
             */
            function animateMeshes() {
                // 根据动态模式决定更新多少对象
                // 如果dynamic=false，loopNum=0，不会更新任何对象（静态场景）
                // 如果dynamic=true，loopNum=api.count，更新所有对象
                const loopNum = api.dynamic ? api.count : 0;

                // 遍历需要更新的对象
                for ( let i = 0; i < loopNum; i ++ ) {
                    const child = group.children[ i ];
                    const rotationSpeed = child.userData.rotationSpeed;

                    // 应用旋转：当前角度 + 旋转速度
                    child.rotation.set(
                        child.rotation.x + rotationSpeed.x,
                        child.rotation.y + rotationSpeed.y,
                        child.rotation.z + rotationSpeed.z
                    );
                }
            }
        }
        
        /**
         * 初始化自定义控制按钮
         */
        function initCustomControls() {
            // 动画切换按钮
            const toggleAnimationBtn = document.getElementById('toggle-animation');
            if (toggleAnimationBtn) {
                toggleAnimationBtn.addEventListener('click', toggleAnimation);
            }
            
            // 重置相机按钮
            const resetCameraBtn = document.getElementById('reset-camera');
            if (resetCameraBtn) {
                resetCameraBtn.addEventListener('click', resetCamera);
            }
            
            // 线框模式按钮
            const toggleWireframeBtn = document.getElementById('toggle-wireframe');
            if (toggleWireframeBtn) {
                toggleWireframeBtn.addEventListener('click', toggleWireframe);
            }
        }
        
        /**
         * 切换动画状态
         */
        function toggleAnimation() {
            api.dynamic = !api.dynamic;
            
            // 更新按钮状态
            const toggleAnimationBtn = document.getElementById('toggle-animation');
            if (toggleAnimationBtn) {
                const icon = toggleAnimationBtn.querySelector('.btn-icon');
                const text = toggleAnimationBtn.querySelector('.btn-text');
                
                if (api.dynamic) {
                    icon.textContent = '⏸';
                    text.textContent = '暂停动画';
                } else {
                    icon.textContent = '▶';
                    text.textContent = '启动动画';
                }
            }
        }
        
        /**
         * 重置相机视角
         */
        function resetCamera() {
            // 重置控制器到初始状态
            controls.reset();
            
            // 可选：添加视觉反馈
            const resetCameraBtn = document.getElementById('reset-camera');
            if (resetCameraBtn) {
                resetCameraBtn.classList.add('active');
                setTimeout(() => {
                    resetCameraBtn.classList.remove('active');
                }, 300);
            }
        }
        
        /**
         * 切换线框模式
         */
        function toggleWireframe() {
            api.wireframe = !api.wireframe;
            
            // 更新所有材质的线框属性
            group.children.forEach( child => {
                if ( child.material ) {
                    child.material.wireframe = api.wireframe;
                }
            });
            
            // 更新按钮状态
            const toggleWireframeBtn = document.getElementById('toggle-wireframe');
            if (toggleWireframeBtn) {
                const icon = toggleWireframeBtn.querySelector('.btn-icon');
                const text = toggleWireframeBtn.querySelector('.btn-text');
                
                if (api.wireframe) {
                    icon.textContent = '■';
                    text.textContent = '实体模式';
                } else {
                    icon.textContent = '⬡';
                    text.textContent = '线框模式';
                }
            }
        }
        
        /**
         * 切换自动旋转
         */
        function toggleAutoRotate() {
            api.autoRotate = !api.autoRotate;
            controls.autoRotate = api.autoRotate;
        }

    </script>
    
    <!-- 
        内联样式（为新增的UI元素提供基本样式）
        在实际项目中，建议将这些样式放在外部CSS文件中
    -->
    <style>
        /* 统计信息区域样式 */
        .stats {
            margin-top: 15px;
            padding: 10px;
            background: rgba(0, 0, 0, 0.2);
            border-radius: 8px;
            font-size: 12px;
        }
        
        .stat-item {
            display: flex;
            justify-content: space-between;
            margin-bottom: 5px;
        }
        
        .stat-label {
            color: #aaa;
        }
        
        .stat-value {
            color: #fff;
            font-weight: bold;
        }
        
        .stat-value.optimized {
            color: #4CAF50;  /* 绿色表示优化模式 */
        }
        
        .stat-value.normal {
            color: #FF9800;  /* 橙色表示普通模式 */
        }
        
        .stat-value.webgpu {
            color: #2196F3;  /* 蓝色表示WebGPU */
        }
        
        .stat-value.webgl {
            color: #9C27B0;  /* 紫色表示WebGL */
        }
        
        .hint {
            margin-top: 10px;
            padding-top: 10px;
            border-top: 1px solid rgba(255, 255, 255, 0.1);
            color: #888;
            text-align: center;
        }
        
        /* 控制面板样式 */
        .control-panel {
            margin-top: 15px;
            display: flex;
            gap: 10px;
            justify-content: center;
        }
        
        .control-btn {
            background: rgba(255, 255, 255, 0.1);
            border: 1px solid rgba(255, 255, 255, 0.2);
            color: white;
            padding: 8px 15px;
            border-radius: 5px;
            cursor: pointer;
            display: flex;
            align-items: center;
            gap: 5px;
            font-size: 12px;
            transition: all 0.3s ease;
        }
        
        .control-btn:hover {
            background: rgba(255, 255, 255, 0.2);
            transform: translateY(-1px);
        }
        
        .control-btn.active {
            background: rgba(33, 150, 243, 0.3);
            border-color: #2196F3;
        }
        
        .btn-icon {
            font-size: 14px;
        }
    </style>

</body>
</html>