<!-- Three.js WebGPU 批量网格渲染演示 - 代码功能与技术点详解
🎯 核心功能概述
这是一个基于Three.js WebGPU版本的高性能批量3D对象渲染演示。演示通过先进的批处理技术，在单个绘制调用中渲染数千个3D对象，充分展示了WebGPU在现代图形渲染中的性能优势。

🚀 主要功能
1. 批量实例化渲染
核心机制：使用BatchedMesh类一次性渲染大量相似但不完全相同的3D对象

性能优势：将多个独立对象的渲染合并到一次GPU绘制调用中

实例数量：支持多达20,000个实例的动态渲染

动态更新：可实时调整渲染实例数量和动态更新比例

2. 几何体复用系统
基础几何体：包含圆锥体、立方体和球体三种基础形状

实例分配：每个实例可以独立选择使用哪种几何体

随机化功能：支持一键随机重新分配所有实例的几何体类型

3. 动态动画系统
旋转动画：每个实例具有独立的随机旋转速度

动态更新控制：可配置多少实例参与动态更新（性能优化）

矩阵更新：每帧更新动态实例的变换矩阵

4. 智能渲染优化
视锥体剔除：

整体剔除：可禁用批量网格的整体剔除

逐对象剔除：为每个实例单独计算可见性

深度排序：

透明渲染排序：确保透明对象正确渲染

自定义基数排序：优化的O(n)复杂度排序算法

5. 交互式调试界面
实时参数调整：通过GUI面板动态修改所有渲染参数

渲染器切换：支持WebGPU和WebGL之间的实时切换

视觉效果控制：调整透明度、排序方式等

💡 核心技术点
1. WebGPU渲染技术
下一代图形API：利用WebGPU的现代图形管线

跨平台兼容：自动回退到WebGL以确保兼容性

高性能渲染：充分发挥现代GPU的并行计算能力

2. BatchedMesh批量渲染
javascript
// 核心批量渲染机制
const mesh = new THREE.BatchedMesh(
    geometryCount,    // 最大实例数
    vertexCount,      // 最大顶点数
    indexCount,       // 最大索引数
    material          // 共享材质
);
技术特点：

单一绘制调用：所有实例通过一次GPU调用渲染

实例数据存储：变换矩阵和颜色存储在GPU缓冲区

几何体共享：多个实例共享基础几何体数据

3. TSL着色器语言
Three.js Shading Language：Three.js的高级着色器系统

节点式编程：可视化着色器编程范式

实时材质效果：基于法向量的渐变着色效果

4. 高级排序算法
javascript
// 自定义基数排序 - 针对透明渲染优化
function sortFunction(list, camera) {
    // 深度值转换为32位整数
    const factor = (2 ** 32 - 1) / camera.far;
    // 基数排序（非比较排序，O(n)复杂度）
    radixSort(list, options);
}
排序策略：

透明物体排序：从远到近渲染（画家算法）

整数化深度：将浮点深度转换为整数，优化排序

基数排序：专门针对整数排序优化的算法

5. 视锥体剔除优化
javascript
// 两级剔除策略
mesh.frustumCulled = false;              // 禁用整体剔除
mesh.perObjectFrustumCulled = true;      // 启用逐对象剔除
剔除逻辑：

整体剔除跳过：避免错误剔除部分可见的批量网格

逐对象计算：为每个实例单独计算可见性

性能平衡：在准确性和性能之间取得平衡

6. 动态资源管理
内存预分配：预先分配足够的顶点和索引缓冲区

实例ID管理：通过ID数组高效访问所有实例

资源释放：正确的dispose()调用，避免内存泄漏

7. 交互控制系统
轨道控制器：支持鼠标/触摸的3D场景导航

自动旋转：场景缓慢自转，增强视觉效果

响应式设计：自动适应窗口大小变化

🔧 技术架构亮点
1. 模块化设计
ES6模块系统：使用import/export管理依赖

Import Maps：现代化的模块路径映射

关注点分离：渲染、控制、UI逻辑分离

2. 性能优化策略
临时对象复用：避免在动画循环中创建新对象

