鸿蒙视频解码

%% 鸿蒙 AVCodec Kit – 视频解码全景图
%% 开发者：Kimi 2024-08-16
%% 说明：一张图读懂“如何调用 Native API 完成视频解码”

flowchart TD
    subgraph 应用侧
        A([应用]) -->|1. 创建| B[OH_VideoDecoder_CreateByMime]
        A -->|2. 注册回调| C[OH_VideoDecoder_RegisterCallback]
        A -->|3. 配置| D[OH_VideoDecoder_Configure]
        A -->|4. 设 Surface| E[OH_VideoDecoder_SetSurface]:::surface
        A -->|5. 就绪| F[OH_VideoDecoder_Prepare]
        A -->|6. 启动| G[OH_VideoDecoder_Start]
    end

    subgraph 输入线程
        H([码流线程]) -->|7. 送入| I[OH_VideoDecoder_PushInputBuffer]
        I -->|携带 SPS/PPS| J{{AnnexB 格式}}
    end

    subgraph 解码内核
        K([解码器]) -->|8. 解码| L[YUV Frame]
        K -->|事件| M>回调]
        M -->|OnNeedInputBuffer| N[继续送码流]
        M -->|OnNewOutputBuffer| O[拿到输出 buffer]
        M -->|OnStreamChanged| P[分辨率变化]
        M -->|OnError| Q[错误处理]
    end

    subgraph 输出线程
        direction TB
        R([渲染线程]) -->|9a. Surface 送显| S[OH_VideoDecoder_RenderOutputBuffer]:::surface
        R -->|9b. 丢弃帧| T[OH_VideoDecoder_FreeOutputBuffer]
        R -->|9c. Buffer 保存| U[写 YUV 文件]
        style U fill:#f9f,stroke:#333
    end

    subgraph 生命周期
        V([Flush]) -->|清缓存| W[重新 Start]
        X([Reset]) -->|回初始态| Y[重新 Configure]
        Z([Stop]) -->|暂停| G
        AA([Destroy]) -->|释放| BB([Released])
    end

    %% 状态机泳道
    subgraph 状态机
        direction LR
        I1((Initialized)) -->|Configure| C1((Configured))
        C1 -->|Prepare| P1((Prepared))
        P1 -->|Start| E1((Executing))
        E1 -->|Flush| F1((Flushed))
        E1 -->|EOS| EOS((End-of-Stream))
        E1 -->|Error| ERR((Error))
        ERR -->|Reset| I1
        ERR -->|Destroy| R1((Released))
    end

    %% 样式
    classDef surface fill:#c2e0c6,stroke:#006100
    classDef buffer  fill:#fce8b4,stroke:#8f7f00
    classDef life    fill:#d5e8d4,stroke:#82b366

---

核心 API 设计速查表

阶段	关键函数	说明
​创建​	OH_VideoDecoder_CreateByMime()/ CreateByName()	按指定格式（MIME类型）或解码器名称创建解码器实例
​配置​	OH_VideoDecoder_Configure()	设置视频宽高、色彩空间、低时延模式等核心参数
​绑定​	OH_VideoDecoder_SetSurface()	关联 OHNativeWindow（通常来自XComponent或OpenGL渲染表面）
​就绪​	OH_VideoDecoder_Prepare()	内部预分配编解码资源，完成初始化准备
​启动​	OH_VideoDecoder_Start()	启动解码器，进入运行（Running）状态
​送码流​	OH_VideoDecoder_PushInputBuffer()	输入AnnexB格式的码流数据，需整帧一次性送入
​取帧​	OH_VideoDecoder_RenderOutputBuffer()	将解码帧送入绑定的Surface进行渲染（Surface模式）
	OH_VideoDecoder_FreeOutputBuffer()	释放内存或存储YUV数据（Buffer模式）
​生命周期​	OH_VideoDecoder_Flush()	清空缓存中的输入/输出数据
	OH_VideoDecoder_Reset()	重置解码器至初始状态
	OH_VideoDecoder_Stop()	暂停解码操作，保留资源配置
	OH_VideoDecoder_Destroy()	彻底释放解码器实例资源

---

模式差异一句话

• Surface 模式：直接送显，性能高；支持动态切换 Surface；支持 DRM 安全通路。
• Buffer 模式：拿到共享内存 YUV，可二次处理；仅非安全通路；需手动拷贝对齐数据。

---

常见坑提示

1. Flush/Reset/Stop 后需重新送 SPS/PPS。
2. Destroy 不能在回调线程里调。
3. Buffer 模式必须 FreeOutputBuffer，否则阻塞后续输出。
4. 多解码器共用同一 NativeWindow 时，先释放再启动，避免画面卡死。