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

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
+33 -2
View File
@@ -225,6 +225,8 @@ Use a clear conventional format:
本节是在原有架构规则上的补充,不替代前文。处理显示、资产、表情、缓存、
刷新或帧率任务时,必须先完整阅读 `docs/GFX表情显示应用与开发指南.md`,
再按任务核对当前源码和配置;不得把历史日志的资源开销或 FPS 当成当前事实。
涉及素材增删或预算时,还需核对 `docs/显示与音频资产台账.zh-CN.md`、构建白名单
及当前文件;台账是有日期的快照,不替代源码、manifest 和实际构建结果。
### 开始工作前
@@ -232,7 +234,7 @@ Use a clear conventional format:
和预览,不把 tq-cat 的实现或其他目录里的旧文件当成当前工程。
2. 优先查看 `lcd_direct.c`、领域表情目录、平台公共接口、构建列表和 Kconfig。
图层制作还需阅读 `split_idle_expression.py`、`compress_idle_expression.py`。
3. 当前是待机 GFX 与其他 PNG 混合后端;未接入 esp_emote_expression 状态机,
3. 当前是待机/listening GFX 与其他 PNG 混合后端;未接入 esp_emote_expression 状态机,
也未整体迁移到 LVGL。不要凭依赖存在或请求优先级字段推断功能已经实现。
### 必须保持的正确性
@@ -267,6 +269,32 @@ Use a clear conventional format:
16. 缓存失败要释放部分成果并维持安全后备。当前资源随 LCD 常驻,停止循环
不等于完整销毁;新增热替换/重复初始化需要显式生命周期、超时和错误测试。
### 素材压缩、成本与视觉约束(强制)
- 新增或替换显示素材必须进行适合该格式的压缩优化及成本评估。根据 Flash、
解码耗时、PSRAM 和效果选择 PNG、RLE 或其他编码,不强制统一格式,不得
默认 GFX/RLE 比优化 PNG 更省空间,也不得仅凭“已压缩”认定整体优化完成。
- PNG 路径先读 `docs/lcd-image-asset-optimization.zh-CN.md`,从原图运行
`tools/optimize_lcd_assets.py generate`、`verify`;GFX 路径使用对应生成脚本
并做编码往返验证。有效 Alpha 不得删除,不能用普通色彩量化静默改变画面。
- 固定短动作优先保存少量关键资源,初始化生成局部缓存。避免保存大量全屏
中间帧;播放期间不得引入未经评估的重复解码、动态分配或整屏缓存复制。
- 交付必须比较原图文件、优化 PNG、未压缩像素、压缩载荷以及整个固件大小,
分别报告常驻/初始化峰值 PSRAM、静态数据/普通堆、内部 RAM 和 DMA 增量。
C 数组源文件的文本大小、文件系统分配空间、Flash 载荷不是同一个数字。
- 新方案比旧方案大时,必须说明成本增加、获益及证据等级;当前 listening
是空间换流畅度的已接受基线(固件增量 53,696 B、常驻像素 PSRAM 增量
423,234 B),不是所有表情的硬上限。不能按表情数量直接复制整套缓存。
超出该表情已确认预算、新增内部/DMA 缓冲,或可能影响 OTA/语音/网络时,
先报告预算、风险及替代方案,获得用户确认后实施;没有预算时先提出预算。
- 保持现有整体造型与画风,允许为性能做细微适配;改变角色造型、表情语义、
大幅改配色或动作方向前需用户确认。默认向中间闭眼,保留表情自身弧线;
不直接复制另一表情的几何参数,不通过两张完整眼型淡化制造双轮廓/高光重影。
- 视觉验收必须检查整体上移、残影、色差、闪烁、眼睑跳变、窗口截断及 HUD
遮挡,同时核对切换/取消/后备。用户观感确认要记入指南,但不能代替实测 FPS、
峰值内存或并行负载日志。资产台账需同步分类与大小;清理旧资源须遵循指南
的迁移完成条件,并另获授权,不得因目录名含 generated 就擅自删除。
### 状态、测量与验收
17. 时间沿用现有同步与时区服务;电量来自领域状态,不在显示层用电压重算。
@@ -278,7 +306,7 @@ Use a clear conventional format:
不把合成耗时当纯 CPU,不把等待传输当纯线上耗时。
20. 内存必须分别报告 Flash、PSRAM、内部 RAM 和 DMA。像素缓冲合计不是整个
组件总开销;应用镜像已包含嵌入式资源,不重复加算。留意联网/唤醒后的最低余量。
21. 变更后至少运行三个显示回归脚本和 ESP-IDF 5.5.4 构建。条件编译要验证
21. 变更后至少运行四个显示回归脚本和 ESP-IDF 5.5.4 构建。条件编译要验证
日志开启/关闭两种情况;涉及资源时检查编码往返及视觉预览。
22. 实机验收包括待机/表情切换、跨分钟、充电、缓存启动、唤醒与网络并行、
取消和超时。区分源码检查、主机测试、编译、设备日志与用户观感证据。
@@ -290,7 +318,10 @@ Use a clear conventional format:
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
```
提交只包含任务相关文件,遵守主题分支与原有提交规则;不要提交临时补丁脚本、
本机 sdkconfig、构建目录或未授权推送。修改当前机制时同步更新中文指南和测试。
纯文档任务只需检查 Markdown、链接、数字与当前代码的一致性,不为此重跑固件
构建或烧录;应明确本次验证层级,不能把之前的测试结果写成本次重新执行。