<!-- 代码功能概述
这是一个基于 Three.js WebGPU 渲染器 的 3D 图形演示应用，专门展示置换贴图（Displacement Mapping） 和其他高级纹理技术的综合效果。应用加载了一个忍者头部模型，并应用了多种贴图来创建高度逼真的表面细节和材质效果。

核心功能模块
1. 3D 场景展示
使用正交相机展示忍者头部模型

支持鼠标拖拽旋转视角（轨道控制）

自适应窗口大小调整

实时渲染的 3D 场景

2. 多纹理复合渲染
法线贴图：模拟表面凹凸细节，不改变几何体

置换贴图：实际改变顶点位置，创建真实几何细节

环境光遮蔽贴图：模拟缝隙和凹陷处的阴影

环境贴图：模拟物体对周围环境的反射

基础颜色贴图：定义物体基本颜色

3. 交互式参数调节
实时调节材质参数的 GUI 控制面板

可调节金属度、粗糙度、各贴图强度等

即时反馈的参数变化效果

4. 动态照明系统
环境光提供均匀照明

多个点光源提供多角度照明

动态移动的红色点光源（圆周运动）

蓝色静态点光源提供对比色照明

主要技术点详解
1. WebGPU 渲染技术
javascript
renderer = new THREE.WebGPURenderer();
下一代图形 API：替代 WebGL，提供更好的性能和更现代的 GPU 功能访问

并行处理能力：更好的多线程支持和计算着色器能力

低开销驱动：减少 CPU 到 GPU 的通信开销

2. 置换贴图技术
javascript
displacementMap: displacementMap,
displacementScale: settings.displacementScale,
displacementBias: -0.428408,
技术原理：
顶点位移：根据贴图像素的灰度值实际移动网格顶点

几何细节：创建真实的表面凹凸，而非视觉假象

性能考量：需要足够的网格细分才能表现细节

与法线贴图的区别：
特性	置换贴图	法线贴图
几何变化	实际改变顶点位置	仅改变表面法线方向
轮廓效果	改变物体轮廓	不改变物体轮廓
性能消耗	较高（需要细分）	较低
真实感	高（有真实深度）	中（视觉假象）
3. PBR（基于物理的渲染）材质
javascript
material = new THREE.MeshStandardNodeMaterial({
  metalness: settings.metalness,
  roughness: settings.roughness,
  // ... 其他属性
});
PBR 核心参数：
金属度（Metalness）：0.0（非金属）到 1.0（金属）

粗糙度（Roughness）：0.0（镜面光滑）到 1.0（完全粗糙）

能量守恒：确保反射和漫反射的总能量不超过入射光

PBR 优势：
物理准确性：基于真实物理的光照模型

一致的外观：在不同光照条件下保持一致性

艺术家友好：参数直观，容易调整

4. 环境贴图与 IBL（基于图像的照明）
javascript
envMap: reflectionCube,
envMapIntensity: settings.envMapIntensity,
技术实现：
立方体贴图：6个方向的场景图像

HDR 支持：可支持高动态范围图像

实时反射：模拟物体对周围环境的反射

应用效果：
真实的反射：金属和高光表面的环境反射

环境照明：作为间接光源照亮场景

氛围营造：通过环境图像设定场景基调

5. 法线贴图技术
javascript
normalMap: normalMap,
normalScale: new THREE.Vector2(1, -1),
工作原理：
法线向量存储：将表面法线方向编码为 RGB 颜色

切线空间：在物体局部坐标系中定义法线

光照计算：修改后的法线影响光照计算，产生凹凸感

6. AO（环境光遮蔽）贴图
javascript
aoMap: aoMap,
aoMapIntensity: 1,
作用机制：
预计算阴影：烘焙物体自身遮挡产生的阴影

接触阴影：增强物体接触区域的阴影深度

细节增强：突出模型的结构细节

7. 正交相机系统
javascript
camera = new THREE.OrthographicCamera(
  -height * aspect, height * aspect,
  height, -height,
  1, 10000
);
正交相机特点：
无透视变形：物体大小不随距离变化

