graphic_math

Class Summary

OHOS::Vector2

二维向量类，提供标量积、向量积、加减法及缩放运算

• 构造：Vector2(T x, T y)

• 成员函数：

  接口名称	功能简述
  Vector2	根据X和Y坐标构造二维向量
  Dot	计算与另一个二维向量的标量积
  Cross	计算与另一个二维向量的向量积
  operator-	取反运算，返回各分量取反的新向量
  operator-	减法运算，返回与另一个向量的差
  operator+	加法运算，返回与另一个向量的和
  operator*	标量乘法运算，返回缩放后的新向量
  operator==	判断两个向量是否相等
  operator=	赋值运算，将另一个向量的值赋给当前对象
  operator+=	复合加法赋值运算
  operator-=	复合减法赋值运算

• 使用包含头文件：#include "gfx_utils/graphic_math.h"

• 声明头文件：middleware/services/gui/uikit/utils/interfaces/kits/gfx_utils/graphic_math.h
• 公有运算符：operator-()、operator-(const Vector2<T>&)、operator+(const Vector2<T>&)、operator*(T)、operator==(const Vector2&)、operator=(const Vector2&)、operator+=(const Vector2&)、operator-=(const Vector2&)
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：typename T

OHOS::Vector3

三维向量类，提供下标访问和相等判断运算

• 构造：Vector3(T x, T y, T z)

• 成员函数：

  接口名称	功能简述
  Vector3	根据X、Y、Z坐标构造三维向量
  operator[]	只读下标访问向量分量
  operator[]	可写下标访问向量分量
  operator==	判断两个三维向量是否相等

• 使用包含头文件：#include "gfx_utils/graphic_math.h"

• 声明头文件：middleware/services/gui/uikit/utils/interfaces/kits/gfx_utils/graphic_math.h
• 公有运算符：operator[](uint8_t) const、operator[](uint8_t)、operator==(const Vector3&) const
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：typename T

OHOS::Vector4

四维向量类，提供下标访问和相等判断运算

• 构造：Vector4(T x, T y, T z, T w)

• 成员函数：

  接口名称	功能简述
  Vector4	根据X、Y、Z、W坐标构造四维向量
  operator[]	只读下标访问向量分量
  operator[]	可写下标访问向量分量
  operator==	判断两个四维向量是否相等

• 使用包含头文件：#include "gfx_utils/graphic_math.h"

• 声明头文件：middleware/services/gui/uikit/utils/interfaces/kits/gfx_utils/graphic_math.h
• 公有运算符：operator[](uint8_t) const、operator[](uint8_t)、operator==(const Vector4&) const
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：typename T

OHOS::Matrix3

3x3矩阵类，提供行列式计算、逆矩阵、旋转/缩放/平移变换

• 构造：Matrix3(T m00, T m01, T m02, T m10, T m11, T m12, T m20, T m21, T m22)

• 成员函数：

  接口名称	功能简述
  Matrix3	根据9个元素值构造3x3矩阵
  GetData	获取矩阵数据指针
  Determinant	计算矩阵行列式
  Inverse	计算逆矩阵
  Rotate	获取旋转变换矩阵
  Scale	获取缩放变换矩阵
  Translate	获取平移变换矩阵
  operator*	矩阵乘法运算
  operator*	矩阵与向量乘法运算
  operator[]	按列下标访问矩阵数据
  operator=	赋值运算
  operator==	判断两个矩阵是否相等

• 使用包含头文件：#include "gfx_utils/graphic_math.h"

• 声明头文件：middleware/services/gui/uikit/utils/interfaces/kits/gfx_utils/graphic_math.h
• 公有运算符：operator*(const Matrix3&) const、operator*(const Vector3<T>&) const、operator[](uint8_t)、operator=(const Matrix3&)、operator==(const Matrix3&) const
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：typename T

OHOS::Matrix4

4x4矩阵类，提供行列式计算、逆矩阵、旋转/缩放/平移/错切变换

• 构造：Matrix4(T m00, T m01, T m02, T m03, T m10, T m11, T m12, T m13, T m20, T m21, T m22, T m23, T m30, T m31, T m32, T m33)

• 成员函数：

  接口名称	功能简述
  Matrix4	根据16个元素值构造4x4矩阵
  GetData	获取矩阵数据指针
  Determinant	计算矩阵行列式
  Inverse	计算逆矩阵
  Rotate	根据余弦和正弦值获取旋转变换矩阵
  Rotate	根据角度获取旋转变换矩阵
  Scale	获取缩放变换矩阵
  Translate	获取平移变换矩阵
  Shear	获取错切变换矩阵
  operator*	矩阵乘法运算
  operator*	矩阵与向量乘法运算
  operator[]	按列下标访问矩阵数据
  operator=	赋值运算
  operator==	判断两个矩阵是否相等

