Cesium 中的 KHR_materials_clearcoat 扩展解析：以 BoxClearcoat 测试模型为例

Cesium 中的 KHR_materials_clearcoat 扩展解析：以 BoxClearcoat 测试模型为例

【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium

导读

本文以 Cesium 仓库测试数据中的BoxClearcoat模型为切入点，深入解析 glTF 2.0 的KHR_materials_clearcoat扩展：从 glTF 文件中的扩展声明与参数配置，到 Cesium 引擎侧的加载流程（GltfLoader）、材质数据模型（Clearcoat类）与着色器实现（MaterialStageFS.glsl、LightingStageFS.glsl）的完整链路。读完本文，你将掌握清漆（Clearcoat）材质扩展的参数含义、Cesium 中该扩展的渲染原理，以及如何在三维场景中加载和使用这类带清漆层的模型。

一、BoxClearcoat 测试模型概览

BoxClearcoat是 Cesium 团队为测试KHR_materials_clearcoat扩展而开发的专用测试模型，其说明文档位于 Specs/Data/Models/glTF-2.0/BoxClearcoat/README.md。README 明确说明：

• 用途：验证KHR_materials_clearcoat扩展在 Cesium 渲染管线中的正确性；
• 许可：模型采用 Creative Commons Attribution 4.0 International License 授权；
• 版权归属：由 Cesium 开发，使用方需遵循 Cesium 商标条款。

模型目录实际包含以下文件（位于glTF子目录下）：

从文件结构看，该模型是典型的"单物体测试台"：仅包含一个盒状网格（24 顶点、36 索引、TRIANGLES 模式），顶点属性仅有POSITION、NORMAL与TEXCOORD_0三组，几何极其简单，目的就是把材质的清漆层效果隔离出来单独验证。

二、glTF 文件中的扩展声明与材质配置

2.1 扩展清单

在 BoxClearcoat.gltf 的顶层，extensionsUsed与extensionsRequired均声明了两个扩展：

"extensionsRequired": [ "KHR_draco_mesh_compression", "KHR_materials_clearcoat" ], "extensionsUsed": [ "KHR_draco_mesh_compression", "KHR_materials_clearcoat" ]

这意味着加载该模型时，KHR_materials_clearcoat是必须支持的扩展；若渲染器不支持，按 glTF 规范应拒绝加载。Cesium 恰好将这两个扩展都列入支持清单（详见第三节）。

2.2 材质定义中的清漆参数

模型的材质名为Texture，位于 BoxClearcoat.gltf。其基础层使用 PBR 金属粗糙度模型，metallicFactor为 0，并将baseColorTexture指向纹理 0（即 CesiumLogoFlat.png）：

"materials": [ { "pbrMetallicRoughness": { "baseColorTexture": { "index": 0 }, "metallicFactor": 0.0 }, "name": "Texture", "extensions": { "KHR_materials_clearcoat": { "clearcoatFactor": 0.5, "clearcoatRoughnessFactor": 0.2, "clearcoatTexture": { "index": 0 }, "clearcoatRoughnessTexture": { "index": 0 }, "clearcoatNormalTexture": { "index": 0, "scale": 0.5 } } } } ]

这段 JSON 完整覆盖了KHR_materials_clearcoat在 glTF 层面的全部可选字段，逐一解读如下：

值得注意的细节：三个清漆纹理通道都复用了同一张CesiumLogoFlat.png。其中clearcoatTexture只取红通道值、clearcoatRoughnessTexture只取绿通道值，这种"一张贴图多通道复用"是 glTF 材质系统允许的紧凑做法（通道分离的机制在 Cesium 的setClearcoat着色器中有明确体现，见第四节）。

2.3 场景与网格结构

场景仅含两个节点：根节点带一个绕 X 轴旋转 -90° 的矩阵变换（矩阵中[1][1]位置为 -1），子节点挂载网格Mesh。网格只有一个 primitive，顶点属性分别索引到法线、位置与 UV 三组 accessor。bufferViews的布局为：0–576 字节为位置+法线（stride 12）、576–768 字节为 UV（stride 8）、768–840 字节为索引（72 字节，即 36 个 16 位索引），与 840 字节的BoxClearcoat.bin完全吻合。

三、Cesium 引擎侧的扩展支持与加载流程