矩阵运算优化：使用预计算的旋转矩阵

条件更新：仅更新需要变化的实例

3. 调试与监控
内置Inspector：Three.js的调试工具集成

参数实时调整：所有效果参数可通过GUI修改

视觉反馈：不同渲染器使用不同背景色

🎮 用户体验特性
1. 直观的控制界面
实时调整：所有参数修改立即生效

范围限制：防止设置不合理值导致崩溃

中文界面：本地化的控制面板

2. 视觉效果
平滑动画：60FPS的流畅渲染

渐变色材质：基于法向量的视觉增强

自动布局：自适应不同屏幕尺寸

3. 教育价值
技术展示：清晰展示批量渲染原理

性能对比：WebGPU vs WebGL直观对比

代码可读：详尽的注释，便于学习

📊 性能指标
渲染效率：数千个对象在60FPS下流畅渲染

内存优化：共享几何体数据，减少内存占用

CPU负载：通过GPU批处理降低CPU负担

扩展性：支持从几个到上万个实例的平滑扩展

🔄 应用场景
游戏开发：大量NPC、道具、特效的渲染

数据可视化：大规模3D数据点的实时展示

建筑可视化：建筑群、室内装饰的批量渲染

科学仿真：粒子系统、分子结构的可视化

教育演示：计算机图形学教学示例

🚀 技术栈总结
前端框架：原生JavaScript + ES6模块

图形引擎：Three.js r162+ (WebGPU版本)

渲染后端：WebGPU (优先) / WebGL (回退)

着色器语言：Three.js TSL (Three.js Shading Language)

UI控制：Three.js Inspector GUI

算法优化：基数排序 + 视锥体剔除 -->


<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <!-- 
    页面标题：Three.js WebGPU 批量网格演示
    这是一个展示使用Three.js WebGPU版本进行批量网格渲染的示例页面，
    批量网格技术允许一次性渲染大量相似的3D对象，显著提升渲染性能。
    -->
    <title>Three.js WebGPU 批量网格渲染演示</title>
    
    <!-- 字符编码设置为UTF-8，支持中文字符 -->
    <meta charset="utf-8">
    
    <!-- 
    视口设置：
    - width=device-width：视口宽度等于设备宽度
    - user-scalable=no：禁止用户手动缩放页面
    - 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样式表，用于页面布局和美化 -->
    <link type="text/css" rel="stylesheet" href="example.css">