平行投影：所有投影线平行

应用场景：技术图示、等距视图、UI 元素

8. 模块化架构
javascript
// ES6 模块导入
import * as THREE from 'three/webgpu';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
架构优势：
代码组织：清晰的依赖关系

按需加载：只导入需要的功能

维护性：易于更新和替换组件

9. GUI 交互系统
javascript
const gui = renderer.inspector.createParameters('settings');
gui.add(settings, 'metalness', 0, 1).onChange(function(value) {
  material.metalness = value;
});
交互设计：
实时反馈：参数变化立即反映在渲染结果中

范围控制：合理的参数范围和默认值

学习工具：帮助理解不同参数对材质的影响

10. 模型加载与处理
javascript
const loader = new OBJLoader();
loader.load('models/obj/ninja/ninjaHead_Low.obj', function(group) {
  const geometry = group.children[0].geometry;
  geometry.center();  // 几何体居中
  // ...
});
处理流程：
加载 OBJ 模型：包含几何数据和材质信息

几何体居中：确保模型在场景中心

缩放调整：适配场景尺寸

材质应用：将 PBR 材质应用到模型

技术栈总结
技术领域	使用的技术	作用
渲染 API	WebGPU	高性能图形渲染
3D 引擎	Three.js	3D 图形框架
材质系统	PBR + 多种贴图	真实感渲染
模型格式	OBJ	3D 模型加载
纹理格式	PNG/JPG	贴图图像
交互控制	OrbitControls	视角控制
UI 界面	Inspector GUI	参数调节
模块系统	ES6 Modules	代码组织
性能优化特点
合理的贴图分辨率：平衡视觉效果和内存使用

静态环境贴图：预计算的立方体贴图，减少实时计算

适当的网格复杂度：足够的细分用于置换贴图，但不过度

优化的着色器：PBR 着色器经过性能优化

按需渲染：仅在参数变化或动画时重新渲染

教育价值
这个示例代码非常适合学习：

WebGPU 入门：了解下一代 Web 图形 API

PBR 材质原理：理解基于物理的渲染

贴图技术对比：比较不同贴图技术的效果和适用场景

Three.js 高级功能：掌握 Three.js 的复杂特性

