低 RAM 配置宏说明文档¶

本文档梳理 HelloPerformance 等低 RAM 场景中使用的细粒度配置宏，说明每个宏的作用机制、默认值、及在 HelloPerformance 下的设定与 RAM 节省效果。

所有宏均可在应用的 app_egui_config.h 中覆盖，不影响其他应用的默认行为。

说明：下文 HelloPerformance 列同时包含“当前 shipped 默认”与“历史 low-RAM 实验值”。当前默认始终以 example/HelloPerformance/app_egui_config.h 为准；若某项已被回退为默认值，会在对应小节里单独说明。

一、图像解码相关宏¶

1. `EGUI_CONFIG_IMAGE_STD_ALPHA_OPAQUE_CACHE_SLOTS`¶

位置： src/image/egui_image_std.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为 src/image/egui_image_std.c 里的实现私有常量，默认行为固定为 4。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `4`
HelloPerformance	当前随实现内固定 `4`（历史 public 实验值 `0`）
RAM 类型	BSS
HP 节省	~33 B

机制： 缓存”某张 RGB565+alpha 图片的 alpha 通道是否全为不透明”的探测结果，跨帧复用以跳过逐行扫描，走更快的纯 RGB565 合成路径。SLOTS 槽数控制最多缓存多少张图片的结论，采用轮转淘汰。

设为 0 时整个 cache 数组不编译，每次绘制均重新扫描。

2026-04-04 基于当前 HelloPerformance 主线重新做完整 A/B 后，结论更新为：

关闭后 HelloPerformance text 2055380 -> 2055224，回收 text -156B、bss -40B
完整 239 perf 场景里没有任何 >=10% 回退，只有 EXTERN_IMAGE_RESIZE_TILED_565_8 -11.4% 这一处 >=10% 改善
基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 全部保持在噪声内
但 runtime 4 vs 0 有 8 帧真实像素差：frame_0066~0069、frame_0095~0098
额外控制组 4 vs 4 repeat 为 hash mismatch 0、pixel mismatch 0，说明这不是录制噪声
HelloUnitTest on / off 仍是 688/688 passed

因此这颗宏当前默认继续保持 4。但它的收益也只有 text -156B, bss -40B，远低于当前“单颗 public 宏至少要值得 >1KB code-size 回收”的门槛；同时 0 路径在当前主线仍会带来 8 帧真实渲染差异，所以这个名字已不再保留为 public 宏入口，只保留历史 A/B 记录。

数据结构（默认 SLOTS=4 时）：

static egui_image_std_alpha_opaque_cache_t g_egui_image_std_alpha_opaque_cache[4]; // 4×8B
static uint8_t g_egui_image_std_alpha_opaque_cache_next;                          // 1B

2. `EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE`¶

位置： src/config/egui_config_default.h

属性	值
默认值	当前默认 `2`（历史默认 `4`，对应 RGBA32 decode 上界）
HelloPerformance	当前直接继承默认 `2`（历史对比值 `4`）
RAM 类型	heap（动态峰值）
HP 节省	相比历史 `4` 约 ~7680 B 峰值堆

机制： 决定 codec 行缓存和单行 pixel scratch 的最大字节上界（PFB 行宽度 × 屏幕宽度 × 本宏）。当前框架默认已经收窄到 2，因为 HelloPerformance 当前压缩图像资产均为纯 RGB565，不含 RGBA32；4 仅保留为历史默认/对比值，用于需要 RGBA32 decode 上界的场景。

公式：

codec_row_cache_pixel_max = PFB_HEIGHT × SCREEN_WIDTH × EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE
当前默认/HelloPerf(PFB=16×16): 16 × 240 × 2 = 7,680 B
历史默认 4 在相同 PFB 下: 16 × 240 × 4 = 15,360 B
差值: 7,680 B

2026-04-05 按当前主线完成 2 -> 4 全量 A/B 后，结果为：

size：text 2055380 -> 2055488，即 text +108B，bss 不变
perf：完整 239 场景没有任何 >=10% 回退或 <=-10% 改善，最大绝对波动仅 IMAGE_TILED_QOI_565_8 -0.325%
基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 全部 +0.0%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 应记为 2，4 只保留为历史默认/外部 A/B 对比值，不再视为 HelloPerformance 的 active app-side override。

3. `EGUI_CONFIG_IMAGE_DECODE_OPAQUE_ALPHA_ROW_USE_ROW_CACHE`¶

位置： src/image/egui_image_decode_utils.h，使用处 src/image/egui_image_decode_utils.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 0。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `0`
HelloPerformance	当前随实现内固定 `0`（历史 public 实验值 `1`）
RAM 类型	heap（节省独立分配）
HP 节省	~248 B（240B data + 8B 指针）
依赖	需 `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW>=1`

机制： 带 mask 的不透明 RGB565 图绘制时需要一行”全 255 alpha”参考缓冲用于合成回退。设为 0 时单独在 heap 上分配并跨帧持久；设为 1 时直接复用已存在的 codec row cache 的 alpha 缓冲头部，省去独立的 240 B 持久堆分配。

2026-04-04 基于当前 HelloPerformance 主线重新做完整 A/B 后，结论更新为：

历史实验值 1 相比当前默认 0 为 text -132B, bss -8B
完整 239 perf 场景里没有任何 >=10% 回退或改善，最大绝对波动仅 ±0.4%
基础主路径 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 全部 +0.0%
runtime 241 帧 hash mismatch 0、pixel mismatch 0
HelloUnitTest on / off 都是 688/688 passed

因此这颗宏当前不应再写成 HelloPerformance=1 的 active override。对 HelloPerformance 而言，1 现阶段更适合作为行为等价、收益很小的历史条件实验值；当前 shipped/default 继续记为 0。由于它最多也只是在 text -132B, bss -8B 量级做取舍，远低于当前“单颗 public 宏至少要值得 >1KB code-size 回收”的门槛，这个名字已不再保留为 public 宏入口。

4. `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW`¶

位置： src/image/egui_image_qoi.c，src/image/egui_image_rle.c

补充：2026-04-06 起，EGUI_CONFIG_IMAGE_CODEC_TAIL_ROW_CACHE_MAX_COLS 已内收为实现私有固定值 0。历史把 tail cap 压到 184/176/144/96 的 A/B 没有任何 code-size 收益，反而会让当前 240px 图宽、PFB_WIDTH=48 横向 walk 下的 QOI/RLE alpha 热点出现 +45% ~ +66% 乃至数倍回退，因此不再保留 public 入口。

