fix(UI): 边界框不再内缩 + 文本获得几何身份 + 补全漏项 + 描边提速 32%

## 1. 取消内缩(这是"边框不清晰"的主因)

第九轮为"父子矩形共边不叠粗"给 depth > 0 的 box 加了 1px 内缩。结果 GX 徽标
(30x17 逻辑像素的胶囊,圆角 = 高的一半,外接矩形正好等于 LaneBadgeRect)内缩 1px 后
框比形状小一圈 ⇒ 左右尖端与上下圆弧全部落在框外。

现行规则:**框 = 可见形状的外接矩形,绝不内缩**。父子共边时让"后画的覆盖"即可,
这本来就是正确的图层语义。层级 > 0 只影响配色,不再影响几何。

## 2. 文本第一次有了几何身份(唯一出口回报,不逐处登记)

文本是本项目唯一"没有几何身份"的元素:65 处绘制点各自现算 gd::RectF、画完即弃。
逐处补登记必漏,因此在唯一出口回报一次:

  PaintUtil 新增
    class UiTextRectSink { virtual void OnTextRect(const gd::RectF&) = 0; };
    void UiSetTextRectSink(UiTextRectSink*);       // 开关关闭时为 nullptr
    void UiSetTextRectOffset(float dx, float dy);  // 离屏位图渲染的坐标换算
    UiTextRectSink* UiGetTextRectSink();

DrawUiText() / UiTextAtClipped() 画完后按对齐方式 + 实测宽高把布局矩形**收窄成墨迹矩形**
再回报。UiDebugBoxList 直接继承该接口,宿主只需 UiSetTextRectSink(&m_debugBoxes) 一句。
开关关闭时只是一次空指针判断,正常绘制零影响。

## 3. 缓存命中的行也要有文本框

面板的行是"先画进位图再贴回",命中缓存的帧**根本不调用 UiText** ⇒ 文本框第二帧起消失。
做法:行渲染时用本地 RowTextCollector 收集(位图坐标)→ 连同位图存进
RowBitmapCache::textRects → 贴图时按 (originX, originY) 回放。
⚠️ **必须无条件收集**:只在"外层有收集器"时收集会导致"关调试时滚过列表 → 打开调试 →
命中缓存 → 永远没有文本框"。

## 4. 补齐 PlotView 漏项(全部读现成成员)

m_timeAxisRect / m_scrollBarRect / BackToTopRect() / m_cursorSpanRect /
m_cursorLabelRects / EditFieldRect()

## 5. 描边提速:图元 12 → 8

微基准结论:图元数量是唯一瓶颈(每次 FillRectangle ≈1µs)。
旧实现把每条边拆成"中段 1px + 两端各一段加粗"= 12 次;新实现 = 4 条 1px 边 + 4 个自适应角块。
实测 paintBoxes 5.892ms → 4.028ms(-32%),观感几乎一致(角仍是两条粗边的交点)。
⚠️ 不要改写成 GraphicsPath/FillPath(单次约 20µs,比 12 段还慢);
GDI PolyPolygon 一次画 5688 个矩形要 114ms,更不能用。

## 6. 关闭开关时清空容器(释放内存,避免误读)

## 7. 验证

- make release / make debug 零 error 零 warning;TargetCheck.exe 909,824 B(888.5 KiB < 900 KiB)。
- 新增探针 .preflight/lbcovr 7/7:box-time-axis / box-plot-scrollbar / box-back-to-top /
  box-gx-badge-matches-pill(容差 0.5px)/ text-boxes-collected(89 个)/
  row-text-boxes-from-cached-rows / boxes-cleared-when-off。
- 回归:lbcheck 21/21、lbresid 5/5、lbzorder 4/4、uicheck 69/69。
- rendercheck:8 个场景的整帧与区域哈希与上一轮**逐一相同** + FUNC 7/7
  (证明调试功能对正常绘制零影响)。
- 帧耗时分解(MF4 / 283 网格):base 9.06ms、仅强制整帧 6.66ms、完整调试 11.35ms;
  collect 0.082ms、paintBoxes 4.028ms(上一轮 5.892ms)。

## 8. 文档

Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md 追加第九阶段;
Documents/agent_mem.md 同步变更日志与「2026-10-28 第十一轮」硬约束与踩坑。
This commit is contained in:
DeepSeek V4.1 Flash committed 2026-10-28 17:38:55 +08:00
1 parent 57e12cfb27
commit aa4925a2b7
14 files changed
+635 -107

No files matched your search

