<!-- Three.js WebGPU BPCEM 演示 - 功能描述与技术分析
一、项目概述
这是一个基于 Three.js WebGPU 渲染器 的盒投影立方体环境映射（BPCEM） 技术演示。该演示展示了在封闭室内场景中实现高质量实时环境反射的高级渲染技术。

二、核心功能
1. 主要展示功能
BPCEM效果对比：实时切换标准环境映射和盒投影环境映射，直观展示视差校正效果

交互式3D场景：用户可通过鼠标自由控制视角（旋转、平移、缩放）

实时参数调整：通过GUI界面动态调整地面粗糙度等材质参数

物理正确的光照：使用矩形区域光模拟真实面光源

2. 场景构成
地面：200×100的反射平面，使用熔岩纹理，演示BPCEM效果

墙面：六个砖墙表面构成的封闭空间（100×100×100）

光源：两个彩色矩形区域光（左侧蓝色，右侧红色）

相机系统：主视角相机 + 立方体相机（用于环境贴图生成）

三、主要技术点
1. 核心渲染技术：盒投影立方体环境映射（BPCEM）
传统环境映射的问题
标准立方体贴图假设环境在无限远处

在有限空间内会产生错误的反射（视差误差）

反射物体会出现在错误的位置

BPCEM解决方案
通过定义投影盒（Bounding Box）来校正视差

考虑反射表面的实际位置和方向

使用 getParallaxCorrectNormal() 函数实现校正

在着色器中实时计算正确的反射向量

javascript
// BPCEM核心实现
boxProjectedMat.envNode = pmremTexture(
    renderTarget.texture, 
    getParallaxCorrectNormal(
        reflectVector, 
        vec3(200, 100, 100),  // 投影盒尺寸
        vec3(0, -50, 0)        // 投影盒中心
    )
);
2. WebGPU 渲染管线
性能优势
相比WebGL，WebGPU提供更直接的GPU控制

支持并行计算和多线程渲染

更好的内存管理和资源绑定

Three.js WebGPU实现
javascript
// 创建WebGPU渲染器
renderer = new THREE.WebGPURenderer({ antialias: true });
await renderer.init();  // 异步初始化
3. Three.js着色器语言（TSL）
节点式材质系统
声明式编程：通过连接节点构建材质

实时编译：运行时编译为WGSL/GLSL

类型安全：编译时类型检查

关键节点使用
pmremTexture()：预过滤辐射环境贴图，提供平滑的反射

bumpMap()：法线贴图，增加表面细节

uniform()：可动态调整的着色器参数

texture()：纹理采样节点

4. 实时立方体贴图生成
立方体相机系统
javascript
// 创建立方体相机
cubeCamera = new THREE.CubeCamera(1, 1000, renderTarget);

// 更新环境贴图
cubeCamera.update(renderer, scene);
工作流程
临时隐藏地面（避免自反射）

将立方体相机定位到地面位置

渲染6个方向（上、下、左、右、前、后）

生成立方体贴图纹理

重新显示地面

5. 物理正确的矩形区域光
LTC（线性变换余弦）技术
使用预计算的LTC纹理

提供物理正确的面光源照明

支持矩形区域光的精确衰减和软阴影

javascript
// 初始化LTC纹理库
THREE.RectAreaLightNode.setLTC(RectAreaLightTexturesLib.init());
矩形区域光实现
两个50×50的矩形光源

左侧蓝色光（0x9aaeff）

右侧红色光（0xf3aaaa）

使用辅助器可视化光源位置和方向

6. 高级材质系统
PBR（基于物理的渲染）材质
javascript
const boxProjectedMat = new THREE.MeshStandardNodeMaterial();
boxProjectedMat.roughnessNode = texture(rMap).mul(roughnessUniform);
boxProjectedMat.metalnessNode = float(1);
纹理处理
重复纹理：熔岩纹理水平重复2次

颜色空间管理：漫反射纹理使用sRGB颜色空间

Mipmap生成：自动生成多级纹理以提高渲染质量

7. 用户交互系统
OrbitControls（轨道控制器）
鼠标左键拖拽：旋转视角

鼠标右键拖拽：平移场景

鼠标滚轮：缩放视角

支持移动端触摸交互

GUI控制系统
盒投影效果开关

