%% 鸿蒙 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，可二次处理；仅非安全通路；需手动拷贝对齐数据。
常见坑提示
- Flush/Reset/Stop 后需重新送 SPS/PPS。
- Destroy 不能在回调线程里调。
- Buffer 模式必须
FreeOutputBuffer，否则阻塞后续输出。 - 多解码器共用同一 NativeWindow 时，先释放再启动，避免画面卡死。