chenjintao/lucky-cat
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(lcd): add cached listening animation and asset guidelines

Browse Source
This commit is contained in:
chenjintao
2026-10-09 18:01:32 +08:00
parent c0770ac459
commit 22f5ac70a2
32 changed files with 3384 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/GFX表情显示应用与开发指南.md
+164 -9
View File
@@ -8,9 +8,9 @@
- 底层为 ESP32-S3、ST7789P3、单线 SPI，当前像素时钟为 40 MHz，逻辑画布为 320×240。
- 当前使用 `esp_emote_gfx` 3.0.5，由 `platform` 私有依赖。没有接入 `esp_emote_expression` 状态管理组件，也没有把当前表情绘制建立在 LVGL 上。依赖目录中存在其他库不等于当前显示链路使用它们。
- 待机基础表情采用 GFX；其他表情仍走原 PNG 或步骤序列，不是所有资产都已经迁移。
- 待机基础表情与 listening 采用 GFX；其他表情仍走原 PNG 或步骤序列，不是所有资产都已经迁移。listening 缓存失败时单独回退旧 PNG，不影响待机。
- 屏幕目前未使用 TE 同步。软件预合成和连续传输能改善撕裂观感，但不能保证面板扫描与写入完全同步。
- 用户已确认缓存与固定时间轴版本的观感满意；最后的固定时间轴版本尚未提供新的量化日志，不能写成“稳定达到 30 FPS”。
- 用户已确认待机缓存/固定时间轴以及新 listening 版本的观感满意。两者最终版本尚无新的配套量化日志，不能写成“稳定达到 30 FPS”或“全部实机验收完成”。
已安装组件提供图片、网格图片、运动、动画、标签、二维码和按钮等接口。但本项目仅实际使用图片、网格、显示刷新及相关对象控制；通用中文文本、按钮、触摸和复杂布局不属于当前已实现能力。
@@ -53,12 +53,16 @@ esp_err_t err = domain_runtime_request_expression(&request);
| `components/platform/src/generated/emote_gfx/idle_base.c` | 静态鼻子和胡须压缩数据 |
| `components/platform/src/generated/emote_gfx/idle_eyes_open.c` | 原始睁眼压缩数据 |
| `components/platform/CMakeLists.txt` | 私有组件依赖及实际参与编译的资产列表 |
| `main/Kconfig.projbuild` | GFX 待机开关与测量日志开关 |
| `main/Kconfig.projbuild` | GFX 待机/listening 开关与测量日志开关 |
| `tools/split_idle_expression.py` | 从旧三帧中拆出静态底图及眼睛图层 |
| `tools/compress_idle_expression.py` | 将底图和睁眼图层转换为压缩 C 资产，并做编码往返检查 |
| `tools/test_lcd_status_hud.py` | 状态栏及自动回待机回归测试 |
| `tools/test_lcd_emote_transport.py` | 离屏捕获、缓存索引、传输、闭眼弧线和统计开关回归测试 |
| `tools/test_lcd_emote_timeline.py` | 固定时间轴、时钟粒度、迟到及取消回归测试 |
| `components/platform/src/lcd_emote_listening.c` | listening 关键眼型的逐列几何插值，仅初始化生成缓存时运行 |
| `components/platform/internal/lcd_emote_listening.h` | 平台私有插值接口，不向领域或控制层泄漏 GFX 类型 |
| `tools/prepare_listening_expression.py` | 拆分旧 listening、编码往返校验、生成四个 C 资产及同算法动画预览 |
| `tools/test_lcd_listening_gfx.py` | 实际资产、全闭合参数、缓存分配失败、GFX 对象失败、静态像素恢复与切换回归 |
`/tmp` 下修改过程中生成的补丁脚本不是工程运行依赖，不应提交或作为正式资源流程使用。
@@ -132,16 +136,56 @@ DMA 等待超时后禁止继续复用可能仍被硬件读取的缓冲，GFX 传
## 六、资源目录、制作和替换
### PNG、RLE 与运行时缓存不是同一份文件
PNG 是源素材格式，也是旧播放路径的压缩格式。新 GFX 路径从 PNG 生成 RLE
数组；不存在独立 `.rle` 文件，压缩字节保存在 `generated/emote_gfx/*.c` 中。
RLE（游程长度编码）把连续相同像素写成“数量＋像素值”。本项目一条记录四字节：
数量（1～255）、RGB565 高字节、RGB565 低字节、Alpha。例如 `0A 00 00 FF`
表示十个不透明黑色像素，替代十份 RGB565+A8 像素的三十字节。
颜色/透明度频繁变化时 RLE 可能压得较差，甚至膨胀；PNG 的压缩可能更紧凑。
| 路径 | 编辑输入 | 固件中的内容 | 运行时处理 |
| --- | --- | --- | --- |
| 普通 PNG 与 GFX 失败后备 | `lcd_source/*.png` | `lcd_optimized/*.png` 经素材包链接入应用 | 原 PNG 解码/缓存链路 |
| 新待机/listening GFX | 原 PNG 与拆分图层 PNG | 六个实际参与编译的 RLE C 资产 | 初始化解压，生成 PSRAM 眼型缓存，之后切换缓存 |
| 离线预览 | 图层与实际插值算法 | 不入固件 | 在电脑上检查造型，不能模拟 LCD 扫描 |
RLE 的编码往返对转换后的 RGB565+A8 数据无损，不等于原 PNG 的所有 RGB888
像素完全不变。RGB565 转换、背景归零、裁剪及性能适配是另一层处理，须单独
验证视觉并保留可编辑源图。九张待机与九张 listening 运行时缓存只在 PSRAM 中，
没有对应的固件图片或磁盘缓存文件；离线 PNG/GIF 预览不能算成这些缓存的 Flash。
### 当前目录与准确入口
```text
components/platform/assets/
lcd_source/ 旧 PNG 源图，仍保留
lcd_layers/jichubiaoqing/ 可编辑拆分图层、布局及预览
lcd_source/ 原 PNG 源图，仍保留，不直接入包
lcd_optimized/ 原 PNG 路径实际入包图片及 manifest
audio_prompts/ 实际入包提示音
lcd_layers/
jichubiaoqing/ 待机可编辑拆分图层、布局及预览
listening/ 聆听可编辑拆分图层、布局及预览
components/platform/src/generated/emote_gfx/
idle_base.c 实际编译的底图压缩数据
idle_eyes_open.c 实际编译的睁眼压缩数据
listening_base.c 实际编译的眉毛、鼻子、胡须数据
listening_eyes_open.c 实际编译的聆听睁眼关键图
listening_eyes_half.c 实际编译的聆听半闭关键图
listening_eyes_closed.c 实际编译的聆听闭眼关键图
```
半闭眼、闭眼源图及对应历史生成文件不代表当前参与编译；以构建列表为准，不把目录里的全部文件自动加入固件，也不擅自删除旧资源。
这里指待机历史 `idle_eyes_half.c`、`idle_eyes_closed.c`，不是 listening 的
半闭/闭眼 C 文件：后两者当前确实参与编译。逐文件大小、入固件分类、音频及
源图/预览汇总见 [显示与音频资产台账](显示与音频资产台账.zh-CN.md)。
- 待机拆分/压缩：`tools/split_idle_expression.py`、`tools/compress_idle_expression.py`。
- listening 拆分、压缩与预览：`tools/prepare_listening_expression.py`。
- RLE 解码：`components/platform/src/lcd_emote_assets.c`。
- 聆听关键图几何插值：`components/platform/src/lcd_emote_listening.c`。
- 缓存与播放：`components/platform/src/lcd_direct.c`。
- PNG 后备优化：`tools/optimize_lcd_assets.py`，流程见 [图片优化说明](lcd-image-asset-optimization.zh-CN.md)。
在仓库根目录，确认 Python 环境有 Pillow 后，可执行：
@@ -175,15 +219,49 @@ python3 tools/compress_idle_expression.py
| 上述合计 | 709,654 字节 PSRAM |
| GFX DMA 暂存区 | 10,240 字节内部 DMA 内存 |
此表不含对象管理、任务栈、SPI 描述符、PNG 缓存和系统其他模块。不能把表中合计当作整个显示组件的完整运行内存开销。
此表是待机与共用缓冲的基线，不包含新增 listening。它也不含对象管理、任务栈、SPI 描述符、PNG 缓存和系统其他模块。不能把表中合计当作整个显示组件的完整运行内存开销。
压缩源图像像素数据为 19,336 字节，不含描述信息和组件代码。运行时眼型缓存不写入 Flash。最新本地构建应用镜像为 3,040,480 字节，OTA 槽为 4,718,592 字节；这是当次构建快照，不是后续版本承诺。
待机压缩源图像像素数据为 19,336 字节，不含描述信息和组件代码。运行时眼型缓存不写入 Flash。接入 listening 前应用镜像为 3,040,480 字节，接入后为 3,094,176 字节，新增 53,696 字节；OTA 槽为 4,718,592 字节，剩余 1,624,416 字节。这是当次本地构建快照，不是后续版本承诺。
实机日志曾显示联网、唤醒同时运行时，内部内存最低只剩约十 KiB，而 PSRAM 尚有数 MiB。后续优先考虑 PSRAM 和局部复用，不能因为外部内存充足就不断扩大 DMA 或内部任务栈。
### 压缩优化的判定与预算限制
新增或替换素材必须做适合编码的压缩优化、数值比较及视觉验证，不强制 PNG 或
RLE，不默认“接入 GFX＝Flash 更小”。RLE 只是简单解压编码；当前播放快主要
依靠初始化生成局部缓存，不能把性能收益全部归因于 RLE，也不能断言 PNG 无法
在初始化解码后缓存。未来可评估 PNG/其他编码初始化解码生成同样缓存的成本。
listening 三张旧原 PNG 共 45,445 字节，已有优化 PNG 共 14,681 字节。
新底图及三个关键图未压缩像素为 255,528 字节，RLE 载荷为 50,176 字节，
相对未压缩像素减少约 80.4%，但比旧优化 PNG 大 35,495 字节。这几个比较对象
并不完全相同：旧图是三个整屏画面，新图是固定底图加三个可变眼型。
旧优化 PNG 仍作后备，因此本次没有从固件扣掉它们，完整镜像实际增加 53,696 字节。
当前方案不是最小 Flash 方案，是用户已接受的空间换流畅度方案。
所有迁移应报告优化前后素材、固件增量、常驻/峰值 PSRAM、静态数据、普通堆及
内部/DMA 增量，说明效果和测量证据。不按源码 C 文件大小推算 Flash，也不把
PSRAM 外部内存充足当成内部 DMA 安全。当前 listening 的已接受基线是固件
增量 53,696 字节、常驻像素 PSRAM 增量 423,234 字节，不是所有表情的硬上限。
超出该表情已确认预算、增加内部/DMA 缓冲、或可能影响 OTA/语音/网络时，先
给出预算、风险和替代方案并取得用户确认；新增表情尚无预算时先提出预算。
### 旧资源保留、整理与迁移完成条件
- 可编辑原 PNG 保留；离线预览和拆分 PNG 不入固件。旧待机/listening 的优化
PNG 仍入包，提供关闭 GFX、初始化/缓存失败等后备，不是可以直接删除的重复文件。
- 未参与编译的历史待机 C 文件、旧预览和 `defaultAudio/` 副本仅标记为待评估，
不因“历史”标签自动删除。实际入包音频来自 `platform/assets/audio_prompts/`。
- 迁移完成至少包括：语义入口与退出/取消一致、正常画面/状态栏验收、故障及
关闭开关时的后备行为明确、联网/语音并行与最低内存记录、生成可重现、文档
和台账同步。用户观感满意仅覆盖其中一项，不自动满足删除后备的条件。
- 删除或移出固件前先列清文件、引用、回退替代方案及预计收益，取得用户授权；
再同步构建清单/资源目录映射、相关测试和台账。保留 Git 可恢复记录并验证
正常与故障路径。清理只是后续计划，本次没有删除资源或改变打包范围。
## 八、性能日志如何读
通过 `menuconfig` 搜索 `TQ_LCD_EMOTE_GFX_TEST` 和 `TQ_LCD_EMOTE_FPS_LOG`。前者控制 GFX 待机路径；后者控制性能统计，默认关闭，当前本地测量配置开启。关闭统计不应改变动画节奏。
通过 `menuconfig` 搜索 `TQ_LCD_EMOTE_GFX_TEST` 和 `TQ_LCD_EMOTE_FPS_LOG`。前者控制 GFX 待机及 listening 路径；后者控制性能统计，默认关闭，当前本地测量配置开启。关闭统计不应改变动画节奏。
每轮完整眨眼输出一次 `emote_fps` 和 `emote_cost`，不在逐帧传输中打印：
@@ -192,7 +270,7 @@ python3 tools/compress_idle_expression.py
- `eye_updates`：眼型步骤中确实完成至少一个区域传输的次数；多个 DMA 块不会重复计数。
- `update_fps`：实际更新次数除以同一眨眼时长，不是仅运动段的瞬时频率。
- `draw_avg_us`、`draw_max_us`：步骤绘制时间；平均包含没有传输的保持步骤。
- `late_steps`：绘制达到或超过 34ms 的步骤数，不等于屏幕丢帧数，也不统计所有调度迟到。
- `late_steps`：绘制达到或超过对应时间线步长的步骤数（待机 34ms、listening 30ms），不等于屏幕丢帧数，也不统计所有调度迟到。
- `lock`：等待 GFX 锁；`compose`：眼型修改及合成、刷新处理，扣除复制和传输；`copy`：复制到 DMA；`spi`：提交并等待传输完成。
各项均为墙钟时间，可能包含被其他任务抢占。各项最大值可能来自不同步骤，不能相加。不能仅凭合成时间大就断言算法慢，也不能仅凭 SPI 等待大就断言线路带宽不足。
@@ -201,6 +279,64 @@ python3 tools/compress_idle_expression.py
## 九、后续开发建议
### 已接入的 listening
旧实现每张停留 500ms，顺序为睁眼、半闭眼、闭眼；新实现保留三种斜眼造型，
并固定第一张的眉毛、鼻子、胡须。背景中的细小杂色归零，旧源图和打包 PNG 全部保留。
动态图层窗口为 `(41,87)`，尺寸 242×77，包含闭眼右端延伸及边缘余量。
Flash 中只保存静态底图和三个关键眼型，不保存九张缓存。初始化时按列提取两张
相邻关键图的上下轮廓，插值出目标轮廓，再变形单张纹理，并做纵向亚像素采样。
不是两张表情交叉淡化；避免高光双影和眼圈灰化。闭合 0、128、232 分别精确使用
睁眼、半闭眼、闭眼关键图，232 以上共用闭眼缓存。
生成阶段的三张 RGB565A8 关键图共 167,706 字节 PSRAM，生成完释放。底图和九个
局部 RGB565 缓存常驻；缓存中的黑色眼睛外区域恢复眉毛/胡须静态像素，不能任意
叠加到不同底图。播放时没有 PNG 解码、关键图解压或逐列变形。
| listening 新增项 | 数值 |
| --- | ---: |
| 静态底图压缩数据 | 8,732 字节 Flash |
| 睁眼、半闭眼、闭眼压缩数据 | 24,036 / 13,236 / 4,172 字节 Flash |
| 四份压缩数据合计 | 50,176 字节 Flash |
| 整个应用镜像实际增量，含新增代码与对齐 | 53,696 字节 Flash |
| 静态底图解压后 | 87,822 字节 PSRAM |
| 九个局部眼型缓存 | 335,412 字节 PSRAM |
| 新增常驻像素合计 | 423,234 字节 PSRAM |
| 初始化新增像素峰值，含临时关键图 | 590,940 字节 PSRAM |
| LCD 文件静态数据/BSS 增量 | 333 字节 |
| 新图片对象、图片状态及链表节点申请量 | 80 + 8 + 8 = 96 字节普通堆，不含分配器开销 |
| 新 DMA 缓冲、新合成缓冲、新任务 | 0，复用原有实现 |
上述静态/对象字节数通过当前 ESP32-S3 编译器核对，不包含链接段对齐、堆分配
管理、栈瞬时使用或绘制临时分配。普通堆的实际放置由 ESP-IDF 内存策略决定。
待机加 listening 的明确常驻像素缓冲总计为 1,132,888 字节 PSRAM，仍不等于整个
显示组件总内存。初始化峰值及联网时真实余量需要设备日志验证。
新时间线是 `24→80→160→232→232→192→128→64→16→0`，共十步，
每步 30ms，锚定共同起点；目标眨眼 300ms，闭眼保持约 60ms，睁眼停留约 2.4 秒。
同一闭眼缓存重复保持不触发新传输。目标步骤频率不是实测 FPS，也不是面板扫描率。
`emote_fps` 日志新增 `face=idle/listening` 区分后端，仍由原测量开关控制。
领域目录和控制层监听状态不变：按键/本地唤醒进入时展示 listening，直到新请求
或停止；它不严格等于录音已经开始。眨眼结束不自动回待机。退出后下一次待机请求
恢复待机静态层与眼型；切换时完整刷新一次，之后只刷新眼睛及变化的状态栏。
缓存失败释放未绑定像素并保留旧 PNG；极端解锁错误下已绑定对象的像素保留到重启，
不能释放后仍被渲染线程引用。GFX 总开关关闭时仍使用原 PNG。
生成资源与预览（需要 Pillow 和 Clang，覆盖本次生成的 listening 图层与资产）：
```bash
python3 tools/prepare_listening_expression.py
python3 tools/test_lcd_listening_gfx.py
```
可编辑 PNG、布局和预览在 `components/platform/assets/lcd_layers/listening/`；
实际编译的四个 `listening_*.c` 在 `components/platform/src/generated/emote_gfx/`。
动画预览 `preview.gif` 调用实际 C 插值生成，但没有模拟 LCD 扫描与语音负载。
固定窗口/锚点变化需同步脚本与测试。需要手工保留眉毛等素材编辑时，不要直接重新
拆分覆盖；当前生成脚本不是所有角色通用的热替换工具。
### 接入更多表情
先逐个迁移，保留未迁移 PNG 路径。每个表情准备静态层、动态图层、锚点、时间线、缓存预算及结束行为。固定短动作适合预生成缓存；大量不同动作或连续交互需要考虑按需生成、共享缓存和生命周期，不应给每个表情无上限常驻一份整屏缓存。
@@ -231,6 +367,7 @@ python3 tools/compress_idle_expression.py
python3 tools/test_lcd_status_hud.py
python3 tools/test_lcd_emote_transport.py
python3 tools/test_lcd_emote_timeline.py
python3 tools/test_lcd_listening_gfx.py
```
这些脚本在电脑上从实际源码提取 C 函数，使用 Clang 与内存、未定义行为检查器。需要 Python 和 Clang；不是固件代码，不占设备 Flash 或 RAM。测试使用模拟接口，不能证明屏幕无撕裂、实时帧率或设备像素完全一致。
@@ -248,3 +385,21 @@ python3 tools/test_lcd_emote_timeline.py
7. 新增停止或资源释放功能时的取消、超时和反复启动测试。
交付时分别报告源码检查、主机测试、编译和实机证据。不能把“编译通过”写成“设备已验证”，也不能只用目标帧率或一次录像承诺持续性能。
### 对话需求与验证记录
| 需求或反馈 | 当前结果与边界 |
| --- | --- |
| 不需要触摸/复杂 GUI，精致流畅为主 | 局部 GFX 图层，不迁移完整 LVGL GUI |
| 拆分原表情，允许性能适配但整体保持 | 待机/listening 拆分与固定静态层；后续延续原画风，大幅变化需确认 |
| 眼睛向中间闭合，避免重影和撕裂 | 单一轮廓、闭眼弧线、缓存和连续传输；没有 TE，不能承诺零撕裂 |
| 统一所有返回待机入口、补时间电量 | 已实现统一后端及 HUD；不能覆盖新 pending；数字点阵不代表任意中文文字 |
| 增加可开关日志、计算具体帧数 | 已有 emote_fps/emote_cost；区分步骤/实际更新/面板扫描率 |
| 全中文开发说明与 AI 注意事项 | 本指南、资产台账及 AGENTS.md 中文 GFX 约束；原有仓库架构规范保留 |
| listening 也迁移为流畅表情并报告开销 | 已接入，开销见上表；保持业务监听生命周期与旧 PNG 后备 |
| 用户确认待机与 listening 效果满意 | 2026-10-09 对话中确认；没有据此声称最终量化 FPS/最低内存及全部场景合格 |
| 素材需要压缩优化与成本限制 | 已补通用强制流程、PNG/RLE 权衡与先确认预算规则 |
此前缓存/时序及中文指南提交为 `89e8e3a`、`c0770ac`；本次基线包含 listening
接入及补充文档。完整状态机、任意中文字体、其他表情批量迁移、
资源清理/热替换是后续方向，不标成已经实现，也不推断用户已要求立即实施。