• 使用包含头文件：#include "gfx_utils/graphic_math.h"

• 声明头文件：middleware/services/gui/uikit/utils/interfaces/kits/gfx_utils/graphic_math.h
• 公有运算符：operator*(const Matrix4&) const、operator*(const Vector4<T>&) const、operator[](uint8_t)、operator=(const Matrix4&)、operator==(const Matrix4&) const
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：typename T

Functions

自由函数

OHOS::Sin

float OHOS::Sin(float angle)

功能说明

• 核心用途：计算指定角度的正弦值
• 使用场景：图形旋转变换中的角度计算
• 返回角度对应的正弦值，输入角度单位为度

入参

名称	参数类型	详细说明	约束取值范围
angle	float	角度值	浮点数，单位为度

返回值

• 返回类型：float

返回指定角度的正弦值

返回值	触发场景
float	正弦计算结果，取值范围 [-1.0, 1.0]

---

OHOS::Cos

float OHOS::Cos(float angle)

功能说明

• 核心用途：计算指定角度的余弦值
• 使用场景：图形旋转变换中的角度计算
• 返回角度对应的余弦值，输入角度单位为度

入参

名称	参数类型	详细说明	约束取值范围
angle	float	角度值	浮点数，单位为度

返回值

• 返回类型：float

返回指定角度的余弦值

返回值	触发场景
float	余弦计算结果，取值范围 [-1.0, 1.0]

---

OHOS::Acos

float OHOS::Acos(float value)

功能说明

• 核心用途：计算指定值的反余弦值
• 使用场景：从余弦值反推角度
• 返回值单位为度

入参

名称	参数类型	详细说明	约束取值范围
value	float	余弦值	[-1.0, 1.0]

返回值

• 返回类型：float

返回反余弦角度值

返回值	触发场景
float	反余弦结果，单位为度，取值范围 [0, 180]

---

OHOS::Fmod

float OHOS::Fmod(float x, float y)

功能说明

• 核心用途：计算浮点数取模运算的余数
• 使用场景：角度归一化、周期性数值计算
• 返回 x 除以 y 的浮点余数

入参

名称	参数类型	详细说明	约束取值范围
x	float	被除数	浮点数
y	float	除数	非零浮点数

返回值

• 返回类型：float

返回浮点取模余数

返回值	触发场景
float	x 除以 y 的浮点余数

---

OHOS::FastAtan2

uint16_t OHOS::FastAtan2(int16_t x, int16_t y)

功能说明

• 核心用途：快速计算二维坐标的反正切值（整数版本）
• 使用场景：需要高性能角度计算的图形变换场景
• 使用近似算法实现，精度低于标准 atan2 但速度更快

入参

名称	参数类型	详细说明	约束取值范围
x	int16_t	X坐标值	int16_t 范围
y	int16_t	Y坐标值	int16_t 范围

返回值

• 返回类型：uint16_t

返回反正切角度值

返回值	触发场景
uint16_t	反正切结果，角度值

---

OHOS::FastAtan2F

float OHOS::FastAtan2F(float x, float y)

功能说明

• 核心用途：快速计算二维坐标的反正切值（浮点版本）
• 使用场景：需要高性能浮点角度计算的图形变换场景
• 使用近似算法实现，精度低于标准 atan2f 但速度更快

入参

名称	参数类型	详细说明	约束取值范围
x	float	X坐标值	浮点数
y	float	Y坐标值	浮点数

返回值

• 返回类型：float

返回反正切角度值

返回值	触发场景
float	反正切结果，浮点角度值

---

OHOS::Sqrt

float OHOS::Sqrt(float x)

功能说明

• 核心用途：计算浮点数的平方根
• 使用场景：向量长度计算、距离计算
• 返回 x 的平方根值

入参

名称	参数类型	详细说明	约束取值范围
x	float	待求平方根的值	非负浮点数

返回值

• 返回类型：float

返回平方根值

返回值	触发场景
float	x 的平方根，x >= 0 时为正数

---

OHOS::FloatToInt64

int64_t OHOS::FloatToInt64(float f)

功能说明

• 核心用途：将浮点数转换为定点整数表示
• 使用场景：浮点坐标到定点坐标的转换，用于图形渲染管线
• 转换结果左移8位保留小数精度，并做四舍五入处理

入参

名称	参数类型	详细说明	约束取值范围
f	float	待转换的浮点数	[-127.0, 127.0]

返回值

• 返回类型：int64_t

返回定点整数

返回值	触发场景
0x7FFF	f > 127.0，超出上限截断
-0x7FFF	f < -127.0，超出下限截断
int64_t	正常范围内的定点转换结果

---

OHOS::FloatEqual

bool OHOS::FloatEqual(float lhs, float rhs, float precision = 0.00001f)

功能说明