3.1 扩展支持清单

KHR_materials_clearcoat被 Cesium 显式列入支持列表。在 packages/engine/Source/Scene/Model/ModelUtility.js 的supportedExtensions对象中：

ModelUtility.supportedExtensions = { ... KHR_materials_common: true, KHR_materials_pbrSpecularGlossiness: true, KHR_materials_specular: true, KHR_materials_anisotropy: true, KHR_materials_clearcoat: true, KHR_materials_unlit: true, ... };

同文件 ModelUtility.checkSupportedExtensions 会遍历 glTF 的extensionsRequired，若遇到不支持的扩展则抛出RuntimeError: Unsupported glTF Extension: xxx。因此，包含KHR_materials_clearcoat的模型在 Cesium 中可以直接加载，无需用户额外注册任何插件。

3.2 加载器解析：GltfLoader

扩展的解析发生在 packages/engine/Source/Scene/GltfLoader.js：加载器读取材质对象的extensions.KHR_materials_clearcoat后调用loadClearcoat。该函数（GltfLoader.js L1798-L1832）的结构与 glTF 字段一一对应：

function loadClearcoat(loader, clearcoatInfo, frameState) { const { clearcoatFactor = Clearcoat.DEFAULT_CLEARCOAT_FACTOR, clearcoatTexture, clearcoatRoughnessFactor = Clearcoat.DEFAULT_CLEARCOAT_ROUGHNESS_FACTOR, clearcoatRoughnessTexture, clearcoatNormalTexture, } = clearcoatInfo; const clearcoat = new Clearcoat(); if (defined(clearcoatTexture)) { clearcoat.clearcoatTexture = loadTexture(/* ... */); } if (defined(clearcoatRoughnessTexture)) { clearcoat.clearcoatRoughnessTexture = loadTexture(/* ... */); } if (defined(clearcoatNormalTexture)) { clearcoat.clearcoatNormalTexture = loadTexture(/* ... */); } clearcoat.clearcoatFactor = clearcoatFactor; clearcoat.clearcoatRoughnessFactor = clearcoatRoughnessFactor; return clearcoat; }

可见 glTF 中缺省未提供的字段会被赋予默认值，纹理则统一通过loadTexture走异步纹理加载通道。

3.3 数据模型：Clearcoat 类

解析结果被封装为 packages/engine/Source/Scene/ModelComponents.js 中的Clearcoat类。该类定义了与扩展字段对应的属性和默认值：