属性	值
默认值	`0`（关闭 codec fast-draw）
HelloPerformance	当前 shipped `1`（full row-band），历史 low-RAM 实验值 `2`（tail-row）
RAM 类型	heap（峰值减小）
HP 节省	`2` 相比 `1` 约 ~2304 B 峰值堆（QOI/RLE α 场景）

机制： EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW 现在统一承载 3 档策略：

0：关闭 codec row-cache fast path
1：启用 full row-band cache fast path
2：启用 tail-row low-RAM fast path（隐含保留 row-cache 主路径）

其中标准 row-band 模式会让第一个 PFB tile 解码全图宽的当前行带并缓存，后续水平 tile 直接读缓存；tail 模式则让第一个 PFB tile 的像素从 scratch 流式解码并渲染，只把“后续 tile 尚未用到的尾列”写入 row cache。

在 240px 宽、48px PFB 步宽的场景下，第一 tile 占 48 列，尾部 192 列进入缓存，节省首 tile 的 16×48×3 = 2304 B 峰值堆分配。

2026-04-04 基于当前主线重新做完整 A/B 后，结论可以拆成两层理解：

0 -> 1
- 会额外带来约 text +5108B
- 但如果关闭到 0，完整 239 perf 场景里会有 4 个 >=10% 回退，全部集中在 internal tiled QOI/RLE
1 -> 2
- 会再额外带来 HelloPerformance text +9976B
- 但能把 tail-row 路径重新打开，并在 240px / PFB_WIDTH=48 条件下再省下约 2304B 峰值堆
当前 shipped 1 相比历史 low-RAM 实验值 2，在完整 239 perf 场景里会有 40 个 >=10% 回退
回退全部集中在 QOI/RLE 压缩图主路径及其 masked 变体：
- IMAGE_QOI_565 +168.2%
- EXTERN_IMAGE_QOI_565 +189.9%
- IMAGE_RLE_565 +121.3%
- EXTERN_IMAGE_RLE_565 +141.3%
- MASK_IMAGE_QOI_NO_MASK +168.2%
- EXTERN_MASK_IMAGE_QOI_NO_MASK +189.9%
- MASK_IMAGE_RLE_NO_MASK +121.3%
- EXTERN_MASK_IMAGE_RLE_NO_MASK +141.3%
基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 都是 +0.0%
runtime 241 帧和 HelloUnitTest 688/688 仍保持等价

因此这颗宏现在不能再按“单一布尔开关”理解：1 是当前 HelloPerformance shipped 的 full row-band 模式，2 是历史 low-RAM tail-row 候选值；如果后续需要重新平衡 codec heap 与压缩图吞吐，这仍是优先级很高的一颗重评估宏。

5. `EGUI_CONFIG_IMAGE_QOI_INDEX_RGB565_CACHE_ENABLE`¶

位置： src/image/egui_image_qoi.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 1。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `1`（预转换缓存）
HelloPerformance	当前随实现内固定 `1`（历史 public 实验值 `0`）
RAM 类型	heap（QOI decode state 内部）
HP 节省	~128 B / 每个活跃解码实例

机制： QOI 解码器维护 64 个历史色彩槽（RGBA index，256 B）。启用时额外维护对应的 RGB565 预转换版本（128 B），INDEX 操作命中时无需重新做 RGB888→RGB565 转换；禁用时节省 128 B heap，每次 INDEX 命中时实时计算颜色转换（代价极小）。

2026-04-04 基于当前 HelloPerformance 主线重新做完整 A/B 后，结论更新为：

关闭后 HelloPerformance text 2055380 -> 2055316，只回收 text -64B，最终 ELF bss 不变
完整 239 perf 场景里没有任何 >=10% 回退或改善
基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 全部 +0.0%
最大绝对波动仍在噪声内，集中在 QOI 路径：
- IMAGE_QOI_565 +2.8%
- MASK_IMAGE_QOI_NO_MASK +2.8%
- MASK_IMAGE_QOI_ROUND_RECT +2.7%
- MASK_IMAGE_QOI_CIRCLE +2.6%
- EXTERN_MASK_IMAGE_QOI_IMAGE -1.7%
- EXTERN_IMAGE_QOI_565 -1.2%
- EXTERN_MASK_IMAGE_QOI_NO_MASK -1.2%
runtime 241 帧和 HelloUnitTest 688/688 仍保持等价

因此这颗宏当前默认继续保持 1。但它的收益也只有每个活动 QOI decode 实例 ~128B heap，同时关闭后只能回收 text -64B，远低于当前“单颗 public 宏至少要值得 >1KB code-size 回收”的门槛；所以这个名字已不再保留为 public 宏入口，只保留历史 A/B 记录。

6. `EGUI_CONFIG_IMAGE_QOI_COMPACT_RGB565_INDEX_ENABLE`¶

位置： src/image/egui_image_qoi.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为 src/image/egui_image_qoi.c 里的实现私有常量，默认行为固定为 0。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `0`
HelloPerformance	当前随实现内固定 `0`（历史 public 实验值 `1`）
RAM 类型	heap（QOI decode state）
HP 节省	~192 B / 每个活跃解码实例

机制： 将 QOI 的 64 项颜色索引表从标准 uint32_t index_rgba[64]（256 B）替换为紧凑版 uint16_t index_rgb565[64] + uint8_t index_aux[64]（共 192 B）。专为纯 RGB565 图源设计，辅助字节存放 alpha 或速度偏置信息，重建 RGB888 时从 RGB565 规范扩展推算，与 RGB565_CACHE=0 联用。

对比当前默认（compact=0, rgb565_cache=1）的 404 B，compact 配置只占 212 B，净省 192 B。

2026-04-04 基于当前 HelloPerformance 主线重新做完整 A/B 后，结论已经更新：

开启后 HelloPerformance text +780B
完整 239 perf 场景里有 10 个 >=10% 回退，全部集中在 QOI RGB565 主路径
- IMAGE_QOI_565 +52.2%
- EXTERN_IMAGE_QOI_565 +19.3%
- MASK_IMAGE_QOI_NO_MASK +52.2%
- EXTERN_MASK_IMAGE_QOI_NO_MASK +19.3%
runtime 241 帧和 HelloUnitTest 688/688 仍保持等价

因此这颗宏当前默认继续保持 0。但它的收益只有每个活动实例 ~192B heap，同时开启还会带来 text +780B 并在当前主线稳定打穿 QOI RGB565 主路径，远低于当前“单颗 public 宏至少要值得 >1KB code-size 回收”的门槛；所以这个名字已不再保留为 public 宏入口，只保留历史 A/B 记录。

