<!-- 代码功能和技术点详解
一、整体功能描述
这是一个基于Three.js WebGPU的实时焦散（Caustics）效果演示程序，展示光线通过透明物体（如玻璃、水晶）时产生的复杂光学现象。

主要功能：
实时渲染焦散效果 - 模拟光线折射、聚焦和色散现象

交互式3D场景 - 用户可旋转、缩放视角，观察不同角度的效果

动态参数调整 - 通过GUI面板实时修改效果参数

模型切换 - 在鸭子模型和玻璃面板之间切换展示

物理准确的光照 - 基于物理的渲染（PBR）材质系统

二、核心焦散效果实现
1. 光学原理实现
折射计算
javascript
// 基于斯涅尔定律计算光线折射
const refractionVector = refract(
    positionViewDirection.negate(),  // 入射光线方向（从表面指向相机）
    normalView,                      // 表面法线方向
    div(1.0, duck.material.ior)     // 折射率（空气到介质：1.0/1.5≈0.667）
).normalize();
斯涅尔定律：n₁·sinθ₁ = n₂·sinθ₂

物理意义：光线从空气进入玻璃（折射率1.5）时的弯曲

色散现象模拟
javascript
// RGB通道分别偏移，模拟色散
const causticProjection = vec3(
    texture(causticMap, textureUV.add(vec2(chromaticAberrationOffset.negate(), 0))).r,  // 红
    texture(causticMap, textureUV.add(vec2(0, chromaticAberrationOffset.negate()))).g, // 绿
    texture(causticMap, textureUV.add(vec2(chromaticAberrationOffset, chromaticAberrationOffset))).b   // 蓝
);
色散原理：不同波长（颜色）光线折射率不同

实现方式：对RGB通道使用不同的UV偏移采样

2. 渲染管线流程
text
1. 光线追踪 → 2. 折射计算 → 3. 纹理映射 → 4. 色散处理 → 5. 衰减处理 → 6. 颜色混合
三、关键技术点
1. WebGPU渲染技术
优势对比WebGL：
特性	WebGPU	WebGL 2.0
性能	多线程并行渲染	单线程渲染
内存管理	显式内存控制	隐式垃圾回收
着色器	WGSL（类型安全）	GLSL
计算着色器	原生支持	有限支持
关键配置：
javascript
renderer = new THREE.WebGPURenderer({ 
    antialias: true  // 抗锯齿，平滑边缘
});
renderer.shadowMap.enabled = true;  // 启用阴影系统
renderer.setAnimationLoop(animate); // 使用requestAnimationFrame
2. Three.js Shader Language（TSL）
TSL核心概念：
javascript
// 声明节点（Node-based）着色器
duck.material.castShadowNode = Fn(() => {
    // 1. 输入节点：positionViewDirection, normalView
    // 2. 处理节点：refract(), pow(), mul(), add()
    // 3. 输出节点：vec3颜色值
})();
节点式着色器优点：
可组合性：节点可复用和连接

实时编译：无需预编译着色器

可视化编辑：支持节点编辑器

3. 基于物理的渲染（PBR）
材质参数：
javascript
duck.material = new THREE.MeshPhysicalNodeMaterial({
    transmission: 1,      // 透光率100%
    ior: 1.5,            // 折射率（玻璃）
    thickness: .25,      // 材质厚度
    roughness: .1,       // 表面粗糙度
    metalness: 0         // 金属度（非金属）
});
PBR材质特性：
能量守恒：反射+折射+吸收=入射光

菲涅尔效应：掠射角反射更强

微表面模型：基于粗糙度的散射

4. 动态阴影系统
阴影优化技术：
javascript
spotLight.shadow.mapSize.width = 1024;    // 阴影贴图分辨率
spotLight.shadow.bias = - .003;           // 阴影偏移（消除阴影痤疮）
spotLight.shadow.mapType = THREE.HalfFloatType;  // HDR阴影
焦散阴影特殊处理：
双重阴影：几何阴影 + 焦散投影

动态采样：基于折射向量的纹理采样

