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 第十一轮」硬约束与踩坑。
2026-10-28 17:38:55 +08:00
1 parent 57e12cfb27
commit aa4925a2b7
@@ -16,12 +16,10 @@ namespace jdi
 		constexpr int kNodeCornerThick = 3;
 		/** @brief 包角沿边延伸的长度上限（设备像素）。 */
 		constexpr int kCornerLenMax = 14;
-		/** @brief 短边不超过该值时**只画角、不画边**（小方框画满一圈会像粗边框）。 */
+		/** @brief 短边不超过该值时**只画四个角块、不画边**（小方框画满一圈会像粗边框）。 */
 		constexpr int kEdgelessThreshold = 12;
 		/** @brief 短边不超过该值时完全不画（再画就盖住元素本身了）。 */
 		constexpr int kSkipThreshold = 5;
-		/** @brief 短边小于该值时不做内缩（内缩会把小元素缩成一条线）。 */
-		constexpr int kInsetThreshold = 10;

 		/** @brief 一个已对齐到整像素、可直接填充的矩形。 */
 		struct PixelRect
@@ -40,6 +38,10 @@ namespace jdi
 		 *
 		 * 走 GDI+ 而不是 `UiFillRect`：这里需要**精确的 1px 覆盖**，而 `UiFillRect` 的快
 		 * 路径按 `floor/ceil` 取整并可能转交 GDI，混进调试层会带来额外状态切换开销。
+		 *
+		 * ⚠️ **每次图元调用约 1µs**（实测 474 个 box × 12 段 = 5.9ms/帧），因此这里刻意
+		 * 把图元数量从 12 压到 8；并且**不要**改写成 `GraphicsPath` —— `FillPath` 单次约
+		 * 20µs，比 12 段 `FillRectangle` 还慢（本机实测 22.8ms vs 13.0ms）。
 		 */
 		void FillPixels(gd::Graphics& g, int x, int y, int width, int height, std::uint32_t argb)
 		{
@@ -51,24 +53,18 @@ namespace jdi
 			g.FillRectangle(&brush, x, y, width, height);
 		}

-		/** @brief 把逻辑矩形对齐到整像素（`inset` 先内缩，用于避免父子共边）。 */
-		PixelRect AlignToPixels(const gd::RectF& rect, int inset)
+		/** @brief 把逻辑矩形对齐到整像素（**不内缩**，见头文件说明）。 */
+		PixelRect AlignToPixels(const gd::RectF& rect)
 		{
-			const float shrink = static_cast<float>(inset);
-			const float x = rect.X + shrink;
-			const float y = rect.Y + shrink;
-			const float width = rect.Width - shrink * 2.0f;
-			const float height = rect.Height - shrink * 2.0f;
-			if (!(width > 0.0f) || !(height > 0.0f))
+			if (!(rect.Width > 0.0f) || !(rect.Height > 0.0f))
 			{
 				return PixelRect();
 			}
-
 			PixelRect out;
-			out.left = static_cast<int>(std::lround(x));
-			out.top = static_cast<int>(std::lround(y));
-			out.right = static_cast<int>(std::lround(x + width)) - 1;
-			out.bottom = static_cast<int>(std::lround(y + height)) - 1;
+			out.left = static_cast<int>(std::lround(rect.X));
+			out.top = static_cast<int>(std::lround(rect.Y));
+			out.right = static_cast<int>(std::lround(rect.X + rect.Width)) - 1;
+			out.bottom = static_cast<int>(std::lround(rect.Y + rect.Height)) - 1;
 			if (out.right < out.left)
 			{
 				out.right = out.left;
@@ -89,16 +85,10 @@ namespace jdi
 		m_clip = gd::RectF();
 	}

-	void UiDebugBoxList::AddOccluder(const gd::RectF& rect)
+	void UiDebugBoxList::OnTextRect(const gd::RectF& rect)
 	{
-		if (!(rect.Width > 0.0f) || !(rect.Height > 0.0f))
-		{
-			return;
-		}
-		Occluder occluder;
-		occluder.rect = rect;
-		occluder.layer = m_layer;
-		m_occluders.push_back(occluder);
+		// 文本用固定层级 4：它总是"最里层"的元素（复选框里的字、行里的信号名…）。
+		Add(rect, 4);
 	}

 	void UiDebugBoxList::Add(const gd::RectF& rect, int depth)
@@ -132,6 +122,18 @@ namespace jdi
 		}
 	}