7. `EGUI_CONFIG_IMAGE_QOI_ROW_INDEX_8BIT_ENABLE`¶

位置： src/image/egui_image_qoi.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 0。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `0`（uint16_t，支持 ≤65535 行）
HelloPerformance	当前随实现内固定 `0`（历史 public 实验值 `1`，uint8_t，限 ≤255 行）
RAM 类型	heap（decode state 内字段）
HP 节省	历史 `1` 可回收 ~2~4 B / 每个解码实例

机制： QOI 解码状态结构体中 current_row（行游标）的整数宽度。降至 uint8_t 要求图片高度不超过 255 行。HelloPerformance 的 QOI 资源最高 240 行，满足条件。

2026-04-05 按当前主线完成 0 -> 1 全量 A/B 后，结果为：

size：text 2055380 -> 2055392，即 text +12B，bss 不变
perf：完整 239 场景没有任何 >=10% 回退或 <=-10% 改善，最大绝对波动仅 IMAGE_TILED_QOI_565_0 +0.551%
QOI 主路径也都在噪声内：IMAGE_QOI_565 +0.016%、EXTERN_IMAGE_QOI_565 -0.006%、IMAGE_QOI_565_8 -0.047%、EXTERN_IMAGE_QOI_565_8 -0.074%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 继续记为 0；1 只保留为历史低 RAM 对比值，不再作为 HelloPerformance 的 active app-side override。由于收益只到每个解码实例 ~2~4B heap 级别，同时完全拿不到 code-size 收益，这个名字已不再保留为 public 宏入口。

二、外部资源行缓存共享宏¶

这组宏协同工作，通过逐步合并/复用缓冲区来减少 RAM 占用。

注意： 原宏 EGUI_CONFIG_IMAGE_EXTERNAL_ROW_CACHE_SHARE_BUFFERS（宏8）和 EGUI_CONFIG_IMAGE_EXTERNAL_SHARED_CACHE_USE_CODEC_ROW_CACHE（宏9）已被移除。

共享模式现在强制启用，std/transform/rle 三路共用一份后备存储，通过 generation 计数自动失效旧缓存。

后备存储改为 heap 动态分配（首次使用时分配），未使用外部资源时 RAM 占用为 0。

不再需要用户判断 std 和 codec 场景是否混用。

8. `EGUI_CONFIG_IMAGE_STD_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE`¶

位置： src/image/egui_image_std.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 1。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `1`
HelloPerformance	当前随实现内固定 `1`（历史 public 实验值 `0`）
RAM 类型	BSS
HP 节省	历史 `0` 可回收 ~40~48 B BSS

机制： 外部 std 图像行块缓存的元数据（chunk 起始行、行数、行字节数、图片指针等）是否存放在全局 BSS。设为 1 跨 tile 保留行位置信息，减少 semihosting I/O 次数；设为 0 元数据转为调用栈局部变量，BSS 消去，代价是每次 draw 调用重建（HP 场景影响不大）。

2026-04-05 按当前主线完成 1 -> 0 全量 A/B 后，结果为：

size：text 2055380 -> 2055400，即 text +20B，bss 3832 -> 3792
perf：完整 239 场景没有任何 >=10% 回退或 <=-10% 改善，最大绝对波动仅 EXTERN_IMAGE_RESIZE_TILED_565_0 +2.467%
基础主路径保持在噪声内：RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT 全部 +0.0%，IMAGE_565 +1.674%、EXTERN_IMAGE_565 +0.959%、IMAGE_RESIZE_565 +0.0%、EXTERN_IMAGE_RESIZE_565 +0.789%
external codec 热点也保持稳定：EXTERN_IMAGE_QOI_565 +0.0%、EXTERN_IMAGE_RLE_565 +0.0%、EXTERN_MASK_IMAGE_QOI_IMAGE -0.03%、EXTERN_MASK_IMAGE_RLE_IMAGE +0.0%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 继续记为 1；0 只保留为低优先级 low-RAM 条件实验值，不再作为 HelloPerformance 的 active app-side override。由于它只是在 text +20B / bss -40B 量级上做取舍，这个名字已不再保留为 public 宏入口。

9. `EGUI_CONFIG_IMAGE_TRANSFORM_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE`¶

位置： src/canvas/egui_canvas_transform.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 1。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `1`
HelloPerformance	当前随实现内固定 `1`（历史 public 实验值 `0`）
RAM 类型	BSS
HP 节省	历史 `0` 可回收 ~56~80 B BSS

机制： 与宏 8 对称，负责 transform（rotate/scale）路径的外部图片行缓存元数据。默认两个全局 slot 各持行块状态；设为 0 后 slot 嵌入各 draw 调用的栈局部 image_transform_external_source_t，BSS 释放。

2026-04-05 按当前主线完成 1 -> 0 全量 A/B 后，结果为：

size：text 2055380 -> 2055356，即 text -24B，bss 3832 -> 3776
perf：完整 239 场景没有任何 >=10% 回退或 <=-10% 改善，最大绝对波动仅 EXTERN_IMAGE_ROTATE_565_1 -1.316%
基础主路径保持在噪声内：RECTANGLE +0.0%、CIRCLE -0.123%、ROUND_RECTANGLE +0.0%、TEXT -0.097%、IMAGE_565 +0.0%、EXTERN_IMAGE_565 +0.0%、IMAGE_RESIZE_565 +0.0%、EXTERN_IMAGE_RESIZE_565 +0.0%
transform/rotate 侧也保持稳定：IMAGE_ROTATE_565 +0.429%、IMAGE_ROTATE_565_8 +0.358%、IMAGE_ROTATE_TILED_565_0 +0.791%、EXTERN_IMAGE_ROTATE_TILED_565_0 +0.360%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 继续记为 1；0 只保留为低优先级 low-RAM 条件实验值，不再作为 HelloPerformance 的 active app-side override。由于它的收益也只有 text -24B / bss -56B 这一档，这个名字已不再保留为 public 宏入口。

三、RLE 外部资源 I/O 窗口宏¶

10. `EGUI_CONFIG_IMAGE_RLE_EXTERNAL_CACHE_WINDOW_SIZE`¶

位置： src/image/egui_image_rle.c

属性	值
默认值	`1024`
HelloPerformance	当前默认 `1024`（历史实验值 `64`）
RAM 类型	BSS 或 transient frame heap（取决于宏11）
HP 节省	~960 B（当前实测 `bss -1024B`）