+86
View File
@@ -509,3 +509,89 @@ lbcheck 21/21 ;uicheck 69/69 ;rendercheck 区域哈希 8/8 不变 + FUNC 7/
(调试而非日常使用),但若将来要让边界常驻,需要改为"只把叠加层位图化再贴回"。
2. 菜单项逐个画框略显拥挤,可选做"只画外框 + 悬停项高亮框"。
3. 开关状态仍未持久化。
---
# 第九阶段报告:把"边界"从补丁改成机制
## 1. 为什么上一轮只能算"打了三个补丁"
第十轮解决了三个症状(包角太粗、残留、层级),但没有触及根因。根因是:
* **框与形状不重合**(内缩)—— 这是我在第九轮为了"父子共边不叠粗"引入的**错误取舍**;
* **文本没有几何身份** —— 65 处绘制点各自现算矩形、画完即弃,任何"逐处补登记"都必漏;
* **描边图元太多** —— 12 图元/box,纯属实现细节没优化。
## 2. 取消内缩:正确的取舍是"后画的覆盖"
第九轮加内缩的理由是"父子矩形共边时两条同色线叠成更粗的一条"。但这个问题的正确解法不是
缩小子框,而是承认**图层语义**:子框后画,就由子框的颜色覆盖父框的那条边。
内缩的代价是:任何**非直角形状**(胶囊形 GX 徽标、带描边环的色块、圆角按钮)的可见边界
都在外接矩形上,内缩 1px 之后框就比形状小一圈 —— 用户看到的正是"GX 标签的圆弧在框之外"。
现行规则:**框 = 可见形状的外接矩形,绝不内缩。**
## 3. 文本:在唯一出口回报一次
```
class UiTextRectSink { virtual void OnTextRect(const gd::RectF&) = 0; };
void UiSetTextRectSink(UiTextRectSink*); // 开关关闭时为 nullptr
void UiSetTextRectOffset(float dx, float dy); // 离屏位图渲染的坐标换算
```
`DrawUiText()` / `UiTextAtClipped()` 画完后按对齐方式与实测宽度/高度把布局矩形**收窄**
成墨迹矩形再回报。于是:
* 65 处调用点**一行都不用改**;
* 每个文本框就是文字真正占据的那一小块(而不是整行);
* 开关关闭时只是一次空指针判断,正常绘制零影响(`rendercheck` 8 场景哈希逐像素不变为证)。
## 4. 缓存:文本框必须跟着位图一起缓存
面板的行是"画进位图再贴回",命中缓存的帧**根本不调用 `UiText`**。所以:
* 行渲染时用本地 `RowTextCollector` 收集(位图坐标);
* 存进 `RowBitmapCache::textRects` 与位图同生命周期;
* 贴图时按 `(originX, originY)` 回放给外层收集器;
* **无条件收集** —— 否则"关闭调试时滚过列表、再打开调试"会命中缓存而永远没有文本框。
## 5. 性能:图元数量是唯一瓶颈
微基准(同一块 1707×949 DIB,5688 段图元):
| 实现 | ms |
| --- | --- |
| GDI+ `FillRectangle` × 5688(每次新建画刷) | 13.0 |
| 复用画刷 | 12.4 |
| 每 box 一条 `GraphicsPath` + `FillPath` | 22.8 |
| 全部 box 合并成一条 path | 8.4 |
| **每 box 只画 1 个矩形**(474 次) | **0.70** |
| GDI `PolyPolygon` 一次调用 | 114 |
结论:瓶颈是**调用次数**(≈1µs/次),合并路径反而更慢。因此把 12 → **8**:
4 条 1px 边 + 4 个自适应角块。实测 `paintBoxes` **5.892 → 4.028ms(−32%)**。
## 6. 覆盖率
`PlotView` 补齐 6 类(时间轴 / 网格滚动条 / 回到最上方 / 光标差值标签 / 光标读数标签 / 内联输入框),
全部读现成成员。新增探针 `.preflight/lbcovr` 用"已知矩形 vs 收集到的 box"逐条比对,
把"有没有漏项"变成可回归的断言 —— 这比肉眼看图可靠。
## 7. 数据
```
四个探针:lbcovr 7/7 · lbcheck 21/21 · lbresid 5/5 · lbzorder 4/4 · uicheck 69/69
rendercheck:整帧与区域哈希与上一轮逐一相同,FUNC 7/7
TargetCheck.exe:909,824 B(888.5 KiB)
帧耗时(MF4 / 283 网格):base 9.06 / 仅强制整帧 6.66 / 完整调试 11.35 (collect 0.082 + paint 4.028)
```
## 8. 遗留
1. 调试模式仍依赖"强制整幅重绘"(`SetForceFullRepaint`);根治需要让快路径支持
"重画指定矩形集合"。另外实测**基线本身**每帧在 `WarmLaneLayersStep()` 上花约 2.4ms
(9.06 vs 6.66),这是与本功能无关的既有开销,值得单独治。
2. 文本墨迹矩形是"字符单元"高度,不含下伸部(descender)的差异;对除 `g/y/p` 多的文本
会略微偏扁,属可接受近似。
3. `PlotView` 的坐标轴刻度带仍未单独上报(只上报整条 `m_timeAxisRect`)。