<!-- Three.js WebGPU 接触阴影演示 - 功能描述与技术点分析
一、核心功能概述
1. 主要功能
这是一个基于Three.js和WebGPU的接触阴影（Contact Shadows） 实时渲染演示。演示展示了如何通过双通道渲染技术实现物体与平面接触区域的柔和阴影效果。

2. 视觉展示
场景中包含三个旋转的几何体：立方体、二十面体和环面纽结

这些物体投射出与平面接触的柔和阴影

阴影具有自然的模糊边缘，模拟真实光照环境中的软阴影效果

所有物体持续旋转，展示动态阴影效果

3. 交互功能
鼠标控制：通过OrbitControls实现视角旋转、平移和缩放

实时参数调节：通过GUI面板可调整阴影和平面属性

调试模式：可显示阴影相机的视锥体辅助线

二、技术架构详解
1. 双通道渲染（Two-Pass Rendering）
这是本演示的核心技术，分为两个独立的渲染阶段：

第一通道：深度图生成
text
输入：场景几何体
输出：深度纹理（512×512像素）
相机：正交相机（shadowCamera）
材质：深度材质（depthMaterial）
目标：离屏渲染缓冲区（renderTarget）
使用正交投影相机从上方向下渲染场景

应用深度材质将所有物体渲染为深度图

深度值通过 alpha = 1.0 - depth * darkness 公式转换为透明度

第二通道：主场景渲染
text
输入：场景几何体 + 深度纹理
输出：屏幕显示
相机：透视相机（主相机）
材质：各种标准材质
目标：屏幕（主帧缓冲区）
使用透视相机渲染完整场景

阴影平面使用高斯模糊处理后的深度纹理作为透明度

实现阴影与场景的合成

2. 接触阴影算法实现
深度信息捕获
javascript
// 深度计算
const alphaDepth = float(1).sub(depth).mul(uDarkness);
// 近处物体：depth小 → alpha大 → 阴影暗
// 远处物体：depth大 → alpha小 → 阴影淡
高斯模糊处理
javascript
// 4次迭代的高斯模糊
const blurredShadow = gaussianBlur(
    texture(renderTarget.texture),
    uBlur,  // 模糊半径
    4,      // 迭代次数
    { premultipliedAlpha: false }
);
阴影合成
javascript
// 阴影平面透明度 = 模糊alpha × 阴影不透明度
shadowPlaneMaterial.opacityNode = blurredShadow.a.mul(uShadowOpacity);
3. 关键性能优化技术
渲染状态管理
javascript
// 保存和恢复渲染状态
const initialBackground = scene.background;
const prevOverride = scene.overrideMaterial;
const initialAutoClear = renderer.autoClear;
// ...渲染后恢复所有状态
GPU资源优化
禁用Mipmaps：generateMipmaps = false，深度纹理不需要多级渐远

禁用深度写入：depthWrite = false，阴影平面不参与深度测试

合理的纹理尺寸：512×512像素，平衡质量与性能

Uniform统一管理：通过TSL uniform集中控制着色器参数

WebGPU特性利用
使用最新的WebGPU API，相比WebGL有更好的性能

支持更复杂的着色器计算

更好的多线程和并行处理能力

4. Three.js高级特性应用
TSL（Three.js Shading Language）
javascript
// 声明uniform变量
const uBlur = uniform(state.shadow.blur);
const uDarkness = uniform(state.shadow.darkness);

// 在着色器节点中使用
shadowPlaneMaterial.opacityNode = blurredShadow.a.mul(uShadowOpacity);
NodeMaterial系统
基于节点的材质系统，可编程性更强

实时编译为WebGPU着色器

支持复杂的材质网络

模块化架构
javascript
// 从addons导入专用模块
import { gaussianBlur } from 'three/addons/tsl/display/GaussianBlurNode.js';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { Inspector } from 'three/addons/inspector/Inspector.js';
三、技术亮点总结
1. 创新的阴影算法
接触阴影 vs 传统阴影：专注于物体与表面接触区域的阴影细节

