Velix-MPV-Core/DOCS/MPV_OHCODEC_GAP_ANALYSIS.md

MPV 与 OHCodec 缺口分析

扫描基线：MPV 当前 harmony-port 工作树，FFmpeg OHCodec 头文件来自锁定 commit 3acec0a1af2dda0a0838689b8b8649e7deb080a0。

MPV location	当前行为	OHCodec requirement	本阶段改动/结论	风险与 upstreamability
video/img_format.h / video/fmt-conversion.c	只有通用 hardware format，没有 OHCodec 专用 ID。	AV_PIX_FMT_OHCODEC 必须成为 MPV hardware image format。	新增 IMGFMT_OHCODEC ↔ AV_PIX_FMT_OHCODEC 单一映射。	纯 MPV 架构改动，可 upstream；依赖 FFmpeg enum。
video/decode/vd_lavc.c:add_all_hwdec_methods()	动态枚举 FFmpeg HW config，并使用 av_hwdevice_get_type_name() 生成 method。	能识别 AV_HWDEVICE_TYPE_OHCODEC、h264_oh、hevc_oh。	不改 decoder core；FFmpeg config 会自然生成 hwdec=ohcodec，且仅 H.264/HEVC 由 adapter 放行。	upstreamable；真实 capability 仍需设备验证。
video/hwdec.c:hwcontext_fns[]	未注册 OHCodec copy-device callback；未知类型会尝试空 device。	copy path 必须不能伪造 null-surface 成功。	注册 hwcontext_fns_ohcodec，明确拒绝无独占窗口的 copy path，并触发 software fallback。	纯 MPV 保护逻辑。
video/out/gpu/hwdec.c	只注册已有 GPU interop/overlay drivers。	Direct Surface 需要独立 backend，不能复用 MediaCodec/DRM。	注册 ohcodec-direct-surface-experimental，仅在 host 提供 ohos_direct_surface native resource 时创建设备。	当前 Playback Lab 不提供该 resource，故默认不会抢占 EGL Surface。
video/out/gpu/video.c / gpu_next	mapper 或 overlay 二选一；overlay 会绕过视频 GL 合成但保留 OSD。	Direct Surface 不能与同一 EGL window 双重呈现。	OHCodec 只使用 overlay probe；没有独占窗口时 init 失败。	Direct Surface 不是最终 ASS/shader/color-management 产品路径。
video/mp_image.c:mp_image_from_av_frame()	复制 AVFrame buffers/data；无 OHCodec 特判。	frame 需要保留 buf[0] 生命周期和硬件格式。	现有 generic path 已满足：data[3] 作为 opaque plane，buf[0] 持有 release。	不能把 opaque plane 当 CPU pixels 或 fd。
video/out/gpu/ra.h native resources	可由 host 注入平台资源。	Surface ownership 需要明确边界。	约定 ohos_direct_surface 为独占、已由 host 管理的 OHNativeWindow*。	当前没有 host 注入，设备验证前不能宣称 direct active。
Diagnostics / Playback Lab	原来只显示 software audio/video 状态。	必须显示 requested/actual decoder、hw state、fallback/capability。	新增导出统计 API、日志识别和 Playback Lab 面板字段。	actual decoder 在设备上需以 FFmpeg 日志和真实 frame 验证。

选择路径

hwdec=ohcodec → FFmpeg OHCodec method → MPV 请求 IMGFMT_OHCODEC → GPU backend 请求 OHCodec device → adapter 查询 capability → 检查独占 Surface → 创建 AVHWDeviceContext → Direct Surface overlay。

任何一步失败均返回负值并保留 software decoder。GPU interop 不走猜测性的 opaque-pointer reinterpretation。