• 核心用途：判断两个浮点数在指定精度下是否相等
• 使用场景：浮点数比较，避免直接使用 == 运算
• 当两数差值绝对值小于 precision 时返回 true

入参

名称	参数类型	详细说明	约束取值范围
lhs	float	左操作数	浮点数
rhs	float	右操作数	浮点数
precision	float	比较精度	正浮点数，默认 0.00001f

返回值

• 返回类型：bool

返回两数是否在精度范围内相等

返回值	触发场景
true	两数差值绝对值小于 precision
false	两数差值绝对值大于等于 precision

---

OHOS::FloatMore

bool OHOS::FloatMore(float lhs, float rhs, float precision = 0.00001f)

功能说明

• 核心用途：判断 lhs 是否大于 rhs（考虑浮点精度）
• 使用场景：浮点数大小比较，避免精度误差
• 当 lhs - rhs > precision 时返回 true

入参

名称	参数类型	详细说明	约束取值范围
lhs	float	左操作数	浮点数
rhs	float	右操作数	浮点数
precision	float	比较精度	正浮点数，默认 0.00001f

返回值

• 返回类型：bool

返回 lhs 是否大于 rhs

返回值	触发场景
true	lhs - rhs > precision
false	lhs - rhs <= precision

---

OHOS::FloatLess

bool OHOS::FloatLess(float lhs, float rhs, float precision = 0.00001f)

功能说明

• 核心用途：判断 lhs 是否小于 rhs（考虑浮点精度）
• 使用场景：浮点数大小比较，避免精度误差
• 当 lhs - rhs < -precision 时返回 true

入参

名称	参数类型	详细说明	约束取值范围
lhs	float	左操作数	浮点数
rhs	float	右操作数	浮点数
precision	float	比较精度	正浮点数，默认 0.00001f

返回值

• 返回类型：bool

返回 lhs 是否小于 rhs

返回值	触发场景
true	lhs - rhs < -precision
false	lhs - rhs >= -precision

---

OHOS::FloatMoreEqual

bool OHOS::FloatMoreEqual(float lhs, float rhs, float precision = 0.00001f)

功能说明

• 核心用途：判断 lhs 是否大于等于 rhs（考虑浮点精度）
• 使用场景：浮点数大小比较，避免精度误差
• 当 lhs - rhs > -precision 时返回 true

入参

名称	参数类型	详细说明	约束取值范围
lhs	float	左操作数	浮点数
rhs	float	右操作数	浮点数
precision	float	比较精度	正浮点数，默认 0.00001f

返回值

• 返回类型：bool

返回 lhs 是否大于等于 rhs

返回值	触发场景
true	lhs - rhs > -precision
false	lhs - rhs <= -precision

---

OHOS::FloatLessEqual

bool OHOS::FloatLessEqual(float lhs, float rhs, float precision = 0.00001f)

功能说明

• 核心用途：判断 lhs 是否小于等于 rhs（考虑浮点精度）
• 使用场景：浮点数大小比较，避免精度误差
• 当 lhs - rhs < precision 时返回 true

入参

名称	参数类型	详细说明	约束取值范围
lhs	float	左操作数	浮点数
rhs	float	右操作数	浮点数
precision	float	比较精度	正浮点数，默认 0.00001f

返回值

• 返回类型：bool

返回 lhs 是否小于等于 rhs

返回值	触发场景
true	lhs - rhs < precision
false	lhs - rhs >= precision

---

OHOS::IsIdentity

bool OHOS::IsIdentity(Matrix3<float>& matrix)

功能说明

• 核心用途：判断3x3矩阵是否为单位矩阵
• 使用场景：图形变换前检查矩阵状态
• 逐元素比较矩阵数据是否与单位矩阵一致

入参

名称	参数类型	详细说明	约束取值范围
matrix	Matrix3&	待判断的3x3矩阵，入参引用	Matrix3 对象

返回值

• 返回类型：bool

返回矩阵是否为单位矩阵

返回值	触发场景
true	矩阵为单位矩阵
false	矩阵非单位矩阵

---

OHOS::IsIdentity

bool OHOS::IsIdentity(Matrix4<float>& matrix)

功能说明

• 核心用途：判断4x4矩阵是否为单位矩阵
• 使用场景：图形变换前检查矩阵状态
• 逐元素比较矩阵数据是否与单位矩阵一致

入参

名称	参数类型	详细说明	约束取值范围
matrix	Matrix4&	待判断的4x4矩阵，入参引用	Matrix4 对象

返回值

• 返回类型：bool

返回矩阵是否为单位矩阵

返回值	触发场景
true	矩阵为单位矩阵
false	矩阵非单位矩阵

OHOS::Vector2

Vector2(args...)

Vector2(T x, T y)

功能说明

• 根据X和Y坐标构造二维向量
• x_ 初始化为 x，y_ 初始化为 y
• 构造后可直接用于向量运算