物理准确性：模拟真实世界中的软阴影效果

实时性能：在保持视觉效果的同时保证交互帧率

2. 现代Web图形技术栈
text
Three.js（场景管理）
├── WebGPU（底层图形API）
├── TSL（着色器语言）
├── NodeMaterial（节点材质）
└── 双通道渲染（算法核心）
3. 可扩展的设计模式
模块化渲染流程：易于添加更多渲染效果

参数化控制：所有视觉效果都可实时调节

调试友好：完整的调试工具和可视化辅助

4. 实际应用价值
这种接触阴影技术在以下领域有重要应用：

电子商务：3D产品展示，增强真实感

游戏开发：提升场景视觉效果

建筑设计：可视化渲染，模拟真实光照

虚拟现实：增强沉浸感

科学可视化：更清晰地展示数据关系

四、学习价值
1. 图形学概念
深度缓冲和深度测试

离屏渲染技术

高斯模糊算法

正交 vs 透视投影

透明度混合

2. 编程模式
状态管理模式（保存/恢复渲染状态）

事件驱动参数更新

模块化架构设计

性能优化实践

3. Three.js最佳实践
WebGPU的正确使用方式

TSL着色器编程

自定义材质开发

调试和性能分析 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面元数据 -->
		<title>Three.js WebGPU - 接触阴影演示</title>
		<!-- 字符编码设置为UTF-8，支持中文字符 -->
		<meta charset="utf-8">
		<!-- 移动端响应式设计：禁止用户缩放，确保WebGL内容正确显示 -->
		<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" class="invert">
			<!-- 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>接触阴影效果演示</span>
			</div>

			<!-- 简要描述：说明技术实现原理 -->
			<small>使用高斯模糊技术实现的平滑接触阴影渲染效果。</small>
			<br>
			<!-- 技术特性说明 -->
			<small style="margin-top: 20px;">技术特性：基于WebGPU渲染，支持实时参数调节，高性能渲染。</small>
		</div>

		<!-- WebGL渲染画布容器：Three.js将在此处创建canvas元素并渲染3D场景 -->
		<div id="container"></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>

		<script type="module">
			// ==================== 模块导入部分 ====================
			// 导入Three.js核心库（WebGPU版本）
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js着色器语言（TSL）的构建块函数
			// vec3: 创建三维向量节点
			// uniform: 创建uniform变量节点（可在着色器外部控制的变量）
			// texture: 创建纹理采样节点
			// depth: 深度值节点（表示当前片元的深度信息）
			// float: 创建浮点数节点
			import { vec3, uniform, texture, depth, float } from 'three/tsl';
			
			// 导入高斯模糊节点函数，用于实现阴影的模糊效果
			import { gaussianBlur } from 'three/addons/tsl/display/GaussianBlurNode.js';
			
			// 导入轨道控制器，实现鼠标拖拽旋转、缩放等交互功能
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入调试检查器，用于创建GUI控制面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ==================== 全局变量声明部分 ====================
			// 主要Three.js对象
			let camera, scene, renderer;                    // 主相机、场景、渲染器
			let shadowCamera, shadowGroup;                  // 阴影专用相机和阴影对象组
			let renderTarget;                               // 离屏渲染目标（用于渲染深度图）
			
			// 场景中的几何对象
			let plane, fillPlane, cameraHelper;             // 阴影平面、填充平面、相机辅助线
			
			// 材质对象
			let depthMaterial;                              // 深度渲染材质（用于生成深度图）
			let shadowPlaneMaterial;                        // 阴影平面材质（显示模糊后的阴影）
			let fillPlaneMaterial;                          // 填充平面材质（显示平面基础颜色）
			
			// 存储场景中所有可旋转网格的数组
			const meshes = [];

			// ==================== 常量定义部分 ====================
			const PLANE_WIDTH = 2.5;     // 阴影平面的宽度（单位：米）
			const PLANE_HEIGHT = 2.5;    // 阴影平面的高度（单位：米）
			const CAMERA_HEIGHT = 0.3;   // 阴影相机的高度（单位：米）

			// ==================== 应用程序状态对象 ====================
			// 存储所有可调节参数的初始值
			const state = {
				// 阴影相关参数
				shadow: { 
					blur: 3.5,      // 高斯模糊半径，控制阴影边缘的柔和程度
					darkness: 1.0,  // 阴影暗度系数，值越大阴影越暗
					opacity: 1.0    // 阴影不透明度，控制阴影的可见程度
				},
				// 平面相关参数
				plane: { 
					color: '#ffffff',  // 平面的基础颜色（十六进制格式）
					opacity: 1.0       // 平面的不透明度
				},
				// 调试相关参数
				showWireframe: false   // 是否显示阴影相机的视锥体辅助线
			};

			// ==================== TSL Uniform变量声明 ====================
			// 将JavaScript中的状态值转换为可在着色器中使用的uniform变量
			const uBlur = uniform( state.shadow.blur );                // 阴影模糊度uniform
			const uDarkness = uniform( state.shadow.darkness );        // 阴影暗度uniform
			const uShadowOpacity = uniform( state.shadow.opacity );    // 阴影不透明度uniform
			const uPlaneOpacity = uniform( state.plane.opacity );      // 平面不透明度uniform
			const uPlaneColor = uniform( new THREE.Color( state.plane.color ) ); // 平面颜色uniform
			const uPlaneY = uniform( - 0.3 );                          // 平面Y轴位置uniform

			// ==================== 初始化函数调用 ====================
			// 页面加载完成后开始初始化Three.js场景
			init();

			// ==================== 初始化函数定义 ====================
			/**
			 * 初始化Three.js场景、相机、渲染器、几何体、材质和GUI
			 * 这是整个应用程序的入口函数
			 */
			function init() {
				// ---------- 1. 创建主相机 ----------
				// 使用透视相机，模拟人眼视角
				camera = new THREE.PerspectiveCamera(
					50,                                // 视野角度（FOV），单位：度
					window.innerWidth / window.innerHeight, // 宽高比，基于窗口尺寸
					0.1,                               // 近裁剪平面，距离小于此值的物体不渲染
					100                                 // 远裁剪平面，距离大于此值的物体不渲染
				);
				// 设置相机初始位置（X, Y, Z坐标）
				camera.position.set( 0.5, 1, 2 );

				// ---------- 2. 创建场景 ----------
				scene = new THREE.Scene();
				scene.background = new THREE.Color( 0xffffff ); // 设置场景背景为白色

				// 监听窗口大小变化事件，当窗口调整时重新计算相机和渲染器参数
				window.addEventListener( 'resize', onWindowResize );

				// ---------- 3. 创建场景中的几何体 ----------
				// 定义三种不同类型的几何体，用于展示阴影效果
				const geometries = [
					new THREE.BoxGeometry( 0.4, 0.4, 0.4 ),              // 立方体几何体
					new THREE.IcosahedronGeometry( 0.3 ),                // 二十面体几何体（球形近似）
					new THREE.TorusKnotGeometry( 0.4, 0.05, 256, 24, 1, 3 ) // 环面纽结几何体（复杂形状）
				];

				// 使用法线材质，根据表面法向量显示不同颜色，便于观察物体形状
				const material = new THREE.MeshNormalMaterial();

				// 创建网格对象并添加到场景中
				for ( let i = 0, l = geometries.length; i < l; i ++ ) {
					// 计算每个物体在圆形轨道上的角度
					const angle = ( i / l ) * Math.PI * 2;
					
					// 创建网格对象：几何体 + 材质
					const mesh = new THREE.Mesh( geometries[ i ], material );
					
					// 设置物体位置
					mesh.position.y = 0.1;                     // Y轴位置，稍微抬高避免与平面穿插
					mesh.position.x = Math.cos( angle ) / 2.0; // X轴位置：cos(角度)/2
					mesh.position.z = Math.sin( angle ) / 2.0; // Z轴位置：sin(角度)/2
					
					// 将物体添加到场景
					scene.add( mesh );
					// 将物体引用存储到数组，方便后续动画控制
					meshes.push( mesh );
				}

				// ---------- 4. 创建阴影系统 ----------
				// 创建一个组来统一管理所有阴影相关的对象
				shadowGroup = new THREE.Group();
				shadowGroup.position.y = uPlaneY.value; // 设置阴影组的Y轴位置
				scene.add( shadowGroup );

				// 创建渲染目标（离屏渲染缓冲区），用于渲染深度图
				// 512x512像素，包含深度缓冲区
				renderTarget = new THREE.RenderTarget( 512, 512, { depthBuffer: true } );
				renderTarget.texture.generateMipmaps = false; // 禁用mipmap生成，提高性能

				// 创建平面几何体，用于显示阴影
				const planeGeometry = new THREE.PlaneGeometry( PLANE_WIDTH, PLANE_HEIGHT )
					.rotateX( Math.PI / 2 ); // 绕X轴旋转90度，使平面水平

				// ---------- 5. 创建深度材质 ----------
				// 深度材质用于第一遍渲染，生成物体的深度信息
				depthMaterial = new THREE.NodeMaterial();
				
				// 计算深度透明度：alpha = 1.0 - depth * darkness
				// depth值范围0-1，表示物体到相机的距离（0=近，1=远）
				// 这个公式使近处的物体更不透明，远处的物体更透明
				const alphaDepth = float( 1 ).sub( depth ).mul( uDarkness );
				
				// 配置深度材质属性
				depthMaterial.colorNode = vec3( 0 );        // 颜色设为黑色（因为只关心深度，不关心颜色）
				depthMaterial.opacityNode = alphaDepth;     // 透明度由深度计算得出
				depthMaterial.depthTest = false;            // 禁用深度测试（所有片元都渲染）
				depthMaterial.depthWrite = false;           // 禁用深度写入（不更新深度缓冲区）

				// ---------- 6. 创建阴影平面材质 ----------
				// 这个材质将显示经过高斯模糊处理的深度图
				shadowPlaneMaterial = new THREE.NodeMaterial();
				shadowPlaneMaterial.transparent = true;     // 启用透明，使阴影可以叠加
				shadowPlaneMaterial.depthWrite = false;     // 禁用深度写入，避免影响其他物体的深度测试

				// 兼容性处理：确保纹理对象包含image属性
				if ( ! renderTarget.texture.image ) {
					renderTarget.texture.image = { width: 512, height: 512 };
				}

				// 对深度纹理应用高斯模糊，创建柔和的阴影边缘
				// 参数说明：纹理，模糊半径，迭代次数（4次=高质量模糊），禁用预乘alpha
				const blurredShadow = gaussianBlur( 
					texture( renderTarget.texture ), 
					uBlur, 
					4, 
					{ premultipliedAlpha: false } 
				);
				
				// 配置阴影平面材质
				shadowPlaneMaterial.colorNode = vec3( 0 );  // 颜色设为黑色
				// 透明度 = 模糊后纹理的alpha通道 × 阴影不透明度
				shadowPlaneMaterial.opacityNode = blurredShadow.a.mul( uShadowOpacity );

				// ---------- 7. 创建阴影平面 ----------
				plane = new THREE.Mesh( planeGeometry, shadowPlaneMaterial );
				plane.renderOrder = 1;       // 设置渲染顺序，确保阴影在其他物体之后渲染
				plane.scale.y = - 1;         // Y轴反转，修正纹理方向
				plane.scale.z = - 1;         // Z轴反转，修正法线方向
				shadowGroup.add( plane );

				// ---------- 8. 创建填充平面材质 ----------
				// 这个材质显示平面的基础颜色（用户可调节）
				fillPlaneMaterial = new THREE.NodeMaterial();
				fillPlaneMaterial.transparent = true;       // 启用透明
				fillPlaneMaterial.depthWrite = false;       // 禁用深度写入
				fillPlaneMaterial.colorNode = uPlaneColor;  // 颜色使用uniform变量
				fillPlaneMaterial.opacityNode = uPlaneOpacity; // 透明度使用uniform变量
				
				// 创建填充平面
				fillPlane = new THREE.Mesh( planeGeometry, fillPlaneMaterial );
				fillPlane.rotateX( Math.PI ); // 旋转180度，使其法线朝上
				shadowGroup.add( fillPlane );

				// ---------- 9. 创建阴影相机 ----------
				// 使用正交相机渲染深度图，确保投影无透视变形
				shadowCamera = new THREE.OrthographicCamera(
					- PLANE_WIDTH / 2,   // 左边界
					PLANE_WIDTH / 2,     // 右边界
					PLANE_HEIGHT / 2,    // 上边界
					- PLANE_HEIGHT / 2,  // 下边界
					0,                   // 近平面
					CAMERA_HEIGHT        // 远平面
				);
				shadowCamera.rotation.x = Math.PI / 2; // 旋转相机使其俯视平面
				shadowGroup.add( shadowCamera );

				// ---------- 10. 创建相机辅助线 ----------
				// 用于可视化阴影相机的视锥体，调试用
				cameraHelper = new THREE.CameraHelper( shadowCamera );

				// ---------- 11. 创建WebGPU渲染器 ----------
				renderer = new THREE.WebGPURenderer( { antialias: true } ); // 启用抗锯齿
				renderer.setPixelRatio( window.devicePixelRatio );          // 适配高清屏幕
				renderer.setSize( window.innerWidth, window.innerHeight );  // 设置渲染尺寸
				renderer.setAnimationLoop( animate );                       // 设置动画循环回调
				document.body.appendChild( renderer.domElement );           // 将canvas添加到DOM

				// ---------- 12. 创建调试检查器和GUI ----------
				// 初始化Three.js Inspector调试工具
				renderer.inspector = new Inspector();

				// GUI参数对象，与state对象同步但用于GUI控件
				const params = {
					shadowBlur: state.shadow.blur,
					shadowDarkness: state.shadow.darkness,
					shadowOpacity: state.shadow.opacity,
					planeColor: state.plane.color,
					planeOpacity: state.plane.opacity,
					showWireframe: state.showWireframe
				};

				// 创建名为"设置"的GUI面板
				const gui = renderer.inspector.createParameters( '设置' );

				// 阴影模糊度滑块控件
				gui.add( params, 'shadowBlur', 0, 15, 0.1 )
					.name('阴影模糊度')  // 控件显示名称
					.onChange( () => {
						state.shadow.blur = params.shadowBlur;  // 更新状态对象
						uBlur.value = state.shadow.blur;       // 更新TSL uniform变量
					} );

				// 阴影暗度滑块控件
				gui.add( params, 'shadowDarkness', 0.1, 5, 0.1 )
					.name('阴影暗度')
					.onChange( () => {
						state.shadow.darkness = params.shadowDarkness;
						uDarkness.value = state.shadow.darkness;
					} );

				// 阴影不透明度滑块控件
				gui.add( params, 'shadowOpacity', 0, 1, 0.01 )
					.name('阴影不透明度')
					.onChange( () => {
						state.shadow.opacity = params.shadowOpacity;
						uShadowOpacity.value = state.shadow.opacity;
					} );

				// 平面颜色选择器控件
				gui.addColor( params, 'planeColor' )
					.name('平面颜色')
					.onChange( () => {
						state.plane.color = params.planeColor;
						// 更新颜色uniform，需要将十六进制字符串转换为THREE.Color对象
						uPlaneColor.value.set( state.plane.color );
					} );

				// 平面不透明度滑块控件
				gui.add( params, 'planeOpacity', 0, 1, 0.01 )
					.name('平面不透明度')
					.onChange( () => {
						state.plane.opacity = params.planeOpacity;
						uPlaneOpacity.value = state.plane.opacity;
					} );

				// 显示/隐藏相机辅助线复选框控件
				gui.add( params, 'showWireframe' )
					.name('显示相机辅助线')
					.onChange( () => {
						if ( params.showWireframe ) {
							scene.add( cameraHelper );  // 将辅助线添加到场景
						} else {
							scene.remove( cameraHelper ); // 从场景移除辅助线
						}
					} );

				// ---------- 13. 创建轨道控制器 ----------
				// 启用鼠标交互：左键旋转，右键平移，滚轮缩放
				new OrbitControls( camera, renderer.domElement );
			}

			// ==================== 窗口大小变化处理函数 ====================
			/**
			 * 当浏览器窗口大小变化时调用的函数
			 * 更新相机宽高比和渲染器尺寸，确保3D场景正确适配窗口
			 */
			function onWindowResize() {
				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				camera.updateProjectionMatrix(); // 必须调用此函数使宽高比更改生效
				
				// 更新渲染器尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 动画循环函数 ====================
			/**
			 * 每一帧渲染时调用的函数
			 * 实现双通道渲染：
			 *   1. 第一遍：使用阴影相机渲染深度图到离屏缓冲区
			 *   2. 第二遍：使用主相机渲染完整场景
			 */
			function animate() {
				// ---------- 1. 更新场景中的物体动画 ----------
				// 旋转所有网格物体，增加场景的动态效果
				meshes.forEach( m => {
					m.rotation.x += 0.01;  // 绕X轴旋转，每帧增加0.01弧度
					m.rotation.y += 0.02;  // 绕Y轴旋转，每帧增加0.02弧度
				} );

				// ---------- 2. 第一遍渲染：生成深度图 ----------
				// 保存当前场景状态，以便渲染后恢复
				const initialBackground = scene.background;  // 保存原始背景
				scene.background = null;                     // 清除背景，渲染透明深度图

				const prevOverride = scene.overrideMaterial; // 保存当前的覆盖材质
				const prevHelperVisible = cameraHelper.visible; // 保存相机辅助线可见性
				cameraHelper.visible = false;                // 隐藏相机辅助线（深度图不需要）
				scene.overrideMaterial = depthMaterial;      // 设置深度材质为覆盖材质

				const initialAutoClear = renderer.autoClear; // 保存自动清除状态
				renderer.autoClear = true;                   // 启用自动清除，确保每帧都清空缓冲区

				// 保存并设置清除alpha值
				const initialClearAlpha = renderer.getClearAlpha ? renderer.getClearAlpha() : undefined;
				if ( initialClearAlpha !== undefined ) {
					renderer.setClearAlpha( 0 ); // 设置清除alpha为0（完全透明背景）
				}

				// 切换到离屏渲染目标
				renderer.setRenderTarget( renderTarget );
				renderer.clear(); // 清除渲染目标的内容
				// 使用阴影相机渲染场景，生成深度图
				renderer.render( scene, shadowCamera );

				// ---------- 3. 恢复场景状态 ----------
				// 恢复所有修改过的状态，确保第二遍渲染正常
				scene.overrideMaterial = prevOverride;       // 恢复原始覆盖材质
				renderer.setRenderTarget( null );            // 切换回主渲染目标（屏幕）
				renderer.autoClear = initialAutoClear;       // 恢复自动清除设置
				if ( initialClearAlpha !== undefined ) {
					renderer.setClearAlpha( initialClearAlpha ); // 恢复原始清除alpha值
				}
				scene.background = initialBackground;        // 恢复原始背景
				cameraHelper.visible = prevHelperVisible;    // 恢复相机辅助线可见性

				// ---------- 4. 第二遍渲染：渲染完整场景 ----------
				// 使用主相机渲染整个场景到屏幕
				// 此时阴影平面材质会使用第一遍生成的深度图（经过高斯模糊）
				renderer.render( scene, camera );
			}

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