<!-- 基于Three.js WebGPU的屏幕空间阴影(SSS)演示系统
🎯 核心功能概述
这是一个展示屏幕空间阴影(Screen-Space Shadows, SSS) 与传统阴影贴图结合使用的交互式3D渲染演示。系统通过WebGPU渲染引擎，在浏览器中实时渲染一个带复杂阴影效果的自然女神雕像场景，用户可交互式调节阴影参数、切换不同渲染模式。

🔧 技术架构
1. 渲染引擎
WebGPU渲染器：使用新一代图形API WebGPU，相比WebGL提供更高的性能和更好的并行处理能力

模块化架构：采用ES6模块系统，支持现代浏览器的模块导入

多通道渲染：将渲染过程分解为多个独立的通道，每个通道完成特定任务

2. 核心渲染管线
text
1. 预渲染通道 → 2. 场景渲染通道 → 3. SSS计算 → 4. TAA处理 → 5. 最终输出
3. 关键技术点详解
🎨 屏幕空间阴影(SSS)
原理：在屏幕空间（2D图像）而非3D空间中计算阴影

优势：

解决传统阴影贴图的边缘锯齿问题

能够捕捉微小细节的阴影

实现更柔和的阴影过渡

实现：基于深度缓冲区进行光线步进，检测遮挡关系

⚡ 时间性反走样(TAA)
目的：减少渲染中的锯齿、闪烁和噪点

方法：利用多帧累积和运动向量

每一帧都与前一帧混合

使用运动向量校正相机和物体移动

随时间平滑噪声和走样

🎭 多渲染目标(MRT)
作用：单个渲染通道输出多个纹理

本应用输出：

颜色缓冲区

深度缓冲区

运动向量缓冲区

可选的附加数据

💡 阴影混合策略
传统阴影贴图：提供基础阴影轮廓和硬阴影

屏幕空间阴影：添加细节阴影和接触阴影

结合方式：通过阴影上下文节点将两者融合

🚀 主要功能模块
1. 场景初始化模块
javascript
// 创建基础场景组件
- 相机系统（透视投影）
- 光照系统（半球光 + 方向光）
- 地面平面（阴影接收体）
- 3D模型加载（GLTF + Draco压缩）
2. 后期处理管线模块
javascript
// 四个主要渲染通道
const prePass = pass(scene, camera);        // 预渲染：获取深度和运动向量
const scenePass = pass(scene, camera);      // 主场景渲染
const sssPass = sss(...);                   // SSS计算
const traaPass = traa(...);                 // TAA处理
3. 交互控制模块
轨道控制器：鼠标控制相机

GUI调试面板：实时参数调节

快捷键系统：快速操作

响应式布局：窗口自适应

4. 渲染模式切换
系统支持三种渲染模式：

模式0：传统阴影贴图 + SSS（默认）

模式1：仅传统阴影贴图

模式2：仅SSS效果（灰度显示）

🌈 视觉特效实现
1. 阴影系统
javascript
// 传统阴影贴图配置
dirLight.castShadow = true;
dirLight.shadow.mapSize.width = 1024;
dirLight.shadow.mapSize.height = 1024;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;

// SSS参数调节
sssPass.maxDistance.value = 0.2;      // 阴影最大距离
sssPass.shadowIntensity.value = 1.0;  // 阴影强度
sssPass.thickness.value = 0.01;       // 几何厚度
sssPass.quality.value = 0.5;          // 采样质量
2. 环境效果
雾效：距离雾增强深度感

环境光照：半球光模拟天空光

材质优化：移除AO贴图突出阴影效果

🔍 性能优化策略
1. 分层渲染优化
预计算：深度和运动向量单独计算

按需渲染：参数变化时仅更新必要通道

纹理复用：多个通道共享纹理数据

2. WebGPU特性利用
并行计算：GPU大规模并行处理

显存管理：高效纹理和缓冲区管理

异步操作：非阻塞渲染流程

3. 渲染质量平衡
动态质量调节：通过quality参数控制采样数

时间性过滤：减少每帧计算量，依赖多帧累积

分辨率自适应：根据窗口大小调整渲染目标

📊 技术亮点总结
创新点
混合阴影方案：传统+屏幕空间阴影的优势结合

实时参数调节：所有阴影参数可动态调整

多模式比较：便于观察不同技术效果差异

技术深度
TSL着色器语言：Three.js的高层着色器抽象

节点化渲染：声明式的渲染管线配置

时间性重投影：精确的运动向量计算

用户体验
直观交互：实时反馈的参数调节

性能可视化：通过调试面板查看中间纹理