入参

名称	参数类型	详细说明	约束取值范围
x	T	X坐标值	模板参数类型范围
y	T	Y坐标值	模板参数类型范围

---

Dot

T Dot(const Vector2<T>& other) const

功能说明

• 核心用途：计算当前二维向量与另一个二维向量的标量积（点积）
• 使用场景：投影计算、夹角余弦计算
• 返回 x_ * other.x_ + y_ * other.y_

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	参与计算的另一个二维向量，入参只读引用	Vector2 对象

返回值

• 返回类型：T

返回标量积结果

返回值	触发场景
T	两向量的点积值

---

Cross

T Cross(const Vector2<T>& other) const

功能说明

• 核心用途：计算当前二维向量与另一个二维向量的向量积（叉积）
• 使用场景：判断两向量相对方向、面积计算
• 返回 x_ * other.y_ - y_ * other.x_

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	参与计算的另一个二维向量，入参只读引用	Vector2 对象

返回值

• 返回类型：T

返回向量积结果

返回值	触发场景
T	两向量的叉积值

---

operator-

Vector2 operator-() const

功能说明

• 核心用途：对二维向量取反，返回各分量取反的新向量
• 使用场景：向量方向反转
• 不修改原向量，返回新对象

返回值

• 返回类型：Vector2

返回各分量取反后的新向量

返回值	触发场景
Vector2	(-x_, -y_)

---

operator-

Vector2 operator-(const Vector2<T>& other) const

功能说明

• 核心用途：计算当前向量与另一个向量的差
• 使用场景：向量减法运算
• 不修改原向量，返回新对象

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	被减向量，入参只读引用	Vector2 对象

返回值

• 返回类型：Vector2

返回向量差

返回值	触发场景
Vector2	(x_ - other.x_, y_ - other.y_)

---

operator+

Vector2 operator+(const Vector2<T>& other) const

功能说明

• 核心用途：计算当前向量与另一个向量的和
• 使用场景：向量加法运算
• 不修改原向量，返回新对象

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	加数向量，入参只读引用	Vector2 对象

返回值

• 返回类型：Vector2

返回向量和

返回值	触发场景
Vector2	(x_ + other.x_, y_ + other.y_)

---

operator*

Vector2 operator*(T scale) const

功能说明

• 核心用途：将向量各分量乘以标量值
• 使用场景：向量缩放运算
• 不修改原向量，返回新对象

入参

名称	参数类型	详细说明	约束取值范围
scale	T	缩放因子	模板参数类型范围

返回值

• 返回类型：Vector2

返回缩放后的新向量

返回值	触发场景
Vector2	(x_ * scale, y_ * scale)

---

operator==

bool operator==(const Vector2& other) const

功能说明

• 核心用途：判断当前向量与另一个向量是否相等
• 使用场景：向量比较
• 两向量的 x_ 和 y_ 分别相等时返回 true

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	待比较向量，入参只读引用	Vector2 对象

返回值

• 返回类型：bool

返回两向量是否相等

返回值	触发场景
true	x_ 和 y_ 均相等
false	任一分量不等

---

operator=

Vector2& operator=(const Vector2& other)

功能说明

• 核心用途：将另一个向量的值赋给当前对象
• 使用场景：向量赋值
• 赋值后返回当前对象的引用

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	源向量，入参只读引用	Vector2 对象

返回值

• 返回类型：Vector2&

返回当前对象的引用

返回值	触发场景
Vector2&	赋值后的当前对象引用

---

operator+=

Vector2& operator+=(const Vector2& other)

功能说明

• 核心用途：将另一个向量加到当前向量上
• 使用场景：向量复合加法运算
• 修改当前对象并返回引用

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	加数向量，入参只读引用	Vector2 对象

返回值

• 返回类型：Vector2&

返回当前对象的引用

返回值	触发场景
Vector2&	累加后的当前对象引用

---

operator-=

Vector2& operator-=(const Vector2& other)

功能说明

• 核心用途：从当前向量中减去另一个向量
• 使用场景：向量复合减法运算
• 修改当前对象并返回引用

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector2&	被减向量，入参只读引用	Vector2 对象

返回值

• 返回类型：Vector2&

返回当前对象的引用

返回值	触发场景
Vector2&	累减后的当前对象引用

OHOS::Vector3

Vector3(args...)

Vector3(T x, T y, T z)

功能说明

• 根据X、Y、Z坐标构造三维向量
• data_[0] 初始化为 x，data_[1] 初始化为 y，data_[2] 初始化为 z
• 构造后可直接用于向量运算

入参

名称	参数类型	详细说明	约束取值范围
x	T	X坐标值	模板参数类型范围
y	T	Y坐标值	模板参数类型范围
z	T	Z坐标值	模板参数类型范围

---