机制： RLE 外部资源解码时，控制字节（操作码+长度字段）具有强局部性，缓存 WINDOW_SIZE 字节可大量减少 semihosting I/O 调用。像素字面量行（240px × 2B = 480 B）超过窗口大小时自动走直接 load，正确性不受影响。历史上 HelloPerformance 曾把它缩到 64B，用于 low-RAM 外部 RLE 实验。

2026-04-04 基于当前 HelloPerformance 主线重新做完整 A/B 后，结论更新为：

1024 -> 64 后 HelloPerformance text 2055380 -> 2055476，同时 bss 3832 -> 2808
即缩小窗口会带来 text +96B，但能回收 bss -1024B
完整 239 perf 场景里有 5 个 >=10% 回退，全部集中在 external RLE 主路径及其 masked 变体：
- EXTERN_IMAGE_RLE_565 +21.8%
- EXTERN_MASK_IMAGE_RLE_NO_MASK +21.8%
- EXTERN_MASK_IMAGE_RLE_ROUND_RECT +20.8%
- EXTERN_MASK_IMAGE_RLE_CIRCLE +20.3%
- EXTERN_MASK_IMAGE_RLE_IMAGE +17.5%
EXTERN_IMAGE_RLE_565_8 / EXTERN_MASK_IMAGE_RLE_8_* 也有 +8.1% ~ +9.4% 的稳定回退
基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 全部 +0.0%
runtime 241 帧 hash mismatch 0、pixel mismatch 0
HelloUnitTest on / off 仍是 688/688 passed

因此这颗宏当前适合保留为 low-RAM 条件实验宏，但不适合作为 HelloPerformance shipped 默认值。若项目明确不关心 external RLE 热点，64 仍然是能稳定回收约 1KB BSS 的选项。

注：当前实现下，宏 10 与宏 11 的组合不再把 external RLE window 放到 draw 调用栈上；关闭 persistent cache 时，window 会改走 transient frame heap。

11. `EGUI_CONFIG_IMAGE_RLE_EXTERNAL_WINDOW_PERSISTENT_CACHE_ENABLE`（已内收）¶

位置： src/image/egui_image_rle.c

属性	值
默认值	`1`（persistent BSS）
HelloPerformance	当前实现内固定 `1`（历史 public 实验值 `0`）
RAM 类型	BSS -> transient frame heap
HP 实测	`bss -1040B`，`text +816B`（默认 `WINDOW_SIZE=1024`）

机制： 控制 external RLE read window 是否常驻在全局 BSS。设为 0 后，当前实现会把 window 本体改成每帧复用的 transient heap buffer，并在 egui_image_rle_release_frame_cache() 里释放，不再把整块 window 放到 draw 调用栈上。

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收到 src/image/egui_image_rle.c 的实现私有常量，默认行为固定为 1。下面保留的是历史 A/B 记录，用来说明为什么它不再值得继续保留成公共宏。

先纠正当前 shipped 关系：

框架默认值是 1
HelloPerformance 当前 shipped 配置也直接继承这个默认值
历史实验值 0 现在只保留为旧 A/B 记录，不再是当前 app-side override

2026-04-05 基于当前 HelloPerformance 主线重新做完整 A/B 后，结论更新为：

1 -> 0 后 HelloPerformance text 2055380 -> 2056196，bss 3832 -> 2792
即关闭 persistent cache 会带来 text +816B，但能回收 bss -1040B
完整 239 perf 场景里没有任何 >=10% 回退或改善，最大绝对波动是 IMAGE_TILED_RLE_565_0 +6.18%
基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 都在噪声内
internal IMAGE_RLE_565 / IMAGE_RLE_565_8 / MASK_IMAGE_RLE_* 基本都在 +0.4% 内
IMAGE_TILED_RLE_565_0 +6.2%、IMAGE_TILED_RLE_565_8 +2.8%
external EXTERN_IMAGE_RLE_565 / EXTERN_MASK_IMAGE_RLE_NO_MASK +5.1%
EXTERN_MASK_IMAGE_RLE_ROUND_RECT +4.8%、EXTERN_MASK_IMAGE_RLE_CIRCLE +4.7%
EXTERN_MASK_IMAGE_RLE_IMAGE +3.7%
EXTERN_IMAGE_RLE_565_8 / EXTERN_MASK_IMAGE_RLE_8_NO_MASK +3.1%
EXTERN_MASK_IMAGE_RLE_8_ROUND_RECT +2.8%、EXTERN_MASK_IMAGE_RLE_8_CIRCLE +2.7%、EXTERN_MASK_IMAGE_RLE_8_IMAGE +2.7%
runtime 241 帧 hash mismatch 0、pixel mismatch 0
HelloUnitTest on / off 仍是 688/688 passed

结论：这颗宏当前已从 public 配置面内收，默认 shipped 行为仍固定为 1。历史实验值 0 虽然能把 external RLE window 从 persistent BSS 切到 transient frame heap，并回收 bss -1040B，但会带来 text +816B，且 tiled / external RLE 仍有 +2.7% ~ +6.2% 的局部回退，因此现在只保留历史 A/B 记录。它与宏 10 的历史联动关系仍然成立：宏 10 决定 window 大小，宏 11 决定这块 window 历史上走 persistent BSS 还是 transient frame heap。

四、字体缓存宏¶

12. `EGUI_CONFIG_FONT_STD_CODE_LOOKUP_CACHE_ASCII_COMPACT`¶

位置： src/font/egui_font_std.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 0。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `0`（uint16_t/uint32_t 字段）
HelloPerformance	当前随实现内固定 `0`；历史 public 实验值为 `1`（uint8_t 紧凑）
RAM 类型	data（静态缓存槽位）
HP 节省	历史 `1` 可回收约 ~20 B 静态缓存槽位

机制： 字体 code lookup 加速缓存（g_font_std_code_lookup_cache），记录上次命中的 ASCII 码及其字形表下标，加速有序 code 数组的二分查找。Compact 模式将内部字段压缩为 uint8_t，适用于纯 ASCII（code ≤ 255）字体，每 slot 从约 32 B 压缩到约 12 B。

2026-04-05 按当前主线完成 0 -> 1 全量 A/B 后，结果为：