</head>
<body>

    <!-- 
    页面顶部信息区域：包含logo、标题和简要描述
    id="info" 用于CSS样式和JavaScript操作
    -->
    <div id="info">
        <!-- 
        three.js官方logo链接：
        - href: 指向three.js官方网站
        - target="_blank": 在新标签页打开链接
        - rel="noopener": 安全设置，防止新页面访问原页面的window.opener
        - 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>标签表示较小的文本
        描述：这是一个展示批量网格渲染技术的示例，通过批处理技术可以高效渲染大量3D对象
        -->
        <small>使用批处理技术高效渲染大量3D对象，展示WebGPU的性能优势</small>

    </div>

    <!-- 
    导入映射(Import Map)配置：
    定义JavaScript模块导入的路径映射，使浏览器知道从哪里加载模块
    这个配置是ES6模块系统的一部分，用于解决模块路径问题
    -->
    <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版本的所有功能
        // THREE对象包含所有的Three.js类和方法
        import * as THREE from 'three/webgpu';

        // 导入调试检查器(Inspector)，用于创建参数面板
        // Inspector提供了可视化的调试界面
        import { Inspector } from 'three/addons/inspector/Inspector.js';

        // 导入轨道控制器(OrbitControls)，用于鼠标/触摸控制相机旋转、平移和缩放
        // 这是Three.js中最常用的相机控制器之一
        import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
        
        // 导入基数排序函数(radixSort)，用于透明物体的深度排序
        // 基数排序是一种非比较排序算法，特别适合整数排序
        import { radixSort } from 'three/addons/utils/SortUtils.js';

        // 导入TSL着色器节点：
        // - normalView: 视图空间中的法向量
        // - directionToColor: 将方向向量转换为颜色
        // - diffuseColor: 漫反射颜色
        import { normalView, directionToColor, diffuseColor } from 'three/tsl';

        // ==============================================
        // 全局变量声明
        // ==============================================
        
        // 核心Three.js对象
        let camera, scene, renderer;
        
        // 控制对象
        let controls;       // 轨道控制器实例
        let gui;            // 调试面板(GUI)实例
        
        // 3D对象
        let geometries;     // 几何体数组，存储不同的几何形状
        let mesh;           // 批量网格(BatchedMesh)实例
        let material;       // 材质实例
        
        // 数据存储
        const ids = [];     // 存储所有实例ID的数组，用于快速访问每个实例

        // 矩阵操作临时变量
        // 用于避免在动画循环中重复创建对象，提高性能
        const matrix = new THREE.Matrix4();

        // 变换操作临时变量
        // 这些变量用于分解和组合变换矩阵
        const position = new THREE.Vector3();   // 位置向量
        const rotation = new THREE.Euler();     // 欧拉角（旋转）
        const quaternion = new THREE.Quaternion(); // 四元数（旋转，避免万向节锁）
        const scale = new THREE.Vector3();      // 缩放向量

        // ==============================================
        // 常量定义
        // ==============================================
        
        // 最大几何体数量限制，防止创建过多实例导致性能问题
        const MAX_GEOMETRY_COUNT = 20000;

        // ==============================================
        // 配置对象(API)
        // ==============================================
        
        // 这个对象的所有属性都可以通过调试面板进行修改
        // 用于实时调整演示效果
        const api = {
            // 渲染器设置
            webgpu: true,           // 是否使用WebGPU渲染器（true使用WebGPU，false使用WebGL）
            
            // 实例数量设置
            count: 512,             // 总共创建的实例数量（最大不超过MAX_GEOMETRY_COUNT）
            dynamic: 16,            // 动态更新的实例数量（只有这些实例会在每帧更新变换）
            
            // 渲染优化设置
            sortObjects: true,              // 是否对物体进行深度排序（对透明渲染很重要）
            perObjectFrustumCulled: true,   // 是否启用逐对象视锥体剔除（移除视野外的对象）
            opacity: 1,                     // 材质透明度（1为不透明，0为完全透明）
            useCustomSort: true,            // 是否使用自定义排序函数（使用基数排序算法）
            
            // 功能函数
            randomizeGeometry: ()=>{        // 随机化几何体类型的函数
                // 遍历所有实例，为每个实例随机分配一个几何体类型
                for ( let i = 0; i < api.count; i ++ ) {
                    // setGeometryIdAt: 设置指定实例的几何体ID
                    // Math.floor(Math.random() * geometries.length): 生成0到几何体数量-1的随机整数
                    mesh.setGeometryIdAt( i, Math.floor( Math.random() * geometries.length ) );
                }
            }
        };

        // ==============================================
        // 程序初始化
        // ==============================================
        
        // 调用初始化函数，启动整个应用
        init();

        // ==============================================
        // 工具函数定义
        // ==============================================

        /**
         * 生成随机变换矩阵
         * @param {THREE.Matrix4} matrix - 要填充的矩阵对象
         * @returns {THREE.Matrix4} 填充了随机变换的矩阵
         * 
         * 这个函数创建一个随机的位置、旋转和缩放，然后组合成变换矩阵
         * 用于初始化每个实例的随机位置和姿态
         */
        function randomizeMatrix( matrix ) {
            // 生成随机位置：在-20到20的范围内
            position.x = Math.random() * 40 - 20;  // X轴位置：-20到20
            position.y = Math.random() * 40 - 20;  // Y轴位置：-20到20
            position.z = Math.random() * 40 - 20;  // Z轴位置：-20到20

            // 生成随机旋转：绕各轴旋转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.5到1.0的范围内
            scale.x = scale.y = scale.z = 0.5 + ( Math.random() * 0.5 );

            // 将位置、旋转（四元数）和缩放组合成变换矩阵
            // matrix.compose()是Three.js中组合变换的标准方法
            return matrix.compose( position, quaternion, scale );
        }

        /**
         * 生成随机旋转速度
         * @param {THREE.Euler} rotation - 要填充的欧拉角对象
         * @returns {THREE.Euler} 包含随机旋转速度的欧拉角
         * 
         * 这个函数为每个实例生成微小的随机旋转速度
         * 用于在动画中让实例缓慢旋转
         */
        function randomizeRotationSpeed( rotation ) {
            // 每个轴的旋转速度在0到0.01弧度/帧之间
            rotation.x = Math.random() * 0.01;  // X轴旋转速度
            rotation.y = Math.random() * 0.01;  // Y轴旋转速度
            rotation.z = Math.random() * 0.01;  // Z轴旋转速度
            return rotation;
        }

        /**
         * 初始化几何体数组
         * 
         * 创建三种基本几何体，这些几何体会被批量网格复用：
         * 1. 圆锥体(ConeGeometry)
         * 2. 立方体(BoxGeometry)
         * 3. 球体(SphereGeometry)
         * 
         * 这些几何体被添加到批量网格中，每个实例可以引用其中一个
         */
        function initGeometries() {
            geometries = [
                // 圆锥体：底面半径1.0，高度2.0
                new THREE.ConeGeometry( 1.0, 2.0 ),
                // 立方体：宽度、高度、深度都是2.0
                new THREE.BoxGeometry( 2.0, 2.0, 2.0 ),
                // 球体：半径1.0，水平分段数16，垂直分段数8
                new THREE.SphereGeometry( 1.0, 16, 8 ),
            ];
        }

        /**
         * 创建材质函数
         * @returns {THREE.MeshBasicNodeMaterial} 创建或返回现有的材质
         * 
         * 使用Three.js Shading Language(TSL)创建自定义材质
         * 材质效果：基于法向量方向着色，创建渐变效果
         */
        function createMaterial() {
            // 如果材质不存在，则创建新材质（单例模式）
            if ( ! material ) {
                // 创建节点材质，支持TSL着色器节点
                material = new THREE.MeshBasicNodeMaterial();
                
                // 设置材质输出节点：
                // 1. normalView: 视图空间中的法向量
                // 2. directionToColor(normalView): 将法向量转换为颜色（RGB对应XYZ）
                // 3. .y: 取Y分量（垂直方向）
                // 4. .add(0.5): 将范围从[-1,1]调整到[-0.5,1.5]，然后clamp到[0,1]
                // 5. diffuseColor.mul(...): 与漫反射颜色相乘
                material.outputNode = diffuseColor.mul( directionToColor( normalView ).y.add( 0.5 ) );
            }
            return material;
        }

        /**
         * 清理函数：移除并释放现有网格
         * 
         * 在创建新网格之前，需要清理旧的网格资源
         * 防止内存泄漏和重复添加
         */
        function cleanup() {
            if ( mesh ) {
                // 从父级（场景）中移除网格
                mesh.parent.remove( mesh );

                // 如果网格有dispose方法，调用它释放GPU资源
                // dispose是Three.js中释放WebGL/WebGPU资源的标准方法
                if ( mesh.dispose ) {
                    mesh.dispose();
                }
            }
        }

        /**
         * 初始化网格函数
         * 
         * 这是创建或重新创建网格的主要入口点
         * 当配置改变（如实例数量变化）时调用
         */
        function initMesh() {
            cleanup();          // 清理现有网格
            initBatchedMesh();  // 创建新的批量网格
        }

        /**
         * 初始化批量网格(BatchedMesh)
         * 
         * BatchedMesh是Three.js中用于批量渲染的核心类
         * 它允许将多个几何体实例合并到一次绘制调用中
         * 显著提升渲染大量相似对象的性能
         */
        function initBatchedMesh() {
            // 从配置中获取几何体数量
            const geometryCount = api.count;
            
            // 预分配顶点和索引缓冲区大小
            // 这里使用估算值：每个几何体类型最多512个顶点和1024个索引
            const vertexCount = geometries.length * 512; // 顶点总数估算
            const indexCount = geometries.length * 1024;  // 索引总数估算

            // 创建临时变量用于矩阵操作
            const euler = new THREE.Euler();          // 用于旋转速度的欧拉角
            const matrix = new THREE.Matrix4();       // 用于初始变换的矩阵
            
            // 创建BatchedMesh实例
            // 参数：最大实例数，最大顶点数，最大索引数，材质
            mesh = new THREE.BatchedMesh( geometryCount, vertexCount, indexCount, createMaterial() );
            
            // 在网格的用户数据中存储旋转速度
            // userData是Three.js对象中用于存储自定义数据的标准属性
            mesh.userData.rotationSpeeds = [];

            // 禁用整个网格的视锥体剔除
            // 因为批量网格中的每个实例都有自己的位置，整体剔除可能不正确
            // 我们使用perObjectFrustumCulled进行逐实例剔除
            mesh.frustumCulled = false;

            // 清空实例ID数组
            ids.length = 0;

            // 将几何体添加到批量网格中，并获取几何体ID
            // 这些ID用于后续为实例指定几何体类型
            const geometryIds = [
                mesh.addGeometry( geometries[ 0 ] ),  // 圆锥体ID
                mesh.addGeometry( geometries[ 1 ] ),  // 立方体ID
                mesh.addGeometry( geometries[ 2 ] ),  // 球体ID
            ];
            
            // 循环创建所有实例
            for ( let i = 0; i < api.count; i ++ ) {
                // 1. 添加新实例，并获取实例ID
                // 使用取模运算循环分配几何体类型：圆锥体、立方体、球体...
                const id = mesh.addInstance( geometryIds[ i % geometryIds.length ] );
                
                // 2. 设置实例的变换矩阵（位置、旋转、缩放）
                mesh.setMatrixAt( id, randomizeMatrix( matrix ) );
                
                // 3. 设置实例的颜色（随机颜色）
                mesh.setColorAt( id, new THREE.Color( Math.random() * 0xffffff ) );

                // 4. 创建并存储旋转速度矩阵
                const rotationMatrix = new THREE.Matrix4();
                // 将随机旋转速度转换为旋转矩阵
                rotationMatrix.makeRotationFromEuler( randomizeRotationSpeed( euler ) );
                // 将旋转矩阵存储到用户数据中
                mesh.userData.rotationSpeeds.push( rotationMatrix );

                // 5. 将实例ID存储到数组中，便于后续访问
                ids.push( id );
            }

            // 将批量网格添加到场景中
            scene.add( mesh );
        }

        /**
         * 主初始化函数
         * @param {boolean} forceWebGL - 是否强制使用WebGL渲染器
         * 
         * 这是整个应用的入口点，负责：
         * 1. 创建和配置渲染器
         * 2. 创建场景和相机
         * 3. 初始化3D对象
         * 4. 设置控制器和调试面板
         * 5. 启动动画循环
         */
        function init( forceWebGL = false ) {
            // ==============================================
            // 清理阶段（如果已经初始化过）
            // ==============================================
            
            if ( renderer ) {
                // 释放渲染器资源
                renderer.dispose();
                
                // 释放控制器资源
                controls.dispose();
                
                // 从DOM中移除渲染器的canvas元素
                document.body.removeChild( renderer.domElement );
            }

            // ==============================================
            // 相机创建与配置
            // ==============================================
            
            // 计算屏幕宽高比
            const aspect = window.innerWidth / window.innerHeight;
            
            // 创建透视相机
            // 参数：视野角度(FOV)，宽高比，近裁剪面，远裁剪面
            camera = new THREE.PerspectiveCamera( 70, aspect, 1, 100 );
            
            // 设置相机初始位置：沿Z轴向后移动30个单位
            camera.position.z = 30;

            // ==============================================
            // 渲染器创建与配置
            // ==============================================
            
            // 创建WebGPU渲染器
            // 参数：
            // - antialias: true 开启抗锯齿
            // - forceWebGL: 是否强制使用WebGL（用于切换测试）
            renderer = new THREE.WebGPURenderer( { antialias: true, forceWebGL } );
            
            // 设置设备像素比，适配高DPI屏幕（Retina显示屏）
            renderer.setPixelRatio( window.devicePixelRatio );
            
            // 设置渲染器大小为整个窗口
            renderer.setSize( window.innerWidth, window.innerHeight );
            
            // 附加调试检查器到渲染器
            renderer.inspector = new Inspector();
            
            // 设置动画循环回调函数
            // setAnimationLoop是requestAnimationFrame的Three.js封装
            renderer.setAnimationLoop( animate );

            // ==============================================
            // 场景创建与配置
            // ==============================================
            
            scene = new THREE.Scene();
            
            // 根据渲染器类型设置不同的背景色
            // WebGPU用蓝色系，WebGL用红色系，便于区分
            scene.background = forceWebGL ? new THREE.Color( 0xffc1c1 ) : new THREE.Color( 0xc1c1ff );

            // 将渲染器的canvas元素添加到页面body中
            document.body.appendChild( renderer.domElement );

            // ==============================================
            // 3D对象初始化
            // ==============================================
            
            initGeometries();  // 初始化几何体
            initMesh();        // 初始化批量网格

            // ==============================================
            // 控制器创建与配置
            // ==============================================
            
            // 创建轨道控制器
            // 参数：要控制的相机，用于监听事件的DOM元素
            controls = new OrbitControls( camera, renderer.domElement );
            
            // 启用自动旋转（场景缓慢自转）
            controls.autoRotate = true;
            
            // 设置自动旋转速度
            controls.autoRotateSpeed = 1.0;

            // ==============================================
            // 调试面板(GUI)创建与配置
            // ==============================================
            
            // 创建参数面板，标题为"设置"
            gui = renderer.inspector.createParameters( '设置' );
            
            // 添加WebGPU/WebGL切换控件
            gui.add( api, 'webgpu' )
               .name('使用WebGPU')  // 显示名称
               .onChange( () => {
                   // 当值改变时，重新初始化并切换渲染器
                   init( ! api.webgpu );
               } );
            
            // 添加实例数量控件
            gui.add( api, 'count', 1, MAX_GEOMETRY_COUNT, 1 )
               .name('实例数量')
               .onChange( initMesh );  // 数量改变时重新创建网格
            
            // 添加动态实例数量控件
            gui.add( api, 'dynamic', 0, MAX_GEOMETRY_COUNT, 1 )
               .name('动态实例数');

            // 添加透明度控件
            gui.add( api, 'opacity', 0, 1 )
               .name('透明度')
               .onChange( v => {
                   // 根据透明度值调整材质属性
                   if ( v < 1 ) {
                       // 透明材质需要启用透明和调整深度写入
                       material.transparent = true;  // 启用透明度
                       material.depthWrite = false;  // 禁用深度写入（避免透明排序问题）
                   } else {
                       // 不透明材质
                       material.transparent = false;
                       material.depthWrite = true;   // 启用深度写入
                   }
                   // 设置透明度值
                   material.opacity = v;
                   
                   // 标记材质需要更新
                   // Three.js在某些属性改变时需要这个标记
                   material.needsUpdate = true;
               } );
            
            // 添加物体排序开关
            gui.add( api, 'sortObjects' )
               .name('启用物体排序');
            
            // 添加逐对象视锥体剔除开关
            gui.add( api, 'perObjectFrustumCulled' )
               .name('逐对象视锥剔除');
            
            // 添加自定义排序开关
            gui.add( api, 'useCustomSort' )
               .name('使用自定义排序');
            
            // 添加随机化几何体按钮
            gui.add( api, 'randomizeGeometry' )
               .name('随机化几何体类型');

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

            /**
             * 窗口大小变化处理函数
             * 当浏览器窗口大小改变时，调整相机和渲染器
             */
            function onWindowResize() {
                // 获取新的窗口尺寸
                const width = window.innerWidth;
                const height = window.innerHeight;

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

                // 更新渲染器大小
                renderer.setSize( width, height );
            }

            // ==============================================
            // 动画循环函数
            // ==============================================
            
            /**
             * 主动画循环函数
             * 每一帧都会被调用（通常是60次/秒）
             * 负责：
             * 1. 更新动画状态
             * 2. 更新控制器
             * 3. 设置渲染参数
             * 4. 渲染场景
             */
            async function animate() {
                // 1. 更新网格动画（旋转）
                animateMeshes();
                
                // 2. 更新轨道控制器（处理自动旋转和用户交互）
                controls.update();

                // 3. 如果是批量网格，应用当前的渲染设置
                if ( mesh.isBatchedMesh ) {
                    // 设置是否排序物体（影响透明渲染）
                    mesh.sortObjects = api.sortObjects;
                    
                    // 设置是否启用逐对象视锥体剔除
                    mesh.perObjectFrustumCulled = api.perObjectFrustumCulled;
                    
                    // 设置自定义排序函数（如果启用）
                    mesh.setCustomSort( api.useCustomSort ? sortFunction : null );
                }

                // 4. 渲染场景
                // 这是Three.js的核心渲染调用
                // 参数：要渲染的场景，要使用的相机
                renderer.render( scene, camera );
            }

            /**
             * 网格动画更新函数
             * 更新动态实例的变换矩阵（实现旋转动画）
             */
            function animateMeshes() {
                // 计算需要更新的实例数量
                // 取配置的dynamic值和总实例数的较小值
                const loopNum = Math.min( api.count, api.dynamic );

                // 遍历需要动态更新的实例
                for ( let i = 0; i < loopNum; i ++ ) {
                    // 获取该实例的旋转速度矩阵
                    const rotationMatrix = mesh.userData.rotationSpeeds[ i ];
                    
                    // 获取该实例的ID
                    const id = ids[ i ];

                    // 获取实例当前的变换矩阵
                    mesh.getMatrixAt( id, matrix );
                    
                    // 将旋转矩阵应用到当前矩阵上
                    // 这会使实例每帧旋转一点点
                    matrix.multiply( rotationMatrix );
                    
                    // 将更新后的矩阵设置回实例
                    mesh.setMatrixAt( id, matrix );
                }
            }
        }

        // ==============================================
        // 自定义排序函数
        // ==============================================
        
        /**
         * 自定义深度排序函数
         * @param {Array} list - 要排序的实例列表
         * @param {THREE.Camera} camera - 当前相机
         * 
         * 这个函数使用基数排序算法对透明物体进行深度排序
         * 基数排序是O(n)复杂度，比快速排序的O(n log n)更快
         * 特别适合对整数（这里是转换后的深度值）进行排序
         * 
         * 透明渲染需要从后往前渲染（画家算法），所以需要深度排序
         */
        function sortFunction( list, camera ) {
            // 初始化排序选项（只初始化一次，提高性能）
            // this._options存储在排序函数对象上，避免每次调用都创建新对象
            this._options = this._options || {
                get: el => el.z,            // 获取元素深度值的方法
                aux: new Array( this.maxInstanceCount ) // 辅助数组，用于基数排序
            };

            // 获取排序选项
            const options = this._options;
            
            // 如果是透明材质，需要反向排序（从远到近）
            // 这是因为透明物体需要从后往前渲染（画家算法）
            options.reversed = this.material.transparent;

            // 将深度值转换为无符号32位整数范围
            // 这是基数排序的要求，因为基数排序对整数排序效率最高
            const factor = ( 2 ** 32 - 1 ) / camera.far; // UINT32_MAX / 最大深度值
            
            // 遍历所有实例，转换它们的深度值
            for ( let i = 0, l = list.length; i < l; i ++ ) {
                // 将深度值映射到0到UINT32_MAX的范围
                list[ i ].z *= factor;
            }

            // 使用混合基数排序算法进行排序
            // radixSort是Three.js提供的优化排序函数
            radixSort( list, options );
        }

    </script>

    <!-- 
    页面结束
    注意：Three.js的canvas元素是通过JavaScript动态添加到body中的
    -->
</body>
</html>