operator[]

T operator[](uint8_t index) const

功能说明

• 核心用途：只读下标访问向量分量
• 使用场景：通过索引读取 x_、y_、z_ 分量
• 不修改对象状态，const 成员函数

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	分量索引	0 ~ 2

返回值

• 返回类型：T

返回对应索引位置的分量值

返回值	触发场景
T	data_[index] 的值

---

operator[]

T& operator[](uint8_t index)

功能说明

• 核心用途：可写下标访问向量分量
• 使用场景：通过索引修改 x_、y_、z_ 分量
• 返回引用，可用于赋值

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	分量索引	0 ~ 2

返回值

• 返回类型：T&

返回对应索引位置分量的可写引用

返回值	触发场景
T&	data_[index] 的引用

---

operator==

bool operator==(const Vector3& other) const

功能说明

• 核心用途：判断当前三维向量与另一个三维向量是否相等
• 使用场景：向量比较
• 三维向量的 x_、y_、z_ 分别相等时返回 true

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector3&	待比较向量，入参只读引用	Vector3 对象

返回值

• 返回类型：bool

返回两向量是否相等

返回值	触发场景
true	x_、y_、z_ 均相等
false	任一分量不等

OHOS::Vector4

Vector4(args...)

Vector4(T x, T y, T z, T w)

功能说明

• 根据X、Y、Z、W坐标构造四维向量
• data_[0] 初始化为 x，data_[1] 初始化为 y，data_[2] 初始化为 z，data_[3] 初始化为 w
• 构造后可直接用于向量运算

入参

名称	参数类型	详细说明	约束取值范围
x	T	X坐标值	模板参数类型范围
y	T	Y坐标值	模板参数类型范围
z	T	Z坐标值	模板参数类型范围
w	T	W坐标值	模板参数类型范围

---

operator[]

T operator[](uint8_t index) const

功能说明

• 核心用途：只读下标访问向量分量
• 使用场景：通过索引读取 x_、y_、z_、w_ 分量
• 不修改对象状态，const 成员函数

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	分量索引	0 ~ 3

返回值

• 返回类型：T

返回对应索引位置的分量值

返回值	触发场景
T	data_[index] 的值

---

operator[]

T& operator[](uint8_t index)

功能说明

• 核心用途：可写下标访问向量分量
• 使用场景：通过索引修改 x_、y_、z_、w_ 分量
• 返回引用，可用于赋值

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	分量索引	0 ~ 3

返回值

• 返回类型：T&

返回对应索引位置分量的可写引用

返回值	触发场景
T&	data_[index] 的引用

---

operator==

bool operator==(const Vector4& other) const

功能说明

• 核心用途：判断当前四维向量与另一个四维向量是否相等
• 使用场景：向量比较
• 四维向量的 x_、y_、z_、w_ 分别相等时返回 true

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector4&	待比较向量，入参只读引用	Vector4 对象

返回值

• 返回类型：bool

返回两向量是否相等

返回值	触发场景
true	x_、y_、z_、w_ 均相等
false	任一分量不等

OHOS::Matrix3

Matrix3(args...)

Matrix3(T m00, T m01, T m02, T m10, T m11, T m12, T m20, T m21, T m22)

功能说明

• 根据9个元素值构造3x3矩阵
• 元素按行优先顺序排列：第一行 m00/m01/m02，第二行 m10/m11/m12，第三行 m20/m21/m22
• 构造后可直接用于矩阵运算

入参

名称	参数类型	详细说明	约束取值范围
m00	T	第1行第1列元素	模板参数类型范围
m01	T	第1行第2列元素	模板参数类型范围
m02	T	第1行第3列元素	模板参数类型范围
m10	T	第2行第1列元素	模板参数类型范围
m11	T	第2行第2列元素	模板参数类型范围
m12	T	第2行第3列元素	模板参数类型范围
m20	T	第3行第1列元素	模板参数类型范围
m21	T	第3行第2列元素	模板参数类型范围
m22	T	第3行第3列元素	模板参数类型范围

---

GetData

const T* GetData() const

功能说明

• 核心用途：获取3x3矩阵的数据指针
• 使用场景：需要直接读取矩阵原始数据的场景
• 返回指向内部数据数组的只读指针

返回值

• 返回类型：const T*

返回矩阵数据只读指针

返回值	触发场景
const T*	指向内部 data_ 数组的只读指针

---

Determinant

T Determinant() const

功能说明

• 核心用途：计算3x3矩阵的行列式
• 使用场景：判断矩阵是否可逆、计算逆矩阵
• const 成员函数，不修改对象状态

返回值

• 返回类型：T

返回行列式值

返回值	触发场景
T	行列式计算结果

---

Inverse

Matrix3 Inverse() const

功能说明