export class Clearcoat { static DEFAULT_CLEARCOAT_FACTOR = 0.0; static DEFAULT_CLEARCOAT_ROUGHNESS_FACTOR = 0.0; constructor() { this.clearcoatFactor = Clearcoat.DEFAULT_CLEARCOAT_FACTOR; // 清漆层强度 this.clearcoatTexture = undefined; // 清漆强度贴图 this.clearcoatRoughnessFactor = Clearcoat.DEFAULT_CLEARCOAT_ROUGHNESS_FACTOR; // 清漆粗糙度 this.clearcoatRoughnessTexture = undefined; // 清漆粗糙度贴图 this.clearcoatNormalTexture = undefined; // 清漆法线贴图 } }

值得注意：引擎侧的DEFAULT_CLEARCOAT_FACTOR与DEFAULT_CLEARCOAT_ROUGHNESS_FACTOR均为0.0，与 glTF 规范的默认值保持一致——即"声明了扩展但未写参数"时，等价于关闭清漆效果。

四、渲染管线中的清漆实现

4.1 材质阶段：从纹理到材质参数

Cesium 的模型材质管线在 packages/engine/Source/Shaders/Model/MaterialStageFS.glsl 中通过setClearcoat函数把 glTF 参数落进czm_modelMaterial：

• 清漆强度：存在clearcoatTexture时采样红通道texture(...).r，再乘以 uniformu_clearcoatFactor；否则直接用因子或 0；
• 清漆粗糙度：存在clearcoatRoughnessTexture时采样绿通道.g，再乘以u_clearcoatRoughnessFactor；否则用因子或 0；
• 清漆法线：存在clearcoatNormalTexture时调用getClearcoatNormalFromTexture（同文件 L138-L165），按scale缩放法线扰动后经 TBN 矩阵变换到切线空间；否则直接复用几何法线。

材质数据在着色器侧由结构体czm_modelMaterial承载，见 packages/engine/Source/Shaders/Builtin/Structs/modelMaterial.glsl。只有在定义了USE_CLEARCOAT宏时，结构体才会扩展出清漆字段：

#ifdef USE_CLEARCOAT float clearcoatFactor; float clearcoatRoughness; vec3 clearcoatNormal; // Add clearcoatF0 when KHR_materials_ior is implemented #endif

代码注释透露了后续演进方向：当 Cesium 支持KHR_materials_ior（折射率扩展）时，这里还会加入clearcoatF0字段。

4.2 光照阶段：能量守恒的清漆分层

清漆渲染的精髓在 packages/engine/Source/Shaders/Model/LightingStageFS.glsl 的addClearcoatReflection函数。其算法要点是：

1. Fresnel 项：f0取常数vec3(0.04)。按注释说明，这是由ior = 1.5代入(ior - 1) / (ior + 1)平方后得到的近似值——在未启用KHR_materials_ior时清漆折射率恒为 1.5；
2. 粗糙度平方：alphaRoughness = roughness * roughness，将感知粗糙度转换为微表面模型的 α 参数；
3. 高光强度：通过computeDirectSpecularStrength计算直接光高光，并乘上NdotL；
4. 环境光（IBL）：在SPECULAR_IBL开启时，沿反射方向reflect(-viewDirection, normal)采样环境贴图，并乘环境遮蔽material.occlusion；
5. 能量守恒分层：最终颜色为baseLayerColor * (1.0 - clearcoatFactor * F) + clearcoatColor——底层颜色按清漆透射损失(1 - clearcoatFactor × F)压暗，上层叠加清漆高光，从而保证加入清漆层后总能量不增加。注释还特别说明，这里 Fresnel 用dot(n, v)而非dot(v, h)计算，正是为了与这种简单的分层函数保持能量守恒。

整体上看，BoxClearcoat 的clearcoatFactor = 0.5意味着底层颜色至多被压暗一半并叠加反射，clearcoatRoughnessFactor = 0.2则让清漆层呈现高光泽效果——这正是"烤漆/车漆"类材质需要的观感。

五、如何在应用中加载与使用

BoxClearcoat 是标准 glTF 2.0 模型，可用 Cesium 的所有模型加载入口直接加载。常用方式包括：

• Model API：Model.fromGltf({ url, modelMatrix, ... })，适合单体模型；
• Cesium3DTileset：将 glTF 作为 tileset 内容托管；
• Entity/ModelGraphics：viewer.entities.add({ position, model: { uri } })，适合在数据源中与 CZML、GeoJSON 等配合使用。

加载后无需额外配置即可看到清漆层：只要extensionsRequired中的KHR_materials_clearcoat能被 ModelUtility.supportedExtensions 识别，材质管线会自动编译出带USE_CLEARCOAT分支的着色器（对应MaterialStageFS.glsl中的setClearcoat与LightingStageFS.glsl中的addClearcoatReflection）。

六、总结

BoxClearcoat虽然只是 Cesium 测试数据中的一个"小盒子"，但它完整覆盖了KHR_materials_clearcoat扩展的全部参数形态（强度因子、粗糙度因子、强度/粗糙度/法线三类纹理、法线 scale），是理解该扩展的最佳最小样例。结合仓库源码可以看到一条清晰的实现链路：

1. glTF 声明→extensionsUsed/extensionsRequired与材质内extensions.KHR_materials_clearcoat（BoxClearcoat.gltf）；
2. 加载解析→GltfLoader.loadClearcoat读取扩展并构造Clearcoat实例（GltfLoader.js）；
3. 数据组织→ModelComponents.Clearcoat提供字段与默认值（ModelComponents.js）；
4. 材质计算→MaterialStageFS.glsl的setClearcoat组装czm_modelMaterial清漆字段；
5. 光照合成→LightingStageFS.glsl的addClearcoatReflection以能量守恒方式完成底层衰减与清漆高光叠加。

对希望为自家模型添加清漆效果的开发者而言，直接对照 BoxClearcoat 的 glTF 配置修改clearcoatFactor、clearcoatRoughnessFactor与对应纹理通道，即可在 Cesium 中获得可预期的渲染结果。

【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium