<!-- 代码功能和技术点详细分析
一、项目概述
这是一个基于Three.js WebGPU的实时体积焦散效果演示项目，展示了高级的实时图形渲染技术。项目通过复杂的着色器编程和后处理管线，实现了逼真的光线透过透明物体（金色鸭子模型）产生的体积焦散效果。

二、核心功能模块
1. 体积焦散效果 (Volumetric Caustics)
焦散定义：模拟光线通过透明或半透明介质（如水、玻璃）时，由于折射和反射形成的明亮光斑图案

实现原理：

使用TSL着色器计算光线在材质内部的折射路径

应用焦散贴图（Caustic Texture）模拟焦散图案

加入色差效果（Chromatic Aberration）增强真实感

2. 体积雾/体积光 (Volumetric Fog/Light)
动态3D烟雾效果：

使用3D Perlin噪声纹理生成自然的湍流效果

多层噪声叠加（多尺度细节）

时间动画使烟雾动态变化

体积光散射：模拟光线在介质中的散射现象

3. 物理精确的折射
折射率(IOR)：设置为1.5，模拟玻璃材质

折射计算：使用斯涅尔定律计算光线折射方向

厚度衰减：材质厚度影响透射和散射效果

4. 后处理特效
Bloom泛光：高亮区域产生光晕扩散效果

分层渲染：将不同效果分配到不同的渲染层

合成管道：多个渲染通道的合成处理

三、主要技术点详解
1. WebGPU渲染器
javascript
renderer = new THREE.WebGPURenderer({ antialias: true });
下一代Web图形API：比WebGL更高效、功能更强大

显式GPU控制：更细粒度的GPU资源管理

计算着色器支持：适合体积渲染等复杂计算

2. TSL着色器语言
javascript
import { uniform, refract, texture, Fn, vec3 } from 'three/tsl';
节点化着色器编程：可视化、模块化的着色器开发

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

自动优化：Three.js自动优化着色器代码

3. 体积渲染技术
光线步进算法：
javascript
volumetricMaterial.steps = 20;
Ray Marching：沿视线方向步进采样

密度场采样：从3D纹理读取烟雾密度

深度测试：避免渲染在实体物体后面的体积效果

3D噪声纹理生成：
javascript
function createTexture3D() {
    // 生成128x128x128的Perlin噪声3D纹理
}
程序化纹理：运行时生成，减少加载时间

多层细节：大、中、小尺度噪声叠加

动画支持：时间维度变化

4. 物理基础渲染(PBR)
javascript
duck.material = new THREE.MeshPhysicalNodeMaterial();
duck.material.ior = 1.5;
duck.material.transmission = 1;
透射率：控制光线穿透程度

折射率：影响光线偏折角度

粗糙度：影响表面的光滑程度

5. 抗条带技术
javascript
volumetricMaterial.offsetNode = bayer16(screenCoordinate.add(frameId));
有序抖动：使用16x16 Bayer矩阵

时间变化：每帧不同的抖动模式

减少量化误差：在低精度渲染中特别重要

6. 分层渲染系统
javascript
const LAYER_VOLUMETRIC_LIGHTING = 10;
volumetricLayer.enable(LAYER_VOLUMETRIC_LIGHTING);
渲染隔离：不同效果独立渲染

性能优化：按需渲染特定内容

合成控制：灵活的效果叠加

7. 动态资源加载
javascript
const gltf = await new GLTFLoader().loadAsync('./models/gltf/duck.glb');
异步加载：不阻塞主线程

Draco压缩：减小模型文件大小

渐进式加载：支持大型场景

四、渲染管线流程
text
1. 场景主渲染通道
   ↓
2. 体积光照专用通道（半分辨率）
   ↓
3. Bloom泛光处理（高斯模糊mip链）
   ↓
4. 通道合成（体积光 + 主场景）
   ↓
5. 最终输出到屏幕
五、性能优化策略
1. 分辨率优化
javascript
volumetricPass.setResolutionScale(.5);  // 体积效果使用半分辨率
原因：体积效果对分辨率不敏感

节省：减少75%像素处理（0.5×0.5=0.25）

2. 渲染目标复用
深度缓冲区在多个通道间共享

纹理内存高效利用

3. GPU计算优化
WebGPU的并行计算能力

计算着色器用于复杂的光线步进

4. 细节层次控制
根据不同效果调整采样精度

动态调整光线步进步数

六、关键技术亮点
1. 实时体积效果
传统体积渲染通常是预计算的

