Velix-MPV-Core/DOCS/OHCODEC_GPU_INTEROP_DESIGN.md

OHCodec GPU interop 设计与当前 blocker

目标

将 OHCodec hardware frame 交给 MPV OpenGL composition，同时保留 ASS、OSD、shader 和 color management。该路径必须是显式实验开关 harmony-ohcodec-gl，不能成为默认 hwdec。

API24 合法链路（仅设计验证）

SDK 头文件提供：

1. OH_AVBuffer_GetNativeBuffer(OH_AVBuffer*)，返回一个需要 OH_NativeBuffer_Unreference() 的 OH_NativeBuffer*。
2. OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer()，把 NativeBuffer 转成 OHNativeWindowBuffer*，并要求随后销毁 wrapper。
3. EGL_OHOS_image_native_buffer / EGL_NATIVE_BUFFER_OHOS、eglCreateImageKHR() 和 glEGLImageTargetTexture2DOES()。

这证明 API 类型是 HarmonyOS 原生接口，不应使用 Android AHardwareBuffer、fd 猜测或指针重解释。未来 mapper 的资源生命周期应为：

OH_AVBuffer frame ref → OH_NativeBuffer_Get/Reference → OHNativeWindowBuffer wrapper → EGLImage → external texture → unmap 时反向销毁。

OHCODEC-BLOCKER-001

当前 upstream libavcodec/ohdec.c 只有两种输出：

• 有 OHCodec device：强制 output_to_window=true、配置 AV_PIXEL_FORMAT_SURFACE_FORMAT、SetSurface(window)；
• 无 device：CPU NV12 buffer，复制到 software frame。

hardware frame 的 OH_AVBuffer* 只存在于带 Surface 的分支，且自定义 AVBuffer release 会调用 OH_VideoDecoder_RenderOutputBuffer()。因此 MPV 不能在不修改 FFmpeg 的前提下请求“NativeBuffer hardware output but no decoder Surface present”模式。若 mapper 同时导入该 buffer 到 EGL，decoder release 仍可能向另一 Surface present，导致两个 owner、未定义 fence/queue ownership 和 seek/recreate race。

结论：本阶段不提交伪 interop mapper，不调用 eglFinish/glFinish 充当同步，不宣称零拷贝/GPU interop/HDR 完成。harmony-ohcodec-gl 作为 disabled-by-default feature 保留 API 探针入口；启用它前必须先解决该 upstream contract blocker，并补齐 output buffer、fence、crop/stride 和 surface ownership 的真实设备验证。

Direct Surface ownership

ohos_direct_surface 是 adapter 专用 native resource。只有 host 明确注入一个不等于 Playback Lab EGL window 的独占窗口时，ohcodec-direct-surface-experimental 才会取得引用并创建设备；当前 Playback Lab 不注入此 resource，所以 decoder 不会和 EGL/libmpv 抢同一 Surface。

Surface destroy/recreate 必须停止 render/decoder、等待所有 AVFrame release、递增 generation，再以新窗口重新创建 OHCodec device。当前只完成 MPV adapter 侧的 ownership guard，实体设备上的 fence、present count、surface recreate 仍为 DEVICE TEST REQUIRED。