• 核心用途：计算3x3矩阵的逆矩阵
• 使用场景：逆变换计算
• 当行列式为0时返回当前矩阵自身（不可逆）

返回值

• 返回类型：Matrix3

返回逆矩阵

返回值	触发场景
Matrix3	逆矩阵结果；行列式为0时返回当前矩阵的副本

---

Rotate

static Matrix3 Rotate(T angle, const Vector2<T>& pivot)

功能说明

• 核心用途：获取绕指定枢轴点旋转指定角度的3x3变换矩阵
• 使用场景：二维图形旋转变换
• 旋转后矩阵数据左移15位，使用时需右移15位

入参

名称	参数类型	详细说明	约束取值范围
angle	T	旋转角度，单位为度	浮点数
pivot	const Vector2&	旋转枢轴点，入参只读引用	Vector2 对象

返回值

• 返回类型：Matrix3

返回旋转变换矩阵

返回值	触发场景
Matrix3	旋转变换矩阵

---

Scale

static Matrix3 Scale(const Vector2<T>& scale, const Vector2<T>& fixed)

功能说明

• 核心用途：获取以指定固定点为基准的缩放变换3x3矩阵
• 使用场景：二维图形缩放变换
• 缩放后矩阵数据左移8位，使用时需右移8位

入参

名称	参数类型	详细说明	约束取值范围
scale	const Vector2&	X轴和Y轴的缩放因子，入参只读引用	Vector2 对象
fixed	const Vector2&	固定缩放点，入参只读引用	Vector2 对象

返回值

• 返回类型：Matrix3

返回缩放变换矩阵

返回值	触发场景
Matrix3	缩放变换矩阵

---

Translate

static Matrix3<T> Translate(const Vector2<T>& trans)

功能说明

• 核心用途：获取沿X轴和Y轴平移指定距离的3x3变换矩阵
• 使用场景：二维图形平移变换

入参

名称	参数类型	详细说明	约束取值范围
trans	const Vector2&	X轴和Y轴的平移距离，入参只读引用	Vector2 对象

返回值

• 返回类型：Matrix3<T>

返回平移变换矩阵

返回值	触发场景
Matrix3	平移变换矩阵

---

operator*

Matrix3 operator*(const Matrix3& other) const

功能说明

• 核心用途：计算两个3x3矩阵的乘积
• 使用场景：组合多个变换矩阵
• 不修改原矩阵，返回新对象

入参

名称	参数类型	详细说明	约束取值范围
other	const Matrix3&	右乘矩阵，入参只读引用	Matrix3 对象

返回值

• 返回类型：Matrix3

返回矩阵乘积

返回值	触发场景
Matrix3	矩阵乘法结果

---

operator*

Vector3<T> operator*(const Vector3<T>& other) const

功能说明

• 核心用途：计算3x3矩阵与三维向量的乘积
• 使用场景：对向量进行矩阵变换
• 不修改原矩阵和向量，返回新对象

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector3&	被变换的三维向量，入参只读引用	Vector3 对象

返回值

• 返回类型：Vector3<T>

返回变换后的向量

返回值	触发场景
Vector3	矩阵与向量乘积结果

---

operator[]

T* operator[](uint8_t col)

功能说明

• 核心用途：按列下标访问矩阵数据
• 使用场景：通过列索引获取该列数据指针
• 返回指向该列首元素的指针

入参

名称	参数类型	详细说明	约束取值范围
col	uint8_t	列索引	0 ~ 2

返回值

• 返回类型：T*

返回该列数据指针

返回值	触发场景
T*	指向 data_[col * 3] 的指针

---

operator=

Matrix3& operator=(const Matrix3& other)

功能说明

• 核心用途：将另一个矩阵的值赋给当前对象
• 使用场景：矩阵赋值
• 逐元素复制9个数据，返回当前对象引用

入参

名称	参数类型	详细说明	约束取值范围
other	const Matrix3&	源矩阵，入参只读引用	Matrix3 对象

返回值

• 返回类型：Matrix3&

返回当前对象的引用

返回值	触发场景
Matrix3&	赋值后的当前对象引用

---

operator==

bool operator==(const Matrix3& other) const

功能说明

• 核心用途：判断两个3x3矩阵是否相等
• 使用场景：矩阵比较
• 逐元素比较9个数据是否全部相等

入参

名称	参数类型	详细说明	约束取值范围
other	const Matrix3&	待比较矩阵，入参只读引用	Matrix3 对象

返回值

• 返回类型：bool

返回两矩阵是否相等

返回值	触发场景
true	9个元素全部相等
false	任一元素不等

OHOS::Matrix4

Matrix4(args...)

Matrix4(T m00, T m01, T m02, T m03, T m10, T m11, T m12, T m13, T m20, T m21, T m22, T m23, T m30, T m31, T m32, T m33)

功能说明

