跳到主要内容

GltiPackageReader

GltiPackageReader 是 GLTI 的恢复器，不是视频解码器，也不是 GLB 反体素化工具。它只从 VoxelKit 可编辑 GLTI 内的 CHARACTECH_voxel_vfp GLB 扩展取出原始 VFP，并对容器、扩展和权威体素数据做严格 校验。这样恢复的结果仍可作为 Viewer 或编辑器的真实输入。

const reader = VoxelKit.createGltiReader();

对象无状态；创建时不读取文件。

extractVfp()​

async extractVfp(gltiBytes: ArrayBuffer): Promise<ArrayBuffer>
参数类型必填说明
gltiBytesArrayBuffer是从文件、网络或应用存储读取的完整 GLTI MP4 字节。

成功时返回一个独立的、完整的 VFP 1.3 ArrayBuffer。原 GLTI 字节不会被修改，也不会自动写出 .vfp 文件；宿主可将结果直接交给 VoxelViewerController.loadBytes()，或保存到用户选择的位置。

const vfpBytes = await VoxelKit.createGltiReader().extractVfp(gltiBytes);
await this.controller.loadBytes(vfpBytes);

验证顺序​

恢复在 Native 异步线程中执行，并依次确认：

  1. MP4 文件声明 glti compatible brand；
  2. 容器中存在顶层 meta/idat 的 GLB 项；
  3. GLB 符合 v2 JSON/BIN 布局；
  4. GLB 声明并完整携带 CHARACTECH_voxel_vfp；
  5. 扩展长度和 SHA-256 与内嵌 VFP 一致；
  6. VFP 的 PAL0、VOX0、目录与 source hash 都通过权威校验。

任一步失败，Promise 都拒绝且不会返回部分 VFP。这种严格性是为了防止损坏、伪造或仅有展示数据的文件 被误当作可编辑工程。

不支持的文件​

以下情况会失败，且属于预期行为：

  • 普通 MP4 或没有 glti brand 的视频；
  • 含 GLB 但没有原始 VFP 扩展的 GLTI；
  • 展示专用 GLTI（embedEditableVfp = false 导出）；
  • GLB/VFP 被截断、修改或 SHA-256 不一致的文件；
  • 内嵌 VFP 的权威数据或 source hash 无效。

Reader 不从 H.264 帧、封面图、GLB 三角面或颜色贴图生成近似 VFP。那些信息不足以恢复空体素、原调色板、 VOX0 分块、编辑意图和 source hash；强行恢复会产生不可验证的工程。

与保存和编辑的衔接​

恢复后得到的 VFP 与普通 VFP 使用相同的后续链路：

const vfpBytes = await VoxelKit.createGltiReader().extractVfp(gltiBytes);
await controller.loadBytes(vfpBytes);

// 只有实际需要编辑时，再按既有流程进入编辑模式。
await editor.enterEdit();

此过程不会创建新的 GLTI，也不会把导入文件自动覆盖。若用户修改后希望继续交付，应重新调用 VoxelGltiExporter.export()；若只是保存工程，使用编辑器的 JSON/VFP 保存 API 即可。

文件保存职责和用户流程见 导出到相册与分享。