2.2 KiB
MPV OHCodec 集成说明
已实现路径
hwdec=ohcodec 由 MPV/FFmpeg 的动态 hardware-decoder 枚举进入独立
AV_HWDEVICE_TYPE_OHCODEC backend。IMGFMT_OHCODEC 与
AV_PIX_FMT_OHCODEC 使用单一映射。当前 adapter 只允许 H.264 和 HEVC，先
查询 API 24 OHCodec hardware capability，再检查 host 注入的独占
ohos_direct_surface，最后创建带 OHNativeWindow* 的 FFmpeg hwdevice。
Direct Surface backend 的名称是
ohcodec-direct-surface-experimental。它只负责证明 device/decoder/surface
plumbing，不与 Playback Lab 的 EGL window 共享呈现权；没有独占窗口时明确失败，
MPV 保留 software decoder fallback。
状态与回退
适配器记录 HWDEC_DISABLED、HWDEC_REQUESTED、HWDEC_CAPABILITY_CHECK、
HWDEC_DEVICE_CREATED、HWDEC_DECODER_CREATED、HWDEC_DIRECT_SURFACE、
HWDEC_GPU_INTEROP、HWDEC_ACTIVE、HWDEC_FALLBACK、HWDEC_ERROR。
Playback Lab 通过 libmpv 诊断 API 与属性显示 requested/actual decoder、active
状态、backend、capability、fallback reason 及 hardware/software frame 计数。
capability 查询失败、codec/profile/level 不支持、surface 不可用、device/decoder 创建失败或后续 interop 失败都必须返回失败并回到 software path；不把空 device、 opaque pointer 或 CPU readback 当成成功的硬件帧。
Surface 生命周期约束
ohos_direct_surface 的引用由 adapter 持有，host 负责提供一个不等于
Playback Lab EGL window 的独占窗口。Surface 销毁或重建时，host 必须先停止
decoder/render、等待 AVFrame release，再销毁旧 device 并用新窗口重建；当前代
码只完成 ownership guard，generation/fence/present 的实体设备验证仍待做。
GPU interop 边界
harmony-ohcodec-gl 默认关闭，仅编译 API probe：API24 可探测
OH_AVBuffer_GetNativeBuffer、NativeWindow wrapper、EGL native-buffer image
和 GLES external texture 扩展。但 FFmpeg upstream 的硬件分支是 surface-first，
没有“不 present 到 decoder Surface、直接导出可导入 NativeBuffer”的契约；见
DOCS/OHCODEC_GPU_INTEROP_DESIGN.md 中的 OHCODEC-BLOCKER-001。因此当前不
提交 mapper、不宣称 zero-copy，也不宣称 HDR。