概览

ESP Emote GFX 是面向 ESP-IDF 的轻量级图形框架,提供简洁而强大的嵌入式显示渲染 API,在内存与性能之间取得平衡,适合资源受限场景。

架构

框架以统一对象系统为核心:图像、标签、动画、按钮、二维码等元素均为对象,共享位置、尺寸、可见性与对齐等属性。

核心组件

核心系统

核心系统(gfx_core)负责:

  • 图形上下文的初始化与反初始化

  • 缓冲区管理(内部或外部)

  • 渲染管线

  • 基于互斥锁的线程安全

  • 屏幕刷新与脏区失效

对象系统

对象系统(gfx_obj)提供:

  • 所有图形元素的基类结构

  • 位置与尺寸管理

  • 对齐系统(类似 LVGL)

  • 可见性控制

  • 对象生命周期管理

定时器系统

定时器系统(gfx_timer)提供:

  • 用于动画的高分辨率定时器

  • 基于回调的定时事件

  • 重复次数与周期控制

  • 系统 tick 管理

组件

图像组件

图像组件支持:

  • RGB565(16 位色)

  • RGB565A8(16 位色 + 8 位 Alpha)

  • C 数组与二进制格式

  • 自动识别格式

标签组件

标签组件提供:

  • 多种字体格式的文本渲染

  • LVGL 字体支持

  • FreeType TTF/OTF 支持

  • 文本对齐(左、中、右)

  • 长文本处理(换行、滚动、裁剪)

  • 背景色与透明度

按钮组件

按钮组件提供:

  • 文本标签管理

  • 常态与按下背景色

  • 边框颜色与宽度

  • 字体与文本对齐控制

动画组件

动画组件支持:

  • EAF(ESP 动画格式)文件

  • 逐帧播放控制

  • 分段播放(起止帧)

  • 帧率控制

  • 循环与重复选项

  • 镜像效果

二维码组件

二维码组件提供:

  • 动态生成二维码

  • 可配置尺寸与纠错等级

  • 自定义前景与背景色

内存管理

框架支持两种缓冲区管理模式:

内部缓冲区

由框架在内部分配并管理帧缓冲。最简单,但需要足够的堆内存。

外部缓冲区

你可自行提供缓冲区,从而可以:

  • 使用内存映射区域

  • 控制缓冲区位置(SRAM、SPIRAM 等)

  • 针对内存约束优化

线程安全

所有组件操作应在图形锁内执行以保证线程安全:

gfx_emote_lock(handle);
// Perform operations
gfx_obj_set_pos(obj, x, y);
gfx_label_set_text(label, "New text");
gfx_emote_unlock(handle);

依赖

  • ESP-IDF 5.0 或更高版本

  • FreeType(TTF/OTF 字体)

  • ESP New JPEG(JPEG 解码)

许可证

本项目采用 Apache License 2.0 许可证。