Size Selection Guide

本页不是新的测量结果，而是把当前 size/ 目录里的几份报告整理成一套更容易执行的取舍顺序。具体数字请以各报告页表格为准。

建议配合以下文档一起看：

  • size_report.md

  • hq_size_report.md

  • canvas_path_size_report.md

  • canvas_feature_size_report.md

  • widget_feature_size_report.md

1. 不要把所有 Delta 直接相加

EmbeddedGUI 的 size 不是“单项线性累加”。

原因很直接：

  • 不同 widget 会复用 egui_view / theme / canvas / font / fixmath / image 等公共代码。

  • 不同 canvas path 之间也会共享底层几何和绘制辅助逻辑。

  • 因此单项 delta 更适合看“边际成本”，组合项和最终应用报告才适合看“真实落地成本”。

实际阅读时，请把几份报告的口径分开：

  • canvas_path_size_report.md 和 hq_size_report.md 看的是“单条路径被链接进来会多多少”。

  • canvas_feature_size_report.md 和 widget_feature_size_report.md 看的是“一组能力或一组控件真正一起启用时的组合成本”。

  • size_report.md 看的是“真实应用最终要付出的总体成本”。

2. 先看 feature，再看 widget，最后看 HQ

推荐顺序：

  1. 先决定全局 feature 要不要开

  2. 再决定真实 widget 要不要引入

  3. 最后才决定某些场景是否需要显式调用 _hq 路径

这样做的原因是：

  • feature 决定的是底层能力有没有进入固件，影响面最大。

  • widget 决定的是业务层真实落地成本。

  • HQ 是锦上添花项，适合最后做精细化开关，而不是一开始就全局打开。

3. 小 ROM 项目怎么选

如果目标是小 ROM，建议这样做：

  • 从 size_preset_profiles.md 的 tiny_rom 或 basic_ui 起步。

  • 只在资源实际使用时打开 QOI 或 RLE codec。

  • 不要默认打开 EGUI_CONFIG_CIRCLE_DEFAULT_ALGO_HQ。

  • 优先确认是否真的需要重控件，而不是先引入再回头裁。

这类项目最应该优先复查的通常是：

  • MASK

  • QOI / RLE

  • WIDGET_ENHANCED_DRAW

  • _hq 调用路径

4. 通用 UI 项目怎么选

如果目标是常规设置页、表单页、简单交互页，建议：

  • 从 basic_ui 模板起步。

  • 先选基础交互控件，再逐步增加视觉增强项。

  • codec 只按资源格式打开，不要因为“可能以后会用”而提前保留。

  • 最终以 size_report.md 验证真实应用，而不是只看 probe 增量。

5. 仪表盘和展示项目怎么选

如果目标是看板、仪表、演示项目，建议：

  • 从 dashboard 或 full_feature 起步。

  • 接受更高的视觉相关 ROM 成本。

  • 先确认是否确实需要 ring / gauge / chart / clock 这类重控件，再决定组合。

  • 即使使用高配模板，也尽量把 HQ 保持为“按场景显式启用”，不要全局默认打开。

6. HQ 路径建议

当前 hq_size_report.md 的结论可以直接用于开关判断：

  • 当前 qemu probe 报告里，LINE_HQ、CIRCLE_HQ、ARC_HQ 的隔离增量都在 +15200B 量级。

  • ARC_ROUND_CAP_HQ 和 ALL_HQ 当前都落在 +13388B。

  • 这说明真实链接结果要看依赖共享关系，不能只看公开符号本身的体积。

实用建议：

  • 不要把 EGUI_CONFIG_CIRCLE_DEFAULT_ALGO_HQ 直接改成全局默认 1。

  • _hq API 只在明确需要画质收益的 widget 或场景里显式调用。

  • 如果关心的是 activity_ring 这类真实业务场景，优先看 ARC_ROUND_CAP_HQ，不要只看 ARC_HQ。

7. 选型时最值得先看的开关

优先级较高的开关包括：

  • EGUI_CONFIG_FUNCTION_SUPPORT_MASK

  • EGUI_CONFIG_FUNCTION_IMAGE_CODEC_QOI

  • EGUI_CONFIG_FUNCTION_IMAGE_CODEC_RLE

  • EGUI_CONFIG_FUNCTION_WIDGET_ENHANCED_DRAW

  • EGUI_CONFIG_CIRCLE_DEFAULT_ALGO_HQ

  • EGUI_CONFIG_FUNCTION_IMAGE_FORMAT_RGB565_8

  • EGUI_CONFIG_FUNCTION_IMAGE_FORMAT_ALPHA_8

这些开关的特点是：

  • 要么决定整类功能是否进入固件；

  • 要么决定资源格式支持范围；

  • 要么会影响后续大量 widget 或绘制路径是否被保留。

8. 推荐实际流程

建议按下面的顺序做一次完整判断：

  1. 先看 size_preset_profiles.md，选一个最接近目标的模板。

  2. 再看 canvas_feature_size_report.md，决定全局 feature。

  3. 再看 widget_feature_size_report.md，决定业务层真实控件。

  4. 最后看 hq_size_report.md，只给必要场景加 HQ。

  5. 用 size_report.md 验证真实应用的最终 ROM/RAM/heap/stack。

如果需要跑一轮统一回归，直接用：

python scripts/size_analysis/main.py run-size-suite --quick
python scripts/size_analysis/main.py run-size-suite --full
python scripts/size_analysis/main.py run-size-suite --only hq,canvas_feature,widget