size：text 2055380 -> 2055580、data 72 -> 52、bss 不变
即历史 1 虽然回收了 data -20B，但同时带来 text +200B
perf：完整 239 场景没有任何 >=10% 回退或 <=-10% 改善，最大绝对波动仅 TEXT_GRADIENT +1.293%
文本主路径也都在噪声内：TEXT +0.0%、EXTERN_TEXT +0.0%、TEXT_ROTATE +0.0%、EXTERN_TEXT_ROTATE +0.0%、TEXT_RECT +0.570%、EXTERN_TEXT_RECT +0.524%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 继续记为 0；1 只保留为历史低 RAM 对比值。由于它的实际收益只有 data -20B，同时还会引入 text +200B，这个名字已不再保留为 public 宏入口。

13. `EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW`¶

位置： src/font/egui_font_std.c

属性	值
默认值	当前默认 `1`（完整 std-font fast draw，含 ASCII 直查表）
HelloPerformance	当前直接继承默认 `1`
RAM 类型	heap + BSS（指针）
HP 节省	当前只保留 `0/1` 开关；历史分层的 `1 -> 2` 成本为 `text +1056B`、`268B` 运行期 heap

机制： EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW 现在是布尔开关：

0：关闭 std-font fast draw 以及其下的字体 fast/cache 路径
1：启用完整 std-font fast draw，包括 ASCII 直查表

同时它也是字体 fast/cache 路径的总门控：code lookup cache、text transform prepare/layout cache、text transform size cache 以及 draw-prefix cache 都只在 EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW>=1 时才会实际编译生效。历史上的 code lookup / transform size 独立子开关已内收，不再作为 public 配置入口暴露。

ASCII 直查表会首次按需分配并跨帧复用，将 ASCII 字形查找从 O(log n) 降至 O(1)。历史上它曾作为 2 档独立启用，但该分层收益不大，当前已合并到 1，避免继续暴露过细的宏配置。

2026-04-25 按当前主线完成 1 -> 2 size/RAM 复测后，结果为：

size（HelloPerformance PORT=qemu CPU_ARCH=cortex-m0plus）：text 2293776 -> 2294832，data 2080 -> 2080，bss 7632 -> 7632
即 2 会带来 text +1056B；静态 data/bss 在该镜像中不变
runtime RAM：sizeof(egui_font_std_ascii_lookup_cache_t)=268B，按需 heap 分配，另有 allocator overhead；egui_core_t 理论上增加 4B，但当前链接 BSS 总量因对齐未增加
结论：虽然总增量略高于 1KB，但分层收益不足以抵消配置复杂度，当前已合并为 0/1 布尔开关

2026-04-05 历史 perf A/B 结果为：

perf：完整 239 场景没有任何 >=10% 回退，并有 3 个 <=-10% 改善
主要改善集中在文本路径：
- TEXT_GRADIENT -11.638%
- TEXT_RECT -11.597%
- TEXT_ROTATE_NONE -11.238%
- 其余文本主路径也稳定改善或持平：EXTERN_TEXT_RECT -5.628%、TEXT -0.974%、EXTERN_TEXT -0.376%、TEXT_ROTATE -0.041%、EXTERN_TEXT_ROTATE -0.076%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 记为 1；历史 2 的能力已并入 1，不再保留第二个 value。

14. `EGUI_CONFIG_FONT_STD_ASCII_LOOKUP_INDEX_8BIT`¶

位置： src/font/egui_font_std.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 0。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `0`（uint16_t）
HelloPerformance	当前随实现内固定 `0`；历史 public 实验值为 `1`（uint8_t）
RAM 类型	heap（ASCII cache 内部）
HP 节省	历史 `1` 理论上可回收约 ~128 B heap（需同时开启 ASCII cache）

机制： ASCII 直查表 ascii_index[128] 内部元素类型。0 使用 uint16_t，1 使用 uint8_t。只有在 EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW=1 时，这颗宏才会影响实际 heap 占用；它不改变查找逻辑，只影响缓存表元素宽度。

2026-04-05 按当前主线完成 0 -> 1 全量 A/B 后，结果为：

size：text/data/bss 全部不变，仍为 2055380 / 72 / 3832
perf：完整 239 场景没有任何 >=10% 回退或 <=-10% 改善；当前结果逐项完全重合，基础 TEXT / EXTERN_TEXT / TEXT_ROTATE / EXTERN_TEXT_ROTATE / TEXT_RECT / EXTERN_TEXT_RECT 全部 +0.0%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 继续记为 0；1 只保留为历史低 RAM 对比值。当前四项验证只能证明它对静态 size、perf、渲染结果和单测都无差异；若要重新评估它的现实收益，需单独补运行期 heap 量化。由于现有证据还不足以证明它值得保留为当前 public 宏，这个名字已内收到实现内部。

15. `EGUI_CONFIG_FONT_STD_LINE_CACHE_ENABLE`¶

位置： src/font/egui_font_std.c

2026-04-06 起，这个名字不再是当前框架 public 配置入口；当前主线已把它内收为实现私有常量，默认行为固定为 0。下面保留的是历史 A/B 记录，便于说明为什么它不再值得暴露成公共宏。

属性	值
默认值	当前实现内固定 `0`
HelloPerformance	当前随实现内固定 `0`；历史 public 实验值为 `1`
RAM 类型	heap + BSS
HP 节省	当前默认 `0` 相比历史 `1` 约节省 ~164 B heap

机制： 多行文本行分割缓存，避免每次 get_str_size 或绘制时重新扫描 \n。结构体中含 lines[MAX_LINES] 指针数组，缓存最近 SLOTS 个字符串的分割结果。当前默认 0 不保留这块运行期 line cache；历史实验值 1 会多占一小块 heap，并换取文本矩形/分行路径的一点吞吐收益。

2026-04-05 按当前主线完成 0 -> 1 全量 A/B 后，结果为：

size：text 2055380 -> 2055868，data/bss 不变
即历史 1 会带来 text +488B
perf：完整 239 场景没有任何 >=10% 回退，也没有任何 <=-10% 改善
主要波动集中在文本矩形路径，仍低于 10% 阈值：
- TEXT_ROTATE_NONE +5.714%
- TEXT_RECT +5.703%
- EXTERN_TEXT_RECT +3.927%
- TEXT_RECT_GRADIENT +3.811%
- 其余文本主路径基本持平：TEXT -0.097%、EXTERN_TEXT +0.0%、TEXT_ROTATE +0.0%、EXTERN_TEXT_ROTATE +0.0%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前 shipped/default 应记为 0；历史 1 不是 active app-side override，而是一个“多付 text +488B 和约 164B line-cache heap，换文本矩形/换行路径少量收益”的对比值。由于 code-size 收益没有达到保留 public 宏的门槛，这个名字已不再作为当前配置入口。

16 + 17. `EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_MAX_GLYPHS` / `EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_SLOTS`¶

