# Fast Path Config

本页是当前 fast-path 相关配置的唯一用户入口。

它只回答三件事：

- 现在还有哪些 fast-path 相关配置值得用户关注
- 每个配置大致在换什么 `ROM / SRAM / perf`
- 哪些历史宏已经不再是推荐用户配置

如果某个 fast-path 名字不在本页里，默认就不要把它当成当前支持的用户配置项。

## 1. 先看结论

当前真正建议用户关注的，主要只有 5 个共享配置宏：

- `EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE`
- `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW`
- `EGUI_CONFIG_IMAGE_CODEC_PERSISTENT_CACHE_MAX_BYTES`
- `EGUI_CONFIG_IMAGE_EXTERNAL_PERSISTENT_CACHE_MAX_BYTES`
- `EGUI_CONFIG_IMAGE_RLE_EXTERNAL_CACHE_WINDOW_SIZE`

这 5 个配置还保留着，是因为它们现在仍然在表达明确的产品取舍：

- decode heap 上界
- 压缩图片主路径策略
- cache / SRAM 预算

而一批只省几十到几百字节的微型 fast-path 宏，已经不再作为用户配置项提供。

## 2. 当前支持的共享配置

下表可以直接当成用户选型入口看。

| 宏 | 当前默认 | 主要作用 | 典型代价 / 收益 | 什么时候考虑调整 |
| --- | --- | --- | --- | --- |
| `EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE` | `2` | 限制 decode 阶段的单像素 scratch 上界 | `2 -> 4` 约 `text +108B`，完整 `239` 场景无明显性能波动 | 只有当资源格式或解码路径确实需要更高像素 scratch 时再调大；一般保持默认 |
| `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW` | `0` | 控制压缩图片 fast draw 的 3 档模式：`0=关闭`，`1=full row-band`，`2=tail-row low-RAM` | `0 -> 1` 会额外引入约 `text +5108B`，但能避免 internal tiled `QOI/RLE` 热点 `+111% ~ +634%` 回退；`1 -> 2` 会再引入约 `text +9976B`，换来约 `2304B` 峰值 heap 收益 | 项目有压缩图片热点时，先做 `0/1` A/B；如果还要继续压峰值 heap，再评估 `1/2` |
| `EGUI_CONFIG_IMAGE_CODEC_PERSISTENT_CACHE_MAX_BYTES` | `0` | 给 codec 整图 persistent cache 预留预算 | `0 -> 5000` 约 `text +2948B, bss +24B`；历史上只有 `IMAGE_TILED_QOI_565_0` 有明显改善 `-13.1%` | 只在你已经确认 codec 热点集中在少量重复资源，且愿意为此付出额外 ROM/BSS 时再调大 |
| `EGUI_CONFIG_IMAGE_EXTERNAL_PERSISTENT_CACHE_MAX_BYTES` | `0` | 给 external image persistent cache 预留预算 | `0 -> 5000` 约 `text +948B, bss +40B`；部分 external tiled/resize 场景改善 `-32.6% ~ -61.6%` | 项目大量使用 external image，且更关心这些场景的吞吐时可考虑调大 |
| `EGUI_CONFIG_IMAGE_RLE_EXTERNAL_CACHE_WINDOW_SIZE` | `1024` | 控制 external RLE 的窗口大小，也就是一块直接的 SRAM 预算 | `1024 -> 64` 约 `text +96B, bss -1024B`，但 external RLE 主路径回退 `+17.5% ~ +21.8%` | 只在 SRAM 非常紧张，且可以接受 external RLE 明显变慢时再缩小 |

### 这 5 个配置怎么理解

- `MAX_PIXEL_SIZE` 主要是 heap 上界问题，不是典型 fast-path 开关。
- `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW` 同时收口了“是否启用 row cache”和“是否切到 tail-row low-RAM 路径”两个决策，应该按 `0 / 1 / 2` 三档做真实场景 A/B。
- 两个 `*_PERSISTENT_CACHE_MAX_BYTES` 更像“预算项”，不是“应该默认打开的优化项”。
- `RLE_EXTERNAL_CACHE_WINDOW_SIZE` 是最直接的 SRAM 换性能入口。

## 3. 示例里还能看到的局部开关

当前仓内仍保留两个示例局部开关，但它们不是框架统一配置面：

| 名字 | 用途 | 对用户的建议 |
| --- | --- | --- |
| `EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW` | 示例或模板里用来做文字路径 A/B；`0=关闭`，`1=打开完整 std-font fast draw（含 ASCII 直查表）` | 普通项目不要额外发散使用；历史上关闭 fast draw 虽可省约 `8328B` 代码，但文本热点会回退 `+27% ~ +465%` |
| `EGUI_CONFIG_CIRCLE_FILL_BASIC` | `HelloPerformance` 的 benchmark 局部入口 | 只在 benchmark 或定向实验里使用；普通产品配置不用关注 |

`EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW` 也是字体 fast/cache 路径的总开关；内部的 code lookup cache、transform prepare/layout cache、transform size cache 和 draw-prefix cache 都不能绕过它单独生效。历史上的 code lookup / transform size 独立宏已经删除，其中 transform size cache 进一步受 `EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW` 约束。

图像 RGB565 alpha opaque cache 也不再保留独立配置入口，随 `EGUI_CONFIG_FUNCTION_IMAGE_FORMAT_RGB565` 直接编译；image/canvas/font 的 frame-cache release 钩子固定在帧结束执行，不再暴露单独的 release 宏。

如果你是在复制 `tiny_rom` / `basic_ui` 这类模板配置，看到 `APP_EGUI_*` 名字是正常的；但它们只代表模板或示例的局部选择，不代表框架统一推荐接口。

## 4. 哪些历史宏已经不建议用户再调

下面这些类型的名字，当前都不建议再作为用户配置入口依赖：

- QOI / RLE 解码内部的小 checkpoint、小索引、小 cache 宏
- 字体内部的小型 lookup / line cache 宏
- 只换回几十字节到一两百字节 `SRAM` 的 external row persistent 宏
- 只换回几十字节 `ROM / BSS` 的 source-opaque / row-cache 细节宏

原因也很直接：

- 它们大多只能换回几十到几百字节
- 继续公开出来会让配置面越来越碎
- 其中一些甚至会用很小的 `size` 收益换来非常大的性能退化

几个典型例子：

- `QOI checkpoint count`
  - 只省约 `text -276B, bss -8B`
  - 但历史 `20` 个 QOI 场景会回退 `+110% ~ +911%`
- `RLE checkpoint`
  - 只省约 `text -92B, bss -16B`
  - 但历史 `20` 个 RLE 场景会回退，峰值约 `+452%`
- `font` 的小 lookup / line cache 宏
  - 典型收益只有 `text +200B / +488B` 量级
  - 不值得继续暴露给用户做长期调参
- `std / transform external row persistent cache`
  - 典型也只有 `bss -40B / -56B`
  - 这类收益太小，不值得保留成用户可配项

判断规则可以简单记成一句话：

- 不能明显改变产品预算的微型宏，不值得继续开放给用户。

## 5. 按目标选择

### 5.1 如果你优先压 ROM

优先做这几件事：

- 保持 `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW=0`
- 保持两个 `*_PERSISTENT_CACHE_MAX_BYTES=0`
- 只有在压缩图片热点确实存在时，才评估 `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW`

不要做的事：

- 不要再去追那些已经移除的历史微宏
- 不要为了省几百字节，把 QOI/RLE 主路径打穿

### 5.2 如果你优先压 SRAM

优先看：

- `EGUI_CONFIG_IMAGE_RLE_EXTERNAL_CACHE_WINDOW_SIZE`
- `EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE`

推荐顺序：

1. 先确认 `MAX_PIXEL_SIZE=2` 是否已经满足需求
2. 再评估 `RLE_EXTERNAL_CACHE_WINDOW_SIZE` 是否能从 `1024` 缩小
3. 如果缩小，就必须做 external RLE 场景回归

### 5.3 如果你优先要压缩图片性能

优先看：

- `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW`
- `EGUI_CONFIG_IMAGE_CODEC_PERSISTENT_CACHE_MAX_BYTES`

适用场景：

- 项目里有明显的 `QOI/RLE` 压缩图片热点
- 尤其是 internal tiled scene
- 先确认 `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW=1` 是否已经足够；只有在还要继续压峰值 heap 时，再评估 `=2`

### 5.4 如果你优先要 external image 性能

优先看：

- `EGUI_CONFIG_IMAGE_EXTERNAL_PERSISTENT_CACHE_MAX_BYTES`

适用场景：

- external image 读取频繁
- 同一批资源会被重复访问
- 你可以接受额外的 `ROM / BSS`

## 6. 用户文档的一条边界

本页只覆盖“当前仍值得用户调”的入口。

如果你在其它 retention 文档里看到更多 fast-path 名字，需要这样理解：

- 这些名字大多只是历史 A/B 记录
- 它们不是当前推荐用户配置面
- 对普通项目来说，不要因为历史文档里出现过，就把它们重新加回产品配置

只有在你明确要做框架维护或重新做一轮完整 A/B 时，才需要继续阅读：

- `example/HelloPerformance/fast_path_retention.md`
- `example/HelloPerformance/macro_decision_matrix.md`
- `example/HelloPerformance/macro_cleanup_summary.md`

## 7. 一句话总结

当前 fast-path 配置的用户口径很简单：

- 真正值得用户调的，只剩少数几个能明显改变 `ROM / SRAM / perf` 预算的配置项。
- 其余微型 fast-path 宏，默认都不要再碰。