<!-- 代码功能描述
项目概述
这是一个基于Three.js WebGPU的选择性辉光效果演示应用，展示了如何使用现代图形技术实现部分物体发光的视觉效果。用户可以与场景中的球体交互，动态开关每个球体的辉光效果。

核心功能
1. 视觉效果
随机分布的球体场景：创建50个随机颜色、随机位置、随机大小的二十面体球体

选择性辉光：只有部分球体（初始50%）具有辉光效果

交互式控制：用户可以点击任意球体切换其辉光状态的开关

2. 交互功能
视角控制：鼠标拖拽旋转视角，滚轮缩放

物体交互：点击球体切换辉光效果（点击后辉光状态会反转）

参数调节：通过调试面板实时调整辉光参数和渲染设置

3. 用户界面
实时预览：同时显示颜色渲染结果和辉光强度蒙版

参数调节面板：可调节辉光阈值、强度、半径和曝光度

响应式设计：自动适应窗口大小变化

主要技术点
1. WebGPU渲染器
javascript
const renderer = new THREE.WebGPURenderer();
现代图形API：使用WebGPU替代传统的WebGL

性能优势：更好的多线程支持、更高效的显存管理

功能丰富：原生支持计算着色器等高级功能

2. MRT（多重渲染目标）技术
javascript
material.mrtNode = mrt({
    bloomIntensity: uniform(bloomIntensity)
});
原理：单次渲染输出多个缓冲区

实现：

主颜色缓冲区：存储场景的正常渲染结果

辉光强度缓冲区：存储每个像素是否应用辉光（0或1）

优势：避免重复渲染，提高性能

3. TSL（Three.js着色器语言）
javascript
import { pass, mrt, output, float, uniform } from 'three/tsl';
节点式着色器：可视化/节点式的着色器编程系统

优势：

无需直接编写复杂的GLSL代码

易于组合和复用着色器效果

更直观的视觉效果调试

4. 选择性辉光算法
javascript
const bloomPass = bloom(outputPass.mul(bloomIntensityPass));
实现流程：

场景渲染：渲染到MRT，同时输出颜色和辉光强度

辉光提取：颜色 × 辉光强度蒙版 → 只提取需要辉光的区域

高斯模糊：对提取的高亮区域进行模糊处理

最终合成：原始颜色 + 模糊后的辉光

5. 后处理管线
javascript
const postProcessing = new THREE.PostProcessing(renderer);
postProcessing.outputNode = outputPass.add(bloomPass).renderOutput();
模块化设计：每个处理效果都是独立的节点

可组合性：可以轻松添加其他后处理效果

高效渲染：自动优化渲染顺序和资源管理

6. 交互系统
javascript
// 光线投射检测
raycaster.setFromCamera(mouse, camera);
const intersects = raycaster.intersectObjects(scene.children, false);

// 切换辉光状态
bloomIntensity.value = bloomIntensity.value === 0 ? 1 : 0;
光线投射：将2D鼠标坐标转换为3D空间射线

物体拾取：检测射线与球体的交点

动态更新：实时修改材质的辉光强度参数

7. 色调映射
javascript
renderer.toneMapping = THREE.NeutralToneMapping;
HDR到LDR转换：将高动态范围颜色转换为显示器能显示的范围

中性映射：保持颜色相对关系，不添加过多艺术效果

8. 调试和参数调节
javascript
const gui = renderer.inspector.createParameters('设置面板');
实时调节：无需刷新页面即可看到参数变化效果

多参数控制：分组管理不同类型的参数

可视化反馈：同时显示多个渲染缓冲区

技术架构
text
用户交互层
    ↓
控制器层（OrbitControls + 点击事件）
    ↓
渲染管线层
    ├── 场景渲染（MRT输出）
    ├── 辉光提取（选择性蒙版）
    ├── 高斯模糊（辉光扩散）
    └── 最终合成（叠加效果）
    ↓
WebGPU渲染层
    ↓
显示输出层
性能优化
单次渲染多输出：MRT避免多次渲染相同场景

选择性处理：只对需要辉光的区域进行昂贵的模糊计算

WebGPU优化：利用现代GPU架构的并行处理能力

