跳到主要内容

VoxelGltiExporter

VoxelGltiExporter 是 HarmonyOS HAR 的 VFP → GLTI 导出门面。它从输入 VFP 的权威数据重建 GLB， 并按配置可选保留原始 VFP 的 CHARACTECH_voxel_vfp 扩展、生成 H.264 转台视频，最后返回一个 MP4/GLTI ArrayBuffer。

创建导出器不执行 I/O：

const exporter = VoxelKit.createGltiExporter();

导出器无状态，可顺序用于多个文件。不要并行启动多个大型导出；多个编码会竞争同一设备媒体编码器、内存 和 GPU，业务层应将导出操作排队。

export()​

async export(
  vfpBytes: ArrayBuffer,
  options: VoxelGltiExportOptions = new VoxelGltiExportOptions()
): Promise<ArrayBuffer>
参数类型必填说明
vfpBytesArrayBuffer是完整 VFP 1.3 文件字节，必须仍包含可验证的权威数据。调用期间不要复用或修改其内容。
optionsVoxelGltiExportOptions否视频预览配置；省略时使用默认高质量转台视频。

成功时返回完整 MP4 字节。返回值不自动写入沙箱、媒体库或相册；宿主需使用自身已授权的文件/媒体 API 保存，并在业务层设置 video/mp4 MIME 类型和 .mp4 扩展名。

Native 解析、贪心面、GLB、离屏绘制、视频编码和封装在异步线程执行。Promise 未完成前不得假设输出可用； 若失败，不能保存任何中间字节。

const options = new VoxelGltiExportOptions();
options.durationMs = 5000;
const bytes = await VoxelKit.createGltiExporter().export(vfpBytes, options);

VoxelGltiExportOptions​

所有字段只影响 H.264 转台预览；不会改变内嵌 VFP、GLB 的源数据，也不会改变输入 VFP。

字段类型默认值说明
includeVideobooleantrue是否写入 H.264 视频轨。为 false 时输出静态 GLTI，仍包含 GLB；是否附带 VFP 由 embedEditableVfp 决定。
embedEditableVfpbooleantrue是否在 GLB 中写入原始 VFP 和 CHARACTECH_voxel_vfp 扩展。为 false 时输出展示专用 GLTI，GltiPackageReader 必须拒绝恢复。此字段只控制编辑源保留策略。
widthnumber1024视频宽度，单位像素。建议保持方形，以获得稳定的作品取景。
heightnumber1024视频高度，单位像素。
frameRatenumber24视频帧率。帧数由此与 durationMs 共同决定。
durationMsnumber3000完整一圈转台时长，单位毫秒。
antiAliasScalenumber2内部抗锯齿倍率。2 使用更高的离屏采样再 resolve 到目标尺寸。

为了兼容不同设备的媒体编码能力，应用应将分辨率、帧率和时长视为资源预算，而不是无限制的渲染参数。 若设备拒绝当前视频配置或系统编码器不可用，Promise 会拒绝；可提示用户降低尺寸/帧率、缩短时长，或设置 includeVideo = false 输出静态交付容器。

输出与互操作​

默认输出由以下内容组成：

  • MP4 文件类型兼容 glti brand；
  • 可播放的 H.264/MP4 视频轨；
  • meta/idat 内的标准 GLB；
  • 当 embedEditableVfp = true 时，GLB 中用于恢复的 CHARACTECH_voxel_vfp 原始 VFP 扩展。

普通播放器只需要处理视频轨；支持 GLB 的工具可以使用 GLB；VoxelKit 则通过 VoxelKit.createGltiReader().extractVfp() 恢复严格校验后的工程源。视频或 GLB 的显示结果不作为体素 编辑数据的校验依据。

不保留编辑源​

const options = new VoxelGltiExportOptions();
options.embedEditableVfp = false;
const albumVideo = await VoxelKit.createGltiExporter().export(vfpBytes, options);

这个模式仍产生 video/mp4 字节，但删除私有 VFP 载荷。是否选择它取决于应用的数据保留和访问策略，而 不是视频保存位置。保存到相册、发送或上传的宿主流程见 导出到相册与分享。

失败与处理​

Promise 可能因以下情况拒绝：VFP 不是 1.3 或缺失/损坏权威区段、source hash 不一致、Native .so 无法 加载、内存不足、设备不具备所需媒体编码能力、离屏 EGL/Surface 创建失败，或 MP4 封装后的 H.264 配置 无法通过完整性检查。

try {
  const gltiBytes = await VoxelKit.createGltiExporter().export(vfpBytes);
  // 保存或上传 gltiBytes
} catch (error) {
  // 记录 error；向用户提供重试或降低视频规格的入口。
}

不能用错误后的普通 GLB、视频帧或部分 MP4 代替成功输出；它们不保证带有可恢复的 VFP。

完整用户流程见 导出到相册与分享。