<!-- 一、代码核心功能描述
这是一个基于Three.js WebGPU的3D图形演示，主要展示自定义颜色和透明度的阴影映射技术。

主要功能：
3D场景渲染：创建一个包含两条龙和地面的3D场景

动态阴影系统：实现实时阴影投射和接收

自定义阴影着色：通过着色器编程控制阴影的颜色和透明度

交互式控制：用户可以通过鼠标旋转、平移和缩放场景

模型加载与处理：加载GLTF格式的3D模型并进行克隆和修改

场景组成：
两条龙模型：使用相同的模型但应用不同的材质

第一条龙：默认材质颜色

第二条龙：红色衰减颜色

地面平面：放大后作为阴影投射的表面

光源系统：环境光 + 定向光（主阴影光源）

交互控制：轨道相机控制器

二、主要技术点详解
1. WebGPU渲染技术
javascript
import * as THREE from 'three/webgpu';
const renderer = new THREE.WebGPURenderer({ antialias: true });
下一代图形API：取代WebGL，提供更底层的GPU访问

更好的性能：多线程支持、更高效的资源管理

现代特性：支持计算着色器、光线追踪等高级功能

2. Three.js着色器语言（TSL）
javascript
import { Fn, mix } from 'three/tsl';
const customShadow = Fn(([color, opacity = 1]) => {
    return mix(1, color, opacity);
});
声明式着色器编程：在JavaScript中直接编写着色器代码

实时编译：运行时将TSL代码编译为WebGPU着色器

类型安全：提供更好的错误检查和类型推断

3. 阴影映射系统
javascript
dirLight.castShadow = true;
dirLight.shadow.mapSize.width = 2048;
dirLight.shadow.mapSize.height = 2048;
原理：从光源视角渲染深度贴图，然后在相机视角比较深度

阴影相机：使用正交相机定义阴影渲染范围

质量参数：

mapSize：阴影贴图分辨率（2048×2048）

radius：阴影模糊半径（软阴影）

bias：阴影偏移（避免阴影失真）

4. 自定义阴影着色器节点
javascript
dragon.material.castShadowNode = customShadow(dragon.material.attenuationColor);
材质扩展：通过castShadowNode属性覆盖默认阴影计算

颜色混合算法：

glsl
mix(1, color, opacity) = 白色 * (1 - opacity) + color * opacity
效果：通过调整opacity控制阴影颜色的饱和度

5. GLTF模型处理
javascript
const loader = new GLTFLoader();
const gltf = await loader.loadAsync('models/gltf/DragonAttenuation.glb');
GLTF格式：业界标准的3D传输格式

异步加载：使用async/await处理模型加载

模型克隆：

javascript
const dragon2 = dragon.clone();
dragon2.material = dragon.material.clone();
几何体共享，材质独立

节省内存，支持差异化材质

6. 光照系统配置
javascript
// 环境光（无阴影）
const hemi = new THREE.AmbientLight(0xffffff, .5);

// 定向光（主阴影光源）
const dirLight = new THREE.DirectionalLight(0x6666ff, 10);
dirLight.position.set(3, 5, 17);
双光源系统：

环境光：提供均匀的基础照明

定向光：模拟太阳光，产生方向性阴影

阴影优化：

javascript
dirLight.shadow.autoUpdate = false;  // 性能优化
dirLight.shadow.needsUpdate = true;   // 初始更新
7. 后处理与色调映射
javascript
renderer.toneMapping = THREE.AgXToneMapping;
renderer.toneMappingExposure = 1.5;
AgX色调映射：先进的色调映射算法

曝光控制：1.5倍曝光增强场景亮度

抗锯齿：antialias: true开启MSAA抗锯齿

8. 交互控制系统
javascript
const controls = new OrbitControls(camera, renderer.domElement);
三轴控制：

左键拖拽：绕目标点旋转

右键拖拽：场景平移

滚轮：缩放视图

限制设置：防止相机过近或过远

9. 响应式设计
javascript
window.addEventListener('resize', onWindowResize);
自适应窗口：实时调整渲染尺寸

相机比例同步：更新相机宽高比

投影矩阵更新：确保正确透视

三、技术架构图
text
应用程序架构：
┌─────────────────────────────────────────┐
│           HTML页面结构                  │
│  ┌───────────────────────────────────┐  │
│  │          Three.js WebGPU          │  │
│  │  ┌─────────────┬───────────────┐  │  │
│  │  │   场景管理   │   渲染管线    │  │  │
│  │  └─────────────┴───────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