动态更新：只更新变化的材质参数，而不是整个着色器

应用场景
这种选择性辉光技术可以应用于：

游戏开发：突出显示重要物品、角色技能特效

数据可视化：高亮显示关键数据点

UI/UX设计：创建视觉层次，引导用户注意力

艺术创作：创建特殊的光效艺术

模拟仿真：模拟发光材料、能量源等 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：使用中文，说明这是一个使用WebGPU的Three.js示例，展示选择性辉光效果 -->
		<title>Three.js WebGPU 示例 - 选择性辉光效果 (Selective Bloom)</title>
		<!-- 字符编码设置为UTF-8，支持中文显示 -->
		<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官网，点击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>WebGPU - 选择性辉光效果</span>
			</div>

			<!-- 描述文字：解释这个示例使用的技术 -->
			<small>
				技术说明：使用MRT（多重渲染目标）技术控制每个物体是否受辉光效果影响。<br>
				交互操作：点击任意球体可以切换其辉光效果，使用鼠标可以旋转和缩放视图。
			</small>
			
		</div>

		<!-- 导入映射配置：定义模块导入的路径映射关系 -->
		<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
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js着色器语言）的核心功能：
			// - pass: 创建渲染通道
			// - mrt: 多重渲染目标（Multiple Render Targets），允许一次渲染输出多个纹理
			// - output: 输出节点
			// - float: 浮点数节点
			// - uniform: 统一值节点，可以在运行时修改
			import { pass, mrt, output, float, uniform } from 'three/tsl';
			
			// 导入辉光（Bloom）后处理节点，用于创建辉光效果
			// Bloom是一种后处理效果，模拟高光区域的溢出效果
			import { bloom } from 'three/addons/tsl/display/BloomNode.js';

			// 导入轨道控制器，用于通过鼠标控制相机旋转、缩放和平移
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入调试器/检查器，用于创建参数调节面板（类似dat.GUI）
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ============ 场景设置 ============
			// 创建一个新的3D场景，场景是所有3D对象的容器
			const scene = new THREE.Scene();

			// 创建透视相机：模拟人眼视角，有近大远小的效果
			// 参数说明：40=视野角度，window.innerWidth/window.innerHeight=宽高比，1=近裁剪面距离，200=远裁剪面距离
			const camera = new THREE.PerspectiveCamera(40, window.innerWidth / window.innerHeight, 1, 200);
			// 设置相机位置：在Z轴上向后移动20个单位
			camera.position.set(0, 0, 20);
			// 设置相机看向场景中心点(0,0,0)
			camera.lookAt(0, 0, 0);

			// 创建二十面体几何体：参数1=半径，参数2=细节级别（细分次数）
			// 二十面体是由20个等边三角形组成的多面体
			const geometry = new THREE.IcosahedronGeometry(1, 15);

			// ============ 创建场景物体 ============
			// 创建50个随机分布的球体
			for (let i = 0; i < 50; i++) {

				// 创建随机颜色：使用HSL颜色模型更容易生成美观的颜色
				// HSL代表色相(Hue)、饱和度(Saturation)、亮度(Lightness)
				const color = new THREE.Color();
				// 设置HSL值：随机色相，固定饱和度0.7，亮度在0.05-0.25之间随机
				color.setHSL(Math.random(), 0.7, Math.random() * 0.2 + 0.05);

				// 随机决定球体是否初始启用辉光效果
				// 50%的概率启用辉光（值为1），50%的概率不启用（值为0）
				const bloomIntensity = Math.random() > 0.5 ? 1 : 0;

				// 创建节点材质：MeshBasicNodeMaterial是基础节点材质
				// 节点材质使用TSL（Three.js着色器语言）系统，更灵活
				const material = new THREE.MeshBasicNodeMaterial({ color: color });
				
				// 设置MRT（多重渲染目标）节点
				// MRT允许在一次渲染中输出多个数据到不同的缓冲区
				// 这里我们输出两个缓冲区：颜色和辉光强度
				material.mrtNode = mrt({
					// bloomIntensity: 辉光强度值，uniform表示这是可以在运行时修改的统一值
					// 值为0表示该物体不受辉光影响，值为1表示完全受辉光影响
					bloomIntensity: uniform(bloomIntensity)
				});

				// 创建球体网格：将几何体和材质组合成可渲染的网格对象
				const sphere = new THREE.Mesh(geometry, material);
				
				// 随机设置球体位置（分三步）：
				// 1. 在-5到5的范围内随机生成位置
				sphere.position.x = Math.random() * 10 - 5;
				sphere.position.y = Math.random() * 10 - 5;
				sphere.position.z = Math.random() * 10 - 5;
				
				// 2. 将位置向量标准化（长度为1），然后乘以2-6之间的随机值
				// 这样确保球体分布在以原点为中心的球形区域内
				sphere.position.normalize().multiplyScalar(Math.random() * 4.0 + 2.0);
				
				// 3. 随机缩放球体大小：Math.random()*Math.random()产生更偏向小尺寸的分布
				sphere.scale.setScalar(Math.random() * Math.random() + 0.5);
				
				// 将球体添加到场景中
				scene.add(sphere);
			}

			// ============ 渲染器设置 ============
			// 创建WebGPU渲染器实例
			// WebGPU是新一代的图形API，相比WebGL有更好的性能和更现代的API设计
			const renderer = new THREE.WebGPURenderer();
			
			// 设置设备像素比，确保在高DPI显示器上清晰显示
			renderer.setPixelRatio(window.devicePixelRatio);
			
			// 设置渲染器尺寸为整个窗口大小
			renderer.setSize(window.innerWidth, window.innerHeight);
			
			// 设置动画循环回调函数，每一帧都会调用animate函数
			renderer.setAnimationLoop(animate);
			
			// 初始化调试器/检查器，用于创建参数调节面板
			renderer.inspector = new Inspector();
			
			// 设置色调映射：NeutralToneMapping是一种中性的色调映射算法
			// 色调映射用于将HDR（高动态范围）颜色转换为显示器能显示的LDR（低动态范围）颜色
			renderer.toneMapping = THREE.NeutralToneMapping;
			
			// 将渲染器的DOM元素（canvas画布）添加到页面body中
			document.body.appendChild(renderer.domElement);

			// ============ 后处理设置 ============
			// 创建场景渲染通道：将场景渲染到纹理中
			// pass函数创建一个渲染通道，输入是场景和相机
			const scenePass = pass(scene, camera);
			
			// 设置MRT（多重渲染目标）：定义渲染通道的输出
			// 这里设置两个输出目标：
			// 1. output: 主颜色输出，存储场景的正常渲染结果
			// 2. bloomIntensity: 辉光强度蒙版，存储每个像素是否应该应用辉光效果
			// float(0)表示默认值为0，即默认不应用辉光
			scenePass.setMRT(mrt({
				output,
				bloomIntensity: float(0)
			}));

			// 获取渲染纹理节点并连接到调试器显示：
			// 1. 获取主颜色输出纹理节点，并在调试器中命名为"Color"
			const outputPass = scenePass.getTextureNode().toInspector('Color');
			
			// 2. 获取辉光强度纹理节点，并在调试器中命名为"Bloom Intensity"
			// 这个纹理显示了哪些区域应该应用辉光效果（白色区域=应用辉光，黑色区域=不应用）
			const bloomIntensityPass = scenePass.getTextureNode('bloomIntensity').toInspector('Bloom Intensity');

			// 创建辉光效果：
			// bloom函数创建一个辉光后处理节点
			// outputPass.mul(bloomIntensityPass)：将颜色输出乘以辉光强度蒙版
			// 这意味着只有在辉光强度不为0的区域（bloomIntensityPass不为黑色）才会应用辉光效果
			// 这就是"选择性辉光"的核心实现
			const bloomPass = bloom(outputPass.mul(bloomIntensityPass));

			// 创建后处理管线：PostProcessing类管理整个后处理流程
			const postProcessing = new THREE.PostProcessing(renderer);
			
			// 禁用输出颜色变换，因为我们手动控制最终输出
			postProcessing.outputColorTransform = false;
			
			// 设置最终输出节点：
			// outputPass.add(bloomPass)：将原始颜色与辉光效果相加
			// .renderOutput()：将节点转换为可渲染的输出
			// 最终效果 = 原始场景 + 选择性辉光效果
			postProcessing.outputNode = outputPass.add(bloomPass).renderOutput();

			// ============ 控制器设置 ============
			// 创建轨道控制器：连接相机和渲染器的DOM元素
			// 允许用户通过鼠标拖拽、滚轮来控制相机
			const controls = new OrbitControls(camera, renderer.domElement);
			
			// 限制垂直旋转角度：最大90度（Math.PI * 0.5弧度）
			// 防止相机翻转到底部，造成视角混乱
			controls.maxPolarAngle = Math.PI * 0.5;
			
			// 设置相机与目标点的最小和最大距离
			controls.minDistance = 1;   // 最小缩放距离
			controls.maxDistance = 100; // 最大缩放距离

			// ============ 交互功能：点击切换辉光 ============
			// 创建光线投射器：用于检测鼠标点击与3D物体的交点
			const raycaster = new THREE.Raycaster();
			
			// 创建二维向量存储鼠标位置（标准化设备坐标）
			const mouse = new THREE.Vector2();

			// 监听鼠标点击事件
			window.addEventListener('pointerdown', (event) => {
				// 将鼠标点击位置从屏幕坐标转换为标准化设备坐标（NDC）
				// NDC范围：x从-1到1（左到右），y从-1到1（下到上）
				mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
				mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;

				// 从相机位置向鼠标点击方向发射一条射线
				raycaster.setFromCamera(mouse, camera);

				// 检测射线与场景中所有物体的交点
				// 参数说明：scene.children=所有子物体，false=不递归检测子物体的子物体
				const intersects = raycaster.intersectObjects(scene.children, false);

				// 如果有交点（点击到了物体）
				if (intersects.length > 0) {
					// 获取第一个交点（最前面的物体）的材质
					const material = intersects[0].object.material;

					// 获取材质的bloomIntensity统一值节点
					const bloomIntensity = material.mrtNode.get('bloomIntensity');
					
					// 切换辉光强度值：如果当前是0则改为1，如果是1则改为0
					// 实现点击物体时开关其辉光效果
					bloomIntensity.value = bloomIntensity.value === 0 ? 1 : 0;
				}
			});

			// ============ GUI调试面板设置 ============
			// 创建主设置面板
			const gui = renderer.inspector.createParameters('设置面板');

			// 创建辉光效果子面板
			const bloomFolder = gui.addFolder('辉光效果设置');
			
			// 添加辉光阈值控制：控制哪些亮度值会产生辉光
			// 只有亮度超过阈值的部分才会产生辉光效果
			bloomFolder.add(bloomPass.threshold, 'value', 0.0, 1.0).name('亮度阈值');
			
			// 添加辉光强度控制：控制辉光的整体强度
			bloomFolder.add(bloomPass.strength, 'value', 0.0, 3).name('辉光强度');
			
			// 添加辉光半径控制：控制辉光扩散的范围
			bloomFolder.add(bloomPass.radius, 'value', 0.0, 1.0).name('辉光半径');

			// 创建色调映射子面板
			const toneMappingFolder = gui.addFolder('色调映射设置');
			
			// 添加曝光度控制：调整整体画面亮度
			toneMappingFolder.add(renderer, 'toneMappingExposure', 0.1, 3).name('曝光度');

			// ============ 窗口大小变化处理 ============
			// 监听窗口大小变化事件，确保渲染器尺寸与窗口尺寸同步
			window.onresize = function () {
				// 获取当前窗口尺寸
				const width = window.innerWidth;
				const height = window.innerHeight;

				// 更新相机纵横比（Aspect Ratio）
				// 纵横比 = 宽度 / 高度，确保渲染画面不会拉伸变形
				camera.aspect = width / height;
				
				// 更新相机的投影矩阵（必须调用此方法才能使纵横比更改生效）
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				renderer.setSize(width, height);
			};

			// ============ 动画循环函数 ============
			// 每一帧渲染时调用的函数
			function animate() {
				// 执行后处理渲染：这会依次执行所有后处理效果
				// 包括场景渲染、辉光计算、最终合成等
				postProcessing.render();
			}

		</script>

	</body>

</html>