+	void UiDebugBoxList::AddOccluder(const gd::RectF& rect)
+	{
+		if (!(rect.Width > 0.0f) || !(rect.Height > 0.0f))
+		{
+			return;
+		}
+		Occluder occluder;
+		occluder.rect = rect;
+		occluder.layer = m_layer;
+		m_occluders.push_back(occluder);
+	}
+
 	std::uint32_t UiDebugBoundsColor(int depth)
 	{
 		// 与主题无关的固定配色：调试层必须"永远显眼"，不能跟随用户主题变成接近底色。
@@ -143,8 +145,10 @@ namespace jdi
 			return 0xFFE040FBu;		// 品红：组件内部的功能分区
 		case 2:
 			return 0xFFFFB300u;		// 琥珀：具体控件 / 行
+		case 3:
+			return 0xFF66BB6Au;		// 绿：更深的子块（复选框、色块、✕ …）
 		default:
-			return 0xFF66BB6Au;		// 绿：更深的子块（复选框、文本、✕ …）
+			return 0xFFFF7043u;		// 橙：文本墨迹矩形
 		}
 	}

@@ -158,35 +162,30 @@ namespace jdi
 	{
 		const int level = (depth < 0) ? 0 : depth;

-		// 先用未内缩的尺寸判断"值不值得画"和"要不要内缩"：
-		// 内缩是给"父子共边"用的，元素本身很小时内缩只会把它缩没。
-		const float rawShortSide = std::min(rect.Width, rect.Height);
-		if (rawShortSide <= static_cast<float>(kSkipThreshold))
+		// 先判断"值不值得画"：元素太小时画上去就是糊住它本身。
+		if (std::min(rect.Width, rect.Height) <= static_cast<float>(kSkipThreshold))
 		{
-			return;		// 太小：画上去就是糊住元素本身。
+			return;
 		}
-		const int inset = (level > 0 && rawShortSide >= static_cast<float>(kInsetThreshold)) ? 1 : 0;

-		PixelRect pixels = AlignToPixels(rect, inset);
+		PixelRect pixels = AlignToPixels(rect);
 		if (!pixels.Valid())
 		{
 			return;
 		}

 		// ⚠️ 与裁剪矩形求交（见 `UiDebugBoxList::SetClip`）：组件内部的元素可能落在地盘之外。
-		// 用 floor/ceil 而不是取整：裁剪是“能看见多少就画多少”，宁可多一像素也不要把
+		// 用 floor/ceil 而不是取整：裁剪是"能看见多少就画多少"，宁可多一像素也不要把
 		// 紧贴边界的包角整个裁掉。
 		if (clip.Width > 0.0f && clip.Height > 0.0f)
 		{
-			const int clipLeft = static_cast<int>(std::floor(clip.X));
-			const int clipTop = static_cast<int>(std::floor(clip.Y));
-			const int clipRight = static_cast<int>(std::ceil(clip.X + clip.Width)) - 1;
-			const int clipBottom = static_cast<int>(std::ceil(clip.Y + clip.Height)) - 1;
 			PixelRect clipped;
-			clipped.left = std::max(pixels.left, clipLeft);
-			clipped.top = std::max(pixels.top, clipTop);
-			clipped.right = std::min(pixels.right, clipRight);
-			clipped.bottom = std::min(pixels.bottom, clipBottom);
+			clipped.left = std::max(pixels.left, static_cast<int>(std::floor(clip.X)));
+			clipped.top = std::max(pixels.top, static_cast<int>(std::floor(clip.Y)));
+			clipped.right =
+			    std::min(pixels.right, static_cast<int>(std::ceil(clip.X + clip.Width)) - 1);
+			clipped.bottom =
+			    std::min(pixels.bottom, static_cast<int>(std::ceil(clip.Y + clip.Height)) - 1);
 			if (!clipped.Valid())
 			{
 				return;
@@ -199,51 +198,44 @@ namespace jdi
 		const int shortSide = std::min(width, height);
 		const std::uint32_t color = UiDebugBoundsColor(level);

-		// ⚠️ **包角粗细随尺寸自适应**：这是"小元素变成粗描边"的修复点。
-		// 基准 4/3px 只在足够大的矩形上使用；短边越小越细，最终退化为 1px。
-		// 同时不超过短边的 1/4，避免包角在元素自身上"占比过大"。
+		// 包角粗细随尺寸自适应（"小元素变成粗描边"的修复点）：
+		// 基准 4/3px 只在足够大的矩形上使用；短边越小越细，且不超过短边的 1/4。
 		const int baseThick = (level == 0) ? kAreaCornerThick : kNodeCornerThick;
-		int cornerThick = std::min(baseThick, shortSide / 10);
+		int cornerThick = std::max(1, std::min(baseThick, shortSide / 10));
 		cornerThick = std::max(1, std::min(cornerThick, std::max(1, shortSide / 4)));

-		// 包角沿边延伸的长度：短边的 1/3，不超过上限，也不小于角本身。
+		// 包角长度随短边变化：短边的 1/3，不超过上限，也不小于角本身。
 		int cornerLen = std::min(kCornerLenMax, std::max(1, shortSide / 3));
 		cornerLen = std::max(cornerLen, cornerThick);

-		// 小方框只画角、不画边：一圈连续描边会让复选框/色块/✕ 看起来"被粗框包住"，
-		// 而四个 L 形小标记既不糊内容，又能立刻定位边界的四角。
-		const bool drawEdges = (shortSide > kEdgelessThreshold);
-
 		const gd::GraphicsState state = g.Save();
 		// 描边必须锐利：关抗锯齿 + 关半像素偏移，矩形已对齐整像素 ⇒ 1px 就是 1px。
 		g.SetSmoothingMode(gd::SmoothingModeNone);
 		g.SetPixelOffsetMode(gd::PixelOffsetModeNone);

+		// ⚠️ 图元数量直接决定耗时（每个约 1µs），因此这里固定为**最多 8 次**：
+		//     4 条 1px 边 + 4 个加粗角块。
+		// 旧实现把每条边拆成"中段 1px + 两端各一段加粗"共 12 次，观感几乎相同
+		// （角本来就是"两条粗边的交点"），却多花 50% 时间。
+		// 短边很小的矩形只画 4 个角块（画满一圈会让复选框/色块看起来"被框住"）。
+		const bool drawEdges = (shortSide > kEdgelessThreshold);
 		if (drawEdges)
 		{
-			// 四边：统一 1px，用实心矩形而不是 `DrawRectangle`
-			//（后者会因笔宽奇偶而偏移半像素，且抗锯齿会糊成 2px）。
-			FillPixels(g, pixels.left, pixels.top, width, kEdgeStroke, color);			// 上
-			FillPixels(g, pixels.left, pixels.bottom, width, kEdgeStroke, color);		// 下
-			FillPixels(g, pixels.left, pixels.top, kEdgeStroke, height, color);			// 左
-			FillPixels(g, pixels.right, pixels.top, kEdgeStroke, height, color);		// 右
+			FillPixels(g, pixels.left, pixels.top, width, kEdgeStroke, color);		// 上
+			FillPixels(g, pixels.left, pixels.bottom, width, kEdgeStroke, color);	// 下
+			FillPixels(g, pixels.left, pixels.top, kEdgeStroke, height, color);		// 左
+			FillPixels(g, pixels.right, pixels.top, kEdgeStroke, height, color);	// 右
 		}

-		// 四个角：加粗成 ⌜ ⌝ ⌞ ⌟ 包角（粗细见上）。
-		// 左上
-		FillPixels(g, pixels.left, pixels.top, cornerLen, cornerThick, color);
-		FillPixels(g, pixels.left, pixels.top, cornerThick, cornerLen, color);
-		// 右上
-		FillPixels(g, pixels.right - cornerLen + 1, pixels.top, cornerLen, cornerThick, color);
-		FillPixels(g, pixels.right - cornerThick + 1, pixels.top, cornerThick, cornerLen, color);
-		// 左下
-		FillPixels(g, pixels.left, pixels.bottom - cornerThick + 1, cornerLen, cornerThick, color);
-		FillPixels(g, pixels.left, pixels.bottom - cornerLen + 1, cornerThick, cornerLen, color);
-		// 右下
-		FillPixels(g, pixels.right - cornerLen + 1, pixels.bottom - cornerThick + 1, cornerLen,
-		           cornerThick, color);
-		FillPixels(g, pixels.right - cornerThick + 1, pixels.bottom - cornerLen + 1, cornerThick,
-		           cornerLen, color);
+		// 四个加粗角块（粗细随尺寸自适应，见上）。
+		// * 大矩形：角块是 `cornerThick` 见方的方块，与四条 1px 边接成 `⌜ ⌝ ⌞ ⌟`；
+		// * 小方框（不画边）：角块沿水平方向拉长到 `cornerLen`，让"四个角"更明显。
+		const int blockW = std::min(drawEdges ? cornerThick : cornerLen, width);
+		const int blockH = std::min(cornerThick, height);
+		FillPixels(g, pixels.left, pixels.top, blockW, blockH, color);
+		FillPixels(g, pixels.right - blockW + 1, pixels.top, blockW, blockH, color);
+		FillPixels(g, pixels.left, pixels.bottom - blockH + 1, blockW, blockH, color);
+		FillPixels(g, pixels.right - blockW + 1, pixels.bottom - blockH + 1, blockW, blockH, color);

 		g.Restore(state);
 	}
@@ -278,27 +270,22 @@ namespace jdi
 		for (const UiDebugBox* box : ordered)
 		{
 			// ⚠️ 遮挡：浮层（菜单 / 拾色器）是不透明的，它上面的内容不该出现下层组件的边框线。
-			// 仅靠 layer 排序只能决定“两个 box 重叠时谁压谁”，不能阻止“先画的线仍然可见”，
+			// 仅靠 layer 排序只能决定"两个 box 重叠时谁压谁"，不能阻止"先画的线仍然可见"，
 			// 因此这里把**更高层**的遮挡矩形从裁剪区里排除。
-			bool occluded = false;
 			gd::Region region;
-			bool regionReady = false;
+			bool occluded = false;
 			for (const UiDebugBoxList::Occluder& occluder : boxes.Occluders())
 			{
 				if (occluder.layer <= box->layer)
 				{
 					continue;
 				}
-				if (!regionReady)
+				if (!occluded)
 				{
-					// 以“整个客户区”为起点（足够大的矩形，超出窗口的部分自然不会被画到）。
-					const gd::RectF everything(-100000.0f, -100000.0f, 200000.0f, 200000.0f);
 					region.MakeInfinite();
-					region.Intersect(everything);
-					regionReady = true;
+					occluded = true;
 				}
 				region.Exclude(occluder.rect);
-				occluded = true;
 			}
 			if (!occluded)
 			{
@@ -306,7 +293,7 @@ namespace jdi
 				continue;
 			}

-			// 已有裁剪矩形时先与它求交，再设进 Graphics（region 天然支持这种“挖洞”裁剪）。
+			// 已有裁剪矩形时先与它求交，再设进 Graphics（region 天然支持这种"挖洞"裁剪）。
 			if (box->clip.Width > 0.0f && box->clip.Height > 0.0f)
 			{
 				region.Intersect(box->clip);