RGF 矩形运算工具类 RectUtils 实战指南:相交、并肩、合并、差集与外接矩形全解析

原创2026-10-14 13:11:431,619 阅读
文章标签:图形学桌面应用

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 的核心特征有三点:

  1. 纯静态工具类:类声明为 public class RectUtils,构造函数被 private init(){} 私有化,所有方法均为 public static,使用时不需实例化,直接以 RectUtils.方法名(...) 调用。
  2. 双精度体系重载:所有方法同时提供 Rect(整数矩形)与 FRect(浮点矩形)两套重载,底层以 FRect 实现,Rect 重载通过类型转换复用同一套算法(见 rect.cj)。
  3. 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 位有符号整数,与 Win32 tagRECT 结构语义对齐(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 纵向并列(左右边界一致,可上下相邻)

实现原理

见 rect.cj 的 abreast:

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。

实现原理

见 rect.cj 的 addition:

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。整体流程为:

  1. 若 rect1 为 None,直接返回空数组 []。
  2. 求交集:若未传入 haveIntersect,则内部调用 intersect(rect1, rect2) 计算;否则直接使用传入值(同样是为批量运算避免重复计算而设的优化入口)。
  3. 相交时:以交集矩形为基准,围绕它切割出最多四个剩余区域——上方、左侧、右侧、下方:
    • 上方区域:当 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 下半部分。
  4. 不相交时: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 的方法天然适合组合成完整业务逻辑。以"碰撞响应与区域刷新"为例:

  1. 用 posInRect 判定鼠标点是否落入某个控件矩形,实现点击命中检测;
  2. 命中后,用 intersect 求该控件与相邻控件的重叠区,用于判断是否需要联动刷新;
  3. 用 bounding(history, now) 沿拖拽路径累计脏矩形,配合渲染器的局部重绘缩小刷新面积;
  4. 需要从某个大矩形中抠掉重叠控件区域时,用 subtract 得到剩余矩形集合;
  5. 当相邻的控件矩形需要合并为一张整图绘制时,先用 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)),理解这套转换关系即可掌握全部整数/浮点重载的等价实现脉络。

登录后查看全文
RGF_CJ