本项目实现了实时动态体积效果

支持交互式参数调整

2. 物理准确性
基于物理的折射计算

能量守恒的光照模型

真实的材质属性

3. 艺术可控性
javascript
gui.add(causticOcclusion, 'value', 0, 20).name('焦散遮蔽强度');
实时参数调整界面

艺术指导与物理准确性的平衡

即时反馈的效果预览

4. 现代Web图形栈
ES6模块化开发

Import Maps依赖管理

响应式设计支持 -->


<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <!-- 
        页面基础元数据设置
        - title: 页面标题，显示在浏览器标签页上
        - charset: 字符编码，UTF-8支持中文等多语言字符
        - viewport: 视口设置，用于移动端适配，禁用用户缩放功能
    -->
    <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样式文件
        - type: 指定MIME类型为text/css
        - rel: 定义与当前文档的关系为样式表
        - href: 样式文件路径，包含页面的布局和视觉效果定义
    -->
    <link type="text/css" rel="stylesheet" href="example.css">
</head>
<body>

    <!-- 
        页面顶部信息展示区域
        - id="info": 用于CSS样式选择和JavaScript操作的标识符
        包含：Three.js徽标链接、标题区域、描述信息
    -->
    <div id="info">
        <!-- 
            Three.js官方徽标链接
            - href: 点击后跳转到Three.js官网
            - target="_blank": 在新标签页中打开链接
            - rel="noopener": 安全设置，防止新页面访问原页面的window.opener
            - class="logo-link": CSS类名，用于设置徽标的背景图片和样式
        -->
        <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标签：语义化表示次要、附属信息
            内容：实时体积焦散效果渲染技术展示
        -->
        <small>实时体积焦散效果渲染技术展示</small>
        
        <!-- 新增技术特性说明 -->
        <div class="tech-info" style="margin-top: 30px;">
            <p>本示例展示了以下高级图形技术：</p>
            <ul>
                <li>WebGPU实时渲染</li>
                <li>物理精确的折射和焦散效果</li>
                <li>动态体积雾模拟</li>
                <li>TSL着色器编程</li>
                <li>后处理特效（泛光、色差）</li>
            </ul>
            <p>使用鼠标或触摸屏可以旋转、缩放查看场景</p>
        </div>
    </div>

    <!-- 
        Import Maps配置
        - type="importmap": HTML5新特性，定义模块导入的映射关系
        作用：将导入标识符（如"three"）映射到实际的文件路径
        好处：避免硬编码路径，便于维护和版本管理
    -->
    <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">
        // ========== 模块导入区域 ==========
        // 这些导入语句在Import Maps解析后执行
        
        // 导入Three.js WebGPU版本的核心库
        // * as THREE: 将所有导出内容作为THREE命名空间的对象
        import * as THREE from 'three/webgpu';

        // 导入TSL（Three.js Shader Language）着色器节点
        // 这些是用于构建着色器图的函数和类
        import {
            uniform,     // 创建uniform变量，用于CPU向GPU传递数据
            refract,     // 折射函数，计算光线折射方向
            div,         // 除法运算节点
            frameId,     // 当前帧编号，用于时间相关效果
            lightViewPosition, // 灯光在视图空间的位置
            float,       // 浮点数节点
            positionView,      // 视图空间位置
            positionViewDirection, // 视图空间方向向量
            screenUV,    // 屏幕UV坐标(0-1范围)
            pass,        // 渲染通道节点，用于多pass渲染
            texture3D,   // 3D纹理采样节点
            time,        // 时间变量，用于动画
            screenCoordinate, // 屏幕坐标
            normalView,  // 视图空间法线
            texture,     // 2D纹理采样节点
            Fn,          // 函数定义节点
            vec2,        // 二维向量
            vec3         // 三维向量
        } from 'three/tsl';

        // 导入Three.js的附加功能（addons）
        // 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';
        // ImprovedNoise: 改进的Perlin噪声生成器，用于程序化纹理
        import { ImprovedNoise } from 'three/addons/math/ImprovedNoise.js';
        // Inspector: 调试检查器，用于查看和调整渲染参数
        import { Inspector } from 'three/addons/inspector/Inspector.js';

        // 导入TSL的数学和显示节点
        // bayer16: 16x16 Bayer矩阵，用于有序抖动，减少渲染条带效应
        import { bayer16 } from 'three/addons/tsl/math/Bayer.js';
        // bloom: Bloom效果节点，创建泛光/光晕效果
        import { bloom } from 'three/addons/tsl/display/BloomNode.js';

        // ========== 全局变量声明 ==========
        // 这些变量在整个模块中共享使用
        let camera;      // 相机对象，定义观察视角
        let scene;       // 场景对象，包含所有3D对象、灯光、相机
        let renderer;    // 渲染器，负责将3D场景渲染到2D画布
        let controls;    // 用户交互控制器
        let postProcessing; // 后处理系统，管理渲染后的特效处理
        let gltf;        // 加载的GLTF模型对象

        // ========== 初始化函数调用 ==========
        // 程序入口点，页面加载后自动执行
        init();

        // ========== 异步初始化函数 ==========
        // async关键字：支持await语法，用于处理异步操作（如模型加载）
        async function init() {
            // 定义渲染层常量
            // 使用分层渲染技术：不同物体可以渲染到不同层，实现特殊效果
            const LAYER_VOLUMETRIC_LIGHTING = 10;

            // ========== 创建相机 ==========
            // PerspectiveCamera: 透视相机，模拟人眼视角
            // 参数：FOV视场角25度、宽高比、近裁剪面0.025、远裁剪面5
            camera = new THREE.PerspectiveCamera(25, window.innerWidth / window.innerHeight, 0.025, 5);
            // 设置相机初始位置：x=-0.7, y=0.2, z=0.2
            camera.position.set(-0.7, 0.2, 0.2);

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

            // ========== 灯光设置 ==========
            // SpotLight: 聚光灯，模拟手电筒或舞台灯光效果
            const spotLight = new THREE.SpotLight(0xffffff, 1);
            // 灯光位置
            spotLight.position.set(.2, .3, .2);
            // 启用阴影投射：灯光会为物体生成阴影
            spotLight.castShadow = true;
            // 灯光角度：照射范围，π/6表示30度锥角
            spotLight.angle = Math.PI / 6;
            // 半影区：光照边缘的柔和过渡区域，1表示完全柔和
            spotLight.penumbra = 1;
            // 衰减系数：光线随距离减弱的程度，2表示平方反比衰减
            spotLight.decay = 2;
            // 照射距离：0表示无限远
            spotLight.distance = 0;
            // 阴影贴图类型：HalfFloatType支持高动态范围(HDR)
            spotLight.shadow.mapType = THREE.HalfFloatType;
            // 阴影贴图分辨率：1024x1024像素，越高阴影越清晰
            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.95表示阴影略微透明
            spotLight.shadow.intensity = .95;
            // 启用体积光照层：只有在这个层的物体会被体积光照影响
            spotLight.layers.enable(LAYER_VOLUMETRIC_LIGHTING);
            // 将灯光添加到场景
            scene.add(spotLight);

            // ========== 模型加载 ==========
            // 配置DRACO解码器：用于解压Google的Draco压缩格式3D模型
            const dracoLoader = new DRACOLoader();
            // 设置解码器文件路径
            dracoLoader.setDecoderPath('jsm/libs/draco/');
            // 配置使用JavaScript版本解码器（相对WASM版本）
            dracoLoader.setDecoderConfig({ type: 'js' });

            // 异步加载GLTF模型
            // 使用await等待模型加载完成，期间不阻塞其他代码执行
            gltf = (await new GLTFLoader()
                .setDRACOLoader(dracoLoader)  // 设置DRACO解码器
                .loadAsync('./models/gltf/duck.glb'))  // 加载模型文件
                .scene;  // 获取场景对象
            
            // 缩放模型：将模型缩小到原来的一半
            gltf.scale.setScalar(.5);
            // 将模型添加到主场景
            scene.add(gltf);

            // ========== 纹理加载 ==========
            // 加载焦散贴图：用于模拟光线通过水或其他介质产生的图案
            const causticMap = new THREE.TextureLoader().load('./textures/opengameart/Caustic_Free.jpg');
            // 设置纹理包裹方式：RepeatWrapping表示平铺重复
            causticMap.wrapS = causticMap.wrapT = THREE.RepeatWrapping;
            // 设置颜色空间：SRGBColorSpace适用于颜色纹理
            causticMap.colorSpace = THREE.SRGBColorSpace;

            // ========== 材质设置 ==========
            // 获取鸭子模型（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表示完全透明，模拟玻璃材质
            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控制
            const causticOcclusion = uniform(1);

            // 定义焦散效果函数
            // Fn: TSL中的函数定义器，创建一个可重用的着色器函数
            const causticEffect = Fn(() => {
                // 计算折射向量：模拟光线通过透明介质的折射
                // refract(入射方向, 法线, 折射率比) -> 折射方向
                const refractionVector = refract(
                    positionViewDirection.negate(), // 取反的视线方向
                    normalView,                     // 视图空间法线
                    div(1.0, duck.material.ior)    // 折射率比（空气/材质）
                ).normalize();  // 归一化为单位向量

                // 计算视图深度：基于法线的Z分量，用于控制焦散强度随角度变化
                // pow函数：使效果随角度变化更明显
                const viewZ = normalView.z.pow(causticOcclusion);

                // 计算纹理UV坐标：基于折射向量
                const textureUV = refractionVector.xy.mul(.6);

                // 创建材质颜色uniform
                const causticColor = uniform(duck.material.color);
                
                // 计算色差（色散）偏移：模拟不同波长光线的折射差异
                // 正常情况：蓝色光折射角度最大，红色最小
                const chromaticAberrationOffset = normalView.z.pow(- .9).mul(.004);

                // 创建色差效果：对RGB通道分别采样，偏移量不同
                const causticProjection = vec3(
                    // 红色通道：负X偏移
                    texture(causticMap, textureUV.add(vec2(chromaticAberrationOffset.negate(), 0))).r,
                    // 绿色通道：负Y偏移
                    texture(causticMap, textureUV.add(vec2(0, chromaticAberrationOffset.negate()))).g,
                    // 蓝色通道：正X,Y偏移
                    texture(causticMap, textureUV.add(vec2(chromaticAberrationOffset, chromaticAberrationOffset))).b
                );

                // 返回最终的焦散颜色
                // mul(60): 增强效果强度
                // add(viewZ): 添加基础亮度
                // mul(causticColor): 应用材质颜色
                return causticProjection
                    .mul(viewZ.mul(60))
                    .add(viewZ)
                    .mul(causticColor);
            })().toVar();  // 立即执行函数并转换为变量

            // 将焦散效果应用到阴影投射节点
            duck.material.castShadowNode = causticEffect;

            // 定义自发光节点：用于模拟材质内部的散射光
            duck.material.emissiveNode = Fn(() => {
                // 厚度幂次参数：控制背面发光效果的衰减程度
                const thicknessPowerNode = float(3.0);

                // 计算散射向量：从当前点到灯光的方向
                const scatteringHalf = lightViewPosition(spotLight)
                    .sub(positionView)  // 计算方向向量
                    .normalize();       // 归一化

                // 计算散射点积：视线方向与散射方向的点积
                // saturate(): 限制在0-1范围
                // pow(): 应用厚度衰减
                const scatteringDot = float(
                    positionViewDirection
                        .dot(scatteringHalf.negate())  // 计算点积（取反）
                        .saturate()
                        .pow(thicknessPowerNode)
                );

                // 返回自发光颜色：基于焦散效果和散射强度
                return causticEffect
                    .mul(scatteringDot.add(.1))  // 加0.1保证基础亮度
                    .mul(.02);                   // 整体强度减弱
            })();

            // ========== 地面设置 ==========
            // 加载地面纹理：木地板贴图
            const textureLoader = new THREE.TextureLoader();
            const map = textureLoader.load('textures/hardwood2_diffuse.jpg');
            map.wrapS = map.wrapT = THREE.RepeatWrapping;  // 重复平铺
            map.repeat.set(10, 10);  // 在U和V方向各重复10次

            // 创建地面几何体：2x2单位的平面
            const geometry = new THREE.PlaneGeometry(2, 2);
            // 创建标准材质：黑色基础色，纹理会覆盖它
            const material = new THREE.MeshStandardMaterial({ color: 0 });

            // 创建地面网格对象
            const ground = new THREE.Mesh(geometry, material);
            // 旋转地面：使其水平（原始平面是垂直的）
            ground.rotation.x = -Math.PI / 2;
            // 启用阴影接收：地面会接收其他物体投射的阴影
            ground.receiveShadow = true;
            scene.add(ground);

            // ========== 渲染器设置 ==========
            // 创建WebGPURenderer：使用WebGPU API的渲染器
            // antialias: true 启用抗锯齿
            renderer = new THREE.WebGPURenderer({ antialias: true });
            // 启用阴影映射
            renderer.shadowMap.enabled = true;
            // 附加调试检查器
            renderer.inspector = new Inspector();
            // 设置设备像素比：匹配屏幕物理像素与CSS像素比例
            renderer.setPixelRatio(window.devicePixelRatio);
            // 设置渲染尺寸为整个窗口
            renderer.setSize(window.innerWidth, window.innerHeight);
            // 设置动画循环回调函数：每帧自动调用animate()
            renderer.setAnimationLoop(animate);
            // 将渲染器的canvas元素添加到页面body
            document.body.appendChild(renderer.domElement);

            // ========== GUI调试界面 ==========
            // 创建参数面板：用于实时调整效果参数
            const gui = renderer.inspector.createParameters('体积焦散参数');
            // 添加焦散遮蔽控制滑块：范围0-20
            gui.add(causticOcclusion, 'value', 0, 20).name('焦散遮蔽强度');
            // 添加材质颜色拾取器
            gui.addColor(duck.material, 'color').name('材质颜色');

            // ========== 后处理设置 ==========
            // 创建后处理系统：管理渲染管线中的后期特效
            postProcessing = new THREE.PostProcessing(renderer);

            // ========== 体积光照层设置 ==========
            // 体积光照强度参数：控制体积雾的亮度
            const volumetricLightingIntensity = uniform(.7);

            // 创建渲染层对象：用于选择性地渲染特定物体
            const volumetricLayer = new THREE.Layers();
            volumetricLayer.disableAll();  // 禁用所有层
            volumetricLayer.enable(LAYER_VOLUMETRIC_LIGHTING);  // 启用体积光照层

            // ========== 体积雾效果 ==========
            // 创建3D噪声纹理函数：用于生成体积雾的密度分布
            function createTexture3D() {
                let i = 0;  // 数据索引
                const size = 128;  // 纹理每维度像素数
                // 创建数据数组：size³个8位无符号整数
                const data = new Uint8Array(size * size * size);

                const scale = 10;  // 噪声缩放因子
                const perlin = new ImprovedNoise();  // Perlin噪声生成器
                const repeatFactor = 5.0;  // 噪声重复因子

                // 三层嵌套循环：遍历3D纹理的所有体素
                for (let z = 0; z < size; z++) {
                    for (let y = 0; y < size; y++) {
                        for (let x = 0; x < size; x++) {
                            // 归一化坐标并应用重复因子
                            const nx = (x / size) * repeatFactor;
                            const ny = (y / size) * repeatFactor;
                            const nz = (z / size) * repeatFactor;

                            // 生成Perlin噪声值：范围[-1, 1]
                            const noiseValue = perlin.noise(
                                nx * scale,
                                ny * scale,
                                nz * scale
                            );

                            // 映射到[0, 255]范围：128 + 128*noise
                            data[i] = (128 + 128 * noiseValue);
                            i++;  // 移动到下一个数据位置
                        }
                    }
                }

                // 创建3D纹理对象
                const texture = new THREE.Data3DTexture(
                    data,    // 纹理数据
                    size,    // 宽度
                    size,    // 高度
                    size     // 深度
                );
                texture.format = THREE.RedFormat;  // 单通道格式
                texture.minFilter = THREE.LinearFilter;  // 缩小过滤器
                texture.magFilter = THREE.LinearFilter;  // 放大过滤器
                texture.wrapS = THREE.RepeatWrapping;  // X轴循环
                texture.wrapT = THREE.RepeatWrapping;  // Y轴循环
                texture.unpackAlignment = 1;  // 内存对齐
                texture.needsUpdate = true;   // 标记需要上传到GPU

                return texture;
            }

            // 生成3D噪声纹理
            const noiseTexture3D = createTexture3D();
            // 烟雾密度参数：控制体积雾的浓度
            const smokeAmount = uniform(3);

            // 创建体积材质：用于渲染体积效果（雾、烟等）
            const volumetricMaterial = new THREE.VolumeNodeMaterial();
            volumetricMaterial.steps = 20;  // 光线步进次数，影响质量/性能
            // 添加抖动偏移：使用Bayer矩阵减少条带伪影
            volumetricMaterial.offsetNode = bayer16(
                screenCoordinate.add(frameId)  // 加入帧编号实现动画
            );
            
            // 设置散射节点：定义体积雾如何散射光线
            volumetricMaterial.scatteringNode = Fn(({ positionRay }) => {
                // 创建时间缩放向量：不同分量有不同速度，创造动态效果
                const timeScaled = vec3(
                    time.mul(.01),  // X轴时间缩放
                    0,              // Y轴无时间变化
                    time.mul(.03)   // Z轴时间缩放（不同速度）
                );

                // 定义噪声采样函数：用于创建多尺度噪声
                const sampleGrain = (scale, timeScale = 1) =>
                    // 采样3D纹理：坐标=位置×缩放+时间偏移，取模1实现平铺
                    texture3D(
                        noiseTexture3D,
                        positionRay
                            .add(timeScaled.mul(timeScale))
                            .mul(scale)
                            .mod(1),
                        0  // mipmap级别
                    ).r.add(.5);  // 调整到[0.5, 1.5]范围

                // 多尺度噪声叠加：创建更自然的湍流效果
                // 1. 基础噪声（大尺度结构）
                let density = sampleGrain(1);
                // 2. 中尺度细节
                density = density.mul(sampleGrain(.5, 1));
                // 3. 小尺度细节
                density = density.mul(sampleGrain(.2, 2));

                // 混合烟雾参数：在常数1和噪声密度之间插值
                // mix(a, b, t) = a*(1-t) + b*t
                return smokeAmount.mix(1, density);
            });

            // 创建体积雾网格：一个长方体区域，包含体积雾
            const volumetricMesh = new THREE.Mesh(
                new THREE.BoxGeometry(1.5, .5, 1.5),  // 几何体
                volumetricMaterial                    // 体积材质
            );
            volumetricMesh.receiveShadow = true;  // 接收阴影
            volumetricMesh.position.y = .25;      // 设置位置（略高于地面）
            volumetricMesh.layers.disableAll();   // 禁用所有渲染层
            volumetricMesh.layers.enable(LAYER_VOLUMETRIC_LIGHTING);  // 启用体积层
            scene.add(volumetricMesh);

            // ========== 场景渲染通道 ==========
            // 创建场景主渲染通道：渲染所有常规物体
            const scenePass = pass(scene, camera).toInspector();
            scenePass.name = '主场景';  // 在调试器中显示的名称

            // 获取场景深度纹理：用于后续的深度测试
            const sceneDepth = scenePass.getTextureNode('depth');
            sceneDepth.name = '场景深度';  // 纹理命名

            // 将场景深度应用到体积材质：体积雾不应该渲染在物体后面
            volumetricMaterial.depthNode = sceneDepth.sample(screenUV);

            // ========== 体积光照渲染通道 ==========
            // 创建专门的体积光照渲染通道
            // depthBuffer: false - 不使用深度缓冲（体积效果需要与主场景融合）
            // samples: 0 - 不使用多重采样（性能优化）
            const volumetricPass = pass(scene, camera, {
                depthBuffer: false,
                samples: 0
            }).toInspector('体积光照 / 原始效果');
            volumetricPass.name = '体积光照';
            volumetricPass.setLayers(volumetricLayer);  // 只渲染体积层物体
            volumetricPass.setResolutionScale(.5);      // 半分辨率渲染（性能优化）

            // ========== 合成与降噪 ==========
            // 应用Bloom效果：创建泛光/光晕，增强视觉冲击力
            // 参数：输入纹理, 半径, 强度, 阈值
            const bloomPass = bloom(volumetricPass, 1, 1, 0)
                .toInspector('体积光照 / Mip链高斯模糊');
            bloomPass.name = '泛光效果';

            // 将Bloom效果合成到主场景：叠加体积光照效果
            const scenePassColor = scenePass.add(
                bloomPass.mul(volumetricLightingIntensity)  // 应用强度控制
            );

            // 设置后处理的最终输出节点
            postProcessing.outputNode = scenePassColor;

            // ========== 轨道控制器 ==========
            // 创建相机轨道控制器：允许用户用鼠标/触摸交互
            controls = new OrbitControls(camera, renderer.domElement);
            controls.target.z = -.05;  // 设置观察目标点（稍微向前）
            controls.target.y = .02;   // 稍微向上
            controls.maxDistance = 1;  // 最大缩放距离限制

            // ========== 窗口大小调整事件监听 ==========
            // 监听窗口大小变化，确保渲染正确适应
            window.addEventListener('resize', onWindowResize);
        }

        // ========== 窗口大小调整处理函数 ==========
        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) {
                mesh.rotation.y -= .01;  // 绕Y轴缓慢旋转
            }

            // 更新控制器状态：处理用户输入
            controls.update();
            
            // 执行后处理渲染：包含所有通道的合成
            postProcessing.render();
        }
    </script>
</body>
</html>