<!-- Three.js WebGPU 实例Uniform技术演示 - 详细功能描述和技术分析
🎯 核心功能概述
这个示例展示了如何使用 Three.js 的 WebGPU 渲染器 和 实例Uniform技术 来高效渲染多个3D模型，每个模型可以拥有独立的外观属性（这里是颜色），同时共享相同的几何体和大部分材质属性。

简单来说：就像用同一个模具制作12个陶瓷茶壶，但给每个茶壶喷上不同的颜色釉料，并且让它们以不同的角度旋转。

📊 场景构成
组件	数量	说明
茶壶模型	12个	经典的计算机图形学测试模型
布局	4×3网格	整齐排列在3D空间中
环境贴图	1套	瑞典皇家城堡的6面环境图片
辅助网格	1个	帮助理解3D空间坐标
🔧 核心技术点详解
1. WebGPU 渲染器（下一代图形API）
javascript
// 传统方式是：new THREE.WebGLRenderer()
// 新技术是：new THREE.WebGPURenderer()
renderer = new THREE.WebGPURenderer({ antialias: true });
优势：比WebGL更高效，直接访问现代GPU功能

特点：支持并行计算、更好的内存管理

兼容性：需要现代浏览器支持

2. 实例Uniform技术（核心创新）
javascript
class InstanceUniformNode extends THREE.Node {
    update(frame) {
        const mesh = frame.object;
        this.uniformNode.value.copy(mesh.color); // 每个实例不同！
    }
}
传统问题：

通常，要渲染不同颜色的12个茶壶，需要创建12个材质实例

每次渲染都要切换材质，性能开销大

实例Uniform解决方案：

创建1个材质 + 1个自定义节点

每个茶壶实例在mesh.color属性中存储自己的颜色

渲染时，InstanceUniformNode动态更新uniform值

性能优势对比：

方法	材质数量	GPU调用	内存占用
传统方法	12个	12次切换	高
实例Uniform	1个	1次绘制	低
3. Three.js 着色器语言（TSL）
javascript
// 使用TSL节点语法构建材质
material.colorNode = instanceUniform.add(cubeTextureNode);
material.emissiveNode = instanceUniform.mul(cubeTextureNode);
声明式编程：描述"做什么"而不是"怎么做"

节点化连接：像流程图一样连接各个处理步骤

实时编译：在运行时生成优化的着色器代码

着色器计算流程：

text
实例颜色 (RGB) + 环境贴图颜色 (RGB) = 最终颜色
实例颜色 (RGB) × 环境贴图颜色 (RGB) = 自发光颜色
4. 立方体贴图环境反射
javascript
// 加载6张图片创建立方体贴图
const urls = [
    'px.jpg', 'nx.jpg', // 左右
    'py.jpg', 'ny.jpg', // 上下
    'pz.jpg', 'nz.jpg'  // 前后
];
原理：模拟真实世界的环境反射

实现：茶壶表面根据视角反射周围环境

效果：增加真实感和立体感

5. 实例化布局与动画
javascript
// 智能布局：自动排列为4×3网格
mesh.position.x = (objects.length % 4) * 200 - 300;
mesh.position.z = Math.floor(objects.length / 4) * 200 - 200;

// 平滑动画：每帧更新旋转
object.rotation.x += 0.01;
object.rotation.y += 0.005;
⚡ 性能优化技术
批量渲染优化
javascript
// 所有12个茶壶共享：
// - 同一个几何体缓冲区
// - 同一个材质
// - 同一个着色器程序
// 只有uniform值在每实例基础上变化
内存使用优化
资源类型	传统方式	本示例	节省比例
材质对象	12个	1个	91.7%
着色器程序	12套	1套	91.7%
GPU状态切换	12次	1次	91.7%
🔄 渲染管线流程
初始化阶段

text
加载资源 → 创建场景 → 设置相机 → 配置渲染器
每帧渲染循环

text
for (每个茶壶实例) {
    1. 更新实例Uniform（颜色值）
    2. 应用变换矩阵（位置/旋转）
    3. 提交绘制命令
}
GPU执行

text
顶点着色器：处理几何形状
片段着色器：计算每个像素颜色
   颜色 = 实例颜色 + 环境贴图采样
   自发光 = 实例颜色 × 环境贴图采样
🎨 视觉效果层次
基础颜色层：每个茶壶的随机颜色

环境反射层：城堡环境贴图的反射

自发光层：增强的材质表现

