概览

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

架构

The framework is built around a core object system where all graphical elements (images, labels, animations, buttons, QR codes, motion scenes) are treated as objects. These objects share common properties like position, size, visibility, and alignment.

核心组件

核心系统

核心系统（gfx_core）负责：

图形上下文的初始化与反初始化
缓冲区管理（内部或外部）
渲染管线
基于互斥锁的线程安全
屏幕刷新与脏区失效

对象系统

对象系统（gfx_obj）提供：

所有图形元素的基类结构
位置与尺寸管理
对齐系统（类似 LVGL）
可见性控制
对象生命周期管理

定时器系统

定时器系统（gfx_timer）提供：

用于动画的高分辨率定时器
基于回调的定时事件
重复次数与周期控制
系统 tick 管理

组件

Motion Scene Widget

The motion scene runtime provides:

Path-driven articulated animation built from joints, poses, and actions
Segment primitives for capsules, rings, open/closed Bezier strokes, and Bezier fills
Per-segment solid color, palette color, opacity, or texture binding
Display-space scaling through a configurable canvas and asset viewbox
Touch-friendly runtime usage for interactive characters and emotes

The public entry points are gfx_motion_player_init(), gfx_motion_player_set_canvas(), gfx_motion_player_set_action(), and gfx_motion_player_set_color(). The underlying asset format is described by gfx_motion_asset_t in widget/gfx_motion_scene.h.

内存管理

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

内部缓冲区

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

外部缓冲区

你可自行提供缓冲区，从而可以：

使用内存映射区域
控制缓冲区位置（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 解码）
No NanoVG or libtess2 dependency is required for the current motion scene path

许可证

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

概览

架构

核心组件

核心系统

对象系统

定时器系统

组件

图像组件

标签组件

按钮组件

动画组件

二维码组件