<!-- Three.js WebGPU 遮挡检测示例 - 详细功能与技术点分析
一、核心功能概述
1. 主要功能
这是一个基于Three.js和WebGPU的3D遮挡检测可视化演示。场景包含一个平面和一个球体，当用户通过鼠标交互改变视角时，系统会实时检测球体是否被平面完全遮挡，并根据检测结果动态改变平面的颜色作为视觉反馈。

2. 用户交互体验
初始状态：平面显示蓝色，球体显示黄色

遮挡发生时：当球体完全位于平面后面（被遮挡），平面变为绿色

遮挡解除时：当球体至少部分可见，平面恢复蓝色

交互方式：用户可以通过鼠标旋转、缩放和平移视角，直观观察遮挡状态的变化

二、关键技术点详解
1. WebGPU图形API
javascript
renderer = new THREE.WebGPURenderer({ antialias: true });
下一代图形标准：取代WebGL的现代Web图形API

性能优势：更接近底层的硬件访问，更好的多线程支持

功能特性：原生计算着色器、更高效的资源管理

抗锯齿支持：通过参数开启，提供更平滑的视觉效果

2. 遮挡检测机制
javascript
const isOccluded = frame.renderer.isOccluded(this.testObject);
GPU遮挡查询：使用WebGPU的遮挡查询功能在GPU端执行检测

性能优化：避免CPU与GPU之间的数据传输开销

精确检测：基于深度缓冲区的像素级遮挡判断

异步操作：检测过程不阻塞主线程

3. TSL着色器语言系统
javascript
import { nodeObject, uniform } from 'three/tsl';
声明式着色器编程：用JavaScript语法编写着色器逻辑

节点化架构：将着色器功能分解为可重用的节点

实时编译：在运行时生成优化的GLSL/WebGPU代码

类型安全：强类型的着色器节点系统

4. 自定义着色器节点
javascript
class OcclusionNode extends THREE.Node
继承体系：基于Three.js的节点系统扩展

更新策略：updateType = THREE.NodeUpdateType.OBJECT 确保每帧更新

数据流：通过uniform节点将JavaScript数据传递到着色器

着色器集成：setup()方法定义节点在着色器中的行为

5. Phong光照模型
javascript
new THREE.MeshPhongNodeMaterial()
真实感渲染：模拟环境光、漫反射和高光效果

材质系统：与节点系统无缝集成

双面渲染：side: THREE.DoubleSide 确保平面两面都可见

6. 轨道控制器
javascript
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
直观交互：鼠标控制相机旋转、缩放、平移

距离限制：minDistance和maxDistance防止极端视角

平滑动画：内置惯性效果和动画插值

三、系统架构设计
1. 数据流架构
text
用户输入 → OrbitControls → 相机更新 → 渲染循环 → 遮挡检测 → 颜色更新 → 画面渲染
2. 核心组件交互
text
[OcclusionNode] ←检测结果→ [WebGPURenderer]
      ↓                             ↑
[平面材质颜色]                [遮挡查询API]
      ↓                             ↑
[视觉反馈]                   [GPU深度测试]
3. 渲染管线流程
几何处理：顶点着色器变换

光栅化：三角形转换为像素

深度测试：确定像素可见性

遮挡查询：执行GPU遮挡检测

片段着色：应用材质和颜色

输出合并：最终像素输出

四、性能优化特性
1. GPU端计算
遮挡检测在GPU端执行，减少CPU负担

避免CPU-GPU之间的数据回读开销

2. 高效更新机制
基于帧的更新：仅当需要时执行遮挡查询

条件渲染：只有遮挡状态变化时才更新材质

3. 内存管理
复用几何体和材质资源

自动垃圾回收管理WebGPU资源

五、扩展应用场景
1. 游戏开发
敌人AI：判断玩家是否可见

优化渲染：跳过被完全遮挡的物体渲染

特效管理：仅对可见物体应用昂贵特效

