调试总览

EmbeddedGUI 的调试建议分成三层来用：

• 画面可视化：直接把 PFB、脏区、触摸轨迹和帧率信息画到屏幕上，先确认“画了什么”。

• 日志和统计：输出脏区来源、合并过程和每帧统计，回答“为什么会这样画”。

• 自动化脚本：把编译、录制、截图和差异检查串起来，避免修完以后回归。

推荐顺序

1. 先在 PORT=pc 上复现问题。

2. 先开画面类宏，看渲染范围、触摸路径和实时指标是否符合预期。

3. 再开日志类宏，定位是谁触发了脏区、脏区是怎么被合并的。

4. 最后接脚本回归，把问题固定成可重复检查的流程。

   如果改动涉及多屏入口、descriptor、线程模型或副屏输入，优先先跑 release_check.py --scope multi-display；如果要细查编译日志或副屏截图，再拆开补跑 code_compile_check.py --scope multi-display 和 code_runtime_check.py --scope multi-display。

宏怎么开启

日常有两种方式：

• 临时调试：直接走 USER_CFLAGS，适合一次性排查。

• 应用常驻：写进对应示例或应用的 app_egui_config.h。

临时调试示例：

make all APP=HelloBasic APP_SUB=slider PORT=pc \
  USER_CFLAGS="-DEGUI_CONFIG_DEBUG_DIRTY_REGION_REFRESH=1 -DEGUI_CONFIG_DEBUG_REFRESH_DELAY=40"

应用内常驻示例：

#define EGUI_CONFIG_DEBUG_DIRTY_REGION_REFRESH 1
#define EGUI_CONFIG_DEBUG_REFRESH_DELAY 40

常见症状对应工具

现象	先开什么	再看什么
只刷新了部分区域、怀疑 tile 错位	EGUI_CONFIG_DEBUG_PFB_REFRESH	EGUI_CONFIG_DEBUG_DIRTY_REGION_REFRESH
脏区太大、不知道为什么整块刷新	EGUI_CONFIG_DEBUG_DIRTY_REGION_REFRESH	EGUI_CONFIG_DEBUG_DIRTY_REGION_STATS、EGUI_CONFIG_DEBUG_DIRTY_REGION_TRACE
点击、拖动位置不对	EGUI_CONFIG_DEBUG_TOUCH_TRACE	scripts/code_runtime_check.py 或手工录制
多屏改动后想快速确认双屏都还能编过、跑通、录到图并过文档校验	scripts/release_check.py --scope multi-display	scripts/code_compile_check.py --scope multi-display 和 scripts/code_runtime_check.py --scope multi-display
想确认当前 FPS、CPU 占用和 LCD latency	EGUI_CONFIG_DEBUG_PERF_MONITOR_SHOW	如需一起看 EGUI 自身 SRAM current / peak，再叠加 EGUI_CONFIG_DEBUG_MEM_MONITOR_SHOW
想知道是哪个控件触发了日志	EGUI_CONFIG_DEBUG_CLASS_NAME	EGUI_CONFIG_DEBUG_VIEW_ID、EGUI_CONFIG_DEBUG_LOG_LEVEL=EGUI_LOG_IMPL_LEVEL_DBG
想批量检查示例渲染和交互	scripts/code_runtime_check.py	scripts/checks/hello_basic_render_workflow.py
想确认动画是否仍然是局部刷新	scripts/checks/code_dirty_animation_check.py	scripts/perf_analysis/dirty_region_stats_report.py

这组文档覆盖什么

• 调试宏：每个调试宏的作用、推荐组合和运行效果。

• PC 端调试流程：PC 端最常用的抓图、录制、回归流程。

• 调试脚本：调试相关脚本的定位、命令和输出结果。

如果你现在关心的是 PFB 和脏区原理本身，可以同时参考 渲染管线 和 脏矩形细粒度优化指南。