位置： src/font/egui_font_std.c

属性	值
默认值	当前默认 MAX_GLYPHS=`0`，SLOTS=`0`
HelloPerformance	当前直接继承默认 `0 / 0`（历史实验值 `64 / 2`）
RAM 类型	BSS
HP 节省	当前默认 `0 / 0` 相比历史 `64 / 2` 约节省 ~2616 B BSS

机制： Draw-prefix cache 缓存每行文字的字形布局元数据（每个字符的 x 坐标、bitmap box、advance、字形下标等）。当同一字符串在多帧多处重复绘制时，跳过字符串扫描和字形 lookup，直接复用缓存位置信息渲染像素，是常规 UI 场景（label/title 等静态文字）的主要加速手段。

当前主线 shipped/default 已经把这组缓存整体下调到 0 / 0，不再保留 draw-prefix cache。历史实验值 64 / 2 对应的当前主线 A/B 结果为：

size：text 2055380 -> 2057196，data 72 -> 72，bss 3832 -> 6448
即历史 64 / 2 会带来 text +1816B, bss +2616B
perf：完整 239 场景里出现 2 个 >=10% 回退、4 个 <=-10% 改善
主要回退：
- TEXT +18.793%
- EXTERN_TEXT +15.681%
主要改善：
- EXTERN_TEXT_RECT -32.199%
- TEXT_GRADIENT -14.224%
- TEXT_RECT -12.357%
- TEXT_ROTATE_NONE -11.429%
基础图元仍在噪声内：RECTANGLE / CIRCLE / ROUND_RECTANGLE 都是 +0.0%
runtime / unit：HelloPerformance 两侧都是 241 frames 且 hash mismatch 0、pixel mismatch 0；HelloUnitTest 两侧都是 688/688 passed

因此当前更准确的定位是：64 / 2 不是 active app-side override，而是一组“多付 text +1816B, bss +2616B，同时重排不同文本路径开销分布”的历史性能对比值；对当前 HelloPerformance 工作负载，它不适合作为默认回开项。

任一为 0 即可禁用，两者联用确保完全关闭：

#define EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_MAX_GLYPHS 0
#define EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_SLOTS       0

五、文字旋转变换宏¶

18 + 19. `EGUI_CONFIG_TEXT_TRANSFORM_LAYOUT_PIXEL_INDEX_16BIT` / `LAYOUT_LINE_INDEX_16BIT`¶

位置： src/canvas/egui_canvas_transform.c

属性	值
默认值	`0 / 0`（关闭 16-bit layout 压缩）
HelloPerformance	当前默认 `0 / 0`（历史实验值 `1 / 1`）
RAM 类型	heap（transient，每帧分配释放）
HP 节省	每颗宏约 `~2N B`（N = 字形数，transient）

机制： Text transform 先将所有字形的像素偏移和行索引打包到 heap layout 数组，再按 PFB tile 顺序渲染。这两个宏将数组元素从 32-bit 降为 16-bit，分别限制最大像素偏移（≤ 65535 B）和最大字形索引（≤ 65535）。对短 benchmark 字符串（≤ 255 字形）和 26pt 以下字体完全够用。layout 数组是 transient heap（每帧分配、每帧释放），短字符串下节省约数十 B。

2026-04-04 基于当前 HelloPerformance 主线重新做完整 A/B 后，这组宏的 shipped/default 关系已明确更新为：

当前 shipped 不是历史上的 1 / 1，而是直接继承框架默认 0 / 0
1 / 1 只保留在 example/HelloPerformance/app_egui_config.h 尾部 #if 0 的可选 low-RAM 块里

其中 EGUI_CONFIG_TEXT_TRANSFORM_LAYOUT_PIXEL_INDEX_16BIT 本轮已经完成定向复测，结论为：

开启后 HelloPerformance text 2055380 -> 2055376，仅回收 text -4B，bss 不变
完整 239 perf 场景里没有任何 >=10% 回退或改善，最大绝对波动约 0.75%
TEXT_ROTATE_GRADIENT / EXTERN_TEXT_ROTATE 与基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 都在噪声内
runtime 241 帧和 HelloUnitTest 688/688 仍保持等价

EGUI_CONFIG_TEXT_TRANSFORM_LAYOUT_LINE_INDEX_16BIT 本轮也已完成定向复测，结论为：

开启后 HelloPerformance text 2055380 -> 2055480，反而 text +100B，bss 不变
完整 239 perf 场景里同样没有任何 >=10% 回退或改善，最大绝对波动约 1.71%，来自 TEXT_ROTATE_QUARTER
基础 RECTANGLE / CIRCLE / ROUND_RECTANGLE / TEXT / IMAGE_565 / EXTERN_IMAGE_565 / IMAGE_RESIZE_565 / EXTERN_IMAGE_RESIZE_565 仍是 +0.0%
TEXT_ROTATE -0.041%、TEXT_ROTATE_GRADIENT -0.039%、EXTERN_TEXT_ROTATE +0.0%
runtime 241 帧和 HelloUnitTest 688/688 仍保持等价

因此当前更合理的定位是：这两颗宏继续保留为可选 low-RAM transient-heap 实验值，而不是 HelloPerformance 的默认 shipped 配置。

20. `EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW`（prepare/layout 子能力）¶

位置： src/canvas/egui_canvas_transform.c

属性	值
默认值	默认跟随 `EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW`
HelloPerformance	`1`（同默认，已保留）
RAM 类型	BSS
大小	~60 B BSS

机制： 预计算 text transform 的逆仿射矩阵（sin/cos × scale 混合）及旋转后包围盒，一帧内多个 PFB tile 渲染同一段文字只计算一次，其余 tile 直接复用。该子能力现在直接由 EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW 门控；默认值跟随 EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW，且不能在 std-font fast draw 关闭时单独启用。禁用后每 tile 均需重新执行三角函数和矩阵求逆，当前 rotated-text 场景会出现稳定回归，60 B BSS 换取的性价比仍然很高，HelloPerformance 选择保留。

21. `EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW`（dim cache 子能力）¶

位置： src/canvas/egui_canvas_transform.c

属性	值
默认值	默认跟随 `EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW`
HelloPerformance	`1`（同默认，已保留）
RAM 类型	BSS（static 局部变量，本质 BSS）
大小	12 B BSS

机制： egui_canvas_draw_string_transform() 内记录上一次调用时的 (font, string) 对及对应的宽高结果（4 个字段，共 12 B 量级）。同一帧内多个 tile 渲染同一字符串时，跳过 get_str_size 遍历。历史上的独立 transform size cache 子开关已删除，该 size cache 现在同样直接挂在 EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW 下。12 B BSS，性价比极高，HelloPerformance 保留。