教育价值：清晰展示图形学算法效果

🛠️ 开发与调试支持
1. 调试工具集成
javascript
// 纹理可视化
prePassDepth.toInspector('深度纹理');
prePassVelocity.toInspector('运动向量');
scenePass.toInspector('场景颜色');

// 参数调节面板
const gui = renderer.inspector.createParameters('SSS设置');
2. 开发辅助
控制台日志：详细的初始化日志

错误处理：加载失败的回调处理

性能提示：关键操作的性能记录

📈 应用场景扩展
1. 游戏开发
实时动态阴影

高质量角色渲染

性能敏感的移动端优化

2. 可视化应用
产品展示

建筑可视化

科学数据渲染

3. 教育演示
图形学算法教学

实时渲染技术展示

性能优化案例研究

🎯 核心价值体现
这个演示不仅仅是展示一个技术功能，而是完整呈现了现代实时渲染引擎的核心架构：

模块化设计：清晰的通道分离

可扩展性：易于添加新效果

性能可控：质量与帧率的平衡

学习价值：图形学技术的生动展示

生产就绪：可直接应用于实际项目

通过这个系统，开发者可以深入理解：

WebGPU的工作原理

现代阴影技术的发展

后期处理管线的构建

实时图形性能优化策略 -->


<!DOCTYPE html>
<!-- 文档类型和语言声明 -->
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js WebGPU 屏幕空间阴影演示 -->
		<title>Three.js WebGPU - 屏幕空间阴影(SSS)演示</title>
		<!-- 字符编码设置：使用UTF-8支持中文和特殊字符 -->
		<meta charset="utf-8">
		<!-- 移动端视口设置：固定视口，禁止用户缩放，设置最小和最大缩放比例为1.0 -->
		<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链接，点击跳转到Three.js官网 -->
			<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>屏幕空间阴影(SSS)演示</span>
			</div>

			<!-- 详细说明区域，使用较小字体 -->
			<small>
				<!-- 技术说明：屏幕空间阴影(SSS)与阴影贴图的结合使用 -->
				<b>技术说明：</b>本演示展示了屏幕空间阴影(SSS)与阴影贴图结合使用的效果。<br/>
				<!-- 使用说明 -->
				<b>操作说明：</b>使用鼠标左键旋转视角，右键平移，滚轮缩放。右侧面板可调整参数。<br/>
				<br/>
				<!-- 模型信息部分 -->
				<b>模型信息：</b><br/>
				<!-- 模型名称和作者信息，包含超链接 -->
				使用的模型：<a href="https://skfb.ly/pAQvU" target="_blank" rel="noopener">Nemetona_NatureBeauty（自然之美）</a><br/>
				模型作者：<a href="https://sketchfab.com/JOJObrush" target="_blank" rel="noopener">JOJObrush</a><br/>
				授权协议：<a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener">知识共享署名4.0国际许可协议</a><br/>
				<br/>
				<!-- 技术特性说明 -->
				<b>技术特性：</b><br/>
				1. 基于WebGPU的实时渲染<br/>
				2. 屏幕空间阴影(SSS)算法<br/>
				3. 时间性反走样(TAA)技术<br/>
				4. 多通道渲染管线<br/>
				5. 实时参数调节<br/>
			</small>
		</div>

		<!-- Import Maps：现代浏览器中的模块映射配置，用于定义模块别名和路径 -->
		<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模块 -->
		<script type="module">

			// ==================== 模块导入区域 ====================
			// 导入Three.js核心库的WebGPU版本
			import * as THREE from 'three/webgpu';
			
			// 导入TSL着色器节点和函数
			// pass: 创建渲染通道
			// vec3/vec4: 三维/四维向量构造函数
			// mrt: 多渲染目标配置
			// screenUV: 屏幕UV坐标
			// velocity: 运动向量
			// builtinShadowContext: 内置阴影上下文
			import { pass, vec3, vec4, mrt, screenUV, velocity, builtinShadowContext } from 'three/tsl';
			
			// 导入屏幕空间阴影(SSS)节点
			import { sss } from 'three/addons/tsl/display/SSSNode.js';
			
			// 导入时间性反走样(TRAANode)节点
			import { traa } from 'three/addons/tsl/display/TRAANode.js';

			// 导入控制器和工具库
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; // 轨道控制器
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';       // GLTF模型加载器
			import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';     // Draco压缩格式加载器
			import { Inspector } from 'three/addons/inspector/Inspector.js';       // 调试面板

			// ==================== 全局变量声明 ====================
			// camera: 场景相机，控制观察视角
			// scene: 3D场景容器，包含所有3D对象
			// renderer: WebGPU渲染器实例
			// postProcessing: 后期处理管理器
			// controls: 用户交互控制器
			let camera, scene, renderer, postProcessing, controls;

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

			// ==================== 异步初始化函数 ====================
			async function init() {

				// ========== 相机设置 ==========
				// 创建透视相机：视角45度，根据窗口宽高比设置，近裁剪面0.1，远裁剪面100
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 100);
				// 设置相机初始位置：X=1, Y=2.5, Z=-3.5
				camera.position.set(1, 2.5, -3.5);

				// ========== 场景设置 ==========
				// 创建3D场景
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色（RGB: 0xa0a0a0）
				scene.background = new THREE.Color(0xa0a0a0);
				// 添加雾效：颜色与背景相同，近处开始距离10，远处结束距离50
				scene.fog = new THREE.Fog(0xa0a0a0, 10, 50);

				// ========== 灯光系统设置 ==========
				
				// 半球光（环境光）
				// 参数：天空颜色，地面颜色，光照强度
				// 模拟环境光照，从天空到地面的渐变光照
				const hemiLight = new THREE.HemisphereLight(0xffffff, 0x8d8d8d, 2);
				hemiLight.position.set(0, 20, 0); // 放置在场景上方
				scene.add(hemiLight);

				// 方向光（主光源，产生阴影）
				// 参数：光照颜色，光照强度
				// 模拟太阳光，有明确方向性的光源
				const dirLight = new THREE.DirectionalLight(0xffffff, 3);
				dirLight.position.set(-3, 10, -10); // 设置光源位置
				dirLight.castShadow = true; // 启用阴影投射
				
				// 阴影相机参数设置（定义阴影的渲染范围）
				// 这些参数定义了正交相机的视锥体
				dirLight.shadow.camera.top = 4;     // 上边界
				dirLight.shadow.camera.bottom = -4; // 下边界
				dirLight.shadow.camera.left = -4;   // 左边界
				dirLight.shadow.camera.right = 4;   // 右边界
				dirLight.shadow.camera.near = 0.1;  // 近平面
				dirLight.shadow.camera.far = 40;    // 远平面
				dirLight.shadow.bias = -0.001;      // 阴影偏移量，用于减少阴影痤疮
				dirLight.shadow.mapSize.width = 1024;   // 阴影贴图宽度（分辨率）
				dirLight.shadow.mapSize.height = 1024;  // 阴影贴图高度（分辨率）
				scene.add(dirLight);

				// 可选：显示阴影相机帮助器，用于调试阴影范围
				// 取消注释以下行可以查看阴影相机的可视范围
				// scene.add(new THREE.CameraHelper(dirLight.shadow.camera));

				// ========== 地面创建 ==========
				// 创建平面几何体作为地面：宽100，高100
				const groundGeometry = new THREE.PlaneGeometry(100, 100);
				// 创建Phong材质：颜色为浅灰色，关闭深度写入（优化性能）
				const groundMaterial = new THREE.MeshPhongMaterial({ 
					color: 0xcbcbcb, 
					depthWrite: false  // 不写入深度缓冲区，避免与场景中其他对象深度冲突
				});
				// 创建网格对象
				const groundMesh = new THREE.Mesh(groundGeometry, groundMaterial);
				groundMesh.rotation.x = -Math.PI / 2; // 旋转90度使平面水平放置
				groundMesh.receiveShadow = true;      // 启用阴影接收
				scene.add(groundMesh);

				// ========== 3D模型加载 ==========
				
				// 创建DRACO加载器（用于加载压缩的GLTF模型）
				// Draco是Google开发的3D几何压缩库，显著减小模型文件大小
				const dracoLoader = new DRACOLoader();
				// 设置DRACO解码器的路径
				dracoLoader.setDecoderPath('jsm/libs/draco/gltf/');

				// 创建GLTF加载器
				const gltfLoader = new GLTFLoader();
				// 将DRACO加载器设置为GLTF加载器的解码器
				gltfLoader.setDRACOLoader(dracoLoader);
				
				// 加载GLB格式的3D模型
				gltfLoader.load('models/gltf/nemetona.glb', function (gltf) {
					// 加载成功回调函数
					
					const model = gltf.scene; // 获取场景根节点
					
					// 模型变换调整
					model.rotation.y = Math.PI;   // 绕Y轴旋转180度
					model.scale.setScalar(10);    // 统一缩放10倍
					model.position.y = 0.45;      // 设置Y轴位置
					
					scene.add(model); // 将模型添加到场景

					// 遍历模型的所有子对象
					model.traverse(function (object) {
						// 检查对象是否为网格（Mesh）
						if (object.isMesh) {
							// 为每个网格设置阴影属性
							object.castShadow = true;     // 启用阴影投射
							object.receiveShadow = true;  // 启用阴影接收
							
							// 移除环境光遮蔽(AO)贴图
							// 这样可以使屏幕空间阴影效果更加明显
							object.material.aoMap = null;
						}
					});
				}, 
				// 可选的加载进度回调
				function (xhr) {
					console.log('模型加载进度: ' + (xhr.loaded / xhr.total * 100) + '%');
				},
				// 可选的加载错误回调
				function (error) {
					console.error('模型加载错误:', error);
				});

				// ========== 渲染器初始化 ==========
				
				// 创建WebGPU渲染器实例
				// WebGPU是新一代图形API，比WebGL更高效
				renderer = new THREE.WebGPURenderer();
				
				// 设置渲染器参数
				renderer.setPixelRatio(window.devicePixelRatio); // 设置设备像素比
				renderer.setSize(window.innerWidth, window.innerHeight); // 设置渲染尺寸
				renderer.setAnimationLoop(animate); // 设置动画循环回调函数
				
				// 阴影配置
				renderer.shadowMap.enabled = true; // 启用阴影映射
				renderer.shadowMap.type = THREE.PCFSoftShadowMap; // 使用PCF软阴影
				
				// 调试面板
				renderer.inspector = new Inspector(); // 创建调试器实例
				
				// 将渲染器的DOM元素（canvas）添加到页面body中
				document.body.appendChild(renderer.domElement);

				// ========== 后期处理系统设置 ==========
				
				// 创建后期处理管理器
				// 后期处理允许在渲染完成后对图像进行额外的处理
				postProcessing = new THREE.PostProcessing(renderer);

				// -------- 预渲染通道 --------
				// 目的：获取深度缓冲和运动向量，用于后续的SSS和TAA计算
				const prePass = pass(scene, camera); // 创建渲染通道
				prePass.name = '预渲染通道';         // 设置通道名称
				prePass.transparent = false;         // 禁用透明度

				// 配置多渲染目标(MRT)
				// MRT允许在一个渲染通道中输出多个纹理
				prePass.setMRT(mrt({
					output: velocity // 输出运动向量（用于TAA）
				}));

				// 将深度和运动向量纹理暴露给调试器
				// 可以在调试面板中查看这些纹理
				const prePassDepth = prePass.getTextureNode('depth').toInspector('深度纹理', () => prePass.getLinearDepthNode());
				const prePassVelocity = prePass.getTextureNode('output').toInspector('运动向量纹理');

				// -------- 场景渲染通道 --------
				// 主场景渲染通道，生成最终的颜色输出
				const scenePass = pass(scene, camera).toInspector('场景颜色');

				// -------- 屏幕空间阴影(SSS)通道 --------
				// 创建SSS效果，参数：深度纹理、相机、方向光
				const sssPass = sss(prePassDepth, camera, dirLight);
				
				// 配置SSS参数
				sssPass.maxDistance.value = 0.2;          // 最大射线距离（控制阴影范围）
				sssPass.useTemporalFiltering = true;      // 启用时间性过滤（减少噪点）

				// -------- 阴影上下文设置 --------
				// 将SSS效果与阴影贴图结合
				const sssSample = sssPass.getTextureNode().sample(screenUV).r; // 采样SSS纹理
				const sssContext = builtinShadowContext(sssSample, dirLight);  // 创建阴影上下文
				
				scenePass.contextNode = sssContext; // 将SSS阴影上下文应用到场景通道

				// -------- 时间性反走样(TRAANode) --------
				// 参数：场景颜色、深度纹理、运动向量、相机
				// TAA通过多帧累积减少锯齿和噪点
				const traaPass = traa(scenePass, prePassDepth, prePassVelocity, camera);
				
				// 设置最终输出节点
				postProcessing.outputNode = traaPass;

				// ========== 用户交互控制器设置 ==========
				
				// 创建轨道控制器
				// 允许用户通过鼠标控制相机旋转、平移和缩放
				controls = new OrbitControls(camera, renderer.domElement);
				
				// 控制器参数配置
				controls.minDistance = 1;     // 最小缩放距离
				controls.maxDistance = 20;    // 最大缩放距离
				controls.target.set(0, 2, 0); // 控制中心点（相机围绕此点旋转）
				controls.enableDamping = true; // 启用阻尼效果（惯性）
				controls.dampingFactor = 0.05; // 阻尼系数
				
				controls.update(); // 初始化更新

				// ========== 调试面板(GUI)设置 ==========
				
				// 参数对象，存储当前设置
				const params = {
					output: 0 // 默认输出模式：0=场景+阴影贴图+SSS
				};

				// 输出模式枚举
				// 键值对：显示名称 -> 模式编号
				const outputModes = {
					'场景+阴影贴图+SSS': 0,
					'场景+阴影贴图': 1,
					'仅SSS': 2
				};

				// 创建调试面板
				const gui = renderer.inspector.createParameters('屏幕空间阴影设置');

				// 添加输出模式选择下拉菜单
				gui.add(params, 'output', outputModes)
				   .name('输出模式')
				   .onChange(updatePostprocessing); // 模式改变时触发更新

				// 添加SSS参数调节滑块
				gui.add(sssPass.shadowIntensity, 'value', 0, 1)
				   .name('阴影强度')
				   .step(0.01); // 调节步长
				   
				gui.add(sssPass.maxDistance, 'value', 0.01, 1)
				   .name('最大射线距离')
				   .step(0.01);
				   
				gui.add(sssPass.quality, 'value', 0, 1)
				   .name('渲染质量')
				   .step(0.01);
				   
				gui.add(sssPass.thickness, 'value', 0.01, 0.1)
				   .name('厚度参数')
				   .step(0.001);

				// 添加时间性过滤开关
				gui.add(sssPass, 'useTemporalFiltering')
				   .name('时间性过滤')
				   .onChange(updatePostprocessing);

				// ========== 后期处理更新函数 ==========
				// 当用户改变设置时调用此函数
				function updatePostprocessing() {
					console.log('更新后期处理设置，当前模式:', params.output);

					// 根据输出模式设置场景上下文
					if (params.output === 1) {
						// 模式1：仅使用阴影贴图，不使用SSS
						scenePass.contextNode = null;
					} else {
						// 模式0和2：使用SSS阴影上下文
						scenePass.contextNode = sssContext;
					}

					// 根据输出模式设置最终输出
					if (params.output === 2) {
						// 模式2：仅显示SSS效果（灰度图）
						// 将SSS的红色通道转换为RGB颜色
						postProcessing.outputNode = vec4(vec3(sssPass.r), 1);
					} else {
						// 模式0和1：显示完整场景
						if (sssPass.useTemporalFiltering) {
							// 启用时间性过滤时使用TAA通道
							postProcessing.outputNode = traaPass;
						} else {
							// 否则直接使用场景通道
							postProcessing.outputNode = scenePass;
						}
					}

					// 标记后期处理需要更新
					postProcessing.needsUpdate = true;
				}

				// ========== 窗口大小变化事件监听 ==========
				// 当浏览器窗口大小改变时调整渲染
				window.addEventListener('resize', onWindowResize);
				
				// 可选的：添加键盘快捷键
				window.addEventListener('keydown', function(event) {
					switch(event.key) {
						case 'h': // 按H键切换帮助信息显示
							document.getElementById('info').style.display = 
								document.getElementById('info').style.display === 'none' ? 'block' : 'none';
							break;
						case ' ': // 按空格键重置视角
							controls.reset();
							break;
					}
				});

				// 初始化完成日志
				console.log('Three.js SSS演示初始化完成');
				console.log('可用功能：');
				console.log('1. 鼠标控制：左键旋转，右键平移，滚轮缩放');
				console.log('2. 快捷键：H键切换帮助信息，空格键重置视角');
				console.log('3. 右侧面板可调节阴影参数');

			} // init函数结束

			// ========== 窗口大小变化处理函数 ==========
			function onWindowResize() {
				// 获取当前窗口尺寸
				const width = window.innerWidth;
				const height = window.innerHeight;

				// 更新相机宽高比
				camera.aspect = width / height;
				// 更新相机投影矩阵（必须手动调用）
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				renderer.setSize(width, height);
				
				// 可选：更新后期处理缓冲区大小
				if (postProcessing) {
					postProcessing.setSize(width, height);
				}

				console.log(`窗口大小调整为: ${width} x ${height}`);
			}

			// ========== 动画循环函数 ==========
			// 每一帧都会调用此函数
			function animate() {
				// 更新控制器状态
				controls.update();
				
				// 执行后期处理渲染
				// 这会触发整个渲染管线：
				// 1. 预渲染通道（深度+运动向量）
				// 2. 场景渲染通道（颜色）
				// 3. SSS计算
				// 4. TAA处理
				// 5. 最终输出到屏幕
				postProcessing.render();
				
				// 可选的：性能监控
				// 可以添加帧率显示或性能统计
			}

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