实时图形编程：学习交互式 3D 应用的开发模式 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 
			页面标题：显示在浏览器标签页上的标题
			修改为中文标题："Three.js WebGPU 置换贴图示例"
		-->
		<title>Three.js WebGPU 置换贴图示例</title>
		<!-- 
			字符编码声明：
			- utf-8：使用UTF-8字符编码，支持中文等多语言字符
			- 确保网页能正确显示中文字符
		-->
		<meta charset="utf-8">
		<!-- 
			视口(viewport)设置：
			- width=device-width：视口宽度等于设备宽度
			- user-scalable=no：禁止用户缩放页面
			- minimum-scale=1.0：最小缩放比例为1.0
			- maximum-scale=1.0：最大缩放比例为1.0
			- 这些设置确保网页在移动设备上正确显示
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 
			外部CSS样式表链接：
			- rel="stylesheet"：指定链接类型为样式表
			- href="example.css"：样式表文件路径
			- 用于控制页面布局和样式
		-->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>

	<body>

		<!-- 
			信息面板容器：
			- id="info"：用于CSS样式和JavaScript选择器
			- 显示Three.js标志、标题和说明信息
		-->
		<div id="info">
			<!-- 
				Three.js官方标志链接：
				- href：链接到Three.js官网
				- target="_blank"：在新标签页打开链接
				- rel="noopener"：安全设置，防止新页面访问原页面的window对象
				- class="logo-link"：CSS样式类，可能包含背景图片显示Three.js标志
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装容器 -->
			<div class="title-wrapper">
				<!-- 
					Three.js链接标题：
					- 点击可访问Three.js官网
					修改为中文："Three.js"保持英文，因为这是库名称
				-->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 
					页面副标题：
					修改为中文："置换贴图演示"
					原英文："Displacement Map"
				-->
				<span>置换贴图演示</span>
			</div>

			<!-- 
				详细说明文字区域：
				- <small>标签：表示小号文字
				全部内容修改为中文
			-->
			<small>
				<!-- 
					第一行：使用的贴图类型说明
					原英文：( normal + ao + displacement + environment ) maps.
				-->
				(法线贴图 + 环境光遮蔽贴图 + 置换贴图 + 环境贴图) 组合应用。<br />
				<!-- 
					第二行：模型来源说明，包含链接
					原英文：Ninja head from <a>AMD GPU MeshMapper</a>.
				-->
				忍者头部模型来自 <a href="https://gpuopen.com/archive/gamescgi/amd-gpu-meshmapper/" target="_blank" rel="noopener">AMD GPU MeshMapper</a>。
			</small>
		</div>

		<!-- 
			导入映射(Import Map)配置：
			- type="importmap"：指定脚本类型为导入映射
			- 用于浏览器模块导入时重定向模块路径
			- 允许使用简化的导入路径
		-->
		<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模块
			- 模块内的代码在严格模式下执行
			- 支持import/export语法
		-->
		<script type="module">

			// ============================================
			// 模块导入部分
			// ============================================
			
			// 导入Three.js核心库（WebGPU版本）
			// 使用importmap中配置的路径"three/webgpu"
			import * as THREE from 'three/webgpu';

			// 导入调试器(Inspector)工具
			// 用于创建参数调节面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器(OrbitControls)
			// 允许用户通过鼠标拖拽、缩放来查看3D场景
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入OBJ模型加载器(OBJLoader)
			// 用于加载.obj格式的3D模型文件
			import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';

			// ============================================
			// 全局变量声明
			// ============================================
			
			// 场景相关变量
			let camera;      // 相机对象 - 定义观察场景的视角
			let scene;       // 场景对象 - 包含所有3D对象、灯光等
			let renderer;    // 渲染器对象 - 负责将3D场景渲染到2D画布
			let controls;    // 控制器对象 - 用户交互控制

			// 材质参数设置对象
			// 存储所有可调节的材质参数，默认值根据视觉效果优化设置
			const settings = {
				metalness: 1.0,           // 金属度：0.0(非金属)到1.0(金属)
				roughness: 0.4,           // 粗糙度：0.0(镜面光滑)到1.0(完全粗糙)
				ambientIntensity: 0.2,    // 环境光强度：控制全局环境光的亮度
				aoMapIntensity: 1.0,      // AO贴图强度：环境光遮蔽效果的强度
				envMapIntensity: 1.0,     // 环境贴图强度：反射环境贴图的亮度
				displacementScale: 2.436143, // 置换贴图缩放：控制顶点位移的程度（来自原始模型数据）
				normalScale: 1.0          // 法线贴图缩放：控制法线贴图效果的强度
			};

			// 网格和材质引用
			let mesh;        // 网格对象 - 包含几何体和材质的3D对象
			let material;    // 材质对象 - 定义3D对象的外观特性

			// 灯光引用
			let pointLight;   // 点光源 - 从单点向所有方向发射光线
			let ambientLight; // 环境光 - 均匀照亮整个场景的光源

			// 相机视锥体高度
			// 正交相机的上平面和下平面的距离
			const height = 500;

			// 用于灯光动画的旋转角度（弧度制）
			// 控制红色点光源的圆周运动
			let r = 0.0;

			// ============================================
			// 初始化函数调用
			// ============================================
			
			// 初始化3D场景
			init();
			// 初始化GUI控制面板
			initGui();

			// ============================================
			// 函数定义
			// ============================================

			/**
			 * 初始化GUI控制面板
			 * 创建交互式参数调节界面，允许用户实时修改材质参数
			 */
			function initGui() {

				// 通过渲染器的调试器创建参数面板
				// 面板标题为'settings'
				const gui = renderer.inspector.createParameters( 'settings' );

				// 添加金属度控制滑块
				gui.add( settings, 'metalness', 0, 1 )      // 参数名、最小值、最大值
					.onChange( function ( value ) {          // 值改变时的回调函数
						material.metalness = value;         // 更新材质的金属度属性
					} );

				// 添加粗糙度控制滑块
				gui.add( settings, 'roughness', 0, 1 )
					.onChange( function ( value ) {
						material.roughness = value;         // 更新材质的粗糙度属性
					} );

				// 添加AO贴图强度控制滑块
				// AO(Ambient Occlusion)：环境光遮蔽，模拟物体缝隙处的阴影
				gui.add( settings, 'aoMapIntensity', 0, 1 )
					.onChange( function ( value ) {
						material.aoMapIntensity = value;    // 更新材质的AO贴图强度
					} );

				// 添加环境光强度控制滑块
				gui.add( settings, 'ambientIntensity', 0, 1 )
					.onChange( function ( value ) {
						ambientLight.intensity = value;     // 更新环境光的强度
					} );

				// 添加环境贴图强度控制滑块
				// 环境贴图用于模拟物体对周围环境的反射
				gui.add( settings, 'envMapIntensity', 0, 3 ) // 最大值设为3，允许过曝效果
					.onChange( function ( value ) {
						material.envMapIntensity = value;   // 更新材质的环境贴图强度
					} );

				// 添加置换贴图缩放控制滑块
				// 置换贴图：通过改变顶点位置创建真实的几何细节
				gui.add( settings, 'displacementScale', 0, 3.0 )
					.onChange( function ( value ) {
						material.displacementScale = value; // 更新材质的置换贴图缩放
					} );

				// 添加法线贴图缩放控制滑块
				// 法线贴图：通过改变表面法线方向模拟细节，不改变几何体
				gui.add( settings, 'normalScale', - 1, 1 )  // 允许负值，可以反转法线方向
					.onChange( function ( value ) {
						// 设置法线缩放向量，Y轴取反（某些模型需要）
						// 乘以value实现缩放控制
						material.normalScale.set( 1, - 1 ).multiplyScalar( value );
					} );

			}

			/**
			 * 主初始化函数
			 * 创建3D场景的所有元素：渲染器、相机、灯光、材质、模型等
			 */
			function init() {

				// ============================================
				// 1. 创建DOM容器和渲染器
				// ============================================
				
				// 创建div元素作为Three.js渲染器的容器
				const container = document.createElement( 'div' );
				// 将容器添加到body元素中
				document.body.appendChild( container );

				// 创建WebGPU渲染器实例
				// WebGPU是新一代图形API，比WebGL性能更好
				renderer = new THREE.WebGPURenderer();
				
				// 设置动画循环回调函数
				// animate函数会每一帧被调用
				renderer.setAnimationLoop( animate );
				
				// 设置设备像素比
				// 确保在高DPI屏幕上清晰显示
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 附加调试器到渲染器
				// 用于创建GUI控制面板
				renderer.inspector = new Inspector();
				
				// 将渲染器的canvas元素添加到容器中
				container.appendChild( renderer.domElement );

				// ============================================
				// 2. 创建场景和相机
				// ============================================
				
				// 创建3D场景对象
				// 所有3D对象、灯光、相机都将添加到场景中
				scene = new THREE.Scene();

				// 计算窗口宽高比
				// 用于设置正交相机的左右平面
				const aspect = window.innerWidth / window.innerHeight;
				
				// 创建正交相机
				// 正交相机不会产生透视变形，物体大小不随距离改变
				camera = new THREE.OrthographicCamera( 
					- height * aspect,  // 左平面：负宽高比乘以高度
					height * aspect,    // 右平面：正宽高比乘以高度
					height,             // 上平面：正高度
					- height,           // 下平面：负高度
					1,                  // 近裁剪面：相机能看到的最近距离
					10000               // 远裁剪面：相机能看到的最远距离
				);
				
				// 设置相机在Z轴上的位置
				// 将相机向后移动，确保能看到场景中的物体
				camera.position.z = 1500;
				
				// 将相机添加到场景中
				scene.add( camera );

				// 创建轨道控制器
				// 将相机和渲染器的canvas元素关联
				controls = new OrbitControls( camera, renderer.domElement );
				
				// 禁用缩放功能
				// 因为正交相机缩放没有透视效果，所以禁用
				controls.enableZoom = false;
				
				// 启用阻尼效果
				// 鼠标松开后相机会有惯性继续移动一点，提升用户体验
				controls.enableDamping = true;

				// ============================================
				// 3. 设置灯光系统
				// ============================================
				
				// 环境光：均匀照亮整个场景
				// 参数：颜色(白色)、强度(从settings读取)
				ambientLight = new THREE.AmbientLight( 0xffffff, settings.ambientIntensity );
				scene.add( ambientLight );

				// 点光源1：红色动态光源
				// 参数：颜色(红色)、强度(1.5)、距离(0表示无限远)、衰减(0表示无衰减)
				pointLight = new THREE.PointLight( 0xff0000, 1.5, 0, 0 );
				pointLight.position.z = 2500;  // 设置在Z轴上较远位置
				scene.add( pointLight );

				// 点光源2：淡红色固定光源（附加到相机上）
				// 强度较大(3.0)，为相机视角提供基本照明
				const pointLight2 = new THREE.PointLight( 0xff6666, 3, 0, 0 );
				camera.add( pointLight2 );  // 添加到相机，随相机移动

				// 点光源3：蓝色静态光源
				// 提供对比色照明，增强模型立体感
				const pointLight3 = new THREE.PointLight( 0x0000ff, 1.5, 0, 0 );
				pointLight3.position.x = - 1000;  // 设置在X轴负方向
				pointLight3.position.z = 1000;    // 设置在Z轴正方向
				scene.add( pointLight3 );

				// ============================================
				// 4. 加载环境贴图（立方体贴图）
				// ============================================
				
				// 环境贴图文件路径
				const path = 'textures/cube/SwedishRoyalCastle/';
				// 图片格式
				const format = '.jpg';
				// 立方体贴图的6个面文件路径
				// 顺序：右(+X)、左(-X)、上(+Y)、下(-Y)、前(+Z)、后(-Z)
				const urls = [
					path + 'px' + format,  // 右面(right/positive X)
					path + 'nx' + format,  // 左面(left/negative X)
					path + 'py' + format,  // 上面(up/positive Y)
					path + 'ny' + format,  // 下面(down/negative Y)
					path + 'pz' + format,  // 前面(front/positive Z)
					path + 'nz' + format   // 后面(back/negative Z)
				];

				// 使用立方体贴图加载器加载环境贴图
				// 用于模拟物体对周围环境的反射
				const reflectionCube = new THREE.CubeTextureLoader().load( urls );

				// ============================================
				// 5. 加载纹理贴图
				// ============================================
				
				// 创建纹理加载器实例
				const textureLoader = new THREE.TextureLoader();
				
				// 加载法线贴图
				// 法线贴图存储表面法线信息，用于模拟细节而不增加多边形
				const normalMap = textureLoader.load( 'models/obj/ninja/normal.png' );
				
				// 加载环境光遮蔽贴图(AO Map)
				// 存储环境光遮蔽信息，模拟缝隙和凹陷处的阴影
				const aoMap = textureLoader.load( 'models/obj/ninja/ao.jpg' );
				
				// 加载置换贴图(Displacement Map)
				// 存储高度信息，实际改变顶点位置创建几何细节
				const displacementMap = textureLoader.load( 'models/obj/ninja/displacement.jpg' );

				// ============================================
				// 6. 创建材质
				// ============================================
				
				// 创建标准材质节点(MeshStandardNodeMaterial)
				// 这是Three.js WebGPU版本的特殊材质，支持节点化着色器
				material = new THREE.MeshStandardNodeMaterial( {
					color: 0xc1c1c1,                    // 基础颜色：浅灰色
					roughness: settings.roughness,      // 粗糙度：从settings读取
					metalness: settings.metalness,      // 金属度：从settings读取

					// 法线贴图设置
					normalMap: normalMap,               // 指定法线贴图纹理
					normalScale: new THREE.Vector2( 1, - 1 ), // 法线缩放向量，Y轴取反
					// 注意：某些模型的法线贴图需要Y轴取反，取决于纹理坐标系

					// AO贴图设置
					aoMap: aoMap,                       // 指定AO贴图纹理
					aoMapIntensity: 1,                  // AO贴图强度，初始为1

					// 置换贴图设置
					displacementMap: displacementMap,   // 指定置换贴图纹理
					displacementScale: settings.displacementScale, // 置换缩放：从settings读取
					displacementBias: - 0.428408,       // 置换偏移：来自原始模型数据
					// displacementBias调整置换的基准位置

					// 环境贴图设置
					envMap: reflectionCube,             // 指定环境贴图（立方体贴图）
					envMapIntensity: settings.envMapIntensity, // 环境贴图强度：从settings读取

					side: THREE.DoubleSide              // 双面渲染：模型内外表面都渲染
				} );

				// ============================================
				// 7. 加载3D模型
				// ============================================
				
				// 创建OBJ加载器实例
				const loader = new OBJLoader();
				
				// 加载忍者头部模型
				loader.load( 
					'models/obj/ninja/ninjaHead_Low.obj',  // 模型文件路径
					function ( group ) {                    // 加载完成后的回调函数
						// 从加载的组中获取第一个子对象的几何体
						const geometry = group.children[ 0 ].geometry;
						
						// 将几何体居中
						// 将几何体的中心点移动到坐标原点(0,0,0)
						geometry.center();

						// 创建网格对象
						// 将几何体和材质组合成可渲染的3D对象
						mesh = new THREE.Mesh( geometry, material );
						
						// 缩放模型
						// 原始模型较小，放大25倍以便观察
						mesh.scale.multiplyScalar( 25 );
						
						// 将网格添加到场景中
						scene.add( mesh );
					},
					// 注意：还可以添加加载进度和错误处理的回调函数
					// 这里省略了这些参数
				);

				// ============================================
				// 8. 事件监听器
				// ============================================
				
				// 监听窗口大小改变事件
				// 当用户调整浏览器窗口大小时，调用onWindowResize函数
				window.addEventListener( 'resize', onWindowResize );

			}

			/**
			 * 窗口大小改变处理函数
			 * 响应浏览器窗口大小变化，调整相机和渲染器
			 */
			function onWindowResize() {
				// 重新计算窗口宽高比
				const aspect = window.innerWidth / window.innerHeight;

				// 更新正交相机的左右平面
				// 保持相机高度不变，根据新的宽高比调整宽度
				camera.left = - height * aspect;    // 左平面
				camera.right = height * aspect;     // 右平面
				camera.top = height;                // 上平面（保持不变）
				camera.bottom = - height;           // 下平面（保持不变）

				// 更新相机投影矩阵
				// 必须在更改相机参数后调用，使更改生效
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				// 使渲染器画布与窗口新尺寸保持一致
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			/**
			 * 动画循环函数
			 * 每一帧被渲染器调用，用于更新场景状态
			 */
			function animate() {
				// 更新轨道控制器
				// 处理用户输入，更新相机位置和方向
				controls.update();
				
				// 调用渲染函数，绘制当前帧
				render();
			}

			/**
			 * 渲染函数
			 * 更新场景中的动画元素并执行渲染
			 */
			function render() {
				// 更新红色点光源的位置，实现圆周运动动画
				// 使用三角函数计算圆周上的X和Z坐标
				// 半径：2500
				pointLight.position.x = 2500 * Math.cos( r );  // X坐标：余弦值
				pointLight.position.z = 2500 * Math.sin( r );  // Z坐标：正弦值

				// 增加旋转角度
				// 每帧增加0.01弧度，控制动画速度
				r += 0.01;

				// 执行渲染
				// 将3D场景通过相机视角渲染到2D画布上
				renderer.render( scene, camera );
			}

		</script>

	</body>

</html>