动画层：连续的旋转运动

📱 交互功能
鼠标拖拽旋转：观察不同角度

鼠标滚轮缩放：调整观察距离

鼠标右键平移：移动观察位置

调试面板：按特定键打开Inspector

🚀 实际应用场景
这种技术非常适合需要渲染大量相似但略有不同对象的场景：

游戏开发：大量NPC/敌人/道具

数据可视化：大量数据点的3D图表

建筑可视化：楼宇中的多个窗户/门

自然场景：森林中的树木/草地

人群模拟：大量行人的渲染

🏆 技术亮点总结
技术点	重要性	解决的问题
实例Uniform	★★★★★	高效渲染差异化实例
WebGPU渲染器	★★★★☆	下一代图形性能
TSL节点系统	★★★★☆	灵活材质定义
环境贴图	★★★☆☆	增强视觉真实感
智能布局算法	★★☆☆☆	自动排列管理
💡 学习价值
这个示例是学习现代Web 3D图形编程的绝佳案例，涵盖了：

渲染优化策略

着色器编程概念

资源管理技巧

动画实现原理

交互设计模式 -->


<!DOCTYPE html>
<html lang="en">
<head>
    <!-- 
        页面标题：描述此Three.js示例的功能
        three.js WebGPU渲染器 - 实例Uniform示例
        实例Uniform技术允许在实例化渲染中为每个实例提供不同的uniform值
    -->
    <title>three.js WebGPU渲染器 - 实例Uniform技术演示</title>
    
    <!-- 
        字符编码设置：UTF-8编码支持多语言字符显示
        确保中文和其他特殊字符能正确显示
    -->
    <meta charset="utf-8">
    
    <!-- 
        视口设置：响应式设计配置
        width=device-width: 视口宽度等于设备宽度
        user-scalable=no: 禁止用户缩放页面（为了保持3D场景最佳显示效果）
        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": 用于CSS样式和JavaScript操作的唯一标识符
        这个div包含了整个示例的信息头部
    -->
    <div id="info">
        <!-- 
            Three.js官方网站链接：
            - 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>实例Uniform技术演示</span>
        </div>

        <!-- 
            示例详细描述：
            <small>标签表示小号字体，用于辅助说明文字
            描述了这个示例的核心功能：使用实例化Uniform渲染实例化网格，每个实例可以有不同的Uniform值
        -->
        <small>
            使用实例化Uniform渲染多个茶壶模型。每个茶壶实例具有独立的颜色，通过实例Uniform技术实现个性化渲染。
        </small>
        
        <!-- 新增技术要点说明 -->
        <div class="tech-points" style="margin-top: 40px;">
            <p><strong>技术要点：</strong></p>
            <ul>
                <li>⚡ 使用Three.js WebGPU渲染器（下一代图形API）</li>
                <li>🎨 每个实例拥有独立颜色（通过InstanceUniformNode实现）</li>
                <li>🔄 实例化渲染优化性能</li>
                <li>🌍 环境贴图反射效果</li>
                <li>🛠️ 集成调试查看器（Inspector）</li>
            </ul>
        </div>
    </div>

    <!-- 
        模块导入映射配置（Import Map）：
        现代JavaScript模块导入的配置，用于定义模块别名和路径映射
        type="importmap": 指定脚本类型为模块导入映射
        这项技术允许浏览器解析模块导入时的路径别名
    -->
    <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';
    
    // 从three/tsl库导入特定的TSL函数
    // uniform(): 创建着色器uniform变量的函数
    // cubeTexture(): 创建立方体贴图节点的函数
    import { uniform, cubeTexture } from 'three/tsl';

    // 导入轨道控制器：允许用户通过鼠标/触摸控制相机视角
    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

    // 导入茶壶几何体：经典的计算机图形学测试模型
    import { TeapotGeometry } from 'three/addons/geometries/TeapotGeometry.js';

    // 导入调试查看器：用于调试Three.js场景的图形界面工具
    import { Inspector } from 'three/addons/inspector/Inspector.js';

    /**
     * 自定义节点类：InstanceUniformNode
     * =============================================
     * 这个类的核心功能是：
     * 1. 为每个渲染实例提供不同的uniform值
     * 2. 继承自THREE.Node，可以与Three.js的节点材质系统集成
     * 3. 实现实例级别的数据传递（每个茶壶不同颜色）
     * 
     * 技术原理：
     * - 在WebGL/WebGPU中，uniform通常是所有实例共享的
     * - 通过这个自定义节点，我们可以为每个实例设置不同的uniform值
     * - 这比创建多个材质实例更高效
     */
    class InstanceUniformNode extends THREE.Node {
        /**
         * 构造函数
         * @description 初始化InstanceUniformNode实例
         */
        constructor() {
            // 调用父类构造函数，指定节点输出类型为三维向量（vec3）
            // vec3类型适合存储颜色值（RGB）
            super('vec3');
            
            // 设置节点更新类型为OBJECT级别
            // NodeUpdateType.OBJECT表示这个节点会在每个对象渲染时更新
            // 这是实现每个实例不同uniform值的关键
            this.updateType = THREE.NodeUpdateType.OBJECT;
            
            // 创建一个uniform节点来存储每个实例的颜色
            // uniform()函数创建一个可以在着色器中访问的uniform变量
            // 初始值为一个新的THREE.Color对象（默认是白色）
            this.uniformNode = uniform(new THREE.Color());
        }

        /**
         * 更新方法
         * @param {Object} frame - 渲染帧相关信息对象
         * @description 在每次渲染对象时被调用，更新当前实例的uniform值
         * 
         * frame对象通常包含：
         * - object: 当前正在渲染的网格对象
         * - camera: 相机对象
         * - renderer: 渲染器对象
         * - 其他渲染状态信息
         */
        update(frame) {
            // 从frame中获取当前正在渲染的网格对象
            const mesh = frame.object;
            
            // 获取网格对象上存储的实例颜色
            // 这个color属性是在addMesh函数中设置的
            const meshColor = mesh.color;
            
            // 将网格的颜色值复制到uniform节点中
            // 这样在着色器中就能访问到这个实例特定的颜色值
            this.uniformNode.value.copy(meshColor);
        }

        /**
         * 节点设置方法
         * @param {Object} builder - 着色器构建器对象（当前未使用，所以注释掉）
         * @returns {THREE.Node} 返回uniform节点供着色器使用
         * @description 在构建着色器时被调用，返回要使用的节点
         */
        setup(/*builder*/) {
            // 返回uniformNode，这样它就会被连接到材质系统中
            return this.uniformNode;
        }
    }

    // ==================== 全局变量声明 ====================
    let camera;     // 相机对象：决定场景的观察视角
    let scene;      // 场景对象：包含所有要渲染的3D对象
    let renderer;   // 渲染器对象：负责将3D场景绘制到2D画布上
    let controls;   // 轨道控制器：用户交互控制
    
    // 存储所有茶壶对象的数组
    // 这个数组用于在动画循环中更新所有茶壶的旋转
    const objects = [];

    // ==================== 初始化函数调用 ====================
    // 页面加载后立即执行初始化
    init();

    /**
     * 初始化函数
     * @description 整个应用程序的入口点，初始化所有Three.js组件
     * 执行顺序：
     * 1. 创建HTML容器
     * 2. 设置相机
     * 3. 创建场景和添加内容
     * 4. 设置渲染器
     * 5. 设置用户交互控制器
     * 6. 设置窗口大小变化监听
     */
    function init() {
        // ---------- 步骤1：创建容器 ----------
        // 创建一个div元素作为Three.js渲染器的容器
        const container = document.createElement('div');
        // 将容器添加到页面的body中
        document.body.appendChild(container);

        // ---------- 步骤2：创建和设置相机 ----------
        // 创建透视相机（Perspective Camera）
        // 透视相机模拟人眼的视觉效果，远处的物体看起来更小
        camera = new THREE.PerspectiveCamera(
            45,  // 视野角度（Field of View, FOV）
                // 单位是度，45°是一个自然的视角
            window.innerWidth / window.innerHeight,  // 宽高比（Aspect Ratio）
                // 使用窗口的宽高比，确保渲染不拉伸
            1,   // 近裁剪面（Near Clipping Plane）
                // 距离相机多近的物体开始被渲染
            4000 // 远裁剪面（Far Clipping Plane）
                // 距离相机多远的物体不再被渲染
        );
        // 设置相机在3D空间中的位置
        // set(x, y, z): x-水平轴, y-垂直轴, z-深度轴
        camera.position.set(0, 200, 1200);  // 在场景上方200单位，向后1200单位

        // ---------- 步骤3：创建场景和添加内容 ----------
        // 创建场景对象，所有3D对象（网格、灯光等）都需要添加到场景中
        scene = new THREE.Scene();

        // 添加网格辅助线（Grid Helper）
        // 网格辅助线是一个平面网格，帮助理解3D空间的位置和尺度
        const helper = new THREE.GridHelper(
            1000,     // 网格尺寸：1000x1000单位
            40,       // 网格划分数量：40x40格
            0x303030, // 主网格线颜色：深灰色（十六进制颜色值）
            0x303030  // 次网格线颜色：深灰色
        );
        // 将网格向下移动75单位，使其位于茶壶下方
        helper.position.y = -75;
        // 将网格辅助线添加到场景中
        scene.add(helper);

        // ---------- 步骤4：创建立方体贴图（环境贴图） ----------
        // 立方体贴图（Cube Map）是一种特殊纹理，包含6个面的图像
        // 用于模拟环境反射效果，使物体看起来像是在真实环境中
        const path = 'textures/cube/SwedishRoyalCastle/';  // 贴图文件夹路径
        const format = '.jpg';  // 图片文件格式
        // 定义立方体贴图6个面的图片URL
        // 顺序：右(+x)、左(-x)、上(+y)、下(-y)、前(+z)、后(-z)
        const urls = [
            path + 'px' + format,  // 右面（positive x）
            path + 'nx' + format,  // 左面（negative x）
            path + 'py' + format,  // 上面（positive y）
            path + 'ny' + format,  // 下面（negative y）
            path + 'pz' + format,  // 前面（positive z）
            path + 'nz' + format   // 后面（negative z）
        ];

        // 使用Three.js的CubeTextureLoader加载立方体贴图
        // CubeTextureLoader会自动加载6张图片并创建立方体贴图对象
        const cTexture = new THREE.CubeTextureLoader().load(urls);

        // ---------- 步骤5：创建材质 ----------
        // 材质定义了物体的外观：颜色、纹理、反光度等
        
        // 5.1 创建实例uniform节点
        // 这个节点将为每个茶壶实例提供不同的颜色
        const instanceUniform = new InstanceUniformNode();
        
        // 5.2 创建立方体贴图节点
        // 将加载的立方体贴图转换为TSL节点，以便在节点材质中使用
        const cubeTextureNode = cubeTexture(cTexture);
        
        // 5.3 创建节点基础材质（MeshBasicNodeMaterial）
        // MeshBasicNodeMaterial是不受灯光影响的基础材质
        const material = new THREE.MeshBasicNodeMaterial();
        
        // 5.4 设置颜色节点
        // 颜色 = 实例颜色 + 立方体贴图颜色
        // .add()是TSL的加法运算，将两个节点相加
        material.colorNode = instanceUniform.add(cubeTextureNode);
        
        // 5.5 设置自发光节点
        // 自发光 = 实例颜色 × 立方体贴图颜色
        // .mul()是TSL的乘法运算，将两个节点相乘
        material.emissiveNode = instanceUniform.mul(cubeTextureNode);

        // ---------- 步骤6：创建几何体 ----------
        // 使用经典的茶壶几何体作为示例模型
        // 茶壶是计算机图形学中著名的测试模型
        const geometry = new TeapotGeometry(
            50,  // 茶壶半径大小
            18   // 细分等级（tessellation level），值越高模型越精细
        );

        // ---------- 步骤7：创建多个茶壶实例 ----------
        // 使用for循环创建12个茶壶实例
        // 每个实例共享相同的几何体和材质，但有不同的位置、旋转和实例颜色
        for (let i = 0, l = 12; i < l; i++) {
            // 调用addMesh函数创建并添加茶壶
            addMesh(geometry, material);
        }

        // ---------- 步骤8：创建和设置渲染器 ----------
        // 创建WebGPURenderer（WebGPU渲染器）
        // WebGPU是下一代图形API，比WebGL更高效
        renderer = new THREE.WebGPURenderer({
            antialias: true  // 开启抗锯齿，使边缘更平滑
        });
        // 设置设备像素比，确保在高DPI屏幕上清晰显示
        renderer.setPixelRatio(window.devicePixelRatio);
        // 设置渲染器大小为整个浏览器窗口大小
        renderer.setSize(window.innerWidth, window.innerHeight);
        // 设置动画循环，传入animate函数作为每帧回调
        renderer.setAnimationLoop(animate);
        // 附加调试查看器到渲染器，按特定快捷键可以打开调试界面
        renderer.inspector = new Inspector();
        // 将渲染器的DOM元素（canvas画布）添加到容器中
        container.appendChild(renderer.domElement);

        // ---------- 步骤9：创建用户交互控制器 ----------
        // 创建轨道控制器，允许用户：
        // 1. 鼠标左键拖拽旋转视角
        // 2. 鼠标右键拖拽平移视角
        // 3. 鼠标滚轮缩放
        controls = new OrbitControls(camera, renderer.domElement);
        // 设置相机最小缩放距离
        controls.minDistance = 400;
        // 设置相机最大缩放距离
        controls.maxDistance = 2000;

        // ---------- 步骤10：设置窗口大小变化监听 ----------
        // 当浏览器窗口大小改变时，重新调整相机和渲染器
        window.addEventListener('resize', onWindowResize);
    }

    /**
     * 添加网格对象到场景的函数
     * @param {THREE.BufferGeometry} geometry - 3D几何体（形状）
     * @param {THREE.Material} material - 材质（外观）
     * @description 创建并配置一个茶壶实例，然后添加到场景中
     */
    function addMesh(geometry, material) {
        // 创建网格对象：组合几何体和材质
        const mesh = new THREE.Mesh(geometry, material);
        
        // 为每个实例分配随机颜色
        // Math.random() * 0xffffff: 生成0到16777215之间的随机数（对应24位颜色值）
        mesh.color = new THREE.Color(Math.random() * 0xffffff);
        
        // 设置实例的位置
        // 计算x坐标：基于实例索引创建4列的网格布局
        // objects.length % 4: 获取列索引（0,1,2,3）
        // * 200: 每列间距200单位
        // - 300: 整体水平居中偏移
        mesh.position.x = (objects.length % 4) * 200 - 300;
        
        // 计算z坐标（在Three.js中，z轴通常是深度轴）
        // Math.floor(objects.length / 4): 获取行索引
        // * 200: 每行间距200单位
        // - 200: 整体深度偏移
        mesh.position.z = Math.floor(objects.length / 4) * 200 - 200;
        
        // 设置随机旋转角度（使每个茶壶朝向不同）
        // Math.random() * 200 - 100: 生成-100到100之间的随机角度
        mesh.rotation.x = Math.random() * 200 - 100;  // 绕X轴旋转
        mesh.rotation.y = Math.random() * 200 - 100;  // 绕Y轴旋转
        mesh.rotation.z = Math.random() * 200 - 100;  // 绕Z轴旋转
        
        // 将对象添加到全局对象数组中
        // 这样我们可以在动画循环中统一更新所有对象
        objects.push(mesh);
        
        // 将对象添加到场景中
        // 只有添加到场景中的对象才会被渲染
        scene.add(mesh);
    }

    /**
     * 窗口大小变化事件处理函数
     * @description 当浏览器窗口大小改变时，调整相机和渲染器以适应新尺寸
     */
    function onWindowResize() {
        // 更新相机的宽高比
        // 使用新的窗口宽高比重新计算相机的投影矩阵
        camera.aspect = window.innerWidth / window.innerHeight;
        
        // 更新相机的投影矩阵
        // 当相机参数（如宽高比）改变后，必须调用此方法更新内部矩阵
        camera.updateProjectionMatrix();
        
        // 更新渲染器的大小
        // 使渲染器画布的大小与窗口大小一致
        renderer.setSize(window.innerWidth, window.innerHeight);
    }

    /**
     * 动画循环函数
     * @description 每一帧都会被调用，更新场景状态并重新渲染
     * 这是实现动画效果的核心函数
     */
    function animate() {
        // 更新每个茶壶的旋转动画
        // 遍历objects数组中的所有茶壶实例
        for (let i = 0, l = objects.length; i < l; i++) {
            // 获取当前茶壶对象
            const object = objects[i];
            
            // 更新茶壶的旋转角度
            // 每帧增加固定角度，实现连续旋转动画
            object.rotation.x += 0.01;  // 绕X轴旋转
            object.rotation.y += 0.005; // 绕Y轴旋转（速度较慢）
            
            // 注意：这里没有更新rotation.z，所以茶壶不会绕Z轴旋转
        }
        
        // 渲染场景
        // 将3D场景通过相机视角渲染到2D画布上
        renderer.render(scene, camera);
        
        // 注意：animate函数会被持续调用（通常每秒60次）
        // 这形成了流畅的动画效果
    }

    </script>

</body>
</html>