RGF 矩形运算工具类 RectUtils 实战指南:相交、并肩、合并、差集与外接矩形全解析
RGF 矩形运算工具类 RectUtils 实战指南:相交、并肩、合并、差集与外接矩形全解析
导读
RectUtils 是 RGF(仓颉 Windows 通用渲染框架)rgf.rgf_utils 工具包中面向矩形几何运算的静态工具类,为开发者提供相交判定、并肩判定、矩形合并、区域差集、外接矩形计算与点在矩形内判定等高频 2D 几何能力。本文从 RectUtils.md 的完整 API 出发,结合 rect.cj 的源码实现与 rgf_struct.cj 中 Rect/FRect 的数据结构定义,逐一讲解每个方法的签名、参数、返回值与底层算法,并给出可直接落地的应用场景,帮助你在窗口布局、碰撞检测、区域裁剪、脏矩形刷新等开发场景中熟练使用这套工具。
一、RectUtils 在 RGF 中的定位
在 RGF 的包结构中,rgf.rgf_utils 属于通用工具包,除 RectUtils 外还包含色彩插值工具类 ColorUtils、定时器 RTimer、安全接管泛型类 Safe<T> 与缓动函数计算类 Tween,包内 API 总览见 rgf.rgf_utils 包说明。
RectUtils 的核心特征有三点:
- 纯静态工具类:类声明为
public class RectUtils,构造函数被private init(){}私有化,所有方法均为public static,使用时不需实例化,直接以RectUtils.方法名(...)调用。 - 双精度体系重载:所有方法同时提供
Rect(整数矩形)与FRect(浮点矩形)两套重载,底层以FRect实现,Rect重载通过类型转换复用同一套算法(见 rect.cj)。 - Option 返回值约定:相交、合并、外接矩形等可能失败或为空的运算均返回
Option<T>,调用方须通过if (let Some(v) <- ...)模式匹配解包,这是仓颉语言惯用的安全写法。
二、先认识操作对象:Rect 与 FRect
在使用 RectUtils 前,需要理解其操作的两个核心数据类型,二者均定义于 rgf_struct.cj:
Rect:整数矩形,实现IRect<LONG>与ToString接口,四个边界left、top、right、bottom的类型为LONG。在 wintype.cj 中public type LONG = Int32,即 32 位有符号整数,与 Win32tagRECT结构语义对齐(Rect内置toStruct()/toClass()负责与tagRECT互转)。FRect:浮点矩形,实现IRect<Float32>与ToString,四个边界为Float32单精度浮点,适合高精度坐标与 DPI 缩放场景。
两个类型均提供以下公共属性(见 Rect 定义 与 FRect 定义):
| 属性 | 类型(Rect / FRect) | 含义 |
|---|---|---|
left / top / right / bottom |
LONG / Float32 | 矩形四条边界 |
width / height |
LONG / Float32 | 宽度与高度(right-left、bottom-top) |
size |
Size / FSize | 尺寸对象 |
point |
Point / FPoint | 左上角点 |
常用的构造方式包括:Rect(l, t, r, b) 四参数构造、Rect(pos, width, height) 从点与宽高构造、Rect(pos, radius) 以点为中心构造方形,以及 Rect(pos1, pos2) 由两点归一化构造(自动保证 left ≤ right、top ≤ bottom)。Rect 与 FRect 之间可以相互转换,RectUtils 的整数重载正是借助 FRect(rect1) 转换后调用浮点实现。
三、相交判定:intersect
签名
public static func intersect(rect1: FRect, rect2: FRect): Option<FRect>
public static func intersect(rect1: Rect, rect2: Rect): Option<Rect>
参数与返回值
| 参数 | 类型 | 描述 |
|---|---|---|
| rect1 | Rect / FRect | 第一个矩形 |
| rect2 | Rect / FRect | 第二个矩形 |
返回值:Option<Rect> / Option<FRect>。两矩形相交时返回相交部分矩形;不相交时返回 None。
实现原理
浮点版本的核心实现位于 rect.cj 的 intersect:
var result: FRect = FRect(
max(rect1.left, rect2.left),
max(rect1.top, rect2.top),
min(rect1.right, rect2.right),
min(rect1.bottom, rect2.bottom)
)
if ((result.left < result.right) && (result.top < result.bottom)) {
return result
} else {
return Option<FRect>.None
}
算法采用经典的"区间交集"思路:交集矩形的左、上边界取两个矩形的较大值,右、下边界取两个矩形的较小值。若结果满足 left < right && top < bottom(即交集区域有正宽度与正高度),说明确实相交,返回交集矩形;否则返回 None。整数版本(L61-L67)将参数转换为 FRect 复用同一算法,再转回 Rect。
需要留意的是,仅边界相触(如 right == left)不视为相交,这与 abreast 并肩判定形成互补关系。
四、并肩判定:abreast
签名
public static func abreast(rect1: FRect, rect2: FRect): Int8
public static func abreast(rect1: Rect, rect2: Rect): Int8
参数与返回值
| 参数 | 类型 | 描述 |
|---|---|---|
| rect1 | Rect / FRect | 第一个矩形 |
| rect2 | Rect / FRect | 第二个矩形 |
返回值(Int8 枚举语义):
| 返回值 | 含义 |
|---|---|
| 0 | 无(两个矩形既非横向并列也非纵向并列) |
| 1 | 横向并列(顶底边界一致,可左右相邻) |
| 2 | 纵向并列(左右边界一致,可上下相邻) |
实现原理
if (rect1.top == rect2.top && rect1.bottom == rect2.bottom) {
return 1 // 横向并列
} else if (rect1.left == rect2.left && rect1.right == rect2.right) {
return 2 // 纵向并列
}
return 0
"并肩"(abreast)描述的是两个矩形沿同一轴线对齐的几何关系:横向并列要求二者的 top 与 bottom 完全一致(即同一水平带内,可以左右拼接);纵向并列要求二者的 left 与 right 完全一致(即同一垂直带内,可以上下拼接)。这一判定是下一节 addition 合并运算的前置条件。
五、矩形合并:addition
签名
public static func addition(rect1: FRect, rect2: FRect, haveAbreast!: Option<Int8> = Option<Int8>.None): Option<FRect>
public static func addition(rect1: Rect, rect2: Rect, haveAbreast!: Option<Int8> = Option<Int8>.None): Option<Rect>
参数与返回值
| 参数 | 类型 | 描述 |
|---|---|---|
| rect1 | Rect / FRect | 第一个矩形 |
| rect2 | Rect / FRect | 第二个矩形 |
| haveAbreast | Option<Int8>(具名参数,默认 None) |
若已预先通过 abreast 计算过并肩结果,可传入以避免重复计算 |
返回值:Option<Rect> / Option<FRect>。两个矩形并肩且有重叠区间时返回合并后的外接矩形;不满足条件时返回 None。
实现原理
if (let Some(abreast) <- if (haveAbreast.isNone()) { abreast(rect1, rect2) } else { haveAbreast }) {
if (abreast == 1 && min(rect1.right, rect2.right) > max(rect1.left, rect2.left)) {
// 横向并列:取左右极值,上下沿用原边界
return FRect(min(rect1.left, rect2.left), rect1.top,
max(rect1.right, rect2.right), rect1.bottom)
} else if (abreast == 2 && min(rect1.bottom, rect2.bottom) > max(rect1.top, rect2.top)) {
// 纵向并列:取上下极值,左右沿用原边界
return FRect(rect1.left, min(rect1.top, rect2.top),
rect1.right, max(rect1.bottom, rect2.bottom))
}
}
return Option<FRect>.None
addition 的语义是"将两个可拼接的矩形合并为一个矩形",它比简单的并集运算更严格:要求两个矩形并肩(abreast 结果非 0)且在同一方向上存在重叠区间(横向并列时要求 min(right) > max(left),纵向并列时要求 min(bottom) > max(top),保证合并结果仍是连续矩形)。满足条件后,横向并列取左右边界的最小值与最大值、上下沿用原边界;纵向并列则相反。
haveAbreast 具名参数(仓颉中以 ! 标注默认参数)用于性能优化:当你需要同时对多个矩形对执行"先判定并肩再合并"时,可以预先调用一次 abreast,把结果传入 addition 的 haveAbreast,避免每次合并都重复计算并肩判定。
六、区域差集:subtract
签名
public static func subtract(rect1: Option<FRect>, rect2: FRect, haveIntersect!: Option<FRect> = Option<FRect>.None): Array<FRect>
public static func subtract(rect1: Option<Rect>, rect2: Rect, haveIntersect!: Option<Rect> = Option<Rect>.None): Array<Rect>
参数与返回值
| 参数 | 类型 | 描述 |
|---|---|---|
| rect1 | Option<Rect> / Option<FRect> | 被减矩形(可为 None,此时返回空数组) |
| rect2 | Rect / FRect | 减去的矩形 |
| haveIntersect | Option<Rect> / Option<FRect>(具名参数,默认 None) |
若已预先通过 intersect 计算过相交部分,可传入以避免重复计算 |
返回值:Array<Rect> / Array<FRect>。返回用 rect2 减去 rect1 后剩余区域的矩形集合。
实现原理与边界处理
这是 RectUtils 中算法最复杂的方法,见 rect.cj 的 subtract。整体流程为:
- 若
rect1为None,直接返回空数组[]。 - 求交集:若未传入
haveIntersect,则内部调用intersect(rect1, rect2)计算;否则直接使用传入值(同样是为批量运算避免重复计算而设的优化入口)。 - 相交时:以交集矩形为基准,围绕它切割出最多四个剩余区域——上方、左侧、右侧、下方:
- 上方区域:当
intersection.top > rect1.top(交集顶部低于rect1顶部)时,取rect1的上半部分;否则若intersection.top > rect2.top,取rect2的上半部分(对应rect2向上凸出rect1的情况); - 左侧区域:当
intersection.left > rect1.left时取rect1左侧条带,否则若intersection.left > rect2.left取rect2左侧条带; - 右侧区域:当
intersection.right < rect1.right时取rect1右侧条带,否则若intersection.right < rect2.right取rect2右侧条带; - 下方区域:当
intersection.bottom < rect1.bottom时取rect1下半部分,否则若intersection.bottom < rect2.bottom取rect2下半部分。
- 上方区域:当
- 不相交时:
rect1本身即为全部剩余区域,直接以单元素数组返回。
需要说明的是,该实现以"矩形 A 减去与矩形 B 的交集"为语义,最终返回的剩余区域集合实际涵盖了 rect1 中未被交集覆盖的部分,同时也会把 rect2 凸出于 rect1 之外的条带纳入(取决于四个分支条件命中 rect1 还是 rect2 的边界)。实际应用时建议结合你的具体业务语义验证输出,尤其在两个矩形部分重叠且彼此都有凸出部分时。
七、外接矩形:bounding
bounding 提供三组共六个重载,覆盖"批量数组求外接矩形"与"流式实时求外接矩形"两种使用模式。
7.1 批量数组版本
public static func bounding(arr: Array<FRect>): Option<FRect>
public static func bounding(arr: Array<Rect>): Option<Rect>
| 参数 | 类型 | 描述 |
|---|---|---|
| arr | Array<Rect> / Array<FRect> | 矩形数组 |
返回值:Option<Rect> / Option<FRect>,即所有矩形的最小外接矩形。
实现见 rect.cj 的 bounding(Array):初始化 left/top 为 Float32.Max(或 Int32.Max)、right/bottom 为 Float32.Min(或 Int32.Min),遍历数组逐一取四个边界的最小/最大值,最后构造并返回结果矩形。整数版本初始值使用 Int32.Max/Int32.Min。注意源码中该方法的边界判断为 if (arr.size < 0),恒为假,因此空数组时仍会返回以极值构造的矩形,实际使用时应自行保证传入非空数组。
7.2 实时矩形版本(history + now)
public static func bounding(history: Option<Rect>, now: Rect): Rect
public static func bounding(history: Option<FRect>, now: FRect): FRect
| 参数 | 类型 | 描述 |
|---|---|---|
| history | Option<Rect> / Option<FRect> | 历史外接矩形(首帧传 None) |
| now | Rect / FRect | 新增矩形 |
返回值:Rect / FRect,即历史外接矩形与新增矩形的合并外接矩形。
实现见 rect.cj 的 bounding(history, now):history 为 None(首帧)时直接返回 now;否则对四个边界逐一取 min/max 得到扩展后的外接矩形。这一版本专为流式累计设计:在逐帧渲染或逐矩形遍历的过程中,把上一次的结果作为 history 传入,即可用 O(1) 的时间维护当前已处理区域的最小外接矩形。
7.3 实时点位版本(history + point)
public static func bounding(history: Option<Rect>, now: Point): Rect
public static func bounding(history: Option<FRect>, now: FPoint): FRect
| 参数 | 类型 | 描述 |
|---|---|---|
| history | Option<Rect> / Option<FRect> | 历史外接矩形(首帧传 None) |
| now | Point / FPoint | 新增点位 |
返回值:Rect / FRect,即覆盖历史外接矩形与新增点位的扩展矩形。
实现见 rect.cj 的 bounding(history, point),两个细节值得关注:
- 点已在矩形内时直接返回原矩形:若
posInRect(old, now)为真,说明新点没有超出已有范围,返回old本身,避免无谓的矩形重建; - 首帧行为是生成 1×1 矩形:当
history为None时,返回以该点坐标为左上角、宽高为 1 的矩形(整数版本为(x, y, x+1, y+1),浮点版本为(x, y, x+1.0, y+1.0)),保证后续扩展始终从合法矩形出发。
点位版本特别适合鼠标拖拽框选、多点轨迹包围盒等"由点集动态累积包围区域"的场景。
八、点在矩形内判定:posInRect
签名
public static func posInRect(rect: FRect, pos: FPoint): Bool
public static func posInRect(rect: Rect, pos: Point): Bool
| 参数 | 类型 | 描述 |
|---|---|---|
| rect | Rect / FRect | 目标矩形 |
| pos | Point / FPoint | 待检测坐标点 |
返回值:Bool,点在矩形内返回 true,否则返回 false。
实现见 rect.cj 的 posInRect:
if (
pos.x >= rect.left && pos.x <= rect.right &&
pos.y >= rect.top && pos.y <= rect.bottom
) {
return true
}
return false
判定采用闭区间语义:四个边界均使用 >= 与 <=,因此位于矩形边界上的点同样判定为"在矩形内"(即文档强调的"包括边界情况")。整数版本同样通过 FRect(rect)、FPoint(pos) 转换复用浮点实现。
九、组合应用:从 API 到实战方案
RectUtils 的方法天然适合组合成完整业务逻辑。以"碰撞响应与区域刷新"为例:
- 用
posInRect判定鼠标点是否落入某个控件矩形,实现点击命中检测; - 命中后,用
intersect求该控件与相邻控件的重叠区,用于判断是否需要联动刷新; - 用
bounding(history, now)沿拖拽路径累计脏矩形,配合渲染器的局部重绘缩小刷新面积; - 需要从某个大矩形中抠掉重叠控件区域时,用
subtract得到剩余矩形集合; - 当相邻的控件矩形需要合并为一张整图绘制时,先用
abreast确认二者并肩,再用addition合并。
此外,abreast 与 addition 也可用于矩形区域合并去重:将大量小矩形两两检测并肩并合并,减少渲染批次中的矩形数量。
十、使用注意事项小结
| 方法 | 易错点 |
|---|---|
intersect |
边界相触不算相交;结果需用 if (let Some(v) <- ...) 解包 |
abreast |
返回 Int8 枚举语义(0/1/2),需与 addition 配合理解 |
addition |
仅并肩且有重叠区间才合并成功,否则返回 None |
subtract |
结果可能是 0~4 个矩形;建议对重叠形态(A 完全覆盖 B、B 完全覆盖 A、部分重叠)分别验证输出 |
bounding(Array) |
空数组边界未做严格防护,使用前请保证数组非空 |
bounding(history, point) |
首帧 history 必须传 None,且会生成 1×1 矩形 |
posInRect |
闭区间语义,边界上的点返回 true |
RectUtils 全部实现位于 src/rgf_utils/rect.cj,所操作的数据类型定义于 src/rgf_core/rgf_struct.cj,完整 API 清单见 doc/api/rgf.rgf_utils/readme.md。阅读源码时留意 FRect 与 Rect 互转的 init 构造函数(Rect(rect: FRect) 与 FRect(rect: Rect)),理解这套转换关系即可掌握全部整数/浮点重载的等价实现脉络。