ESP-Video-Render 组件

[English]

概述

ESP-Video-Render 是乐鑫面向 ESP 芯片的视频渲染与画面合成组件，适用于需要在 LCD 上显示视频、叠加轻量 UI、管理多路画面或构建视频优先界面的产品。它把视频流、Overlay、Widget 和显示后端组织在统一的渲染模型中，降低多媒体界面开发的集成复杂度。

组件架构、核心功能、格式支持、API 与示例等，请参考 ESP-Video-Render。

架构示意

ESP-Video-Render 位于视频处理链路的显示侧。它接收视频帧或由视频处理模块输出的图像数据，将视频内容与 Overlay UI 合成后，再输出到 LCD、LVGL 或自定义 framebuffer 后端。

ESP-Video-Render 架构示意图

对于单视频场景，Overlay 可以直接叠加在视频画面上；对于多视频场景，组件会先完成各个 stream 的处理，再按照显示区域、透明度和层级关系合成到最终帧缓冲。

典型应用场景

本地视频播放器

对于带屏设备，应用可以从 SD 卡读取 MP4、AVI、TS 或 MJPEG 测试资源，经提取、解码后交给 ESP-Video-Render 显示。Overlay 可用于显示播放状态、进度、音量、文件名和 FPS 等信息。

智能显示终端

智能中控、教育设备、桌面屏、可视对讲等产品通常需要在视频画面上叠加状态栏、按钮提示或告警信息。ESP-Video-Render 可将视频和轻量 UI 放在同一渲染路径中，减少应用层自己处理多层画面的工作量。

摄像头预览和双路画面

摄像头类产品可能需要单路预览、双路并排预览或画中画布局。通过多个 stream 的显示区域、裁剪、层级和透明度控制，可以快速构建不同的预览布局。

机器人眼睛和表情动画

双眼或双屏产品可以使用双流渲染 API 同步输出左右眼动画。相比应用层分别驱动两路显示，组件提供了更清晰的缓冲和同步模型，便于实现稳定的表情显示效果。

桌面侧 UI 验证

Linux 仿真后端可在没有真实硬件的情况下验证部分渲染逻辑和 UI 布局。对于需要频繁调试界面的项目，这有助于缩短开发和回归验证周期。

开发便利性

ESP-Video-Render 对产品开发最直接的价值，是把视频渲染常见问题沉到组件层：

  • 应用只需要按 stream 写入视频帧，并配置显示区域、层级和旋转等属性。

  • 轻量 UI 可通过 Overlay / Widget 方式叠加到视频上，避免为简单状态显示单独搭建一套绘制流程。

  • 同一套应用逻辑可以在 LCD backend、LVGL backend 或仿真 backend 间迁移。

  • dirty region 和缓存机制降低了应用手动优化局部刷新的负担。

  • 示例覆盖单流、多流、Overlay、视频播放器和双眼渲染，便于从已有工程快速改造。

设计建议

  • 如果产品以视频为主、UI 为辅，优先考虑使用 ESP-Video-Render 管理视频显示和轻量 UI 叠加。

  • 如果项目已经使用 LVGL，可评估启用 LVGL backend，在现有 GUI 框架中集成视频区域。

  • 如果屏幕为 RGB / DPI 等持续扫描型 LCD，应根据 framebuffer 数量评估闪烁或撕裂风险；单 framebuffer 下同时混合视频和 UI 时，建议结合组件 FAQ 调整 Blender 任务或改用双 framebuffer。

  • 如果启用文本 widget，需预留 FreeType 相关栈空间；不需要文本渲染时，可通过配置降低 Blender 任务栈占用。

  • 对高分辨率或多路视频场景，建议结合 PSRAM、缓存模式、异步渲染和实际 FPS 目标做端到端测试。

FAQ

Q: ESP-Video-Render 和 LVGL 是替代关系吗？

A: 不是。ESP-Video-Render 主要解决视频画面渲染、合成和显示输出问题；LVGL 更适合完整 GUI。对于视频优先、只需要少量状态 UI 的产品，可以直接使用 ESP-Video-Render 的 Overlay / Widget；如果项目已有复杂 LVGL 界面，则可以通过 LVGL backend 集成视频显示。

Q: 什么时候需要 cached stream？

A: 当视频输入 FPS 与 render FPS 不匹配，或希望减少处理任务与渲染任务之间的等待时，可以考虑开启 cached stream。代价是占用更多内存，因此需要结合分辨率、帧大小和可用 PSRAM 评估。

Q: 单 framebuffer 的 RGB / DPI LCD 为什么可能闪烁？

A: 单 framebuffer 下，渲染写入和屏幕扫描可能访问同一块缓冲。如果视频和 UI 由 Blender 任务先后混合到同一 framebuffer，再输出到面板，就可能出现可见闪烁或撕裂。可考虑关闭该模式下的 Blender 任务，或改用双 framebuffer。

Q: 是否适合机器人眼睛这类双画面产品？

A: 适合。组件提供双流渲染 API，可用于左右眼动画、单屏并排输出或双屏分别输出。示例 examples/dual_eyes 展示了典型使用流程。

相关链接