汇总参考表¶

#	宏名（省略通用前缀）	默认值	HP 设定	类型	HP 节省估算
1	`EGUI_CONFIG_IMAGE_STD_ALPHA_OPAQUE_CACHE_SLOTS`	当前实现内固定 4（历史 public 实验 0）	当前随实现内固定 4	BSS	~33 B（当前关闭仅回收 `text -156B, bss -40B`，且仍有 `8` 帧像素差，现已内化）
2	`EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE`	当前默认 2（历史默认 4）	当前默认 2（历史对比 4）	heap峰值	相比历史 `4` 约 ~7680 B（当前 `2 -> 4` 仅 `text +108B`，perf/runtime/unit 等价）
3	`EGUI_CONFIG_IMAGE_DECODE_OPAQUE_ALPHA_ROW_USE_ROW_CACHE`	当前实现内固定 0（历史 public 实验 1）	当前随实现内固定 0	heap+BSS	~248 B（当前 `1` 仅额外拿到 `text -132B, bss -8B`，perf/runtime/unit 等价，现已内化）
4	`EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW`	0	当前 shipped 1（历史 low-RAM 2）	heap峰值	`1` 避免 internal tiled `QOI/RLE` 灾难性回退；`2` 相比 `1` 再省约 ~2304 B，但需额外 `text +9976B`
5	`EGUI_CONFIG_IMAGE_QOI_INDEX_RGB565_CACHE_ENABLE`	当前实现内固定 1（历史 public 实验 0）	当前随实现内固定 1	heap	~128 B（当前关闭只回收 `text -64B`，现已内化）
6	`EGUI_CONFIG_IMAGE_QOI_COMPACT_RGB565_INDEX_ENABLE`	当前实现内固定 0（历史 public 实验 1）	当前随实现内固定 0	heap	~192 B（历史 `1` 会带来 `text +780B` 且有 `10` 个 `>=10%` QOI 主路径回退，现已内化）
7	`EGUI_CONFIG_IMAGE_QOI_ROW_INDEX_8BIT_ENABLE`	当前实现内固定 0（历史 public 实验 1）	当前随实现内固定 0	heap	历史 `1` 可回收 ~2~4 B / 解码实例（当前 `0 -> 1` 仅 `text +12B`，perf/runtime/unit 等价，现已内化）
~~8~~	~~`EGUI_CONFIG_IMAGE_EXTERNAL_ROW_CACHE_SHARE_BUFFERS`~~	—	—	—	已移除，强制共享+heap
~~9~~	~~`EGUI_CONFIG_IMAGE_EXTERNAL_SHARED_CACHE_USE_CODEC_ROW_CACHE`~~	—	—	—	已移除
8	`EGUI_CONFIG_IMAGE_STD_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE`	当前实现内固定 1（历史 public 实验 0）	当前随实现内固定 1	BSS	历史 `0` 可回收 `bss -40B`（代价 `text +20B`，当前 perf/runtime/unit 等价，现已内化）
9	`EGUI_CONFIG_IMAGE_TRANSFORM_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE`	当前实现内固定 1（历史 public 实验 0）	当前随实现内固定 1	BSS	历史 `0` 可回收 `text -24B, bss -56B`（当前 perf/runtime/unit 等价，现已内化）
10	`EGUI_CONFIG_IMAGE_RLE_EXTERNAL_CACHE_WINDOW_SIZE`	1024	当前默认 1024（历史实验 64）	BSS/frame heap	~960 B（当前 `64` 可回收 `bss -1024B`，但 external RLE 场景回退 `+17.5% ~ +21.8%`）
11	`EGUI_CONFIG_IMAGE_RLE_EXTERNAL_WINDOW_PERSISTENT_CACHE_ENABLE`	1	当前默认 1（历史实验 0）	BSS -> frame heap	~1040 B（当前 `0` 回收 `bss -1040B`，但 `text +816B` 且 RLE 场景约 `+2.7% ~ +6.2%`）
12	`EGUI_CONFIG_FONT_STD_CODE_LOOKUP_CACHE_ASCII_COMPACT`	当前实现内固定 0（历史 public 实验 1）	当前随实现内固定 0	data	历史 `1` 仅回收 `data -20B`，但会带来 `text +200B`；现已内化，不再保留 public 入口
13	`EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW`	当前默认 1（含历史 ASCII cache 能力）	当前默认 1	heap+BSS	当前已合并为 `0/1`；历史 `1 -> 2` 成本为 `text +1056B` 和 `268B` 运行期 heap，文本场景可见 `11%` 级改善
14	`EGUI_CONFIG_FONT_STD_ASCII_LOOKUP_INDEX_8BIT`	当前实现内固定 0（历史 public 实验 1）	当前随实现内固定 0	heap	历史 `1` 理论上可回收约 ~128 B heap†；当前静态 size/perf/runtime/unit 全等，现已内化
15	`EGUI_CONFIG_FONT_STD_LINE_CACHE_ENABLE`	当前实现内固定 0（历史 public 实验 1）	当前随实现内固定 0	heap	当前 `0` 可省约 ~164 B heap；历史 `1` 需额外付出 `text +488B`，当前 perf 仅见 `+3.8% ~ +5.7%` 级文本矩形波动，现已内化
16	`EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_MAX_GLYPHS`	当前默认 0（历史实验 64）	当前默认 0（与宏17联动）	BSS	当前 `0/0` 相比历史 `64/2` 可省 `text -1816B, bss -2616B`；但 `64/2` 同时带来 `TEXT +18.8%`、`EXTERN_TEXT +15.7%`，又改善 `TEXT_RECT / EXTERN_TEXT_RECT / TEXT_GRADIENT / TEXT_ROTATE_NONE`
17	`EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_SLOTS`	当前默认 0（历史实验 2）	当前默认 0（与宏16联动）	BSS	必须与宏16一起回开到 `64/2` 才会实际启用 draw-prefix cache
18	`EGUI_CONFIG_TEXT_TRANSFORM_LAYOUT_PIXEL_INDEX_16BIT`	0	当前默认 0（历史实验 1）	heap transient	~2N B（当前 `1` 仅 `text -4B`，perf/runtime/unit 等价）
19	`EGUI_CONFIG_TEXT_TRANSFORM_LAYOUT_LINE_INDEX_16BIT`	0	当前默认 0（历史实验 1）	heap transient	~2N B（当前 `1` 会 `text +100B`，perf/runtime/unit 等价）
20	`EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW`（prepare/layout）	默认跟随 `EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW`	1（保留）	BSS	0（已开）
21	`EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW`（dim）	默认跟随 `EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW`	1（保留）	BSS	0（已开）