地面粗糙度实时调整（0-1范围）

基于Three.js Inspector的可扩展界面

8. 响应式设计
javascript
// 窗口大小变化处理
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
}
四、技术架构
1. 模块化设计
ES6模块导入系统

Import Map路径映射

清晰的依赖关系

2. 异步加载策略
javascript
// 并行加载纹理
const [diffuseTex, bumpTex] = await Promise.all([
    loader.loadAsync('textures/brick_diffuse.jpg'),
    loader.loadAsync('textures/brick_bump.jpg')
]);
3. 渲染优化
设备像素比适配：setPixelRatio(window.devicePixelRatio)

抗锯齿：WebGPU渲染器启用抗锯齿

Mipmap过滤：线性Mipmap线性过滤提高纹理质量

五、应用场景
1. 适用场景
室内渲染：房间、展厅、车辆内部

产品可视化：金属、玻璃等高反射材质产品

游戏开发：高质量的环境反射效果

建筑可视化：室内空间的光照和反射模拟

2. 技术优势
真实感：消除传统环境映射的视差错误

实时性：完全实时的渲染和交互

灵活性：可调整参数适应不同场景需求

现代性：基于最新的WebGPU标准

六、性能考量
1. 资源开销
立方体贴图：512×512×6面 = 1.5MB（半浮点数格式）

几何体：地面100×100分段，墙面中等复杂度

纹理：3张纹理（熔岩、砖墙漫反射、砖墙凹凸）

2. 优化建议
根据设备性能调整立方体贴图分辨率

使用纹理压缩格式

实现LOD（细节层次）系统

添加帧率监控和自适应质量

七、扩展可能性
1. 功能增强
动态物体反射（每帧更新环境贴图）

多材质支持（不同粗糙度、金属度）

实时阴影系统

后处理效果（Bloom、色调映射）

2. 交互改进
物体拾取和操作

动画系统（旋转、平移物体）

多相机视角切换

VR/AR支持

3. 场景扩展
添加更多几何体类型

室外环境支持

天气和时间系统

粒子效果 -->


<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <!-- 
        页面标题：
        three.js - 盒投影立方体环境映射演示
        WebGPU是新一代的图形API，提供比WebGL更好的性能
        BPCEM = Box Projected Cube Environment Mapping (盒投影立方体环境映射)
    -->
    <title>three.js WebGPU - 盒投影立方体环境映射(BPCEM)演示</title>
    
    <!-- 
        字符编码设置：
        UTF-8支持中文和国际字符集
    -->
    <meta charset="utf-8">
    
    <!-- 
        响应式视口设置：
        width=device-width - 宽度等于设备宽度
        user-scalable=no - 禁止用户手动缩放（为保持3D场景体验）
        minimum-scale=1.0 - 最小缩放比例
        maximum-scale=1.0 - 最大缩放比例
    -->
    <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
    
    <!-- 
        外部样式表链接：
        用于页面的基本样式，如info面板的样式等
    -->
    <link type="text/css" rel="stylesheet" href="example.css">