2. 虚拟现实
性能优化：避免渲染用户看不到的内容

交互反馈：视觉提示物体的可见状态

场景管理：动态加载/卸载基于可见性的资源

3. 数据可视化
层次筛选：自动隐藏被遮挡的数据点

焦点引导：突出显示重要的可见元素

交互分析：基于可见性的统计分析

4. 建筑与设计
视线分析：评估设计方案的视线遮挡

光照分析：模拟自然光遮挡效果

空间规划：优化布局避免不必要的遮挡

六、技术亮点总结
现代Web图形栈：Three.js + WebGPU + TSL的完整现代Web 3D方案

实时交互反馈：毫秒级的遮挡检测和视觉反馈

可扩展架构：模块化的节点系统便于功能扩展

跨平台兼容：基于Web标准，支持多种设备和浏览器

教育资源价值：展示了高级3D图形概念的完整实现

七、潜在改进方向
性能监控：添加FPS和GPU使用率显示

多物体检测：扩展支持多个物体的遮挡关系

渐进式遮挡：显示部分遮挡的渐变效果

移动端优化：针对触屏设备的交互优化

离线渲染：支持高质量截图和动画导出 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面标题：Three.js WebGPU 遮挡检测示例
			- three.js: JavaScript 3D库名称
			- webgpu: 使用的图形API（下一代Web图形API，替代WebGL）
			- occlusion: 遮挡检测技术，用于判断物体是否被其他物体完全遮挡
		-->
		<title>Three.js WebGPU - 遮挡检测演示</title>
		
		<!-- 
			字符编码设置：使用UTF-8编码支持多语言字符
			- UTF-8: 通用的Unicode字符编码，支持中文、英文等所有语言字符
		-->
		<meta charset="utf-8">
		
		<!-- 
			响应式视口配置：
			- width=device-width: 宽度等于设备宽度
			- user-scalable=no: 禁止用户手动缩放页面
			- minimum-scale=1.0: 最小缩放比例为1.0（不缩小）
			- maximum-scale=1.0: 最大缩放比例为1.0（不放大）
			这个设置确保3D场景在不同设备上保持固定比例，防止变形
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		
		<!-- 
			引入外部CSS样式表：
			- type="text/css": 指定样式表类型为CSS
			- rel="stylesheet": 定义当前文档与链接资源的关系为样式表
			- href="example.css": 外部CSS文件的路径，包含页面的布局和样式
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>
		<!-- 
			信息展示区域：
			- id="info": 用于CSS样式选择和JavaScript操作的元素标识
			- 包含页面标题、描述和Three.js链接
		-->
		<div id="info">
			<!-- 
				Three.js官方Logo链接：
				- href: 链接到Three.js官方网站
				- target="_blank": 在新标签页中打开链接
				- rel="noopener": 安全属性，防止新页面访问原页面的window对象
				- class="logo-link": CSS类名，通常用于设置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> - 遮挡检测示例</span>
			</div>

			<!-- 
				功能描述文本：
				- <small>: 表示旁注或小号字体文本
				- 描述示例的核心功能：当球体被完全遮挡时，平面颜色会改变
			-->
			<small>
				场景说明：拖动鼠标可以旋转视角，滚动鼠标可以缩放。<br>
				当黄色球体被蓝色平面完全遮挡时，平面将变为绿色。<br>
				尝试旋转视角，观察平面颜色如何根据遮挡状态变化。
			</small>
		</div>

		<!-- 
			Import Maps 配置：
			- 现代JavaScript模块导入映射系统，允许为模块指定别名或自定义路径
			- type="importmap": 声明这是一个导入映射配置
			- 作用：在浏览器中直接使用ES6模块时，定义模块的别名和路径
		-->
		<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核心模块
			 * - import * as THREE: 导入所有导出并命名为THREE对象
			 * - from 'three/webgpu': 从importmap中定义的路径导入WebGPU版本
			 * WebGPU是下一代Web图形API，提供更好的性能和更低的开销
			 */
			import * as THREE from 'three/webgpu';
			
			/*
			 * 从TSL库导入关键功能
			 * - nodeObject: 将TSL节点转换为Three.js对象，用于材质系统
			 * - uniform: 创建统一值节点，在着色器中表示不会变化的常量或每帧更新的值
			 * TSL允许以声明式方式构建着色器，无需编写GLSL代码
			 */
			import { nodeObject, uniform } from 'three/tsl';
			
			/*
			 * 导入轨道控制器
			 * - OrbitControls: 允许用户通过鼠标/触摸控制相机
			 * - 功能：左键旋转、右键平移、滚轮缩放
			 * - 从addons目录导入，这是Three.js的官方扩展
			 */
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ==================== 全局变量声明 ====================
			
			/*
			 * 全局场景变量声明（未初始化）
			 * - camera: 相机对象，定义观察3D场景的视角
			 * - scene: 场景对象，包含所有3D物体、光源等
			 * - renderer: 渲染器对象，负责将3D场景绘制到2D画布
			 * - controls: 控制器对象，处理用户交互
			 * 使用let而非const，因为这些变量需要在init函数中初始化
			 */
			let camera, scene, renderer, controls;

			// ==================== 自定义节点类 ====================
			
			/**
			 * OcclusionNode类 - 自定义遮挡检测着色器节点
			 * 
			 * 继承自THREE.Node，这是Three.js TSL系统的基础节点类
			 * 功能：根据目标物体是否被遮挡，动态改变材质颜色
			 * 
			 * 工作原理：
			 * 1. 每帧通过renderer.isOccluded()检测目标物体是否被遮挡
			 * 2. 根据检测结果选择不同的颜色
			 * 3. 将颜色值传递给着色器，实现视觉反馈
			 * 
			 * @extends THREE.Node
			 */
			class OcclusionNode extends THREE.Node {
				
				/**
				 * 构造函数：初始化遮挡检测节点
				 * 
				 * @param {THREE.Object3D} testObject - 需要检测遮挡状态的3D物体
				 *    - 在这个示例中是球体（sphere）
				 *    - 当该物体被完全遮挡时，会触发颜色变化
				 * 
				 * @param {THREE.Color} normalColor - 正常状态下的颜色
				 *    - 当testObject未被遮挡时使用的颜色
				 *    - 示例中为蓝色(0x0000ff)
				 * 
				 * @param {THREE.Color} occludedColor - 被遮挡状态下的颜色
				 *    - 当testObject被完全遮挡时使用的颜色
				 *    - 示例中为绿色(0x00ff00)
				 */
				constructor( testObject, normalColor, occludedColor ) {
					
					// 调用父类THREE.Node的构造函数
					// 参数'vec3'表示这个节点返回一个三维向量（RGB颜色）
					super( 'vec3' );
					
					/*
					 * 设置节点更新类型为OBJECT
					 * THREE.NodeUpdateType定义了节点何时更新：
					 * - OBJECT: 每帧为每个对象更新（最频繁）
					 * - FRAME: 每帧更新一次
					 * - RENDER: 每次渲染时更新
					 * - NONE: 从不自动更新
					 * 
					 * OBJECT类型适合需要每帧检测物体状态的逻辑
					 */
					this.updateType = THREE.NodeUpdateType.OBJECT;
					
					/*
					 * 创建统一值节点（Uniform Node）
					 * - uniform()函数创建一个可以在着色器中访问的统一值
					 * - 初始化为一个THREE.Color对象
					 * - 统一值在着色器执行期间保持不变（同一绘制调用中）
					 * - 但可以在JavaScript中每帧更新
					 */
					this.uniformNode = uniform( new THREE.Color() );
					
					// 保存参数到实例属性
					this.testObject = testObject;    // 要检测遮挡的物体
					this.normalColor = normalColor;  // 正常状态颜色
					this.occludedColor = occludedColor; // 遮挡状态颜色
				}
				
				/**
				 * 更新方法 - 每帧自动调用（因为updateType = OBJECT）
				 * 
				 * 功能：
				 * 1. 检测目标物体是否被遮挡
				 * 2. 根据检测结果更新颜色值
				 * 
				 * @param {Object} frame - 帧数据对象，包含当前帧的渲染信息
				 *    - frame.renderer: 当前渲染器实例
				 *    - 其他帧相关数据（时间、相机等）
				 * 
				 * @async 标记为异步函数，因为isOccluded()可能是异步操作
				 */
				async update( frame ) {
					
					/*
					 * 调用渲染器的isOccluded方法检测遮挡
					 * - isOccluded()是WebGPURenderer特有的方法
					 * - 返回布尔值：true表示完全遮挡，false表示可见
					 * - 原理：使用GPU的遮挡查询功能，性能比CPU检测高
					 */
					const isOccluded = frame.renderer.isOccluded( this.testObject );
					
					/*
					 * 根据遮挡状态设置颜色
					 * - 使用copy()方法复制颜色值，而不是直接赋值
					 * - 这是THREE.Color的标准做法，确保颜色对象正确更新
					 * - 条件运算符：如果被遮挡使用occludedColor，否则使用normalColor
					 */
					this.uniformNode.value.copy( isOccluded ? this.occludedColor : this.normalColor );
				}
				
				/**
				 * 设置方法 - 在着色器编译阶段调用
				 * 
				 * 功能：告诉Three.js如何将这个节点连接到着色器系统
				 * 在这个简单的例子中，直接返回uniformNode
				 * 更复杂的节点可能会进行数学运算或组合多个节点
				 * 
				 * @param {Object} builder - 着色器构建器对象（未使用）
				 * @returns {THREE.UniformNode} 返回统一值节点
				 */
				setup( /* builder */ ) {
					// 将这个节点连接到着色器系统
					return this.uniformNode;
				}
			}
			
			// ==================== 应用初始化 ====================
			
			// 立即调用初始化函数
			init();
			
			/**
			 * 异步初始化函数 - 应用的主入口点
			 * 
			 * 执行顺序：
			 * 1. 创建相机和场景
			 * 2. 设置光源
			 * 3. 创建3D物体并应用遮挡检测
			 * 4. 初始化渲染器
			 * 5. 设置控制器和事件监听
			 * 
			 * @async 标记为异步函数，因为某些WebGPU操作可能是异步的
			 */
			async function init() {
				// ---------- 相机初始化 ----------
				
				/*
				 * 创建透视投影相机（PerspectiveCamera）
				 * 参数说明：
				 * 1. fov: 视野角度（50度）- 垂直方向的视角范围
				 * 2. aspect: 宽高比（窗口宽/窗口高）- 保持图像比例
				 * 3. near: 近裁剪面（0.01）- 距离相机多近开始渲染
				 * 4. far: 远裁剪面（100）- 距离相机多远停止渲染
				 * 
				 * 透视相机模拟人眼视角，远处物体看起来更小
				 */
				camera = new THREE.PerspectiveCamera( 
					50, 
					window.innerWidth / window.innerHeight, 
					0.01, 
					100 
				);
				
				// 设置相机初始位置：沿Z轴正方向移动7个单位
				camera.position.z = 7;
				
				// ---------- 场景初始化 ----------
				
				/*
				 * 创建场景对象
				 * - 场景是所有3D物体、光源、摄像机的容器
				 * - 类似于一个虚拟的3D世界
				 */
				scene = new THREE.Scene();
				
				// ---------- 光源设置 ----------
				
				/*
				 * 环境光（AmbientLight）
				 * - 参数：颜色（0xb0b0b0，浅灰色）
				 * - 特点：均匀照亮场景中的所有物体，无方向性
				 * - 作用：提供基础照明，避免完全黑暗的区域
				 */
				const ambientLight = new THREE.AmbientLight( 0xb0b0b0 );
				
				/*
				 * 平行光（DirectionalLight）
				 * - 参数1：颜色（0xFFFFFF，白色）
				 * - 参数2：强度（1.0，最大强度）
				 * - 特点：模拟太阳光，所有光线平行
				 * - 作用：提供主要照明，产生阴影和高光
				 */
				const light = new THREE.DirectionalLight( 0xFFFFFF, 1.0 );
				
				// 设置平行光的方向向量（归一化坐标）
				light.position.set( 0.32, 0.39, 0.7 );
				
				// 将光源添加到场景中
				scene.add( ambientLight );
				scene.add( light );
				
				// ---------- 3D物体创建 ----------
				
				/*
				 * 创建几何体：
				 * - PlaneGeometry: 平面几何体，参数：宽度(2)，高度(2)
				 * - SphereGeometry: 球体几何体，参数：半径(0.5)
				 * 几何体定义了物体的形状和顶点数据
				 */
				const planeGeometry = new THREE.PlaneGeometry( 2, 2 );
				const sphereGeometry = new THREE.SphereGeometry( 0.5 );
				
				/*
				 * 创建平面网格（Mesh）
				 * - Mesh是几何体(Geometry)和材质(Material)的组合
				 * - MeshPhongNodeMaterial: Phong光照模型的节点材质
				 *   - color: 初始颜色（绿色，0x00ff00）
				 *   - side: THREE.DoubleSide - 双面渲染，两面都可见
				 */
				const plane = new THREE.Mesh( 
					planeGeometry, 
					new THREE.MeshPhongNodeMaterial( { 
						color: 0x00ff00,
						side: THREE.DoubleSide 
					} ) 
				);
				
				/*
				 * 创建球体网格
				 * - 使用Phong材质，初始颜色为黄色（0xffff00）
				 * - Phong材质支持高光反射，适合光滑表面
				 */
				const sphere = new THREE.Mesh( 
					sphereGeometry, 
					new THREE.MeshPhongNodeMaterial( { 
						color: 0xffff00 
					} ) 
				);
				
				/*
				 * 创建遮挡检测节点实例
				 * 参数说明：
				 * 1. sphere: 要检测的物体（球体）
				 * 2. new THREE.Color(0x0000ff): 正常颜色（蓝色）
				 * 3. new THREE.Color(0x00ff00): 遮挡颜色（绿色）
				 * 
				 * nodeObject()将TSL节点包装为Three.js可用的对象
				 */
				const instanceUniform = nodeObject( 
					new OcclusionNode( 
						sphere, 
						new THREE.Color( 0x0000ff ), 
						new THREE.Color( 0x00ff00 ) 
					) 
				);
				
				/*
				 * 将遮挡检测节点连接到平面材质的颜色节点
				 * - colorNode: TSL材质系统的颜色输入节点
				 * - 这样平面的颜色将由OcclusionNode动态控制
				 */
				plane.material.colorNode = instanceUniform;
				
				// 设置球体位置：沿Z轴负方向移动1个单位（在平面后面）
				sphere.position.z = -1;
				
				/*
				 * 启用球体的遮挡测试
				 * - occlusionTest = true: 告诉渲染器这个物体需要参与遮挡查询
				 * - 只有启用了遮挡测试的物体才能被isOccluded()检测
				 */
				sphere.occlusionTest = true;
				
				// 将平面和球体添加到场景中
				scene.add( plane );
				scene.add( sphere );
				
				// ---------- 渲染器初始化 ----------
				
				/*
				 * 创建WebGPU渲染器
				 * 参数配置：
				 * - antialias: true - 开启抗锯齿，平滑边缘锯齿
				 * WebGPURenderer是Three.js对WebGPU API的封装
				 */
				renderer = new THREE.WebGPURenderer( { 
					antialias: true 
				} );
				
				/*
				 * 设置设备像素比
				 * - window.devicePixelRatio: 设备物理像素与CSS像素的比率
				 * - 高DPI屏幕（如Retina）的devicePixelRatio > 1
				 * - 设置像素比可以确保在高分辨率屏幕上清晰渲染
				 */
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为整个浏览器窗口
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				/*
				 * 设置动画循环
				 * - setAnimationLoop()是requestAnimationFrame的封装
				 * - 参数render是每帧调用的渲染函数
				 * - 这创建了一个持续运行的渲染循环（约60FPS）
				 */
				renderer.setAnimationLoop( render );
				
				/*
				 * 将渲染器的canvas元素添加到页面body中
				 * - renderer.domElement: 渲染器创建的<canvas>元素
				 * - appendChild(): DOM操作方法，添加子元素
				 */
				document.body.appendChild( renderer.domElement );
				
				// ---------- 控制器初始化 ----------
				
				/*
				 * 创建轨道控制器（OrbitControls）
				 * 参数：
				 * 1. camera: 要控制的相机对象
				 * 2. renderer.domElement: 事件监听的DOM元素（canvas）
				 */
				controls = new OrbitControls( camera, renderer.domElement );
				
				/*
				 * 设置相机距离限制
				 * - minDistance: 相机与目标点的最小距离（不能更近）
				 * - maxDistance: 相机与目标点的最大距离（不能更远）
				 * 这些限制防止用户缩放得过近或过远
				 */
				controls.minDistance = 3;
				controls.maxDistance = 25;
				
				// ---------- 事件监听器 ----------
				
				/*
				 * 监听窗口大小变化事件
				 * - 'resize': 当浏览器窗口大小改变时触发
				 * - onWindowResize: 事件处理函数
				 * 这确保当用户调整窗口大小时，3D场景能正确适应
				 */
				window.addEventListener( 'resize', onWindowResize );
				
				/*
				 * 初始化完成
				 * 此时场景已建立，渲染循环已启动
				 * 用户可以通过鼠标与3D场景交互
				 */
			}
			
			// ==================== 工具函数 ====================
			
			/**
			 * 窗口大小变化处理函数
			 * 
			 * 功能：当浏览器窗口大小改变时，调整相机和渲染器
			 * 保持3D场景的正确比例和显示
			 */
			function onWindowResize() {
				/*
				 * 更新相机的宽高比
				 * 重新计算窗口宽度与高度的比值
				 * 确保3D场景不被拉伸或压缩
				 */
				camera.aspect = window.innerWidth / window.innerHeight;
				
				/*
				 * 更新相机的投影矩阵
				 * - 当相机参数改变时，必须调用此方法
				 * - 重新计算3D到2D的投影变换
				 */
				camera.updateProjectionMatrix();
				
				/*
				 * 更新渲染器尺寸
				 * 使canvas元素的大小与窗口大小保持一致
				 */
				renderer.setSize( window.innerWidth, window.innerHeight );
			}
			
			/**
			 * 渲染函数 - 动画循环的每一帧调用
			 * 
			 * 功能：
			 * 1. 更新控制器状态（处理用户输入）
			 * 2. 执行遮挡检测（通过OcclusionNode.update()）
			 * 3. 将3D场景渲染到2D画布
			 */
			function render() {
				/*
				 * 渲染场景
				 * 参数：
				 * 1. scene: 要渲染的3D场景
				 * 2. camera: 用于渲染的相机视角
				 * 
				 * 内部过程：
				 * 1. 更新所有需要更新的对象（包括OcclusionNode）
				 * 2. 执行遮挡查询（如果启用）
				 * 3. 执行WebGPU绘制命令
				 * 4. 将结果输出到canvas元素
				 */
				renderer.render( scene, camera );
			}
			
			/*
			 * 注意：这里没有显式调用controls.update()
			 * OrbitControls在内部使用requestAnimationFrame自动更新
			 * 当用户交互时，控制器会自动更新相机位置和方向
			 */
			
		</script>
	</body>
</html>