• 根据16个元素值构造4x4矩阵
• 元素按行优先顺序排列
• 构造后可直接用于矩阵运算

入参

名称	参数类型	详细说明	约束取值范围
m00	T	第1行第1列元素	模板参数类型范围
m01	T	第1行第2列元素	模板参数类型范围
m02	T	第1行第3列元素	模板参数类型范围
m03	T	第1行第4列元素	模板参数类型范围
m10	T	第2行第1列元素	模板参数类型范围
m11	T	第2行第2列元素	模板参数类型范围
m12	T	第2行第3列元素	模板参数类型范围
m13	T	第2行第4列元素	模板参数类型范围
m20	T	第3行第1列元素	模板参数类型范围
m21	T	第3行第2列元素	模板参数类型范围
m22	T	第3行第3列元素	模板参数类型范围
m23	T	第3行第4列元素	模板参数类型范围
m30	T	第4行第1列元素	模板参数类型范围
m31	T	第4行第2列元素	模板参数类型范围
m32	T	第4行第3列元素	模板参数类型范围
m33	T	第4行第4列元素	模板参数类型范围

---

GetData

const T* GetData() const

功能说明

• 核心用途：获取4x4矩阵的数据指针
• 使用场景：需要直接读取矩阵原始数据的场景
• 返回指向内部数据数组的只读指针

返回值

• 返回类型：const T*

返回矩阵数据只读指针

返回值	触发场景
const T*	指向内部 data_ 数组的只读指针

---

Determinant

T Determinant() const

功能说明

• 核心用途：计算4x4矩阵的行列式
• 使用场景：判断矩阵是否可逆、计算逆矩阵
• const 成员函数，不修改对象状态

返回值

• 返回类型：T

返回行列式值

返回值	触发场景
T	行列式计算结果

---

Inverse

Matrix4<T> Inverse() const

功能说明

• 核心用途：计算4x4矩阵的逆矩阵
• 使用场景：逆变换计算
• 当行列式为0时返回当前矩阵自身（不可逆）

返回值

• 返回类型：Matrix4<T>

返回逆矩阵

返回值	触发场景
Matrix4	逆矩阵结果；行列式为0时返回当前矩阵的副本

---

Rotate

static Matrix4<T> Rotate(T cosA, T sinA, const Vector3<T>& pivot1, const Vector3<T>& pivot2)

功能说明

• 核心用途：根据余弦和正弦值获取绕指定轴旋转的4x4变换矩阵
• 使用场景：三维图形绕任意轴旋转变换
• pivot1 和 pivot2 定义旋转轴的两端点

入参

名称	参数类型	详细说明	约束取值范围
cosA	T	旋转角度的余弦值	[-1.0, 1.0]
sinA	T	旋转角度的正弦值	[-1.0, 1.0]
pivot1	const Vector3&	旋转轴端点1，入参只读引用	Vector3 对象
pivot2	const Vector3&	旋转轴端点2，入参只读引用	Vector3 对象

返回值

• 返回类型：Matrix4<T>

返回旋转变换矩阵

返回值	触发场景
Matrix4	旋转变换矩阵；pivot1与pivot2重合时返回单位矩阵

---

Rotate

static Matrix4<T> Rotate(T angle, const Vector3<T>& pivot1, const Vector3<T>& pivot2)

功能说明

• 核心用途：根据角度获取绕指定轴旋转的4x4变换矩阵
• 使用场景：三维图形绕任意轴旋转变换
• 内部通过 Sin 函数计算余弦和正弦值后调用 Rotate(cosA, sinA, pivot1, pivot2)

入参

名称	参数类型	详细说明	约束取值范围
angle	T	旋转角度，单位为度	浮点数
pivot1	const Vector3&	旋转轴端点1，入参只读引用	Vector3 对象
pivot2	const Vector3&	旋转轴端点2，入参只读引用	Vector3 对象

返回值

• 返回类型：Matrix4<T>

返回旋转变换矩阵

返回值	触发场景
Matrix4	旋转变换矩阵

---

Scale

static Matrix4<T> Scale(const Vector3<T>& scale, const Vector3<T>& fixed)

功能说明

• 核心用途：获取以指定固定点为基准的三维缩放变换4x4矩阵
• 使用场景：三维图形缩放变换
• scale 指定三轴缩放因子，fixed 指定缩放固定点

入参

名称	参数类型	详细说明	约束取值范围
scale	const Vector3&	X/Y/Z轴缩放因子，入参只读引用	Vector3 对象
fixed	const Vector3&	固定缩放点，入参只读引用	Vector3 对象

返回值

• 返回类型：Matrix4<T>

返回缩放变换矩阵

返回值	触发场景
Matrix4	缩放变换矩阵

---

Translate

static Matrix4<T> Translate(const Vector3<T>& trans)

功能说明