渲染流程：
1. 初始化WebGPU上下文
2. 创建3D场景和相机
3. 加载并处理GLTF模型
4. 设置光照和阴影系统
5. 应用自定义着色器节点
6. 每帧执行渲染循环
7. 处理用户交互输入
四、创新点与亮点
1. 自定义阴影颜色
传统阴影通常是灰色或黑色

本示例允许为阴影指定任意颜色（如蓝色、红色）

2. 阴影透明度控制
通过mix函数实现颜色混合

模拟半透明阴影效果

3. WebGPU优化
利用现代GPU架构

支持更复杂的着色器计算

4. 模块化设计
清晰的代码结构

易于扩展和修改 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：显示Three.js的WebGPU示例，包含阴影映射和透明度功能 -->
		<title>Three.js WebGPU示例 - 阴影映射与透明度</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>透明度阴影映射示例</span>
			</div>

			<!-- 功能描述：简要说明示例的核心特性 -->
			<small>通过材质实现自定义颜色和透明度的阴影映射技术演示</small>
			
		</div>

		<!-- 导入映射配置（Import Maps）：定义JavaScript模块的别名和路径 -->
		<!-- 作用：让浏览器知道如何解析模块导入语句中的模块标识符 -->
		<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>

		<!-- 主应用程序脚本：使用ES模块语法，在页面加载时执行 -->
		<script type="module">
			// 导入Three.js的WebGPU模块：这是Three.js的WebGPU后端实现
			// 与传统的WebGL渲染器不同，WebGPU提供了更底层的GPU访问和更好的性能
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js着色器语言（TSL）功能：
			// Fn: 用于创建自定义着色器函数
			// mix: 线性混合函数，用于颜色和值的插值计算
			import { Fn, mix } from 'three/tsl';

			// 导入调试检查器：用于在运行时检查和调试Three.js场景
			// 可以查看场景层次结构、材质属性、光照设置等
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器：提供鼠标和触摸交互，用于控制相机绕目标点旋转、平移和缩放
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入GLTF加载器：用于加载GLTF格式的3D模型
			// GLTF（GL Transmission Format）是Khronos Group制定的3D模型标准格式
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

			// 全局变量声明：这些变量将在整个应用程序中共享使用
			let camera;      // 相机对象：定义观察场景的视角
			let scene;       // 场景对象：包含所有3D对象（模型、灯光、相机等）的容器
			let renderer;    // 渲染器对象：负责将3D场景渲染到2D画布上

			// 初始化函数调用：启动整个应用程序
			init();

			// 异步初始化函数：使用async/await处理异步操作（如模型加载）
			async function init() {
				// 创建容器元素：用于承载渲染器的画布元素
				// 这个div将作为Three.js渲染输出的父容器
				const container = document.createElement('div');
				
				// 将容器添加到body中，使其在页面上可见
				document.body.appendChild(container);

				// ==================== 相机设置 ====================
				// 创建透视相机：模拟人眼的视角，物体近大远小
				// 参数说明：
				// 45 - 视野角度（Field of View），单位是度，决定相机可见范围
				// window.innerWidth / window.innerHeight - 宽高比，匹配窗口比例
				// 0.1 - 近裁剪平面，距离相机0.1单位以内的物体不显示
				// 40 - 远裁剪平面，距离相机40单位以外的物体不显示
				camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 40);
				
				// 设置相机初始位置：使用三维坐标(x, y, z)
				// x: -4（左侧），y: 2（上方），z: 6（前方）
				camera.position.set(-4, 2, 6);

				// ==================== 渲染器设置 ====================
				// 创建WebGPU渲染器实例：这是Three.js的WebGPU后端
				// 参数：{ antialias: true } 开启抗锯齿，使边缘更平滑
				renderer = new THREE.WebGPURenderer({ antialias: true });
				
				// 设置设备像素比：匹配显示设备的物理像素和CSS像素比例
				// 在高DPI屏幕（如Retina显示屏）上提供更清晰的渲染
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环：将渲染函数注册为持续调用的回调函数
				// 这创建了一个持续的渲染循环，通常以显示器刷新率（60Hz）运行
				renderer.setAnimationLoop(render);
				
				// 设置色调映射（Tone Mapping）：将HDR（高动态范围）颜色转换为显示器的LDR范围
				// AgXToneMapping是一种先进的色调映射算法，提供更好的颜色表现
				renderer.toneMapping = THREE.AgXToneMapping;
				
				// 设置曝光值：控制场景的整体亮度，1.5表示150%的亮度
				renderer.toneMappingExposure = 1.5;
				
				// 启用阴影映射：允许物体投射和接收阴影
				renderer.shadowMap.enabled = true;
				
				// 初始化检查器：附加调试工具到渲染器
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到容器中
				// 这样canvas就会显示在网页上
				container.appendChild(renderer.domElement);

				// ==================== 场景设置 ====================
				// 创建场景对象：这是所有3D对象的根容器
				scene = new THREE.Scene();
				
				// 设置场景背景颜色：使用十六进制颜色值0x9e9eff（浅蓝色）
				scene.background = new THREE.Color(0x9e9eff);

				// ==================== 灯光和阴影系统 ====================
				// 1. 环境光（Ambient Light）：提供均匀的全方位光照，没有方向
				// 参数：颜色（白色），强度（0.5，即50%强度）
				// 环境光没有阴影，只影响所有物体的基本亮度
				const hemi = new THREE.AmbientLight(0xffffff, .5);
				scene.add(hemi);

				// 2. 定向光（Directional Light）：模拟太阳光，所有光线平行
				// 参数：颜色（0x6666ff，蓝紫色），强度（10，非常高）
				// 定向光可以产生清晰的阴影
				const dirLight = new THREE.DirectionalLight(0x6666ff, 10);
				
				// 设置光源位置：使用三维坐标
				// 这个位置决定了光线的方向和阴影的角度
				dirLight.position.set(3, 5, 17);
				
				// 启用光源投射阴影：允许这个光源产生阴影
				dirLight.castShadow = true;

				// 阴影相机参数设置：阴影相机是一个正交相机，定义了阴影的渲染范围
				// 近裁剪面：距离光源0.1单位开始渲染阴影
				dirLight.shadow.camera.near = 0.1;
				// 远裁剪面：距离光源50单位停止渲染阴影
				dirLight.shadow.camera.far = 50;
				// 定义阴影相机的视锥体范围（形成一个长方体区域）
				dirLight.shadow.camera.right = 5;   // 右边界
				dirLight.shadow.camera.left = -5;   // 左边界
				dirLight.shadow.camera.top = 5;     // 上边界
				dirLight.shadow.camera.bottom = -5; // 下边界

				// 阴影贴图分辨率：决定阴影的质量和清晰度
				// 分辨率越高，阴影越清晰，但性能消耗也越大
				// 2048x2048是高质量阴影的常用设置
				dirLight.shadow.mapSize.width = 2048;
				dirLight.shadow.mapSize.height = 2048;

				// 阴影模糊半径：控制阴影边缘的模糊程度
				// 值越大，阴影边缘越模糊，可以创建更柔和的阴影
				dirLight.shadow.radius = 4;
				
				// 阴影偏移：解决阴影失真（Shadow Acne）问题
				// 当阴影表面与阴影贴图像素不完全匹配时，会出现条纹状失真
				// 负值将阴影稍微拉离物体表面
				dirLight.shadow.bias = -0.0005;

				// 性能优化设置：
				// 禁用阴影自动更新，只在需要时手动更新
				// 这可以避免每一帧都重新计算阴影贴图
				dirLight.shadow.autoUpdate = false;
				// 标记阴影需要更新，确保初始渲染时有正确的阴影
				dirLight.shadow.needsUpdate = true;

				// 将定向光添加到场景中
				scene.add(dirLight);

				// ==================== 3D模型加载 ====================
				// 创建GLTF加载器实例
				const loader = new GLTFLoader();
				
				// 异步加载GLTF模型文件
				// 'models/gltf/DragonAttenuation.glb' 是模型文件路径
				// .glb是GLTF的二进制格式，包含模型、材质、动画等所有数据
				const gltf = await loader.loadAsync('models/gltf/DragonAttenuation.glb');
				
				// 调整整个模型场景的位置
				// 参数：x, y, z 坐标，将模型向后移动0.5单位
				gltf.scene.position.set(0, 0, -0.5);

				// 从加载的场景中获取子对象
				// gltf.scene.children[0] 通常是地面或基础平面
				const floor = gltf.scene.children[0];
				
				// 放大地面尺寸：在原有基础上增加4个单位
				// 这样地面就更大了，能更好地显示阴影效果
				floor.scale.x += 4;
				floor.scale.y += 4;

				// 获取龙模型：通常是场景中的第二个子对象
				const dragon = gltf.scene.children[1];
				
				// 设置第一条龙的位置
				dragon.position.set(-1.5, -0.8, 1);

				// 克隆第二条龙：创建第一条龙的副本
				const dragon2 = dragon.clone();
				
				// 克隆龙的材质：确保两条龙有独立的材质实例
				// 这样我们可以单独修改第二条龙的材质属性而不影响第一条
				dragon2.material = dragon.material.clone();
				
				// 修改第二条龙的衰减颜色：设置为红色
				// attenuationColor可能是材质自定义属性，用于控制阴影颜色
				dragon2.material.attenuationColor = new THREE.Color(0xff0000);
				
				// 设置第二条龙的位置：在第一条龙的基础上向右移动4个单位
				dragon2.position.x += 4;
				
				// 将第二条龙添加到GLTF场景中
				gltf.scene.add(dragon2);

				// ==================== 自定义阴影着色器节点 ====================
				// 使用TSL（Three.js着色器语言）创建自定义阴影处理函数
				// Fn函数创建一个可在着色器中调用的函数
				// 参数：[color, opacity = 1] 定义函数参数，opacity有默认值1
				const customShadow = Fn(([color, opacity = 1]) => {
					// 这里是着色器代码的执行部分
					
					// 方法1：使用透明度混合（注释状态）
					// 直接返回带有透明度的颜色向量(r,g,b,a)
					// 这种方法的透明度会影响整个阴影的透明度
					// return vec4(color, opacity);
					
					// 方法2：使用颜色混合（当前使用的方法）
					// mix函数执行线性插值：mix(x, y, a) = x * (1 - a) + y * a
					// 这里：1代表白色，color是指定颜色，opacity是混合系数
					// 当opacity=1时，完全使用color；当opacity=0时，完全使用白色
					// 这种方法通过改变颜色亮度来模拟透明度效果
					return mix(1, color, opacity);
				});

				// ==================== 应用阴影设置 ====================
				// 设置地面接收阴影：地面会显示其他物体投射的阴影
				floor.receiveShadow = true;

				// 设置两条龙的阴影属性：
				// castShadow = true: 龙会投射阴影到其他物体上
				// receiveShadow = true: 龙会接收其他物体投射的阴影
				dragon.castShadow = dragon2.castShadow = true;
				dragon.receiveShadow = dragon2.receiveShadow = true;

				// 应用自定义阴影着色器节点到材质：
				// castShadowNode属性允许材质定义自定义的阴影着色器
				// 这里将自定义的阴影函数应用到每条龙的材质上
				// 传递材质中的attenuationColor作为阴影颜色参数
				dragon.material.castShadowNode = customShadow(dragon.material.attenuationColor);
				dragon2.material.castShadowNode = customShadow(dragon2.material.attenuationColor);

				// 将完整的GLTF场景（包含地面和两条龙）添加到主场景中
				scene.add(gltf.scene);

				// ==================== 交互控制设置 ====================
				// 创建轨道控制器：连接相机和渲染器的DOM元素
				// 这样用户可以通过鼠标与场景交互
				const controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置相机的最小缩放距离：防止相机离目标太近
				controls.minDistance = 0.1;
				
				// 设置相机的最大缩放距离：防止相机离目标太远
				controls.maxDistance = 10;
				
				// 设置控制器的目标点：相机围绕这个点旋转
				controls.target.set(0, 0, 0);
				
				// 初始化更新控制器：计算初始状态
				controls.update();

				// ==================== 窗口事件监听 ====================
				// 监听窗口大小改变事件：当用户调整浏览器窗口大小时触发
				window.addEventListener('resize', onWindowResize);
			}

			// 窗口大小改变事件处理函数
			function onWindowResize() {
				// 更新相机的宽高比：匹配新的窗口尺寸比例
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵：当相机参数改变后必须调用
				// 这会重新计算相机的内部参数，确保正确渲染
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸：使渲染画布与窗口新尺寸匹配
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			// ==================== 渲染循环函数 ====================
			// 这是动画循环的核心函数，每帧都会被调用
			function render() {
				// 执行渲染：将3D场景通过相机视角渲染到2D画布上
				// 参数：scene - 要渲染的场景，camera - 使用的相机
				renderer.render(scene, camera);
				
				// 注意：这里没有调用requestAnimationFrame，因为
				// renderer.setAnimationLoop(render)已经创建了循环
			}
		</script>
	</body>
</html>