† 宏 14 需搭配 EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW=1 才有实际作用；它当前已内化，列入仅为历史参考。

使用建议¶

激进低 RAM 场景（类 HelloPerformance）¶

建议优先启用那些已经验证为功能等价或可接受条件实验的项；其中宏1（alpha opaque cache）当前不再默认推荐关闭，因为 4 -> 0 虽能回收 text -156B, bss -40B，但会带来 8 帧 runtime 像素差。其余如 compress index（宏5/6）、禁用持久元数据全局 slot（宏8/9=0；宏11已内收，仅保留历史 A/B）、缩小 RLE window（宏10=64）、禁用 prefix 缓存（宏16/17=0）、把 EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW 从 1 降到 0、以及禁用 line cache（宏15=0）仍需结合对应小节单独评估。外部行缓存共享现已强制启用，heap 分配按需进行。

常规 UI 应用（label/button 等）¶

若是常规 UI 应用并且更看重静态文本吞吐，可单独评估重新开启 draw-prefix cache、line cache 这两类字体缓存；ASCII lookup cache 已随 EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW=1 默认启用。图像宏按实际 codec 支持情况配置。

注意事项¶

宏 3（OPAQUE_ALPHA_ROW_USE_ROW_CACHE）的历史行为依赖 EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW>=1；该入口现已内收到实现内部。
宏 20/21（同一颗 EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW 的 prepare/layout 与 dim 子能力）现在统一由该宏直接门控；它默认跟随 std-font fast draw，且不能绕过 std-font fast draw 单独启用。在 std-font fast draw 打开的前提下，它仍是文字旋转性能的关键，禁用会导致每 tile 重计算仿射/宽高，不建议关闭。

低 RAM 配置宏说明文档¶

一、图像解码相关宏¶

1. EGUI_CONFIG_IMAGE_STD_ALPHA_OPAQUE_CACHE_SLOTS¶

2. EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE¶

3. EGUI_CONFIG_IMAGE_DECODE_OPAQUE_ALPHA_ROW_USE_ROW_CACHE¶

4. EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW¶

5. EGUI_CONFIG_IMAGE_QOI_INDEX_RGB565_CACHE_ENABLE¶

6. EGUI_CONFIG_IMAGE_QOI_COMPACT_RGB565_INDEX_ENABLE¶

7. EGUI_CONFIG_IMAGE_QOI_ROW_INDEX_8BIT_ENABLE¶

二、外部资源行缓存共享宏¶

8. EGUI_CONFIG_IMAGE_STD_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE¶

9. EGUI_CONFIG_IMAGE_TRANSFORM_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE¶

三、RLE 外部资源 I/O 窗口宏¶

10. EGUI_CONFIG_IMAGE_RLE_EXTERNAL_CACHE_WINDOW_SIZE¶

11. EGUI_CONFIG_IMAGE_RLE_EXTERNAL_WINDOW_PERSISTENT_CACHE_ENABLE（已内收）¶

四、字体缓存宏¶

12. EGUI_CONFIG_FONT_STD_CODE_LOOKUP_CACHE_ASCII_COMPACT¶

13. EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW¶

14. EGUI_CONFIG_FONT_STD_ASCII_LOOKUP_INDEX_8BIT¶

15. EGUI_CONFIG_FONT_STD_LINE_CACHE_ENABLE¶

16 + 17. EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_MAX_GLYPHS / EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_SLOTS¶

五、文字旋转变换宏¶

18 + 19. EGUI_CONFIG_TEXT_TRANSFORM_LAYOUT_PIXEL_INDEX_16BIT / LAYOUT_LINE_INDEX_16BIT¶

20. EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW（prepare/layout 子能力）¶

21. EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW（dim cache 子能力）¶

汇总参考表¶

使用建议¶

激进低 RAM 场景（类 HelloPerformance）¶

常规 UI 应用（label/button 等）¶

注意事项¶

1. `EGUI_CONFIG_IMAGE_STD_ALPHA_OPAQUE_CACHE_SLOTS`¶

2. `EGUI_CONFIG_IMAGE_DECODE_MAX_PIXEL_SIZE`¶

3. `EGUI_CONFIG_IMAGE_DECODE_OPAQUE_ALPHA_ROW_USE_ROW_CACHE`¶

4. `EGUI_CONFIG_FUNCTION_IMAGE_CODEC_FAST_DRAW`¶

5. `EGUI_CONFIG_IMAGE_QOI_INDEX_RGB565_CACHE_ENABLE`¶

6. `EGUI_CONFIG_IMAGE_QOI_COMPACT_RGB565_INDEX_ENABLE`¶

7. `EGUI_CONFIG_IMAGE_QOI_ROW_INDEX_8BIT_ENABLE`¶

8. `EGUI_CONFIG_IMAGE_STD_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE`¶

9. `EGUI_CONFIG_IMAGE_TRANSFORM_EXTERNAL_ROW_PERSISTENT_CACHE_ENABLE`¶

10. `EGUI_CONFIG_IMAGE_RLE_EXTERNAL_CACHE_WINDOW_SIZE`¶

11. `EGUI_CONFIG_IMAGE_RLE_EXTERNAL_WINDOW_PERSISTENT_CACHE_ENABLE`（已内收）¶

12. `EGUI_CONFIG_FONT_STD_CODE_LOOKUP_CACHE_ASCII_COMPACT`¶

13. `EGUI_CONFIG_FUNCTION_FONT_STD_FAST_DRAW`¶

14. `EGUI_CONFIG_FONT_STD_ASCII_LOOKUP_INDEX_8BIT`¶

15. `EGUI_CONFIG_FONT_STD_LINE_CACHE_ENABLE`¶

16 + 17. `EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_MAX_GLYPHS` / `EGUI_CONFIG_FONT_STD_DRAW_PREFIX_CACHE_SLOTS`¶

18 + 19. `EGUI_CONFIG_TEXT_TRANSFORM_LAYOUT_PIXEL_INDEX_16BIT` / `LAYOUT_LINE_INDEX_16BIT`¶

20. `EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW`（prepare/layout 子能力）¶

21. `EGUI_CONFIG_FUNCTION_FONT_TRANSFORM_FAST_DRAW`（dim cache 子能力）¶