</head>
<body>

    <!-- 
        信息展示面板：
        这个div包含页面的标题、logo和描述信息
        id="info"用于CSS样式选择
    -->
    <div id="info">
        <!-- 
            Three.js官方网站链接：
            target="_blank" - 在新标签页打开链接
            rel="noopener" - 安全设置，防止新页面访问原页面的window对象
            class="logo-link" - 样式类，可能包含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>盒投影立方体环境映射(BPCEM)</span>
        </div>

        <!-- 
            详细描述：
            <small>标签表示小号文字
            这里解释BPCEM技术的基本概念和应用场景
        -->
        <small>
            <!-- 
                盒投影立方体环境映射技术：
                这是一种用于模拟真实环境反射的高级渲染技术。
                与传统的立方体贴图不同，BPCEM考虑了反射表面的位置和方向，
                通过"盒投影"来校正反射的视差误差，使反射效果更加真实。
                特别适用于室内场景或有边界的反射表面。
            -->
            盒投影立方体环境映射（BPCEM）技术演示。
            此技术通过校正视差误差，在有限空间内实现更准确的环境反射效果。
            常用于室内场景、车辆漆面、金属表面等需要精确反射的渲染场景。
        </small>
        
        <!-- 
            操作说明部分：
            为用户提供基本的交互操作指引
        -->
        <div class="instructions" style="margin-top: 50px;">
            <small>
                <strong>操作指南：</strong><br>
                1. 鼠标左键拖拽：旋转视角<br>
                2. 鼠标右键拖拽：平移场景<br>
                3. 鼠标滚轮：缩放视角<br>
                4. 右侧面板：切换效果和调整参数
            </small>
        </div>
        
        <!-- 
            技术要点说明：
            解释当前场景中的关键技术实现
        -->
        <div class="tech-points">
            <small>
                <strong>技术实现：</strong><br>
                • WebGPU渲染管线<br>
                • 实时立方体贴图生成<br>
                • TSL着色器节点系统<br>
                • 物理正确的矩形区域光
            </small>
        </div>
    </div>

    <!-- 
        Import Map（导入映射）：
        现代浏览器支持的功能，用于映射JavaScript模块的导入路径。
        允许开发者使用简短的模块名称，而不需要完整的相对路径。
        这在大型项目中特别有用，可以简化模块导入语句。
        
        type="importmap" - 指定此script标签的内容是导入映射配置
    -->
    <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模块
        模块中的代码具有自己的作用域，不会污染全局命名空间
        支持顶级的await语法
    -->
    <script type="module">
        // ============================================
        // 模块导入部分
        // ============================================
        
        // 导入Three.js的核心WebGPU模块
        // * as THREE表示将所有导出内容作为一个名为THREE的对象导入
        import * as THREE from 'three/webgpu';
        
        // 从TSL模块导入特定的着色器节点和函数
        // TSL是Three.js的着色器语言，提供声明式的着色器编程方式
        import { 
            bumpMap,        // 法线/凹凸贴图节点：用于根据纹理创建表面凹凸感
            float,          // 浮点数节点：在着色器图中表示浮点数值
            getParallaxCorrectNormal,  // 获取视差校正法线函数：BPCEM的核心函数
            pmremTexture,   // PMREM纹理节点：预过滤的辐射环境贴图，用于更真实的反射
            reflectVector,  // 反射向量节点：计算光线反射方向
            texture,        // 纹理节点：在着色器图中加载和使用纹理
            uniform,        // 统一变量节点：可在运行时修改的着色器参数
            vec3            // 三维向量节点：表示3D向量(x, y, z)
        } from 'three/tsl';
        
        // 导入Three.js的附加组件（addons）
        // 这些是官方提供的工具和扩展功能
        
        // Inspector：调试检查器，提供GUI界面用于调试和查看场景信息
        import { Inspector } from 'three/addons/inspector/Inspector.js';
        
        // OrbitControls：轨道控制器，实现基于鼠标的3D场景交互
        import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
        
        // RectAreaLightHelper：矩形区域光辅助器，可视化显示矩形光的位置和方向
        import { RectAreaLightHelper } from 'three/addons/helpers/RectAreaLightHelper.js';
        
        // RectAreaLightTexturesLib：矩形区域光纹理库，提供线性变换余弦(LTC)纹理
        import { RectAreaLightTexturesLib } from 'three/addons/lights/RectAreaLightTexturesLib.js';

        // ============================================
        // 全局变量声明
        // ============================================
        
        // 核心Three.js对象
        let camera;     // 相机：定义视图的观察点和投影方式
        let scene;      // 场景：包含所有3D对象的容器
        let renderer;   // 渲染器：负责将3D场景渲染到2D画布上
        
        // 控制器和特殊相机
        let controls;   // 轨道控制器：处理用户输入控制相机
        let cubeCamera; // 立方体相机：用于生成立方体环境贴图
        
        // 场景对象引用
        let groundPlane;    // 地面平面：演示BPCEM效果的主要对象
        let wallMat;        // 墙面材质：用于所有墙面的共享材质

        // ============================================
        // 初始化函数调用
        // ============================================
        
        // 调用异步初始化函数
        // async/await用于处理异步操作（如纹理加载）
        init();

        // ============================================
        // 主初始化函数
        // ============================================
        
        /**
         * 异步初始化函数
         * 负责初始化所有Three.js组件和场景设置
         * @async
         */
        async function init() {
            // ----------------------------------------------------
            // 初始化矩形区域光纹理库
            // ----------------------------------------------------
            
            // LTC：Linear Transformed Cosines（线性变换余弦）
            // 这是实现物理正确矩形区域光的技术
            // 首先初始化纹理库，然后设置给Three.js的矩形区域光节点
            THREE.RectAreaLightNode.setLTC(RectAreaLightTexturesLib.init());

            // ----------------------------------------------------
            // 场景设置
            // ----------------------------------------------------
            
            // 创建场景对象
            // 场景是所有3D对象的容器，包含网格、光源、相机等
            scene = new THREE.Scene();
            // 注意：这里可以设置场景的背景色、雾效等属性，但本示例中没有设置

            // ----------------------------------------------------
            // 主相机设置（透视相机）
            // ----------------------------------------------------
            
            /**
             * 创建透视相机
             * 参数说明：
             * @param {number} 45 - 垂直视野角度（Field of View），单位：度
             * @param {number} window.innerWidth/window.innerHeight - 宽高比
             * @param {number} 0.1 - 近裁剪平面距离，距离相机小于此值的物体不可见
             * @param {number} 1000 - 远裁剪平面距离，距离相机大于此值的物体不可见
             */
            camera = new THREE.PerspectiveCamera(
                45, 
                window.innerWidth / window.innerHeight, 
                0.1, 
                1000
            );
            
            // 设置相机初始位置
            // 参数：x, y, z坐标
            camera.position.set(0, 200, -200);
            // 位置解释：
            // y=200：相机位于上方，俯视场景
            // z=-200：相机在z轴负方向，看向场景中心

            // ----------------------------------------------------
            // 立方体相机设置（用于环境贴图）
            // ----------------------------------------------------
            
            /**
             * 创建立方体渲染目标
             * 参数说明：
             * @param {number} 512 - 立方体贴图每个面的分辨率（512x512像素）
             * 分辨率越高，环境贴图质量越好，但性能开销越大
             */
            const renderTarget = new THREE.WebGLCubeRenderTarget(512);
            
            // 配置渲染目标的纹理属性
            
            // 纹理类型：半浮点数
            // HalfFloatType比FloatType占用更少内存，适合HDR内容
            renderTarget.texture.type = THREE.HalfFloatType;
            
            // 缩小过滤器：线性Mipmap线性过滤
            // 当纹理在屏幕上显示得比实际尺寸小时使用
            // LinearMipmapLinearFilter提供高质量的纹理缩小过滤
            renderTarget.texture.minFilter = THREE.LinearMipmapLinearFilter;
            
            // 放大过滤器：线性过滤
            // 当纹理在屏幕上显示得比实际尺寸大时使用
            renderTarget.texture.magFilter = THREE.LinearFilter;
            
            // 生成Mipmaps：启用
            // Mipmaps是纹理的预先缩小的版本，用于提高渲染质量和性能
            renderTarget.texture.generateMipmaps = true;
            
            // 纹理映射方式：立方体反射映射
            // 这种映射方式将纹理视为立方体环境，用于反射效果
            renderTarget.texture.mapping = THREE.CubeReflectionMapping;
            
            /**
             * 创建立方体相机
             * 立方体相机可以一次渲染6个方向（上下左右前后）
             * 参数说明：
             * @param {number} 1 - 近裁剪面距离
             * @param {number} 1000 - 远裁剪面距离
             * @param {WebGLCubeRenderTarget} renderTarget - 渲染目标
             */
            cubeCamera = new THREE.CubeCamera(1, 1000, renderTarget);
            
            // 设置立方体相机位置
            // 位置在地面附近，以便捕捉到正确的环境反射
            cubeCamera.position.set(0, -100, 0);

            // ----------------------------------------------------
            // 地面平面设置（BPCEM演示主体）
            // ----------------------------------------------------
            
            // 创建纹理加载器
            // 用于异步加载图像文件作为纹理
            const loader = new THREE.TextureLoader();
            
            /**
             * 加载粗糙度贴图
             * 这个纹理定义了地面不同区域的粗糙程度
             * 粗糙度影响反射的模糊程度：0=完全镜面反射，1=完全漫反射
             */
            const rMap = loader.load('textures/lava/lavatile.jpg');
            
            // 设置纹理包裹方式：重复
            // 这样小纹理可以覆盖大的表面
            rMap.wrapS = THREE.RepeatWrapping;  // 水平方向重复
            rMap.wrapT = THREE.RepeatWrapping;  // 垂直方向重复
            
            // 设置纹理重复次数
            // 2倍水平重复，1倍垂直重复
            rMap.repeat.set(2, 1);
            
            // 创建粗糙度统一变量
            // uniform是可以在着色器外部修改的参数
            // 初始值0.25表示中等粗糙度
            const roughnessUniform = uniform(0.25);
            
            // ----------------------------------------------------
            // 创建两种材质进行对比
            // ----------------------------------------------------
            
            /**
             * 标准环境映射材质（作为对比）
             * 使用传统的立方体环境映射，没有盒投影校正
             */
            const defaultMat = new THREE.MeshStandardNodeMaterial();
            
            // 设置环境贴图节点
            // pmremTexture：预过滤辐射环境贴图，提供更真实的反射
            defaultMat.envNode = pmremTexture(renderTarget.texture);
            
            // 设置粗糙度节点
            // texture(rMap)：从粗糙度贴图读取值
            // .mul(roughnessUniform)：乘以粗糙度统一变量
            defaultMat.roughnessNode = texture(rMap).mul(roughnessUniform);
            
            // 设置金属度节点
            // float(1)：固定值1，表示完全金属材质
            defaultMat.metalnessNode = float(1);
            
            /**
             * 盒投影环境映射材质（BPCEM）
             * 使用视差校正的立方体环境映射
             */
            const boxProjectedMat = new THREE.MeshStandardNodeMaterial();
            
            // 设置带盒投影校正的环境贴图节点
            // getParallaxCorrectNormal函数的参数：
            // 1. reflectVector：反射向量计算函数
            // 2. vec3(200, 100, 100)：投影盒的尺寸（长宽高）
            // 3. vec3(0, -50, 0)：投影盒的中心位置
            boxProjectedMat.envNode = pmremTexture(
                renderTarget.texture, 
                getParallaxCorrectNormal(
                    reflectVector, 
                    vec3(200, 100, 100), 
                    vec3(0, -50, 0)
                )
            );
            
            // 粗糙度和金属度设置与标准材质相同
            boxProjectedMat.roughnessNode = texture(rMap).mul(roughnessUniform);
            boxProjectedMat.metalnessNode = float(1);
            
            // ----------------------------------------------------
            // 创建地面网格
            // ----------------------------------------------------
            
            /**
             * 创建平面几何体
             * 参数说明：
             * @param {number} 200 - 平面宽度
             * @param {number} 100 - 平面高度
             * @param {number} 100 - 宽度分段数（影响几何细节）
             * @param {number} 100 - 高度分段数
             */
            const planeGeometry = new THREE.PlaneGeometry(200, 100, 100, 100);
            
            /**
             * 创建地面网格对象
             * 将几何体和材质组合成可渲染的网格
             */
            groundPlane = new THREE.Mesh(
                planeGeometry,
                boxProjectedMat  // 初始使用盒投影材质
            );
            
            // 旋转平面使其水平
            // 平面默认是垂直的，需要绕X轴旋转-90度
            groundPlane.rotateX(-Math.PI / 2);
            
            // 设置平面位置
            // y=-49：略低于场景中心，形成地面
            groundPlane.position.set(0, -49, 0);
            
            // 将地面添加到场景
            scene.add(groundPlane);

            // ----------------------------------------------------
            // 墙面设置（创建封闭空间）
            // ----------------------------------------------------
            
            /**
             * 异步加载墙面纹理
             * Promise.all用于并行加载多个纹理
             * 这样可以提高加载效率
             */
            const [diffuseTex, bumpTex] = await Promise.all([
                // 漫反射贴图：定义墙面的颜色
                loader.loadAsync('textures/brick_diffuse.jpg'),
                
                // 凹凸贴图：定义墙面的表面凹凸细节（法线信息）
                loader.loadAsync('textures/brick_bump.jpg')
            ]);
            
            // 设置漫反射贴图的颜色空间
            // sRGB颜色空间更符合人眼感知，用于颜色纹理
            diffuseTex.colorSpace = THREE.SRGBColorSpace;
            
            /**
             * 创建墙面材质
             * 使用标准节点材质
             */
            wallMat = new THREE.MeshStandardNodeMaterial();
            
            // 设置颜色节点：使用砖墙的漫反射贴图
            wallMat.colorNode = texture(diffuseTex);
            
            // 设置法线节点：使用凹凸贴图
            // bumpMap函数的第二个参数5表示凹凸强度
            wallMat.normalNode = bumpMap(texture(bumpTex), float(5));
            
            // 创建墙面几何体（100x100的平面）
            const planeGeo = new THREE.PlaneGeometry(100, 100);
            
            // ----------------------------------------------------
            // 创建六个墙面，形成封闭的立方体空间
            // ----------------------------------------------------
            
            // 后墙左半部分
            const planeBack1 = new THREE.Mesh(planeGeo, wallMat);
            planeBack1.position.z = -50;  // z轴负方向
            planeBack1.position.x = -50;  // x轴负方向（左侧）
            scene.add(planeBack1);
            
            // 后墙右半部分
            const planeBack2 = new THREE.Mesh(planeGeo, wallMat);
            planeBack2.position.z = -50;
            planeBack2.position.x = 50;   // x轴正方向（右侧）
            scene.add(planeBack2);
            
            // 前墙左半部分
            const planeFront1 = new THREE.Mesh(planeGeo, wallMat);
            planeFront1.position.z = 50;   // z轴正方向
            planeFront1.position.x = -50;
            planeFront1.rotateY(Math.PI);  // 旋转180度，使纹理方向正确
            scene.add(planeFront1);
            
            // 前墙右半部分
            const planeFront2 = new THREE.Mesh(planeGeo, wallMat);
            planeFront2.position.z = 50;
            planeFront2.position.x = 50;
            planeFront2.rotateY(Math.PI);
            scene.add(planeFront2);
            
            // 右侧墙
            const planeRight = new THREE.Mesh(planeGeo, wallMat);
            planeRight.position.x = 100;   // 最右侧
            planeRight.rotateY(-Math.PI / 2);  // 旋转-90度，面向场景中心
            scene.add(planeRight);
            
            // 左侧墙
            const planeLeft = new THREE.Mesh(planeGeo, wallMat);
            planeLeft.position.x = -100;   // 最左侧
            planeLeft.rotateY(Math.PI / 2);   // 旋转90度，面向场景中心
            scene.add(planeLeft);
            
            // 现在场景有了一个100x100x100的封闭房间
            // 地面是200x100，所以房间不是完全立方体

            // ----------------------------------------------------
            // 光源设置（矩形区域光）
            // ----------------------------------------------------
            
            // 定义光源参数
            const width = 50;      // 光源宽度
            const height = 50;     // 光源高度
            const intensity = 5;   // 光源强度
            
            /**
             * 创建蓝色矩形区域光
             * 参数说明：
             * @param {number} 0x9aaeff - 光的颜色（十六进制RGB）
             * @param {number} intensity - 光强度
             * @param {number} width - 光源宽度
             * @param {number} height - 光源高度
             */
            const blueRectLight = new THREE.RectAreaLight(
                0x9aaeff,  // 淡蓝色
                intensity, 
                width, 
                height
            );
            
            // 设置光源位置（左侧）
            blueRectLight.position.set(-99, 5, 0);
            
            // 设置光源朝向（看向场景中心）
            blueRectLight.lookAt(0, 5, 0);
            
            // 添加到场景
            scene.add(blueRectLight);
            
            /**
             * 创建蓝色光的辅助器
             * 参数说明：
             * @param {RectAreaLight} blueRectLight - 要辅助显示的光源
             * @param {number} 0xffffff - 辅助器的颜色（白色）
             */
            const blueRectLightHelper = new RectAreaLightHelper(
                blueRectLight, 
                0xffffff
            );
            
            // 将辅助器添加到光源（这样辅助器会随光源移动）
            blueRectLight.add(blueRectLightHelper);
            
            /**
             * 创建红色矩形区域光
             * 原理与蓝色光相同，位置在右侧
             */
            const redRectLight = new THREE.RectAreaLight(
                0xf3aaaa,  // 淡红色
                intensity, 
                width, 
                height
            );
            
            redRectLight.position.set(99, 5, 0);  // 右侧位置
            redRectLight.lookAt(0, 5, 0);
            scene.add(redRectLight);
            
            // 红色光的辅助器
            const redRectLightHelper = new RectAreaLightHelper(
                redRectLight, 
                0xffffff
            );
            redRectLight.add(redRectLightHelper);
            
            // 现在场景有两个对称的矩形区域光
            // 一个蓝色（左侧），一个红色（右侧）
            // 它们提供主要照明并产生有趣的彩色反射

            // ----------------------------------------------------
            // 渲染器设置（WebGPU）
            // ----------------------------------------------------
            
            /**
             * 创建WebGPU渲染器
             * 参数说明：
             * @param {Object} { antialias: true } - 配置对象
             * antialias: true 启用抗锯齿，平滑边缘锯齿
             */
            renderer = new THREE.WebGPURenderer({ antialias: true });
            
            // 设置设备像素比
            // 这确保在高DPI显示器上正确渲染
            renderer.setPixelRatio(window.devicePixelRatio);
            
            // 设置渲染器尺寸为整个窗口
            renderer.setSize(window.innerWidth, window.innerHeight);
            
            // 设置动画循环函数
            // animate函数将在每一帧被调用
            renderer.setAnimationLoop(animate);
            
            // 初始化调试检查器
            // Inspector提供GUI界面，可以查看场景结构、对象属性等
            renderer.inspector = new Inspector();
            
            // 将渲染器的画布DOM元素添加到页面body
            // renderer.domElement是一个<canvas>元素
            document.body.appendChild(renderer.domElement);
            
            // ----------------------------------------------------
            // 异步初始化渲染器
            // ----------------------------------------------------
            
            /**
             * WebGPU渲染器需要异步初始化
             * 因为需要请求WebGPU设备，编译着色器等
             * await会等待初始化完成再继续执行
             */
            await renderer.init();
            
            // ----------------------------------------------------
            // 更新立方体贴图
            // ----------------------------------------------------
            
            /**
             * 首次生成环境贴图
             * 立方体贴图需要基于当前场景内容生成
             */
            updateCubeMap();
            
            // ----------------------------------------------------
            // 窗口大小变化事件监听
            // ----------------------------------------------------
            
            /**
             * 监听窗口大小变化事件
             * 当用户调整浏览器窗口大小时，需要更新相机和渲染器
             */
            window.addEventListener('resize', onWindowResize);

            // ----------------------------------------------------
            // 控制器设置（用户交互）
            // ----------------------------------------------------
            
            /**
             * 创建轨道控制器
             * 参数说明：
             * @param {Camera} camera - 要控制的相机
             * @param {HTMLElement} renderer.domElement - 监听事件的DOM元素
             */
            controls = new OrbitControls(camera, renderer.domElement);
            
            // 设置控制器的目标点（相机围绕此点旋转）
            controls.target.set(0, -10, 0);
            
            // 设置相机与目标点的最大距离
            controls.maxDistance = 400;
            
            // 设置相机与目标点的最小距离
            controls.minDistance = 10;
            
            // 更新控制器状态
            controls.update();
            
            // 现在用户可以通过鼠标与场景交互：
            // - 左键拖拽：旋转视角
            // - 右键拖拽：平移场景
            // - 滚轮：缩放

            // ----------------------------------------------------
            // GUI参数界面（调试和控制）
            // ----------------------------------------------------
            
            /**
             * 创建参数面板
             * Inspector提供的方法，创建可调整参数的GUI
             */
            const gui = renderer.inspector.createParameters('控制面板');
            
            // 定义可调整的参数对象
            const params = {
                '启用盒投影': true  // 默认启用盒投影效果
            };
            
            /**
             * 添加"启用盒投影"复选框
             * 允许用户在标准环境映射和盒投影环境映射之间切换
             */
            gui.add(params, '启用盒投影')
               .onChange((value) => {
                    // 当复选框状态改变时，切换地面材质
                    groundPlane.material = (value) ? boxProjectedMat : defaultMat;
                    
                    // 如果启用了盒投影，需要更新立方体贴图
                    if (value) {
                        updateCubeMap();
                    }
               })
               .name('盒投影效果');  // 设置GUI中显示的名称
            
            /**
             * 添加粗糙度滑块
             * 允许用户实时调整地面的粗糙度
             * 参数说明：
             * @param {Object} roughnessUniform - 统一变量对象
             * @param {string} 'value' - 要控制的属性名
             * @param {number} 0 - 最小值
             * @param {number} 1 - 最大值
             */
            gui.add(roughnessUniform, 'value', 0, 1)
               .name('地面粗糙度')
               .step(0.01);  // 设置滑块步长（每次调整的最小变化量）
            
            /**
             * 可以添加更多控制选项，例如：
             * - 光源强度
             * - 光源颜色
             * - 是否显示辅助器
             * - 背景色等
             */
        }

        // ============================================
        // 窗口大小变化处理函数
        // ============================================
        
        /**
         * 处理窗口大小变化
         * 当浏览器窗口大小改变时，需要更新相机和渲染器
         */
        function onWindowResize() {
            // 更新相机的宽高比
            // 相机需要知道画布的新宽高比，否则图像会被拉伸
            camera.aspect = window.innerWidth / window.innerHeight;
            
            // 更新相机的投影矩阵
            // 投影矩阵定义了3D空间如何映射到2D屏幕
            // 当相机参数改变后，必须调用此方法
            camera.updateProjectionMatrix();
            
            // 更新渲染器大小
            // 确保渲染器画布与窗口大小一致
            renderer.setSize(window.innerWidth, window.innerHeight);
            
            // 注意：这里不需要重新生成环境贴图
            // 因为环境贴图的内容不依赖于窗口大小
        }

        // ============================================
        // 更新立方体贴图函数
        // ============================================
        
        /**
         * 更新立方体环境贴图
         * 这个函数从立方体相机的位置渲染六个方向，
         * 生成当前场景的环境贴图
         */
        function updateCubeMap() {
            // 临时隐藏地面
            // 这是为了防止地面在自己的反射中出现（无限递归）
            groundPlane.visible = false;
            
            // 将立方体相机移动到地面位置
            // 环境贴图应该从地面的视角生成
            cubeCamera.position.copy(groundPlane.position);
            
            /**
             * 更新立方体相机
             * 这个方法会：
             * 1. 在立方体相机当前位置渲染6个方向
             * 2. 将结果保存到renderTarget中
             * 3. 更新环境贴图纹理
             * 
             * 参数说明：
             * @param {WebGPURenderer} renderer - 使用的渲染器
             * @param {Scene} scene - 要渲染的场景
             */
            cubeCamera.update(renderer, scene);
            
            // 重新显示地面
            groundPlane.visible = true;
            
            // 注意：这个函数可以在运行时多次调用
            // 例如，如果场景中的物体移动了，可能需要重新生成环境贴图
        }

        // ============================================
        // 动画循环函数
        // ============================================
        
        /**
         * 动画循环函数
         * 这个函数由renderer.setAnimationLoop注册
         * 会在每一帧自动调用（通常是60次/秒）
         * 
         * 注意：现代浏览器使用requestAnimationFrame
         * 在页面不可见时会自动暂停，节省资源
         */
        function animate() {
            /**
             * 渲染场景
             * 这是每一帧的主要工作：
             * 1. 处理用户输入（通过OrbitControls）
             * 2. 更新场景中需要动画的对象
             * 3. 执行WebGPU渲染命令
             * 4. 将结果绘制到canvas上
             * 
             * 参数说明：
             * @param {Scene} scene - 要渲染的场景
             * @param {Camera} camera - 使用的相机
             */
            renderer.render(scene, camera);
            
            // 注意：这里没有更新立方体贴图
            // 因为在这个演示中，环境是静态的
            // 如果场景中有移动的物体，可能需要每帧更新环境贴图
        }
        
        // ============================================
        // 额外的性能优化建议
        // ============================================
        
        /**
         * 可以添加的性能优化：
         * 1. 使用requestAnimationFrame的时间参数实现帧率无关动画
         * 2. 添加加载管理器显示加载进度
         * 3. 添加性能监视器（FPS显示）
         * 4. 实现自适应分辨率（根据性能调整渲染质量）
         * 5. 添加场景卸载/资源清理逻辑
         */
    </script>
    
    <!-- 
        页面加载完成后的额外说明：
        在实际项目中，可能还需要添加：
        1. 加载动画
        2. 错误处理
        3. 移动端触摸支持增强
        4. WebGPU特性检测和回退方案
    -->
</body>
</html>