• 核心用途：获取沿X/Y/Z轴平移指定距离的4x4变换矩阵
• 使用场景：三维图形平移变换

入参

名称	参数类型	详细说明	约束取值范围
trans	const Vector3&	X/Y/Z轴的平移距离，入参只读引用	Vector3 对象

返回值

• 返回类型：Matrix4<T>

返回平移变换矩阵

返回值	触发场景
Matrix4	平移变换矩阵

---

Shear

static Matrix4<T> Shear(const Vector2<T>& shearX, const Vector2<T>& shearY, const Vector2<T>& shearZ)

功能说明

• 核心用途：获取三维错切变换4x4矩阵
• 使用场景：三维图形错切变换
• shearX/shearY/shearZ 分别指定各轴方向的错切参数

入参

名称	参数类型	详细说明	约束取值范围
shearX	const Vector2&	X轴方向错切参数，入参只读引用	Vector2 对象
shearY	const Vector2&	Y轴方向错切参数，入参只读引用	Vector2 对象
shearZ	const Vector2&	Z轴方向错切参数，入参只读引用	Vector2 对象

返回值

• 返回类型：Matrix4<T>

返回错切变换矩阵

返回值	触发场景
Matrix4	错切变换矩阵

---

operator*

Matrix4 operator*(const Matrix4& other) const

功能说明

• 核心用途：计算两个4x4矩阵的乘积
• 使用场景：组合多个三维变换矩阵
• 不修改原矩阵，返回新对象

入参

名称	参数类型	详细说明	约束取值范围
other	const Matrix4&	右乘矩阵，入参只读引用	Matrix4 对象

返回值

• 返回类型：Matrix4

返回矩阵乘积

返回值	触发场景
Matrix4	矩阵乘法结果

---

operator*

Vector4<T> operator*(const Vector4<T>& other) const

功能说明

• 核心用途：计算4x4矩阵与四维向量的乘积
• 使用场景：对向量进行4x4矩阵变换
• 不修改原矩阵和向量，返回新对象

入参

名称	参数类型	详细说明	约束取值范围
other	const Vector4&	被变换的四维向量，入参只读引用	Vector4 对象

返回值

• 返回类型：Vector4<T>

返回变换后的向量

返回值	触发场景
Vector4	矩阵与向量乘积结果

---

operator[]

T* operator[](uint8_t col)

功能说明

• 核心用途：按列下标访问矩阵数据
• 使用场景：通过列索引获取该列数据指针
• 返回指向该列首元素的指针

入参

名称	参数类型	详细说明	约束取值范围
col	uint8_t	列索引	0 ~ 3

返回值

• 返回类型：T*

返回该列数据指针

返回值	触发场景
T*	指向 data_[col * 4] 的指针

---

operator=

Matrix4& operator=(const Matrix4& other)

功能说明

• 核心用途：将另一个矩阵的值赋给当前对象
• 使用场景：矩阵赋值
• 逐元素复制16个数据，返回当前对象引用

入参

名称	参数类型	详细说明	约束取值范围
other	const Matrix4&	源矩阵，入参只读引用	Matrix4 对象

返回值

• 返回类型：Matrix4&

返回当前对象的引用

返回值	触发场景
Matrix4&	赋值后的当前对象引用

---

operator==

bool operator==(const Matrix4& other) const

功能说明

• 核心用途：判断两个4x4矩阵是否相等
• 使用场景：矩阵比较
• 逐元素比较16个数据是否全部相等

入参

名称	参数类型	详细说明	约束取值范围
other	const Matrix4&	待比较矩阵，入参只读引用	Matrix4 对象

返回值

• 返回类型：bool

返回两矩阵是否相等

返回值	触发场景
true	16个元素全部相等
false	任一元素不等

Structures

OHOS::Vector2

template<typename T>
class Vector2 : public HeapBase {
public:
    T x_;
    T y_;
};

成员说明：

成员名称	数据类型	描述
x_	T	X坐标分量
y_	T	Y坐标分量

OHOS::Vector3

template<typename T>
class Vector3 : public HeapBase {
public:
    union {
        struct {
            T x_;
            T y_;
            T z_;
        };
        T data_[3];
    };
};

成员说明：

成员名称	数据类型	描述
x_	T	X坐标分量
y_	T	Y坐标分量
z_	T	Z坐标分量
data_	T[3]	分量数组，与 x_/y_/z_ 共享内存

OHOS::Vector4

template<typename T>
class Vector4 : public HeapBase {
public:
    union {
        struct {
            T x_;
            T y_;
            T z_;
            T w_;
        };
        T data_[4];
    };
};

成员说明：

成员名称	数据类型	描述
x_	T	X坐标分量
y_	T	Y坐标分量
z_	T	Z坐标分量
w_	T	W坐标分量
data_	T[4]	分量数组，与 x_/y_/z_/w_ 共享内存