衰减控制：基于视角深度的强度调节

5. 模型加载与优化
Draco压缩：
javascript
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('jsm/libs/draco/');
dracoLoader.setDecoderConfig({ type: 'js' });
压缩比：通常可达5-10倍

加载优化：减少网络传输时间

内存优化：减少GPU内存占用

6. 实时交互系统
轨道控制器：
javascript
controls = new OrbitControls(camera, renderer.domElement);
controls.maxDistance = 3;                  // 限制缩放
controls.maxPolarAngle = Math.PI / 2;      // 限制俯仰角度
GUI参数面板：
javascript
// 创建可调节参数
gui.add(causticOcclusion, 'value', 0, 20).name('焦散遮挡强度');
gui.addColor(duck.material, 'color').name('材质颜色');
实时反馈：参数修改立即生效

实验性调整：支持艺术化调整

四、渲染技术细节
1. 焦散纹理映射技术
javascript
const textureUV = refractionVector.xy.mul(.6);
UV生成：使用折射向量作为纹理坐标

缩放因子：0.6控制焦散图案密度

重复映射：THREE.RepeatWrapping实现无缝平铺

2. 深度感知衰减
javascript
const viewZ = normalView.z.pow(causticOcclusion);
const final = causticProjection.mul(viewZ.mul(25)).add(viewZ);
数学公式：effect = texture * (depth^exponent * 25) + depth^exponent

物理意义：模拟光线在介质中的吸收和散射

可调节：exponent参数控制衰减曲线

3. HDR（高动态范围）处理
javascript
spotLight.shadow.mapType = THREE.HalfFloatType;
支持范围：16位浮点数（-65504~65504）

优点：避免亮度溢出，保持细节

应用：焦散亮斑可能超过1.0亮度

五、性能优化策略
1. 渲染优化
批处理：相似材质对象合并渲染

LOD系统：根据距离切换细节层次（可扩展）

视锥剔除：自动剔除视野外物体

2. 内存管理
纹理复用：相同纹理共享内存

几何体实例化：重复对象共享几何数据

及时释放：动态资源管理

3. GPU优化
着色器最小化：只包含必要计算

纹理压缩：使用适当压缩格式

缓存友好：优化数据布局

六、可扩展性和应用场景
1. 技术扩展方向
体积焦散：3D空间中的光场渲染

动态介质：流动水体的焦散效果

多层折射：复杂光学系统的模拟

实时GI：结合全局光照

2. 应用场景
产品展示：珠宝、玻璃器皿的在线展示

建筑可视化：玻璃幕墙、水景设计

游戏开发：水下场景、魔法效果

教育演示：光学原理可视化

3. 艺术创作
参数化设计：通过调整参数创造独特效果

程序化生成：动态生成焦散图案

交互艺术：用户参与的光学装置

七、技术挑战与解决方案
1. 性能与质量的平衡
挑战：实时计算精确折射路径开销大

方案：使用预计算纹理+实时变形

2. 色散模拟精度
挑战：精确色散需要光谱渲染

方案：RGB通道偏移近似，艺术化控制

3. 多光源支持
挑战：多个焦散源叠加计算复杂

方案：可扩展为多光源累加系统

八、总结
这个演示展示了现代Web图形技术的强大能力：

技术先进性：使用最新的WebGPU API和Three.js框架

物理准确性：基于真实光学原理的效果模拟

实时交互性：毫秒级响应的参数调整

视觉质量：电影级的光影效果

跨平台性：在现代浏览器中直接运行 -->


