1# drawing_matrix.h 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphic--> 5<!--Owner: @hangmengxin--> 6<!--Designer: @wangyanglan--> 7<!--Tester: @nobuggers--> 8<!--Adviser: @ge-yafang--> 9 10## 概述 11 12文件中定义了与矩阵相关的功能函数。 13 14<!--RP1--> 15**相关示例：** [NDKAPIDrawing (API14)](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Drawing/NDKAPIDrawing)<!--RP1End--> 16 17**引用文件：** <native_drawing/drawing_matrix.h> 18 19**库：** libnative_drawing.so 20 21**起始版本：** 11 22 23**相关模块：** [Drawing](capi-drawing.md) 24 25## 汇总 26 27### 枚举 28 29| 名称 | typedef关键字 | 描述 | 30| -- | -- | -- | 31| [OH_Drawing_ScaleToFit](#oh_drawing_scaletofit) | OH_Drawing_ScaleToFit | 矩阵缩放方式枚举。 | 32 33### 函数 34 35| 名称 | 描述 | 36| -- | -- | 37| [OH_Drawing_Matrix* OH_Drawing_MatrixCreate(void)](#oh_drawing_matrixcreate) | 用于创建一个矩阵对象。 | 38| [OH_Drawing_Matrix* OH_Drawing_MatrixCopy(const OH_Drawing_Matrix* matrix)](#oh_drawing_matrixcopy) | 用于创建一个矩阵对象的拷贝。 | 39| [OH_Drawing_Matrix* OH_Drawing_MatrixCreateRotation(float deg, float x, float y)](#oh_drawing_matrixcreaterotation) | 创建一个带旋转属性的矩阵对象。<br>该矩阵对象为：单位矩阵在(x, y)旋转点以度为单位进行旋转后得到的矩阵。 | 40| [OH_Drawing_Matrix* OH_Drawing_MatrixCreateScale(float sx, float sy, float px, float py)](#oh_drawing_matrixcreatescale) | 创建一个带缩放属性的矩阵对象。<br>该矩阵对象为：单位矩阵在(px, py)旋转点以sx和sy为缩放因子进行缩放后得到的矩阵。 | 41| [OH_Drawing_Matrix* OH_Drawing_MatrixCreateTranslation(float dx, float dy)](#oh_drawing_matrixcreatetranslation) | 创建一个带平移属性的矩阵对象。<br>该矩阵对象为：单位矩阵平移(dx, dy)后得到的矩阵。 | 42| [void OH_Drawing_MatrixSetMatrix(OH_Drawing_Matrix* matrix, float scaleX, float skewX, float transX,float skewY, float scaleY, float transY, float persp0, float persp1, float persp2)](#oh_drawing_matrixsetmatrix) | 用于给矩阵对象设置参数。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>OH_Drawing_Matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 43| [bool OH_Drawing_MatrixSetRectToRect(OH_Drawing_Matrix* matrix, const OH_Drawing_Rect* src,const OH_Drawing_Rect* dst, OH_Drawing_ScaleToFit stf)](#oh_drawing_matrixsetrecttorect) | 将矩阵以缩放方式适配目标矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 44| [void OH_Drawing_MatrixPreRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py)](#oh_drawing_matrixprerotate) | 将矩阵设置为矩阵左乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。 | 45| [void OH_Drawing_MatrixPreScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py)](#oh_drawing_matrixprescale) | 将矩阵设置为矩阵左乘围绕轴心点按一定缩放因子缩放后的单位矩阵后得到的矩阵。 | 46| [void OH_Drawing_MatrixPreTranslate(OH_Drawing_Matrix* matrix, float dx, float dy)](#oh_drawing_matrixpretranslate) | 将矩阵设置为矩阵左乘平移一定距离后的单位矩阵后得到的矩阵。 | 47| [void OH_Drawing_MatrixPostRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py)](#oh_drawing_matrixpostrotate) | 将矩阵设置为矩阵右乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。 | 48| [void OH_Drawing_MatrixPostScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py)](#oh_drawing_matrixpostscale) | 将矩阵设置为矩阵右乘围绕轴心点按一定缩放因子缩放后的单位矩阵后得到的矩阵。 | 49| [void OH_Drawing_MatrixPostTranslate(OH_Drawing_Matrix* matrix, float dx, float dy)](#oh_drawing_matrixposttranslate) | 将矩阵设置为矩阵右乘平移一定距离后的单位矩阵后得到的矩阵。 | 50| [void OH_Drawing_MatrixReset(OH_Drawing_Matrix* matrix)](#oh_drawing_matrixreset) | 重置当前矩阵为单位矩阵。 | 51| [void OH_Drawing_MatrixConcat(OH_Drawing_Matrix* total, const OH_Drawing_Matrix* a,const OH_Drawing_Matrix* b)](#oh_drawing_matrixconcat) | 将矩阵total设置为矩阵a乘以矩阵b。 | 52| [OH_Drawing_ErrorCode OH_Drawing_MatrixGetAll(OH_Drawing_Matrix* matrix, float value[9])](#oh_drawing_matrixgetall) | 获取矩阵所有元素值。 | 53| [float OH_Drawing_MatrixGetValue(OH_Drawing_Matrix* matrix, int index)](#oh_drawing_matrixgetvalue) | 获取矩阵给定索引位的值。索引范围0-8。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>index小于0或者大于8时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 | 54| [void OH_Drawing_MatrixRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py)](#oh_drawing_matrixrotate) | 设置矩阵为单位矩阵，并围绕位于(px, py)的旋转轴点进行旋转。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 55| [void OH_Drawing_MatrixTranslate(OH_Drawing_Matrix* matrix, float dx, float dy)](#oh_drawing_matrixtranslate) | 设置矩阵为单位矩阵，并平移(dx, dy)。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 56| [void OH_Drawing_MatrixScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py)](#oh_drawing_matrixscale) | 设置矩阵为单位矩阵，并围绕位于(px, py)的旋转轴点，以sx和sy进行缩放。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 57| [bool OH_Drawing_MatrixInvert(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* inverse)](#oh_drawing_matrixinvert) | 将矩阵inverse设置为矩阵的倒数，并返回结果。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、inverse任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 58| [bool OH_Drawing_MatrixSetPolyToPoly(OH_Drawing_Matrix* matrix, const OH_Drawing_Point2D* src,const OH_Drawing_Point2D* dst, uint32_t count)](#oh_drawing_matrixsetpolytopoly) | 通过设置源点以及目标点，生成对应的变换矩阵。<br>源点以及目标点的个数要大于等于0，小于等于4。本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>count小于0或者大于4时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 | 59| [void OH_Drawing_MatrixMapPoints(const OH_Drawing_Matrix* matrix, const OH_Drawing_Point2D* src,OH_Drawing_Point2D* dst, int count)](#oh_drawing_matrixmappoints) | 通过矩阵变换将源点数组映射到目标点数组。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、src、dst任意一个为NULL或者count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 60| [bool OH_Drawing_MatrixMapRect(const OH_Drawing_Matrix* matrix, const OH_Drawing_Rect* src, OH_Drawing_Rect* dst)](#oh_drawing_matrixmaprect) | 将目标矩形设置为一个新的矩形，该矩形是能够包围源矩形的四个顶点通过矩阵变换映射后形成的新顶点的最小矩形。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 61| [bool OH_Drawing_MatrixIsEqual(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* other)](#oh_drawing_matrixisequal) | 判断两个矩阵是否相等。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、other任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 62| [bool OH_Drawing_MatrixIsIdentity(OH_Drawing_Matrix* matrix)](#oh_drawing_matrixisidentity) | 判断矩阵是否是单位矩阵。 | 63| [void OH_Drawing_MatrixDestroy(OH_Drawing_Matrix* matrix)](#oh_drawing_matrixdestroy) | 用于销毁矩阵对象并回收该对象占有的内存。 | 64 65## 枚举类型说明 66 67### OH_Drawing_ScaleToFit 68 69``` 70enum OH_Drawing_ScaleToFit 71``` 72 73**描述** 74 75矩阵缩放方式枚举。 76 77**起始版本：** 12 78 79| 枚举项 | 描述 | 80| -- | -- | 81| SCALE_TO_FIT_FILL | 按水平轴和垂直轴缩放以填充目标矩形。 | 82| SCALE_TO_FIT_START | 缩放并对齐到左侧和顶部。 | 83| SCALE_TO_FIT_CENTER | 缩放并居中对齐。 | 84| SCALE_TO_FIT_END | 缩放并向右和向下对齐。 | 85 86 87## 函数说明 88 89### OH_Drawing_MatrixCreate() 90 91``` 92OH_Drawing_Matrix* OH_Drawing_MatrixCreate(void) 93``` 94 95**描述** 96 97用于创建一个矩阵对象。 98 99**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 100 101**起始版本：** 11 102 103**返回：** 104 105| 类型 | 说明 | 106| -- | -- | 107| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* | 函数会返回一个指针，指针指向创建的矩阵对象。 | 108 109### OH_Drawing_MatrixCopy() 110 111``` 112OH_Drawing_Matrix* OH_Drawing_MatrixCopy(const OH_Drawing_Matrix* matrix) 113``` 114 115**描述** 116 117用于创建一个矩阵对象的拷贝。 118 119**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 120 121**起始版本：** 20 122 123 124**参数：** 125 126| 参数项 | 描述 | 127| -- | -- | 128| const [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向用于拷贝的矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 129 130**返回：** 131 132| 类型 | 说明 | 133| -- | -- | 134| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* | 函数会返回一个指针，指针指向创建的新矩阵对象。 | 135 136### OH_Drawing_MatrixCreateRotation() 137 138``` 139OH_Drawing_Matrix* OH_Drawing_MatrixCreateRotation(float deg, float x, float y) 140``` 141 142**描述** 143 144创建一个带旋转属性的矩阵对象。<br>该矩阵对象为：单位矩阵在(x, y)旋转点以度为单位进行旋转后得到的矩阵。 145 146**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 147 148**起始版本：** 12 149 150 151**参数：** 152 153| 参数项 | 描述 | 154| -- | -- | 155| float deg | 旋转的角度，单位为度。正数表示按顺时针旋转，负数表示按逆时针旋转。 | 156| float x | 轴上坐标点。 | 157| float y | 轴上坐标点。 | 158 159**返回：** 160 161| 类型 | 说明 | 162| -- | -- | 163| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* | 函数返回一个指针，指针指向创建的矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)。 | 164 165### OH_Drawing_MatrixCreateScale() 166 167``` 168OH_Drawing_Matrix* OH_Drawing_MatrixCreateScale(float sx, float sy, float px, float py) 169``` 170 171**描述** 172 173创建一个带缩放属性的矩阵对象。<br>该矩阵对象为：单位矩阵在(px, py)旋转点以sx和sy为缩放因子进行缩放后得到的矩阵。 174 175**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 176 177**起始版本：** 12 178 179 180**参数：** 181 182| 参数项 | 描述 | 183| -- | -- | 184| float sx | 水平缩放因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。 | 185| float sy | 垂直缩放因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。 | 186| float px | 轴上坐标点。 | 187| float py | 轴上坐标点。 | 188 189**返回：** 190 191| 类型 | 说明 | 192| -- | -- | 193| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* | 函数返回一个指针，指针指向创建的矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)。 | 194 195### OH_Drawing_MatrixCreateTranslation() 196 197``` 198OH_Drawing_Matrix* OH_Drawing_MatrixCreateTranslation(float dx, float dy) 199``` 200 201**描述** 202 203创建一个带平移属性的矩阵对象。<br>该矩阵对象为：单位矩阵平移(dx, dy)后得到的矩阵。 204 205**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 206 207**起始版本：** 12 208 209 210**参数：** 211 212| 参数项 | 描述 | 213| -- | -- | 214| float dx | 水平方向平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。 | 215| float dy | 垂直方向平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。 | 216 217**返回：** 218 219| 类型 | 说明 | 220| -- | -- | 221| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* | 函数返回一个指针，指针指向创建的矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)。 | 222 223### OH_Drawing_MatrixSetMatrix() 224 225``` 226void OH_Drawing_MatrixSetMatrix(OH_Drawing_Matrix* matrix, float scaleX, float skewX, float transX,float skewY, float scaleY, float transY, float persp0, float persp1, float persp2) 227``` 228 229**描述** 230 231用于给矩阵对象设置参数。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>OH_Drawing_Matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 232 233**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 234 235**起始版本：** 11 236 237 238**参数：** 239 240| 参数项 | 描述 | 241| -- | -- | 242| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象的指针。 | 243| float scaleX | 水平缩放系数。 | 244| float skewX | 水平倾斜系数。 | 245| float transX | 水平位移系数。 | 246| float skewY | 垂直倾斜系数。 | 247| float scaleY | 垂直缩放系数。 | 248| float transY | 垂直位移系数。 | 249| float persp0 | X轴透视系数。 | 250| float persp1 | Y轴透视系数。 | 251| float persp2 | 透视缩放系数。 | 252 253### OH_Drawing_MatrixSetRectToRect() 254 255``` 256bool OH_Drawing_MatrixSetRectToRect(OH_Drawing_Matrix* matrix, const OH_Drawing_Rect* src,const OH_Drawing_Rect* dst, OH_Drawing_ScaleToFit stf) 257``` 258 259**描述** 260 261将矩阵以缩放方式适配目标矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 262 263**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 264 265**起始版本：** 12 266 267 268**参数：** 269 270| 参数项 | 描述 | 271| -- | -- | 272| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 273| const [OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)* src | 指向映射源的[OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)对象Rect的指针。 | 274| const [OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)* dst | 指向要映射到的[OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)对象Rect的指针。 | 275| [OH_Drawing_ScaleToFit](#oh_drawing_scaletofit) stf | 缩放方式，支持方式[OH_Drawing_ScaleToFit](capi-drawing-matrix-h.md#oh_drawing_scaletofit)。 | 276 277**返回：** 278 279| 类型 | 说明 | 280| -- | -- | 281| bool | 如果设置失败，则返回false；如果设置成功，则返回true；如果矩阵为空，则返回true，并将矩阵设置为：<br> 如果源矩形src的宽高任意一个小于等于0，则返回false，并将矩阵设置为单位矩阵；<br> 如果目标矩形dst的宽高任意一个小于等于0，则返回true，并将矩阵设置为除透视缩放系数为1外其余值皆为0的矩阵; | 282 283### OH_Drawing_MatrixPreRotate() 284 285``` 286void OH_Drawing_MatrixPreRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py) 287``` 288 289**描述** 290 291将矩阵设置为矩阵左乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 292 293**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 294 295**起始版本：** 12 296 297 298**参数：** 299 300| 参数项 | 描述 | 301| -- | -- | 302| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 303| float degree | 旋转角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转。 | 304| float px | 旋转中心点的横坐标。 | 305| float py | 旋转中心点的纵坐标。 | 306 307### OH_Drawing_MatrixPreScale() 308 309``` 310void OH_Drawing_MatrixPreScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py) 311``` 312 313**描述** 314 315将矩阵设置为矩阵左乘围绕轴心点按一定缩放因子缩放后的单位矩阵后得到的矩阵。 316 317本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 318 319**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 320 321**起始版本：** 12 322 323 324**参数：** 325 326| 参数项 | 描述 | 327| -- | -- | 328| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 329| float sx | 轴方向的缩放比例因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。 | 330| float sy | 轴方向的缩放比例因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。 | 331| float px | 缩放中心点的横坐标。 | 332| float py | 缩放中心点的纵坐标。 | 333 334### OH_Drawing_MatrixPreTranslate() 335 336``` 337void OH_Drawing_MatrixPreTranslate(OH_Drawing_Matrix* matrix, float dx, float dy) 338``` 339 340**描述** 341 342将矩阵设置为矩阵左乘平移一定距离后的单位矩阵后得到的矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 343 344**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 345 346**起始版本：** 12 347 348 349**参数：** 350 351| 参数项 | 描述 | 352| -- | -- | 353| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 354| float dx | 表示在x轴方向上的平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。 | 355| float dy | 表示在y轴方向上的平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。 | 356 357### OH_Drawing_MatrixPostRotate() 358 359``` 360void OH_Drawing_MatrixPostRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py) 361``` 362 363**描述** 364 365将矩阵设置为矩阵右乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 366 367**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 368 369**起始版本：** 12 370 371 372**参数：** 373 374| 参数项 | 描述 | 375| -- | -- | 376| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 377| float degree | 旋转角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转。 | 378| float px | 旋转中心点的横坐标。 | 379| float py | 旋转中心点的纵坐标。 | 380 381### OH_Drawing_MatrixPostScale() 382 383``` 384void OH_Drawing_MatrixPostScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py) 385``` 386 387**描述** 388 389将矩阵设置为矩阵右乘围绕轴心点按一定缩放因子缩放后的单位矩阵后得到的矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 390 391**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 392 393**起始版本：** 12 394 395 396**参数：** 397 398| 参数项 | 描述 | 399| -- | -- | 400| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 401| float sx | 轴方向的缩放比例因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。 | 402| float sy | 轴方向的缩放比例因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。 | 403| float px | 缩放中心点的横坐标。 | 404| float py | 缩放中心点的纵坐标。 | 405 406### OH_Drawing_MatrixPostTranslate() 407 408``` 409void OH_Drawing_MatrixPostTranslate(OH_Drawing_Matrix* matrix, float dx, float dy) 410``` 411 412**描述** 413 414将矩阵设置为矩阵右乘平移一定距离后的单位矩阵后得到的矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 415 416**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 417 418**起始版本：** 12 419 420 421**参数：** 422 423| 参数项 | 描述 | 424| -- | -- | 425| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 426| float dx | 表示在x轴方向上的平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。 | 427| float dy | 表示在y轴方向上的平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。 | 428 429### OH_Drawing_MatrixReset() 430 431``` 432void OH_Drawing_MatrixReset(OH_Drawing_Matrix* matrix) 433``` 434 435**描述** 436 437重置当前矩阵为单位矩阵。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 438 439**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 440 441**起始版本：** 12 442 443 444**参数：** 445 446| 参数项 | 描述 | 447| -- | -- | 448| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 449 450### OH_Drawing_MatrixConcat() 451 452``` 453void OH_Drawing_MatrixConcat(OH_Drawing_Matrix* total, const OH_Drawing_Matrix* a,const OH_Drawing_Matrix* b) 454``` 455 456**描述** 457 458将矩阵total设置为矩阵a乘以矩阵b。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>total、a、b任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 459 460**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 461 462**起始版本：** 12 463 464 465**参数：** 466 467| 参数项 | 描述 | 468| -- | -- | 469| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* total | 指向最终的矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 470| const [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* a | 指向矩阵对象a[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 471| const [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* b | 指向矩阵对象b[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 472 473### OH_Drawing_MatrixGetAll() 474 475``` 476OH_Drawing_ErrorCode OH_Drawing_MatrixGetAll(OH_Drawing_Matrix* matrix, float value[9]) 477``` 478 479**描述** 480 481获取矩阵所有元素值。 482 483**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 484 485**起始版本：** 12 486 487 488**参数：** 489 490| 参数项 | 描述 | 491| -- | -- | 492| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 493| value | 用于存储得到的矩阵元素值的数组。 | 494 495**返回：** 496 497| 类型 | 说明 | 498| -- | -- | 499| [OH_Drawing_ErrorCode](capi-drawing-error-code-h.md#oh_drawing_errorcode) | 返回错误码。<br> 返回OH_DRAWING_SUCCESS，表示成功获取矩阵的所有元素值。<br> 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示获取矩阵元素值失败，原因是矩阵对象或者存储矩阵元素值数组为空。 | 500 501### OH_Drawing_MatrixGetValue() 502 503``` 504float OH_Drawing_MatrixGetValue(OH_Drawing_Matrix* matrix, int index) 505``` 506 507**描述** 508 509获取矩阵给定索引位的值。索引范围0-8。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>index小于0或者大于8时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 510 511**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 512 513**起始版本：** 12 514 515 516**参数：** 517 518| 参数项 | 描述 | 519| -- | -- | 520| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 521| int index | 索引位置，范围0-8。 | 522 523**返回：** 524 525| 类型 | 说明 | 526| -- | -- | 527| float | 函数返回矩阵给定索引位对应的值。 | 528 529### OH_Drawing_MatrixRotate() 530 531``` 532void OH_Drawing_MatrixRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py) 533``` 534 535**描述** 536 537设置矩阵为单位矩阵，并围绕位于(px, py)的旋转轴点进行旋转。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 538 539**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 540 541**起始版本：** 12 542 543 544**参数：** 545 546| 参数项 | 描述 | 547| -- | -- | 548| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 549| float degree | 角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转。 | 550| float px | 轴上坐标点。 | 551| float py | 轴上坐标点。 | 552 553### OH_Drawing_MatrixTranslate() 554 555``` 556void OH_Drawing_MatrixTranslate(OH_Drawing_Matrix* matrix, float dx, float dy) 557``` 558 559**描述** 560 561设置矩阵为单位矩阵，并平移(dx, dy)。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 562 563**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 564 565**起始版本：** 12 566 567 568**参数：** 569 570| 参数项 | 描述 | 571| -- | -- | 572| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 573| float dx | 水平方向平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。 | 574| float dy | 垂直方向平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。 | 575 576### OH_Drawing_MatrixScale() 577 578``` 579void OH_Drawing_MatrixScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py) 580``` 581 582**描述** 583 584设置矩阵为单位矩阵，并围绕位于(px, py)的旋转轴点，以sx和sy进行缩放。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 585 586**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 587 588**起始版本：** 12 589 590 591**参数：** 592 593| 参数项 | 描述 | 594| -- | -- | 595| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 596| float sx | 水平缩放因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。 | 597| float sy | 垂直缩放因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。 | 598| float px | 轴上坐标点。 | 599| float py | 轴上坐标点。 | 600 601### OH_Drawing_MatrixInvert() 602 603``` 604bool OH_Drawing_MatrixInvert(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* inverse) 605``` 606 607**描述** 608 609将矩阵inverse设置为矩阵的倒数，并返回结果。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、inverse任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 610 611**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 612 613**起始版本：** 12 614 615 616**参数：** 617 618| 参数项 | 描述 | 619| -- | -- | 620| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 621| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* inverse | 指向逆矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针，开发者可调用[OH_Drawing_MatrixCreate](capi-drawing-matrix-h.md#oh_drawing_matrixcreate)接口创建。 | 622 623**返回：** 624 625| 类型 | 说明 | 626| -- | -- | 627| bool | 函数返回true表示矩阵可逆，inverse被填充为逆矩阵；函数返回false表示矩阵不可逆，inverse不被改变。 | 628 629### OH_Drawing_MatrixSetPolyToPoly() 630 631``` 632bool OH_Drawing_MatrixSetPolyToPoly(OH_Drawing_Matrix* matrix, const OH_Drawing_Point2D* src,const OH_Drawing_Point2D* dst, uint32_t count) 633``` 634 635**描述** 636 637通过设置源点以及目标点，生成对应的变换矩阵。<br>源点以及目标点的个数要大于等于0，小于等于4。本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>count小于0或者大于4时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 638 639**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 640 641**起始版本：** 12 642 643 644**参数：** 645 646| 参数项 | 描述 | 647| -- | -- | 648| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 649| const [OH_Drawing_Point2D](capi-drawing-oh-drawing-point2d.md)* src | 源点数组，为NULL时count应当为0。 | 650| const [OH_Drawing_Point2D](capi-drawing-oh-drawing-point2d.md)* dst | 目标点数组，个数要与源点相等，为NULL时count应当为0。 | 651| uint32_t count | 源点数组以及目标点数组的个数，为0时将矩阵对象设为单位矩阵。 | 652 653**返回：** 654 655| 类型 | 说明 | 656| -- | -- | 657| bool | 函数返回是否可以生成对应矩阵以用来完成变换。true表示矩阵生成成功，false表示无法生成对应矩阵。 | 658 659### OH_Drawing_MatrixMapPoints() 660 661``` 662void OH_Drawing_MatrixMapPoints(const OH_Drawing_Matrix* matrix, const OH_Drawing_Point2D* src,OH_Drawing_Point2D* dst, int count) 663``` 664 665**描述** 666 667通过矩阵变换将源点数组映射到目标点数组。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、src、dst任意一个为NULL或者count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 668 669**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 670 671**起始版本：** 12 672 673 674**参数：** 675 676| 参数项 | 描述 | 677| -- | -- | 678| const [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 679| const [OH_Drawing_Point2D](capi-drawing-oh-drawing-point2d.md)* src | 源点数组。 | 680| [OH_Drawing_Point2D](capi-drawing-oh-drawing-point2d.md)* dst | 目标点数组，个数要与源点相等。 | 681| int count | 源点数组以及目标点数组的个数。 | 682 683### OH_Drawing_MatrixMapRect() 684 685``` 686bool OH_Drawing_MatrixMapRect(const OH_Drawing_Matrix* matrix, const OH_Drawing_Rect* src, OH_Drawing_Rect* dst) 687``` 688 689**描述** 690 691将目标矩形设置为一个新的矩形，该矩形是能够包围源矩形的四个顶点通过矩阵变换映射后形成的新顶点的最小矩形。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 692 693**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 694 695**起始版本：** 12 696 697 698**参数：** 699 700| 参数项 | 描述 | 701| -- | -- | 702| const [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 703| const [OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)* src | 源矩形。 | 704| [OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)* dst | 目标矩形。 | 705 706**返回：** 707 708| 类型 | 说明 | 709| -- | -- | 710| bool | 函数返回源矩形与映射后的目标矩形是否相等。true表示相等，false表示不相等。 | 711 712### OH_Drawing_MatrixIsEqual() 713 714``` 715bool OH_Drawing_MatrixIsEqual(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* other) 716``` 717 718**描述** 719 720判断两个矩阵是否相等。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix、other任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 721 722**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 723 724**起始版本：** 12 725 726 727**参数：** 728 729| 参数项 | 描述 | 730| -- | -- | 731| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向用于判断的其中一个矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 732| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* other | 指向用于判断的另一个矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 733 734**返回：** 735 736| 类型 | 说明 | 737| -- | -- | 738| bool | 函数返回两个矩阵的比较结果，返回true表示两个矩阵相等，返回false表示两个矩阵不相等。 | 739 740### OH_Drawing_MatrixIsIdentity() 741 742``` 743bool OH_Drawing_MatrixIsIdentity(OH_Drawing_Matrix* matrix) 744``` 745 746**描述** 747 748判断矩阵是否是单位矩阵。<br>单位矩阵为 : | 1 0 0 || 0 1 0 || 0 0 1 |本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 749 750**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 751 752**起始版本：** 12 753 754 755**参数：** 756 757| 参数项 | 描述 | 758| -- | -- | 759| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向矩阵对象[OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)的指针。 | 760 761**返回：** 762 763| 类型 | 说明 | 764| -- | -- | 765| bool | 函数返回true表示矩阵是单位矩阵，函数返回false表示矩阵不是单位矩阵。 | 766 767### OH_Drawing_MatrixDestroy() 768 769``` 770void OH_Drawing_MatrixDestroy(OH_Drawing_Matrix* matrix) 771``` 772 773**描述** 774 775用于销毁矩阵对象并回收该对象占有的内存。 776 777**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 778 779**起始版本：** 11 780 781 782**参数：** 783 784| 参数项 | 描述 | 785| -- | -- | 786| [OH_Drawing_Matrix](capi-drawing-oh-drawing-matrix.md)* matrix | 指向字体对象的指针。 | 787 788 789