transform
Class Summary
OHOS::TransformMap
提供矩形的二维/三维变换能力，包括旋转、缩放、平移、剪切及透视变换
- 构造：
explicit TransformMap(const Rect& rect) -
成员函数：
接口名称 功能简述 TransformMap 以指定矩形构造变换映射对象 GetClockWise 检查多边形顶点是否为顺时针方向 SetPolygon 设置矩形变换后的多边形 GetPolygon 获取矩形变换后的多边形 GetPivot 获取旋转或缩放操作的旋转中心 GetScaleCoef 获取缩放系数 SetTransMapRect 设置待变换的矩形 GetTransMapRect 获取待变换的矩形 SetInvalid 设置变换映射的无效状态 IsInvalid 检查变换映射是否无效 GetBoxRect 获取包含多边形的最小外接矩形 GetTransformMatrix 获取三维齐次变换矩阵 GetOrigTransformMatrix 获取原始变换矩阵 GetRotateMatrix 获取旋转变换矩阵 GetScaleMatrix 获取缩放变换矩阵 GetTranslateMatrix 获取平移变换矩阵 GetShearMatrix 获取剪切变换矩阵 GetPerspectiveMatrix 获取透视变换矩阵 GetRotateAngle 获取旋转角度 GetOrigPoint 获取变换前原始点坐标 Rotate 围绕指定轴旋转矩形 Scale 缩放矩形 Translate 平移矩形 Shear 对矩形进行剪切变换 operator== 判断两个变换映射是否相等 SetMatrix 设置变换矩阵 SetCameraDistance 设置相机距离 SetCameraPosition 设置相机位置 Is3DTransform 检查是否为三维变换 -
使用包含头文件：
#include "gfx_utils/transform.h" - 声明头文件：
middleware/services/gui/uikit/utils/interfaces/kits/gfx_utils/transform.h - 公有运算符：
bool operator==(const TransformMap& other) const - 继承关系：
HeapBase - 嵌套类型：无
- 模板形参：无
自由函数
| 接口名称 | 功能简述 |
|---|---|
| OHOS::Rotate | 将点/线段/矩形围绕旋转中心旋转指定角度 |
Functions
自由函数
OHOS::Rotate
void OHOS::Rotate(const Vector2<int16_t>& point, int16_t angle, const Vector2<int16_t>& pivot, Vector2<int16_t>& out)
功能说明
- 核心用途：将指定点围绕旋转中心旋转指定角度
- 使用场景：对单个坐标点进行旋转变换
- 结果通过出参
out返回旋转后的点坐标
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| point | const Vector2\<int16_t>& | 待旋转的点坐标，入参只读引用 | - |
| angle | int16_t | 旋转角度 | - |
| pivot | const Vector2\<int16_t>& | 旋转中心坐标，入参只读引用 | - |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| out | Vector2\<int16_t>& | 旋转后的点坐标，出参引用 |
OHOS::Rotate
void OHOS::Rotate(const Line& origLine, int16_t angle, const Vector2<int16_t>& pivot, Line& out)
功能说明
- 核心用途：将线段围绕旋转中心旋转指定角度
- 使用场景：对线段的两个端点同时进行旋转变换
- 结果通过出参
out返回旋转后的线段
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| origLine | const Line& | 待旋转的线段，入参只读引用 | - |
| angle | int16_t | 旋转角度 | - |
| pivot | const Vector2\<int16_t>& | 旋转中心坐标，入参只读引用 | - |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| out | Line& | 旋转后的线段，出参引用 |
OHOS::Rotate
void OHOS::Rotate(const Rect& origRect, int16_t angle, const Vector2<int16_t>& pivot, Polygon& out)
功能说明
- 核心用途：将矩形围绕旋转中心旋转指定角度
- 使用场景：对矩形的四个顶点同时进行旋转变换，旋转后矩形退化为四边形多边形
- 结果通过出参
out返回旋转后的多边形
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| origRect | const Rect& | 待旋转的矩形，入参只读引用 | - |
| angle | int16_t | 旋转角度 | - |
| pivot | const Vector2\<int16_t>& | 旋转中心坐标，入参只读引用 | - |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| out | Polygon& | 旋转后的多边形，出参引用 |
OHOS::TransformMap
TransformMap
explicit TransformMap(const Rect& rect)
功能说明
- 核心用途：以指定矩形构造变换映射对象，初始化各变换矩阵为单位矩阵
- 使用场景：创建绑定特定矩形的变换映射，后续可对其施加旋转、缩放、平移等变换操作
- 对象构造后即处于可操作状态，可直接调用 Rotate/Scale/Translate 等成员函数
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| rect | const Rect& | 待变换的矩形，入参只读引用 | - |
GetClockWise
bool GetClockWise() const
功能说明
- 核心用途：检查多边形顶点是否按顺时针方向排列
- 使用场景：判断变换后多边形的绕向，用于面剔除或填充规则判定
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
bool
返回多边形顶点绕向判断结果
| 返回值 | 触发场景 |
|---|---|
| true | 顶点按顺时针方向排列 |
| false | 顶点按逆时针方向排列或顶点数不足 |
SetPolygon
void SetPolygon(const Polygon& polygon)
功能说明
- 核心用途：设置矩形变换后的多边形
- 使用场景：手动指定变换结果多边形，覆盖当前变换计算结果
- 设置后不影响内部变换矩阵
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| polygon | const Polygon& | 要设置的多边形，入参只读引用 | - |
GetPolygon
Polygon GetPolygon() const
功能说明
- 核心用途：获取矩形变换后得到的多边形
- 使用场景：获取当前变换结果的多边形表示，用于后续绘制或碰撞检测
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
Polygon
返回变换后的多边形
| 返回值 | 触发场景 |
|---|---|
| Polygon | 当前变换结果的多边形 |
GetPivot
const Vector3<float>& GetPivot() const
功能说明
- 核心用途：获取旋转或缩放操作的旋转中心
- 使用场景：查询上次 Scale 或 Rotate 操作使用的旋转中心坐标
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Vector3<float>&
返回旋转中心坐标
| 返回值 | 触发场景 |
|---|---|
| const Vector3\<float>& | 当前旋转中心坐标 |
GetScaleCoef
const Vector3<float>& GetScaleCoef() const
功能说明
- 核心用途：获取当前的缩放系数
- 使用场景：查询上次 Scale 操作设置的 x/y/z 轴缩放比例
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Vector3<float>&
返回缩放系数
| 返回值 | 触发场景 |
|---|---|
| const Vector3\<float>& | 当前 x/y/z 轴缩放系数 |
SetTransMapRect
void SetTransMapRect(const Rect& rect)
功能说明
- 核心用途：设置待变换的矩形
- 使用场景：更换变换目标矩形，设置后根据当前矩阵状态重新计算变换结果
- 调用后内部会重新执行变换计算
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| rect | const Rect& | 新的待变换矩形，入参只读引用 | - |
GetTransMapRect
const Rect& GetTransMapRect() const
功能说明
- 核心用途：获取当前待变换的矩形
- 使用场景：查询当前变换映射绑定的原始矩形
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Rect&
返回当前待变换矩形
| 返回值 | 触发场景 |
|---|---|
| const Rect& | 当前待变换矩形 |
SetInvalid
void SetInvalid(bool state)
功能说明
- 核心用途：设置变换映射的无效状态标记
- 使用场景：手动标记变换结果为无效，后续 IsInvalid 调用将返回该标记值
- 该接口直接设置内部状态标记，不触发变换重新计算
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| state | bool | 无效状态标记 | true: 无效; false: 有效 |
IsInvalid
bool IsInvalid() const
功能说明
- 核心用途：检查变换映射是否无效，当多边形所有顶点坐标均为 0 或被手动标记为无效时返回 true
- 使用场景：在绘制前检查变换结果是否有效，避免对无效结果进行渲染
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
bool
返回变换映射有效性判断结果
| 返回值 | 触发场景 |
|---|---|
| true | 变换映射无效（所有顶点为 0 或被手动标记为无效） |
| false | 变换映射有效 |
GetBoxRect
Rect GetBoxRect() const
功能说明
- 核心用途：获取包含多边形的最小外接矩形（AABB）
- 使用场景：确定变换后多边形的包围盒，用于裁剪判断或重绘区域计算
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
Rect
返回多边形的最小外接矩形
| 返回值 | 触发场景 |
|---|---|
| Rect | 包含多边形所有顶点的最小外接矩形 |
GetTransformMatrix
const Matrix4<float>& GetTransformMatrix() const
功能说明
- 核心用途：获取包含平移偏移的三维齐次变换矩阵
- 使用场景：获取当前所有变换操作（旋转、缩放、平移、剪切、透视）的合成矩阵
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Matrix4<float>&
返回合成变换矩阵
| 返回值 | 触发场景 |
|---|---|
| const Matrix4\<float>& | 当前合成变换矩阵（含平移偏移） |
GetOrigTransformMatrix
const Matrix4<float>& GetOrigTransformMatrix() const
功能说明
- 核心用途：获取原始变换矩阵（不含额外平移偏移）
- 使用场景：获取 SetMatrix 设置的原始矩阵数据
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Matrix4<float>&
返回原始变换矩阵
| 返回值 | 触发场景 |
|---|---|
| const Matrix4\<float>& | 原始变换矩阵 |
GetRotateMatrix
const Matrix4<float>& GetRotateMatrix() const
功能说明
- 核心用途：获取旋转变换矩阵
- 使用场景：查询当前旋转变换对应的矩阵数据
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Matrix4<float>&
返回旋转变换矩阵
| 返回值 | 触发场景 |
|---|---|
| const Matrix4\<float>& | 当前旋转变换矩阵 |
GetScaleMatrix
const Matrix4<float>& GetScaleMatrix() const
功能说明
- 核心用途：获取缩放变换矩阵
- 使用场景：查询当前缩放变换对应的矩阵数据
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Matrix4<float>&
返回缩放变换矩阵
| 返回值 | 触发场景 |
|---|---|
| const Matrix4\<float>& | 当前缩放变换矩阵 |
GetTranslateMatrix
const Matrix4<float>& GetTranslateMatrix() const
功能说明
- 核心用途：获取平移变换矩阵
- 使用场景：查询当前平移变换对应的矩阵数据
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Matrix4<float>&
返回平移变换矩阵
| 返回值 | 触发场景 |
|---|---|
| const Matrix4\<float>& | 当前平移变换矩阵 |
GetShearMatrix
const Matrix4<float>& GetShearMatrix() const
功能说明
- 核心用途：获取剪切变换矩阵
- 使用场景：查询当前剪切变换对应的矩阵数据
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Matrix4<float>&
返回剪切变换矩阵
| 返回值 | 触发场景 |
|---|---|
| const Matrix4\<float>& | 当前剪切变换矩阵 |
GetPerspectiveMatrix
const Matrix4<float>& GetPerspectiveMatrix() const
功能说明
- 核心用途：获取透视变换矩阵
- 使用场景：查询当前透视投影变换对应的矩阵数据
- 返回值为 const 引用，不修改对象状态
返回值
- 返回类型：
const Matrix4<float>&
返回透视变换矩阵
| 返回值 | 触发场景 |
|---|---|
| const Matrix4\<float>& | 当前透视变换矩阵 |
GetRotateAngle
int16_t GetRotateAngle() const
功能说明
- 核心用途：获取当前的旋转角度
- 使用场景：查询上次 Rotate 操作设置的旋转角度值
- 该函数为 const 成员函数，不修改对象状态
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_SWEEP_CLOCK | 启用时返回类型为 float，未启用时返回类型为 int16_t | n |
返回值
- 返回类型：
int16_t（ENABLE_SWEEP_CLOCK 未启用时）
返回旋转角度
| 返回值 | 触发场景 |
|---|---|
| int16_t | 当前旋转角度 |
GetOrigPoint
Point GetOrigPoint(const Point& point, const Rect& relativeRect)
功能说明
- 核心用途：根据变换后的点坐标，计算其在原始矩形中的对应点
- 使用场景：在变换后的图像中点击某点时，反算该点在原始图像中的坐标位置
- 调用后不修改对象当前状态
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| point | const Point& | 待反算的点坐标，入参只读引用 | - |
| relativeRect | const Rect& | 相对偏移矩形，入参只读引用 | - |
返回值
- 返回类型：
Point
返回原始点坐标
| 返回值 | 触发场景 |
|---|---|
| Point | 反算得到的原始坐标点 |
Rotate
void Rotate(int16_t angle, const Vector2<float>& pivot)
void Rotate(int16_t angle, const Vector3<float>& rotatePivotStart, const Vector3<float>& rotatePivotEnd)
功能说明
- 核心用途：围绕指定旋转中心/轴旋转矩形指定角度
- 使用场景：对矩形进行二维或三维旋转变换；二维版本使用二维旋转中心，三维版本使用由两个三维点确定的旋转轴
- 调用后内部自动更新变换矩阵和多边形
入参（重载1：二维旋转）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| angle | int16_t | 旋转角度 | - |
| pivot | const Vector2\<float>& | 二维旋转中心，入参只读引用 | - |
入参（重载2：三维旋转）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| angle | int16_t | 旋转角度 | - |
| rotatePivotStart | const Vector3\<float>& | 旋转轴起始点，入参只读引用 | - |
| rotatePivotEnd | const Vector3\<float>& | 旋转轴终止点，入参只读引用 | - |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_SWEEP_CLOCK | 启用时 angle 参数类型为 float | n |
Scale
void Scale(const Vector2<float>& scale, const Vector2<float>& pivot)
void Scale(const Vector3<float>& scale, const Vector3<float>& pivot)
功能说明
- 核心用途：以指定缩放中心和缩放系数对矩形进行缩放变换
- 使用场景：对矩形进行二维或三维缩放；二维版本使用 Vector2 指定缩放系数和中心，三维版本使用 Vector3
- 调用后内部自动更新变换矩阵和多边形
入参（重载1：二维缩放）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| scale | const Vector2\<float>& | x/y 轴缩放系数，入参只读引用 | - |
| pivot | const Vector2\<float>& | 二维缩放中心，入参只读引用 | - |
入参（重载2：三维缩放）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| scale | const Vector3\<float>& | x/y/z 轴缩放系数，入参只读引用 | - |
| pivot | const Vector3\<float>& | 三维缩放中心，入参只读引用 | - |
Translate
void Translate(const Vector2<int16_t>& trans)
void Translate(const Vector3<int16_t>& trans)
void Translate(const Vector2<float>& trans)
void Translate(const Vector3<float>& trans)
功能说明
- 核心用途：以指定偏移量平移矩形
- 使用场景：对矩形进行平移变换，提供 int16_t 和 float 两种精度的二维/三维偏移量重载
- 调用后内部自动更新变换矩阵和多边形
入参（重载1：二维整型偏移）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| trans | const Vector2\<int16_t>& | 二维整型平移偏移量，入参只读引用 | - |
入参（重载2：三维整型偏移）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| trans | const Vector3\<int16_t>& | 三维整型平移偏移量，入参只读引用 | - |
入参（重载3：二维浮点偏移）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| trans | const Vector2\<float>& | 二维浮点平移偏移量，入参只读引用 | - |
入参（重载4：三维浮点偏移）
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| trans | const Vector3\<float>& | 三维浮点平移偏移量，入参只读引用 | - |
Shear
void Shear(const Vector2<float>& shearX, const Vector2<float>& shearY, const Vector2<float>& shearZ)
功能说明
- 核心用途：对矩形进行剪切变换
- 使用场景：对矩形施加沿 x/y/z 方向的剪切变形
- 调用后内部自动更新变换矩阵和多边形
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| shearX | const Vector2\<float>& | x 方向剪切参数，入参只读引用 | - |
| shearY | const Vector2\<float>& | y 方向剪切参数，入参只读引用 | - |
| shearZ | const Vector2\<float>& | z 方向剪切参数，入参只读引用 | - |
operator==
bool operator==(const TransformMap& other) const
功能说明
- 核心用途：判断两个变换映射对象是否相等
- 使用场景：比较两个 TransformMap 的旋转、平移、缩放矩阵及矩形和合成矩阵是否一致
- 该函数为 const 成员函数，不修改对象状态
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| other | const TransformMap& | 待比较的另一个变换映射对象，入参只读引用 | - |
返回值
- 返回类型：
bool
返回比较结果
| 返回值 | 触发场景 |
|---|---|
| true | 两个变换映射的旋转、平移、缩放矩阵及矩形和合成矩阵均相等 |
| false | 任一矩阵或矩形不相等 |
SetMatrix
void SetMatrix(const Matrix4<float>& matrix, bool isInternalMatrix = false)
功能说明
- 核心用途：直接设置变换矩阵，替代通过 Rotate/Scale/Translate 等操作逐步构建的变换
- 使用场景：需要使用自定义变换矩阵时，可直接设置完整矩阵
- 设置后根据矩阵重新计算多边形顶点及逆矩阵
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| matrix | const Matrix4\<float>& | 变换矩阵，入参只读引用 | - |
| isInternalMatrix | bool | 是否为内部矩阵标记，缺省值为 false | true: 内部矩阵; false: 外部矩阵 |
SetCameraDistance
void SetCameraDistance(int16_t distance)
功能说明
- 核心用途：设置透视变换的相机距离
- 使用场景：配置透视投影的观察距离，影响透视效果的强弱
- 调用后内部自动更新透视矩阵和合成变换矩阵
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| distance | int16_t | 相机距离 | - |
SetCameraPosition
void SetCameraPosition(const Vector2<float>& position)
功能说明
- 核心用途：设置透视变换的相机位置
- 使用场景：配置透视投影的观察位置，影响透视变换的偏移
- 调用后内部自动更新透视矩阵和合成变换矩阵
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| position | const Vector2\<float>& | 相机位置坐标，入参只读引用 | - |
Is3DTransform
bool Is3DTransform() const
功能说明
- 核心用途：检查当前变换是否为三维变换
- 使用场景：判断变换结果是否涉及透视除法（齐次坐标 w 分量不为 1 时为三维变换）
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
bool
返回三维变换判断结果
| 返回值 | 触发场景 |
|---|---|
| true | 变换涉及三维透视效果（齐次坐标 w 分量不为 1） |
| false | 变换为纯二维变换 |
Structures
成员说明：
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| invMatrix_ | Matrix3\<float> | 变换矩阵的逆矩阵，用于反向坐标映射 |