RDK X5 decode2display Demo 完整解析

一、Demo 实现功能

decode2display 是地平线 hobot-multimedia 多媒体组件官方示例程序，实现硬件解码直通硬件显示的硬件流水线。

1. 硬件 VPU 解码：支持 H.264/H.265 码流文件硬解码，CPU 不参与像素解码运算；解码输出图像格式固定为 NV12 (YUV420SP)。即把 H.264/H.265视频文件通过硬件转化成NV12格式的视频文件，并直接通过HDMI显示，无需CPU软件参与！！！
2. 零拷贝硬件链路传输：解码器输出 NV12 图像帧，通过共享 Buffer 直接输送至 VO 显示模块，无 CPU 图像内存拷贝。
3. 硬件显示输出：支持 HDMI 输出画面；支持设置窗口位置、缩放、多窗口布局。
4. 可选硬件 OSD 叠加：可在画面绘制矩形、文字、线条（硬件渲染，不占用 CPU）。
5. 底层完全依托芯片硬件资源（VPU、VO），CPU 仅负责任务调度、码流读取、模块控制，CPU 占用极低、延迟小。

拓展链路：可以插入 splitter分流器，将解码 NV12 帧一路送显示、一路送入 BPU 做 AI 推理（decode2dnn2display）。

架构定位：整条链路属于数据面硬件通路，ARM CPU 属于控制面，仅做配置与调度。

二、Demo 设计目标

1. 验证多媒体硬件通路可用性：打通 VPU 解码器 → VO 显示控制器硬件流水线，验证硬件编解码、图像缓冲区共享机制。
2. 演示零拷贝架构优势：展示如何避免 OpenCV、CPU 参与图像像素转换，降低系统负载，适合机器人实时预览场景。
3. 提供标准开发范式：给出标准模块创建、绑定、启停、资源释放流程，作为 RTSP 回放、录像回放、视频预览二次开发模板。
4. 性能目标：实现稳定流畅视频预览，验证多路解码、硬件缩放、硬件 OSD 能力，适用于机器人本地录像回放、网络视频实时预览场景。

三、代码完整执行流程（官方 Demo 标准时序）

阶段 1：全局多媒体初始化

1. 调用 hobot_mm_init()
   • 加载多媒体驱动；初始化硬件内存管理器，统一管理物理连续内存块（VPU/VO 硬件只能访问物理连续内存）。
2. 读取启动入参：码流文件路径、编码类型（H264/H265）、显示窗口参数。

阶段 2：创建解码器实例 Decoder

1. 填充 DecoderParam 参数：编码协议、期望输出格式（NV12）、缓存队列深度。
2. hobot_mm_create_decoder() 创建解码器句柄。

阶段 3：创建显示实例 Display

1. 填充 DisplayParam：输出设备（HDMI）、窗口坐标、窗口宽高、帧率、OSD 开关。
2. hobot_mm_create_display() 创建显示句柄。

阶段 4：模块绑定（链路建立，核心）

plaintext

Decoder → Display 直接绑定

hobot_mm_bind() 将解码器输出端口与显示输入端口关联； 框架内部自动建立帧缓冲区队列，解码器输出的 NV12 帧自动投递给 Display，开发者无需手动传递图像数据。

拓展方案：若需要同时预览 + AI 推理，则增加 Splitter 分流器：Decoder bind Splitter；Splitter 分别 bind Display、DNN。

阶段 5：启动链路【顺序不可颠倒】

1. 先启动 Display：hobot_mm_start_display()，保证接收端就绪；
2. 再启动 Decoder：hobot_mm_start_decoder()，解码器开始等待码流输入。

阶段 6：主线程循环送入码流（业务循环）

plaintext

while(文件未读完)
{
    1. 从本地文件读取一段H264/H265 NAL码流；
    2. 调用 decoder_input() 将码流送入解码器；
    3. VPU硬件完成解码，生成NV12帧；
    4. 解码帧自动通过绑定链路送入VO；
    5. VO硬件完成色域转换、缩放，推送画面至HDMI显示器；
}

⚠️ CPU 只负责读取码流二进制数据包，图像解码、渲染、输出全部硬件执行。

阶段 7：码流读取完成 / 收到退出信号（Ctrl+C），停止流程

1. 发送解码结束信号，等待解码器处理缓存内剩余帧；
2. 停止解码器：hobot_mm_stop_decoder()；
3. 停止显示器：hobot_mm_stop_display()；

阶段 8：资源逆序销毁（防止内存泄漏）

1. hobot_mm_unbind() 解除 Decoder 与 Display 绑定；
2. hobot_mm_destroy_decoder() 销毁解码器；
3. hobot_mm_destroy_display() 销毁显示实例；
4. hobot_mm_deinit() 反初始化多媒体框架，释放所有硬件内存。

四、关键补充说明

1. 时序红线：启动顺序 Display → Decoder；销毁顺序与创建相反。顺序错误极易出现丢帧、黑屏、内存异常。
2. 裸流文件坑点：播放 .h264/.h264 裸流，码流必须包含 SPS/PPS；缺少序列参数集会出现画面花屏。MP4 封装文件内部自带参数，一般不会出现该问题。
3. 与 AI 联动区别
   • decode2display：仅预览，不经过 BPU；
   • decode2dnn2display：解码帧分流送入 BPU 推理，推理结果通过硬件 OSD 叠加画面输出，机器人视觉项目最常用拓展链路。

五、精简口述版本

decode2display 示例程序目标是打通硬件解码直显流水线，验证 VPU 与 VO 硬件通路，实现低 CPU 占用视频预览。程序先初始化多媒体框架，依次创建解码器、显示模块并建立绑定关系；先启动显示模块，再启动解码器；主线程持续读取码流送入硬件解码器，硬件输出 NV12 图像直接送至 HDMI 显示。程序结束后按照逆序停止、销毁所有模块，释放硬件资源。整条链路图像数据依靠硬件共享内存流转，全程避免 CPU 图像拷贝，实现低延迟视频预览。