<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <!-- 页面基本信息：设置标题为"Three.js WebGPU - 实时焦散效果演示" -->
    <title>Three.js WebGPU - 实时焦散效果演示</title>
    <meta charset="utf-8">
    <!-- 设置视口：适配移动端，禁止用户手动缩放页面 -->
    <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>

    <!-- 页面信息展示区域，用于显示标题、链接和说明 -->
    <div id="info">
        <!-- Three.js官方网站链接：点击跳转到Three.js官网 -->
        <a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link" title="访问Three.js官网"></a>

        <!-- 标题区域：显示主标题和副标题 -->
        <div class="title-wrapper">
            <a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a><span>焦散效果演示</span>
        </div>

        <!-- 简要描述：说明这是一个实时焦散效果实现 -->
        <small>基于WebGPU的实时焦散效果实现</small>
    </div>

    <!-- 
        导入映射配置（Import Map）： 
        定义模块别名，让浏览器知道如何解析import语句中的模块路径
        这是ES模块系统的配置，替代传统的打包工具配置
    -->
    <script type="importmap">
        {
            "imports": {
                "three": "../build/three.webgpu.js",
                "three/webgpu": "../build/three.webgpu.js",
                "three/tsl": "../build/three.tsl.js",
                "three/addons/": "./jsm/"
            }
        }
    </script>

    <!-- 主JavaScript模块：使用type="module"声明这是一个ES6模块 -->
    <script type="module">

        // 导入Three.js WebGPU渲染器的核心模块
        // WebGPU是新一代的Web图形API，相比WebGL有更好的性能和功能
        import * as THREE from 'three/webgpu';

        // 导入TSL（Three.js Shader Language）着色器语言的相关函数和节点
        // TSL是Three.js的着色器语言，用于编写自定义着色器效果
        // uniform: 声明着色器中的统一变量（在着色器执行期间保持不变的变量）
        // refract: 计算光线的折射向量，基于斯涅尔定律（Snell's Law）
        // div: 除法运算节点
        // positionViewDirection: 视图空间中的位置方向向量
        // positionLocal: 局部坐标系中的位置
        // normalView: 视图空间中的法线向量
        // texture: 纹理采样节点
        // Fn: 函数节点，用于定义自定义着色器函数
        // vec2, vec3, vec4: 创建2D、3D、4D向量的节点
        import { uniform, refract, div, positionViewDirection, positionLocal, normalView, texture, Fn, vec2, vec3, vec4 } from 'three/tsl';

        // 导入Three.js的附加组件（插件）
        // OrbitControls: 轨道控制器，允许用户通过鼠标拖拽和滚轮控制相机
        import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
        // GLTFLoader: GLTF格式模型加载器，GLTF是标准的3D模型传输格式
        import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
        // DRACOLoader: Draco压缩格式解码器，用于加载压缩的3D模型以减小文件大小
        import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
        // Inspector: 调试检查器，用于创建GUI控制面板和调试信息显示
        import { Inspector } from 'three/addons/inspector/Inspector.js';

        // 全局变量声明
        let camera;      // 相机对象，用于定义观察场景的视角
        let scene;       // 场景对象，包含所有的3D对象、灯光和相机
        let renderer;    // 渲染器对象，负责将3D场景渲染到2D画布上
        let controls;    // 相机控制器对象，用于用户交互控制
        let gltf;        // GLTF模型对象，存储加载的3D模型数据

        // 调用初始化函数，开始程序执行
        init();

        // 异步初始化函数：async关键字表示函数内部可以使用await进行异步操作
        async function init() {
            /*
             * 第一部分：相机设置
             * 创建透视相机，模拟人眼的视觉效果
             * 参数说明：
             *   25 - 视野角度（FOV），单位度，决定相机能看到多大范围
             *   window.innerWidth / window.innerHeight - 宽高比，根据窗口大小动态计算
             *   0.025 - 近裁剪面，距离相机多近的物体开始渲染
             *   5 - 远裁剪面，距离相机多远的物体停止渲染
             */
            camera = new THREE.PerspectiveCamera(25, window.innerWidth / window.innerHeight, 0.025, 5);
            // 设置相机初始位置：(x, y, z)坐标
            camera.position.set(-0.5, 0.35, 0.2);

            // 创建场景对象：场景是所有3D对象的容器
            scene = new THREE.Scene();

            // ------------------- 第二部分：光源设置 -------------------
            /*
             * 创建聚光灯（SpotLight）作为主光源
             * 聚光灯从一个点向特定方向发射锥形光线
             * 参数说明：
             *   0xffffff - 灯光颜色，白色
             *   1 - 灯光强度
             */
            const spotLight = new THREE.SpotLight(0xffffff, 1);
            // 设置光源位置
            spotLight.position.set(.2, .3, .2);
            // 启用阴影投射：光源可以产生阴影
            spotLight.castShadow = true;
            // 设置光线锥角：Math.PI / 6 等于30度
            spotLight.angle = Math.PI / 6;
            // 设置半影区：光线边缘的柔和程度，1表示完全柔和
            spotLight.penumbra = 1;
            // 设置光线衰减：光线强度随距离减弱的速率
            spotLight.decay = 2;
            // 设置光线距离：0表示无限远
            spotLight.distance = 0;
            // 设置阴影贴图类型：使用半浮点类型，支持HDR（高动态范围）效果
            spotLight.shadow.mapType = THREE.HalfFloatType;
            // 设置阴影贴图分辨率：影响阴影的清晰度
            spotLight.shadow.mapSize.width = 1024;
            spotLight.shadow.mapSize.height = 1024;
            // 设置阴影相机参数：定义哪些物体可以投射阴影
            spotLight.shadow.camera.near = .1;  // 近裁剪面
            spotLight.shadow.camera.far = 1;    // 远裁剪面
            // 设置阴影偏移：防止阴影失真（自阴影问题）
            spotLight.shadow.bias = - .003;
            // 设置阴影强度：0到1之间，1表示完全阴影
            spotLight.shadow.intensity = .95;
            // 将光源添加到场景中
            scene.add(spotLight);

            // ------------------- 第三部分：模型和纹理加载 -------------------
            /*
             * 配置Draco解码器
             * Draco是Google开发的3D几何压缩库，可以显著减小3D模型文件大小
             */
            const dracoLoader = new DRACOLoader();
            // 设置解码器文件路径
            dracoLoader.setDecoderPath('jsm/libs/draco/');
            // 配置使用JavaScript版本解码器（也可以选择WebAssembly版本）
            dracoLoader.setDecoderConfig({ type: 'js' });

            /*
             * 异步加载GLTF模型
             * 使用async/await语法确保模型加载完成后再执行后续代码
             * 加载流程：
             *   1. 创建GLTFLoader实例
             *   2. 设置DRACOLoader用于解码压缩模型
             *   3. 异步加载模型文件
             *   4. 获取加载后的场景对象
             */
            gltf = (await new GLTFLoader().setDRACOLoader(dracoLoader).loadAsync('./models/gltf/duck.glb')).scene;
            // 缩放模型：将模型缩小到原来的50%
            gltf.scale.setScalar(.5);
            // 将模型添加到场景
            scene.add(gltf);

            /*
             * 加载焦散纹理贴图
             * 焦散纹理是预计算的焦散图案，用于模拟光线折射后的效果
             */
            const causticMap = new THREE.TextureLoader().load('./textures/opengameart/Caustic_Free.jpg');
            // 设置纹理重复模式：当UV坐标超出[0,1]范围时重复纹理
            causticMap.wrapS = causticMap.wrapT = THREE.RepeatWrapping;
            // 设置颜色空间：sRGB颜色空间更符合人眼感知
            causticMap.colorSpace = THREE.SRGBColorSpace;

            // ------------------- 第四部分：对象和材质设置 -------------------
            /*
             * 获取鸭子模型并设置材质
             * gltf.children[0] 获取GLTF场景中的第一个子对象（鸭子模型）
             */
            const duck = gltf.children[0];
            // 创建物理节点材质：支持基于物理的渲染（PBR）和自定义着色器节点
            duck.material = new THREE.MeshPhysicalNodeMaterial();
            // 设置双面渲染：材质两面都可见
            duck.material.side = THREE.DoubleSide;
            // 启用透明度：材质支持透明效果
            duck.material.transparent = true;
            // 设置材质基础颜色：金色 (0xFFD700)
            duck.material.color = new THREE.Color(0xFFD700);
            // 设置透光率：1表示完全透明（光线100%通过）
            duck.material.transmission = 1;
            // 设置材质厚度：影响折射效果，单位米
            duck.material.thickness = .25;
            // 设置折射率：1.5是玻璃的典型折射率
            duck.material.ior = 1.5;
            // 设置金属度：0表示非金属材质
            duck.material.metalness = 0;
            // 设置粗糙度：0.1表示稍微粗糙的表面
            duck.material.roughness = .1;
            // 启用模型阴影投射
            duck.castShadow = true;

            // ------------------- 第五部分：TSL着色器编程 -------------------
            /*
             * 创建焦散遮挡系数统一变量
             * uniform变量在着色器执行期间保持不变，可以从JavaScript代码中修改
             * 初始值20，值越大焦散效果衰减越快
             */
            const causticOcclusion = uniform(20);

            /*
             * 定义阴影投射位置节点
             * Fn() 创建一个TSL函数节点，可以包含复杂的着色器逻辑
             * 这里可以添加几何变形效果，但当前仅返回局部位置
             */
            duck.material.castShadowPositionNode = Fn(() => {
                // 返回局部坐标系中的位置
                // 如果需要几何变形，可以在这里添加变形计算
                return positionLocal;
            })();

            /*
             * 定义焦散效果的主要着色器节点
             * 这是实现实时焦散效果的核心代码
             */
            duck.material.castShadowNode = Fn(() => {
                /*
                 * 计算折射向量
                 * 基于斯涅尔定律（Snell's Law）计算光线从一种介质进入另一种介质时的折射方向
                 * 参数说明：
                 *   positionViewDirection.negate() - 从表面指向相机的方向（视线方向的反方向）
                 *   normalView - 视图空间中的表面法线
                 *   div(1.0, duck.material.ior) - 折射率的倒数（从空气到介质的折射率）
                 *   .normalize() - 将结果向量归一化（长度为1）
                 */
                const refractionVector = refract(
                    positionViewDirection.negate(),  // 入射方向：从表面指向相机
                    normalView,                       // 表面法线
                    div(1.0, duck.material.ior)      // 相对折射率：1.0 / 1.5 = 0.666...
                ).normalize();

                /*
                 * 计算视角深度衰减
                 * 基于法线的z分量计算焦散效果的衰减
                 * normalView.z - 法线在视图空间中的z分量，表示表面朝向
                 * .pow(causticOcclusion) - 使用指数函数控制衰减强度
                 * causticOcclusion值越大，衰减越快
                 */
                const viewZ = normalView.z.pow(causticOcclusion);

                /*
                 * 计算纹理UV坐标
                 * 将折射向量的xy分量用作纹理坐标
                 * .mul(.6) - 缩放纹理坐标，控制焦散图案的大小
                 */
                const textureUV = refractionVector.xy.mul(.6);

                // 将材质颜色转换为统一变量，以便在着色器中使用
                const causticColor = uniform(duck.material.color);
                
                /*
                 * 计算色散偏移
                 * 模拟色散现象：不同波长的光折射率不同，导致分离
                 * normalView.z.pow(-.9) - 基于法线z分量的色散强度
                 * .mul(.004) - 控制色散偏移的大小
                 */
                const chromaticAberrationOffset = normalView.z.pow(-.9).mul(.004);

                /*
                 * 计算焦散投影
                 * 通过折射后的UV坐标采样焦散纹理
                 * 对RGB通道分别进行偏移采样，模拟色散效果
                 * 色散原理：不同颜色的光波长不同，折射率也不同，导致分离
                 */
                const causticProjection = vec3(
                    // 红色通道：使用负X偏移和零Y偏移
                    texture(causticMap, textureUV.add(vec2(chromaticAberrationOffset.negate(), 0))).r,
                    // 绿色通道：使用零X偏移和负Y偏移
                    texture(causticMap, textureUV.add(vec2(0, chromaticAberrationOffset.negate()))).g,
                    // 蓝色通道：使用正X和正Y偏移
                    texture(causticMap, textureUV.add(vec2(chromaticAberrationOffset, chromaticAberrationOffset))).b
                );

                /*
                 * 最终焦散效果计算
                 * 公式：焦散投影 × (视角衰减 × 25) + 基础衰减 × 材质颜色
                 * 分解说明：
                 *   causticProjection - 采样的焦散纹理颜色
                 *   .mul(viewZ.mul(25)) - 应用衰减并乘以强度系数25
                 *   .add(viewZ) - 添加基础衰减，确保效果平滑过渡
                 *   .mul(causticColor) - 应用材质颜色
                 */
                return causticProjection.mul(viewZ.mul(25)).add(viewZ).mul(causticColor);
            })();

            // ------------------- 第六部分：玻璃面板对象 -------------------
            // 创建纹理加载器实例
            const textureLoader = new THREE.TextureLoader();

            // 加载玻璃面板纹理（彩色图案纹理）
            const colorMap = textureLoader.load('textures/colors.png');
            // 设置纹理重复模式
            colorMap.wrapS = colorMap.wrapT = THREE.RepeatWrapping;
            // 设置颜色空间
            colorMap.colorSpace = THREE.SRGBColorSpace;

            // 创建玻璃材质：使用物理节点材质
            const glassMaterial = new THREE.MeshPhysicalNodeMaterial();
            glassMaterial.map = colorMap;                   // 设置纹理贴图
            glassMaterial.side = THREE.DoubleSide;          // 双面渲染
            glassMaterial.transparent = true;               // 透明材质
            glassMaterial.color = new THREE.Color(0xffffff); // 白色基础色
            glassMaterial.transmission = 1;                 // 完全透光
            glassMaterial.ior = 1.5;                        // 玻璃折射率
            glassMaterial.metalness = 0;                    // 非金属材质
            glassMaterial.roughness = .1;                   // 轻微粗糙度
            // 设置简单的阴影投射：直接使用纹理颜色，透明度0.8
            glassMaterial.castShadowNode = vec4(texture(colorMap).rgb, .8);

            // 创建玻璃平面网格
            const glass = new THREE.Mesh(
                new THREE.PlaneGeometry(.2, .2),  // 创建0.2x0.2的平面几何体
                glassMaterial                      // 使用玻璃材质
            );
            glass.position.y = .1;        // 设置Y轴位置
            glass.castShadow = true;      // 启用阴影投射
            glass.visible = false;        // 初始状态不可见（默认显示鸭子）
            scene.add(glass);             // 将玻璃添加到场景

            // ------------------- 第七部分：地面对象 -------------------
            // 加载地面纹理（木地板纹理）
            const map = textureLoader.load('textures/hardwood2_diffuse.jpg');
            map.wrapS = map.wrapT = THREE.RepeatWrapping;  // 设置重复模式
            map.repeat.set(10, 10);                        // 设置重复次数：10x10

            // 创建地面几何体：2x2的平面
            const geometry = new THREE.PlaneGeometry(2, 2);
            // 创建标准材质：灰色基础色，应用木地板纹理
            const material = new THREE.MeshStandardMaterial({ 
                color: 0x999999,  // 灰色
                map: map          // 木地板纹理
            });

            // 创建地面网格
            const ground = new THREE.Mesh(geometry, material);
            ground.rotation.x = -Math.PI / 2;  // 旋转-90度，使平面水平（作为地面）
            ground.receiveShadow = true;       // 启用阴影接收：地面可以显示其他物体的阴影
            scene.add(ground);                 // 将地面添加到场景

            // ------------------- 第八部分：渲染器设置 -------------------
            /*
             * 创建WebGPU渲染器
             * WebGPU是下一代Web图形API，提供比WebGL更好的性能和更底层的控制
             * 参数说明：
             *   antialias: true - 启用抗锯齿，平滑边缘锯齿
             */
            renderer = new THREE.WebGPURenderer({ antialias: true });
            // 设置设备像素比：适应高DPI显示屏（如Retina显示屏）
            renderer.setPixelRatio(window.devicePixelRatio);
            // 设置渲染器尺寸：与浏览器窗口大小一致
            renderer.setSize(window.innerWidth, window.innerHeight);
            // 设置动画循环：传入animate函数，每帧调用一次
            renderer.setAnimationLoop(animate);
            // 启用阴影映射：渲染器支持阴影效果
            renderer.shadowMap.enabled = true;
            // 创建调试检查器：用于显示GUI控制面板
            renderer.inspector = new Inspector();
            // 将渲染器的canvas元素添加到页面body中
            document.body.appendChild(renderer.domElement);

            // ------------------- 第九部分：GUI控制面板 -------------------
            /*
             * 创建GUI参数面板
             * 允许用户在运行时调整效果参数
             */
            const gui = renderer.inspector.createParameters('设置面板');
            
            /*
             * 添加焦散遮挡控制滑块
             * 参数说明：
             *   causticOcclusion - 控制的对象
             *   'value' - 控制的属性
             *   0, 20 - 滑块的最小值和最大值
             *   'caustic occlusion' - 在GUI中显示的名称
             */
            gui.add(causticOcclusion, 'value', 0, 20).name('焦散遮挡强度');
            
            /*
             * 添加材质颜色选择器
             * 允许用户实时更改鸭子材质的颜色
             */
            gui.addColor(duck.material, 'color').name('材质颜色');
            
            /*
             * 添加模型切换下拉菜单
             * 允许用户在鸭子和玻璃面板之间切换显示
             */
            gui.add({ model: 'duck' }, 'model', [
                'duck',   // 鸭子模型
                'glass'   // 玻璃面板
            ]).name('显示模型').onChange(model => {
                // 切换模型可见性：先隐藏所有模型
                duck.visible = glass.visible = false;

                if (model === 'duck') {
                    // 显示鸭子模型
                    duck.visible = true;
                } else if (model === 'glass') {
                    // 显示玻璃面板
                    glass.visible = true;
                }
            });

            // ------------------- 第十部分：控制器设置 -------------------
            /*
             * 创建轨道控制器
             * 允许用户通过鼠标控制相机视角
             * 参数说明：
             *   camera - 要控制的相机对象
             *   renderer.domElement - 监听用户输入的DOM元素（渲染器的canvas）
             */
            controls = new OrbitControls(camera, renderer.domElement);
            // 设置最大缩放距离：防止相机过于远离场景
            controls.maxDistance = 3;
            // 设置最大俯仰角度：限制相机不能看到地面以下
            controls.maxPolarAngle = Math.PI / 2;  // 90度

            // 添加窗口大小变化事件监听器
            // 当浏览器窗口大小改变时，重新调整相机和渲染器
            window.addEventListener('resize', onWindowResize);
        }

        /*
         * 窗口大小变化处理函数
         * 当浏览器窗口大小改变时，确保3D场景正确适应新尺寸
         */
        function onWindowResize() {
            // 更新相机的宽高比：根据新的窗口尺寸计算
            camera.aspect = window.innerWidth / window.innerHeight;
            // 更新相机的投影矩阵：应用新的宽高比
            camera.updateProjectionMatrix();
            // 更新渲染器尺寸：使其与窗口大小一致
            renderer.setSize(window.innerWidth, window.innerHeight);
        }

        /*
         * 动画循环函数
         * 每帧调用一次，用于更新场景状态和重新渲染
         */
        function animate() {
            // 旋转GLTF模型中的所有子网格
            // 让鸭子模型缓慢旋转，展示不同角度的焦散效果
            for (const mesh of gltf.children) {
                // 每帧绕Y轴旋转-0.01弧度（逆时针旋转）
                mesh.rotation.y -= .01;
            }

            // 更新相机控制器：处理用户输入（鼠标拖拽、滚轮缩放）
            controls.update();
            
            // 渲染场景：将3D场景绘制到2D画布上
            // 参数说明：
            //   scene - 要渲染的场景
            //   camera - 用于渲染的相机视角
            renderer.render(scene, camera);
        }

    </script>
</body>
</html>