第 6A 章：MATL 材质扩展

MATL 是由格式变更 26072704-matl-v1 引入的 VFP 1.3 可选全局材质区段。它将一组 PBR 外观参数绑定到已有的 PAL0.paletteIndex，而不是复制到每个 VOX0 体素中。因此，一个颜色可以表现为金属、磨砂塑料、发光体或半透明玻璃，而体素缓冲仍保持单字节 Palette Index。

设计目标

不修改 PAL0 固定记录布局；旧 Reader 不会发生字段错位。
不修改 VOX0、Chunk、坐标或历史 sourceHash 算法。
不认识 MATL 的 VFP 1.3 Reader 仍可按 PAL0 基础色展示模型。
新 Reader 只有在 MATL 的 CRC、目录属性与 baseSourceHash 都通过后才能应用材质。

MATL 描述的是可选视觉语义扩展。VOX0 仍是唯一的权威几何体素源；MATL 缺失不影响编辑、体素恢复或基础色预览。

目录属性

字段	固定值
Tag	`MATL`
`chunkId`	`-1`
`codec`	`0`（RAW8）
`flags`	`0`
数量	最多一个

重复 MATL、非全局 Chunk、非 RAW8 或非零 flags 都是格式错误。旧实现可忽略未知可选区段；支持 MATL 的实现必须拒绝不满足上述属性的 MATL，而不能猜测字段布局。

MATL v1 二进制布局

所有整数为 little-endian：

MATL Header（36 B）
version        u8       = 1
recordSize     u8       = 21
recordCount    u16      = 1..paletteCount
baseSourceHash u8[32]   = Header sourceHash

MATL Record v1（21 B，按 paletteIndex 严格升序）
paletteIndex       u8
alphaMode          u8       0=OPAQUE, 1=MASK, 2=BLEND
flags              u8       = 0
reserved0          u8       = 0
alpha              u8       0..255
metallic           u8       0..255
roughness          u8       0..255
emissiveR,G,B      u8[3]
emissiveStrength   u8       0..255
alphaCutoff        u8       0..255
specularFactor     u8       0..255
transmission       u8       0..255
iorMilli           u16      IOR × 1000，1000..2500
thicknessMilli     u16      thickness × 1000
reserved1..3       u8[3]   = 0

归一化字段通过 value / 255 得到引擎侧的 0..1 数值；IOR 为 iorMilli / 1000，厚度为 thicknessMilli / 1000。Writer 必须把未使用的保留字段写为零；Reader 遇到未知 alphaMode、非零保留字段、重复/未定义 paletteIndex 或超范围 IOR 时必须拒绝 MATL。

渲染含义与降级

字段	PBR 含义	无对应引擎能力时的安全降级
`metallic` / `roughness`	金属与微表面粗糙度	使用默认 `0 / 1`。
`emissive*` / `emissiveStrength`	自发光颜色和强度	保留基础色，不产生 Bloom。
`alphaMode=MASK`	硬切透明	以 `alphaCutoff` 做裁切。
`alphaMode=BLEND`	半透明混合	可降级为 OPAQUE，但必须报告能力不足。
`transmission` / `ior` / `thickness`	透射和玻璃近似	降级为普通半透明，不得假称真实折射。

透明体素需要引擎单独处理深度排序、阴影和内部面。MATL 规定数据语义，不规定某个渲染引擎必须实现实时折射。

与 sourceHash、缓存的关系

MATL 不进入 VFP 1.3 既有 sourceHash 输入。这是为了让旧 Reader 仍可验证 PAL0 + VOX0 的几何/基础色资产。MATL 使用两层绑定：目录 CRC32 保护载荷，baseSourceHash 必须与 Header sourceHash 完全一致。

材质变化不会使 MSH0、VBUF、PMSH 或 ANM0 的几何失效；但任何携带最终颜色/材质外观的 RND0、PRVW、THMB 都必须失效并从 MATL 重建。无法生成材质感知预览缓存的 Writer 应省略这些缓存，而不是写入错误的纯色版本。

META 声明

含 MATL 的文件在 META 顶层添加以下对象：

{
  "materials": {
    "section": "MATL",
    "version": 1,
    "recordCount": 3,
    "baseSourceHash": "ba2d2cb0fede4346e54eab56d1da4642ca7fff25ddcaebd6f5d6c904657e13b6"
  }
}

META 声明与实际 MATL 不一致，或 META 声明 MATL 但目录缺失 MATL，均应拒绝材质扩展。没有 materials 的旧文件继续是完全有效的 VFP 1.3 文件。

PixForge JSON 编译输入

Python Writer 接受可选 materials 对象，键为 colors 中已有的单字符 palette symbol：

{
  "colors": {"M": "#B8C6D8", "G": "#77BCEB"},
  "materials": {
    "M": {"metallic": 0.92, "roughness": 0.18},
    "G": {
      "alpha_mode": "blend",
      "alpha": 0.62,
      "roughness": 0.08,
      "transmission": 0.70,
      "ior": 1.45,
      "thickness": 0.35
    }
  }
}

可用字段为 alpha_mode、alpha、metallic、roughness、emissive（#RRGGBB）、emissive_strength、alpha_cutoff、specular_factor、transmission、ior、thickness。未给出的字段使用本章默认值；没有 materials 时 Writer 不写 MATL。

实现状态

Python VoxelKit 支持 MATL 的编译、读取、严格校验和材质感知 PRVW GLB 生成。HarmonyOS 当前 VoxelViewer 尚未将 MATL 应用于 ArkGraphics；它会安全地忽略该扩展并按 PAL0 基础色显示。这个边界必须在产品 UI 与 API 文档中明确说明。

设计目标​

目录属性​

MATL v1 二进制布局​

渲染含义与降级​

与 sourceHash、缓存的关系​

META 声明​

PixForge JSON 编译输入​

实现状态​