<!-- 代码功能详细描述
一、核心功能概述
这是一个使用Three.js WebGPU版本和TSL（Three.js Shading Language） 创建的高级自定义雾效系统演示。程序模拟了一个城市景观，包含动态变化的复杂雾效环境，用户可以通过交互控制相机视角探索场景。

二、主要视觉特效
1. 多层次动态雾效系统
距离雾（Distance Fog）：物体随距离相机越远，雾效越浓

地面雾（Ground Fog）：从地面向上逐渐变淡的雾层，模拟真实地面雾

动态噪声雾（Animated Noise Fog）：随时间变化的有机纹理雾，增加视觉复杂性和真实感

颜色渐变雾：雾的颜色从地面的灰蓝色渐变到天空的淡蓝色

2. 程序化生成的城市景观
4000个随机建筑：不同高度、大小的建筑实例

建筑窗户效果：基于楼层高度的条纹纹理，模拟建筑窗户

距离分布规则：离中心越远的建筑越高，创建自然的天际线

3. 交互与动态元素
自动旋转相机：场景缓慢自动旋转展示

用户交互控制：鼠标拖拽旋转、滚轮缩放

实时更新：雾效随时间动态变化，噪声纹理持续动画

三、主要技术点详解
1. WebGPU渲染引擎
javascript
// 使用下一代图形API WebGPU
import * as THREE from 'three/webgpu';
renderer = new THREE.WebGPURenderer({ antialias: true });
优势：

比WebGL更低的CPU开销

更好的多线程支持

更现代的GPU特性访问

计算着色器支持

2. TSL（Three.js Shading Language）
javascript
import { color, fog, float, positionWorld, triNoise3D } from 'three/tsl';
声明式着色器编程：在JavaScript中直接构建着色器图

节点化系统：每个着色器操作都是可连接的节点

实时编译：自动生成优化的GLSL/WebGPU着色器代码

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

3. 雾效着色器节点系统
javascript
// 复杂雾效的节点连接
scene.fogNode = fog(
    fogNoiseDistance.oneMinus().mix(groundColor, fogNoise),
    groundFogArea
);
数学运算链：.mul()、.add()、.sub()、.div()、.pow()

插值函数：.mix()、.smoothstep()、.saturate()

噪声生成：triNoise3D()三角形噪声

4. 实例化渲染技术
javascript
const buildMesh = new THREE.InstancedMesh(buildGeometry, buildMaterial, 4000);
高性能批量渲染：一次绘制调用渲染4000个建筑

矩阵实例化：每个实例有自己的变换矩阵

共享资源：所有实例共享相同的几何体和材质

GPU优化：减少CPU到GPU的数据传输

5. 程序化内容生成算法
javascript
// 建筑生成规则
const distanceToCenter = Math.max(dummy.position.distanceTo(center) * .012, 1);
dummy.scale.y = scaleY * distanceToCenter; // 距离越远建筑越高
伪随机分布：使用Math.random()但加入规则约束

参数化生成：基于距离和随机因子计算属性

程序化纹理：基于Y坐标生成建筑窗户图案

6. 高级着色器技术
噪声叠加：
javascript
const fogNoiseA = triNoise3D(positionWorld.mul(.005), 0.2, timer);
const fogNoiseB = triNoise3D(positionWorld.mul(.01), 0.2, timer.mul(1.2));
const fogNoise = fogNoiseA.add(fogNoiseB).mul(groundColor);
多频率噪声：低频+高频噪声叠加增加细节

时间动画：噪声随时间变化创建动态效果

世界空间坐标：使用世界坐标确保雾效与场景一致

距离衰减计算：
javascript
const fogNoiseDistance = positionView.z.negate().smoothstep(0, camera.far - 300);
视图空间深度：基于相机距离计算雾密度

平滑过渡：smoothstep()函数创建自然渐变

可调节参数：雾效范围和强度可调

7. 交互与性能优化
轨道控制器：
javascript
controls = new OrbitControls(camera, renderer.domElement);
controls.autoRotate = true;
controls.autoRotateSpeed = .1;
响应式设计：
javascript
window.addEventListener('resize', resize);
function resize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
}
8. 调试与开发工具
javascript
renderer.inspector = new Inspector();
内置检查器：按快捷键可查看场景层次结构

性能分析：实时监控渲染性能

着色器调试：查看生成的着色器代码

四、技术架构优势
模块化设计：

清晰的模块导入结构

功能分离明确

易于维护和扩展

性能优化：

WebGPU的并行处理能力

实例化渲染减少绘制调用

智能裁剪和剔除

可扩展性：

TSL节点系统易于修改和扩展

参数化设计方便调整效果

模块化架构支持功能添加

跨平台兼容：

WebGPU的广泛浏览器支持

响应式设计适应不同设备

优雅降级策略（如有需要）

五、实际应用场景
游戏开发：动态天气系统、环境氛围

数据可视化：三维数据雾效增强深度感知

建筑可视化：城市景观模拟、环境效果

艺术创作：程序化生成艺术、动态视觉

教育培训：计算机图形学教学示例

六、技术挑战与解决方案
挑战	解决方案
大量对象渲染性能	实例化网格 + WebGPU并行渲染
复杂雾效实时计算	TSL节点优化 + 着色器预编译
跨浏览器兼容性	WebGPU标准 + 优雅降级
内存管理	共享几何体/材质 + 智能缓存 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面基本信息 -->
		<!-- 修改标题为中文 -->
		<title>Three.js WebGPU - 自定义雾效演示</title>
		<meta charset="utf-8">
		<!-- 视口设置，确保WebGL/WebGPU画布正确显示 -->
		<!-- width=device-width: 宽度等于设备宽度 -->
		<!-- user-scalable=no: 禁止用户缩放 -->
		<!-- minimum-scale=1.0, maximum-scale=1.0: 固定缩放比例为1 -->
		<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>

		<!-- 页面左上角的信息面板，显示项目信息和链接 -->
		<!-- id="info": 用于CSS选择器定位 -->
		<!-- class="invert": 反转颜色样式类，通常用于暗色背景上的亮色文字 -->
		<div id="info" class="invert">
			<!-- 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">
				<!-- 主标题链接 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 页面副标题 -->
				<span> - 自定义雾效演示</span>
			</div>

			<!-- 描述文字 -->
			<small>
				使用TSL(Three.js着色器语言)创建的高级自定义雾效系统
				<br>
				（包含动态噪声、距离衰减和地面雾效）
			</small>
		</div>

		<!-- 导入映射表(Import Maps) -->
		<!-- 现代JavaScript模块系统特性，定义模块路径别名 -->
		<!-- 允许浏览器将模块标识符映射到实际URL -->
		<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是下一代图形API，替代WebGL，提供更好的性能和现代GPU特性支持
			import * as THREE from 'three/webgpu';
			
			// 从TSL模块导入各种着色器节点
			// TSL是一种声明式着色器语言，允许在JavaScript中构建着色器图
			import { 
				color,      // 颜色节点：创建颜色值
				fog,        // 雾效节点：创建雾效
				float,      // 浮点数节点：创建浮点数值
				positionWorld,  // 世界空间位置节点：片段在世界坐标系中的位置
				triNoise3D, // 3D三角形噪声节点：生成有机的噪声纹理
				positionView,   // 视图空间位置节点：片段在相机坐标系中的位置
				normalWorld,    // 世界空间法线节点：片段的法线方向
				uniform     // 统一变量节点：可在着色器外部设置的变量
			} from 'three/tsl';
			
			// 导入轨道控制器：允许用户用鼠标/触摸控制相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// 导入检查器：用于调试和查看场景状态
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ==================== 全局变量声明 ====================
			
			let camera;     // 相机对象：定义观察场景的视角
			let scene;      // 场景对象：包含所有3D对象、灯光和雾效
			let renderer;   // 渲染器对象：负责将3D场景绘制到2D画布上
			let controls;   // 控制器对象：用户交互控制

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

			// ==================== 初始化函数定义 ====================
			
			function init() {

				// ==================== 相机创建与设置 ====================
				
				// 创建透视相机(PerspectiveCamera)
				// 参数说明：
				// 45: 垂直视野角度(FOV)，单位度，45°是自然视野
				// window.innerWidth / window.innerHeight: 宽高比，保持画面不变形
				// 1: 近裁剪平面，距离相机1个单位以内的物体不显示
				// 600: 远裁剪平面，距离相机600个单位以外的物体不显示
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 1, 600);
				
				// 设置相机初始位置(x, y, z)
				// x=30: 右侧30个单位
				// y=15: 上方15个单位
				// z=30: 前方30个单位
				camera.position.set(30, 15, 30);

				// ==================== 场景创建 ====================
				
				// 创建场景容器，所有3D对象、灯光、雾效都将添加到这里
				scene = new THREE.Scene();

				// ==================== 自定义雾效实现 ====================
				// 这是本示例的核心部分，展示了如何使用TSL创建复杂雾效
				
				// 1. 定义基础颜色
				// color()函数创建颜色节点，参数是十六进制颜色值
				// skyColor: 天空颜色，淡蓝色调，用于远处和上方
				const skyColor = color(0xf0f5f5);
				// groundColor: 地面颜色，灰蓝色调，用于近处和下方
				const groundColor = color(0xd0dee7);

				// 2. 计算基于距离的雾效强度
				// positionView.z: 在相机坐标系中，z值表示深度（离相机的距离）
				// .negate(): 取反，因为positionView.z是负值（相机看向-z方向）
				// .smoothstep(0, camera.far - 300): 平滑插值函数
				//   将距离映射到[0, 1]范围，从0到(camera.far-300)平滑过渡
				// fogNoiseDistance: 值越大表示雾越浓，1表示完全被雾覆盖
				const fogNoiseDistance = positionView.z.negate().smoothstep(0, camera.far - 300);

				// 3. 计算地面雾效区域
				// 创建从地面向上逐渐变淡的雾效，模拟真实世界的地面雾
				const distance = fogNoiseDistance.mul(20).max(4); 
				// 将雾效距离乘以20，然后限制最小值至少为4
				// 这控制了地面雾的高度范围
				
				const alpha = .98; // 雾效最大不透明度
				
				// 复杂的地面雾计算：
				// float(distance): 将距离转换为浮点数节点
				// .sub(positionWorld.y): 减去当前片段的世界Y坐标
				// .div(distance): 除以距离，得到[0,1]范围的渐变
				// .pow(3): 三次方，创建更陡峭的衰减曲线
				// .saturate(): 限制结果在[0,1]范围
				// .mul(alpha): 乘以最大不透明度
				// 结果是：Y值越低（越接近地面），雾越浓；Y值越高，雾越淡
				const groundFogArea = float(distance)
					.sub(positionWorld.y)
					.div(distance)
					.pow(3)
					.saturate()
					.mul(alpha);

				// 4. 创建动画计时器
				// uniform(0): 创建一个初始值为0的统一变量
				// .onFrameUpdate(): 每帧更新回调函数
				// (frame) => frame.time: 将变量更新为当前时间（毫秒）
				// 这个计时器用于驱动噪声动画
				const timer = uniform(0).onFrameUpdate((frame) => frame.time);

				// 5. 创建两种不同频率的3D三角形噪声
				// triNoise3D(): 生成三角形噪声，比柏林噪声更快速，视觉上更有机
				// 参数1: 噪声坐标，positionWorld.mul(.005)将世界坐标缩小
				// 参数2: 噪声幅度，0.2
				// 参数3: 时间参数，驱动噪声动画
				
				// 低频噪声：坐标缩放0.005，随时间缓慢变化
				const fogNoiseA = triNoise3D(positionWorld.mul(.005), 0.2, timer);
				// 高频噪声：坐标缩放0.01，随时间较快变化（乘以1.2倍速）
				const fogNoiseB = triNoise3D(positionWorld.mul(.01), 0.2, timer.mul(1.2));

				// 6. 混合噪声并应用地面颜色
				// 将两种噪声相加，增加复杂性
				// 然后乘以地面颜色，使噪声呈现地面色调
				const fogNoise = fogNoiseA.add(fogNoiseB).mul(groundColor);

				// 7. 将自定义雾效应用到场景
				// fogNoiseDistance.oneMinus(): 1 - fogNoiseDistance，反转距离权重
				// .mix(groundColor, fogNoise): 混合地面颜色和噪声
				//   远处使用更多地面颜色，近处使用更多噪声
				// groundFogArea: 地面雾区域的不透明度
				scene.fogNode = fog(
					fogNoiseDistance.oneMinus().mix(groundColor, fogNoise),
					groundFogArea
				);

				// 8. 设置动态背景
				// normalWorld.y: 世界坐标系中的法线Y分量（向上方向）
				// .max(0): 只取正值（朝上的面）
				// .mix(groundColor, skyColor): 混合地面色和天空色
				//   法线朝上（水平面）显示天空色，法线朝下（底面）显示地面色
				// 创建地平线渐变效果
				scene.backgroundNode = normalWorld.y.max(0).mix(groundColor, skyColor);

				// ==================== 创建建筑群 ====================
				// 使用实例化渲染技术高效绘制大量相似建筑

				// 1. 创建建筑窗户效果着色器
				// 基于Y坐标创建条纹模式，模拟不同楼层的窗户
				const buildWindows = positionWorld.y
					.mul(10)        // 乘以10，将每0.1个单位作为一个楼层
					.floor()        // 向下取整，得到楼层编号
					.mod(4)         // 对4取模，每4层一个模式循环
					.sign()         // 取符号，将非零值转为1，零值保持0
					.mix(           // 混合函数，根据条件选择颜色
						color(0x000066).add(fogNoiseDistance),  // 条件为0时的颜色：深蓝色加雾效影响
						color(0xffffff)                         // 条件为1时的颜色：纯白色
					);
				// 效果：每4层中，有一层是白色窗户（可能表示亮灯），其他是深蓝色

				// 2. 创建建筑几何体和材质
				// 立方体几何体，作为建筑的基本形状
				const buildGeometry = new THREE.BoxGeometry(1, 1, 1);
				
				// MeshPhongNodeMaterial：支持TSL节点的Phong材质
				// Phong光照模型包含环境光、漫反射和高光反射
				const buildMaterial = new THREE.MeshPhongNodeMaterial({
					colorNode: buildWindows  // 使用上面定义的窗户着色器节点
				});

				// 3. 创建实例化网格
				// InstancedMesh：高效渲染大量相同几何体的技术
				// 参数：几何体、材质、实例数量
				// 所有实例共享几何体和材质，但可以有不同的变换矩阵
				const buildMesh = new THREE.InstancedMesh(buildGeometry, buildMaterial, 4000);
				scene.add(buildMesh);

				// 4. 为每个建筑实例设置随机属性
				const dummy = new THREE.Object3D();  // 临时对象，用于计算变换
				const center = new THREE.Vector3();   // 场景中心点(0,0,0)

				// 遍历所有4000个实例
				for (let i = 0; i < buildMesh.count; i++) {

					// 随机生成建筑高度：0.5到7.5之间
					const scaleY = Math.random() * 7 + .5;

					// 随机生成X和Z坐标：-300到300之间
					dummy.position.x = Math.random() * 600 - 300;
					dummy.position.z = Math.random() * 600 - 300;

					// 根据距离场景中心的远近调整建筑高度
					// 距离乘以0.012，至少为1
					// 效果：离中心越远，建筑越高
					const distanceToCenter = Math.max(dummy.position.distanceTo(center) * .012, 1);
					
					// 设置建筑Y坐标：基础高度的一半乘以距离因子
					// 确保建筑底部在地面上
					dummy.position.y = .5 * scaleY * distanceToCenter;

					// 随机生成建筑宽度和深度：0.5到3.5之间
					dummy.scale.x = dummy.scale.z = Math.random() * 3 + .5;
					// 建筑高度：基础高度乘以距离因子
					// 离中心越远的建筑越高
					dummy.scale.y = scaleY * distanceToCenter;

					// 更新变换矩阵
					// 将位置、旋转、缩放信息转换为4x4变换矩阵
					dummy.updateMatrix();

					// 将变换矩阵设置到实例化网格
					// 每个实例都有自己的变换矩阵
					buildMesh.setMatrixAt(i, dummy.matrix);
				}

				// ==================== 光源设置 ====================
				
				// 创建半球光(HemisphereLight)
				// 模拟天空和地面的环境光照
				// 参数：天空颜色、地面颜色、光照强度
				scene.add(new THREE.HemisphereLight(
					skyColor.value,    // 从TSL颜色节点获取实际颜色值
					groundColor.value, // 从TSL颜色节点获取实际颜色值
					0.5                // 光照强度
				));

				// ==================== 创建地面 ====================
				
				// 1. 创建地面几何体和材质
				const planeGeometry = new THREE.PlaneGeometry(200, 200);  // 200x200的平面
				const planeMaterial = new THREE.MeshPhongMaterial({
					color: 0x999999  // 中灰色
				});

				// 2. 创建地面网格对象
				const ground = new THREE.Mesh(planeGeometry, planeMaterial);
				ground.rotation.x = -Math.PI / 2;  // 旋转-90度，使平面水平
				ground.scale.multiplyScalar(3);    // 放大3倍，变为600x600
				ground.castShadow = true;          // 地面投射阴影
				ground.receiveShadow = true;       // 地面接收阴影
				scene.add(ground);

				// ==================== 渲染器设置 ====================
				
				// 创建WebGPU渲染器
				// WebGPU是下一代图形API，提供比WebGL更好的性能
				renderer = new THREE.WebGPURenderer({
					antialias: true  // 开启抗锯齿，平滑边缘
				});
				
				// 设置设备像素比，适应高DPI屏幕（如Retina显示屏）
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器大小为整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// 替代传统的requestAnimationFrame，WebGPU专用方法
				renderer.setAnimationLoop(animate);
				
				// 附加检查器工具，用于调试
				// 按特定快捷键（通常是Ctrl+Shift+I）可以打开调试面板
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild(renderer.domElement);

				// ==================== 轨道控制器设置 ====================
				
				// 创建轨道控制器，将相机与渲染器画布关联
				controls = new OrbitControls(camera, renderer.domElement);
				controls.target.set(0, 2, 0);              // 设置控制目标点（相机围绕旋转的点）
				controls.minDistance = 7;                  // 最小缩放距离，相机不能比这更近
				controls.maxDistance = 100;                // 最大缩放距离，相机不能比这更远
				controls.maxPolarAngle = Math.PI / 2;      // 最大极角，限制相机不能看到地面以下
				controls.autoRotate = true;                // 启用自动旋转，场景会自动缓慢旋转
				controls.autoRotateSpeed = .1;             // 自动旋转速度，值越大旋转越快
				controls.update();                         // 初始化更新控制器状态

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

			// ==================== 窗口大小调整处理函数 ====================
			
			function resize() {
				// 更新相机宽高比，防止画面拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵
				// 必须在更改相机参数后调用，使更改生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器大小，填满整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			// ==================== 动画循环函数 ====================
			
			function animate() {
				// 更新轨道控制器状态
				// 处理用户输入（鼠标拖动、滚轮缩放等）
				controls.update();
				
				// 渲染场景
				// 将3D场景通过相机视角渲染到2D画布上
				renderer.render(scene, camera);
				
				// 注意：这里没有使用requestAnimationFrame
				// 因为使用了WebGPU的setAnimationLoop，它会自动循环调用此函数
			}

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