1 /* 2 * Copyright (c) 2023-2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Drawing 18 * @{ 19 * 20 * @brief Provides functions such as 2D graphics rendering, text drawing, and image display. 21 * 22 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 23 * 24 * @since 11 25 * @version 1.0 26 */ 27 28 /** 29 * @file drawing_matrix.h 30 * 31 * @brief Declares functions related to the <b>matrix</b> object in the drawing module. 32 * 33 * @kit ArkGraphics2D 34 * @library libnative_drawing.so 35 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 36 * @since 11 37 * @version 1.0 38 */ 39 40 #ifndef C_INCLUDE_DRAWING_MATRIX_H 41 #define C_INCLUDE_DRAWING_MATRIX_H 42 43 #include "drawing_error_code.h" 44 #include "drawing_types.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Creates an <b>OH_Drawing_Matrix</b> object. 52 * 53 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 54 * @return Returns the pointer to the <b>OH_Drawing_Matrix</b> object created. 55 * @since 11 56 * @version 1.0 57 */ 58 OH_Drawing_Matrix* OH_Drawing_MatrixCreate(void); 59 60 /** 61 * @brief Creates an <b>OH_Drawing_Matrix</b> copy object. 62 * 63 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 64 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 65 * @return Returns the pointer to the <b>OH_Drawing_Matrix</b> object created. 66 * @since 20 67 * @version 1.0 68 */ 69 OH_Drawing_Matrix* OH_Drawing_MatrixCopy(const OH_Drawing_Matrix* matrix); 70 71 /** 72 * @brief Creates an <b>OH_Drawing_Matrix</b> object with rotation. Sets matrix to 73 * rotate by degrees about a pivot point at (px, py). 74 * 75 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 76 * @param deg angle of axes relative to upright axes 77 * @param x pivot on x-axis. 78 * @param y pivot on y-axis. 79 * @since 12 80 * @version 1.0 81 */ 82 OH_Drawing_Matrix* OH_Drawing_MatrixCreateRotation(float deg, float x, float y); 83 84 /** 85 * @brief Creates an <b>OH_Drawing_Matrix</b> object with scale. Sets matrix to scale 86 * by sx and sy, about a pivot point at (px, py). 87 * 88 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 89 * @param sx horizontal scale factor. 90 * @param sy vertical scale factor. 91 * @param px pivot on x-axis. 92 * @param py pivot on y-axis. 93 * @return Returns the pointer to the <b>OH_Drawing_Matrix</b> object created. 94 * @since 12 95 * @version 1.0 96 */ 97 OH_Drawing_Matrix* OH_Drawing_MatrixCreateScale(float sx, float sy, float px, float py); 98 99 /** 100 * @brief Creates an <b>OH_Drawing_Matrix</b> object with translation. 101 * 102 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 103 * @param dx horizontal translation. 104 * @param dy vertical translation. 105 * @return Returns the pointer to the <b>OH_Drawing_Matrix</b> object created. 106 * @since 12 107 * @version 1.0 108 */ 109 OH_Drawing_Matrix* OH_Drawing_MatrixCreateTranslation(float dx, float dy); 110 111 /** 112 * @brief Sets the params for a matrix. 113 * 114 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 115 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 116 * @param scaleX horizontal scale factor to store 117 * @param skewX horizontal skew factor to store 118 * @param transX horizontal translation to store 119 * @param skewY vertical skew factor to store 120 * @param scaleY vertical scale factor to store 121 * @param transY vertical translation to store 122 * @param persp0 input x-axis values perspective factor to store 123 * @param persp1 input y-axis values perspective factor to store 124 * @param persp2 perspective scale factor to store 125 * @since 11 126 * @version 1.0 127 */ 128 void OH_Drawing_MatrixSetMatrix(OH_Drawing_Matrix* matrix, float scaleX, float skewX, float transX, 129 float skewY, float scaleY, float transY, float persp0, float persp1, float persp2); 130 131 /** 132 * @brief Enumerates of scale to fit flags, how matrix is constructed to map one rect to another. 133 * 134 * @since 12 135 * @version 1.0 136 */ 137 typedef enum { 138 /** 139 * Scales in x and y to fill destination rect. 140 */ 141 SCALE_TO_FIT_FILL, 142 /** 143 * Scales and aligns to left and top. 144 */ 145 SCALE_TO_FIT_START, 146 /** 147 * Scales and aligns to center. 148 */ 149 SCALE_TO_FIT_CENTER, 150 /** 151 * Scales and aligns to right and bottom. 152 */ 153 SCALE_TO_FIT_END, 154 } OH_Drawing_ScaleToFit; 155 156 /** 157 * @brief Sets matrix to scale and translate src rect to dst rect. 158 * 159 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 160 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 161 * @param src Indicates the pointer to an <b>OH_Drawing_Rect</b> object rect to map from. 162 * @param dst Indicates the pointer to an <b>OH_Drawing_Rect</b> object rect to map to. 163 * @param stf Scales to fit enum method. 164 * @return Returns true if dst is empty, and sets matrix to: 165 * | 0 0 0 | 166 * | 0 0 0 | 167 * | 0 0 1 | 168 * 169 * @since 12 170 * @version 1.0 171 */ 172 bool OH_Drawing_MatrixSetRectToRect(OH_Drawing_Matrix* matrix, const OH_Drawing_Rect* src, 173 const OH_Drawing_Rect* dst, OH_Drawing_ScaleToFit stf); 174 175 /** 176 * @brief Sets matrix to matrix multiplied by matrix constructed from rotating by degrees 177 * about pivot point(px, py), positive degrees rotates clockwise. 178 * Given: 179 * 180 * | A B C | | c -s dx | 181 * Matrix = | D E F |, R(degrees, px, py) = | s c dy | 182 * | G H I | | 0 0 1 | 183 * 184 * where: 185 * 186 * c = cos(degrees) 187 * s = sin(degrees) 188 * dx = s * py + (1 - c) * px 189 * dy = -s * px + (1 - c) * py 190 * 191 * sets Matrix to: 192 * 193 * | A B C | | c -s dx | | Ac+Bs -As+Bc A*dx+B*dy+C | 194 * Matrix * R(degrees, px, py) = | D E F | | s c dy | = | Dc+Es -Ds+Ec D*dx+E*dy+F | 195 * | G H I | | 0 0 1 | | Gc+Hs -Gs+Hc G*dx+H*dy+I | 196 * 197 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 198 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 199 * @param degree Indicates the angle of axes relative to upright axes. 200 * @param px Indicates the pivot on x-axis. 201 * @param py Indicates the pivot on y-axis. 202 * @since 12 203 * @version 1.0 204 */ 205 void OH_Drawing_MatrixPreRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py); 206 207 /** 208 * @brief Sets matrix to forward scale by sx and sy, about a pivot point at (px, py). 209 * Given: 210 * 211 * | A B C | | sx 0 dx | 212 * Matrix =| D E F |, S(sx, sy, px, py) = | 0 sy dy | 213 * | G H I | | 0 0 1 | 214 * 215 * where: 216 * 217 * dx = px - sx * px 218 * dy = py - sy * py 219 * 220 * sets Matrix to: 221 * 222 * | A B C | | sx 0 dx | | A*sx B*sy A*dx+B*dy+C | 223 * Matrix * S(sx, sy, px, py) = | D E F | | 0 sy dy | = | D*sx E*sy D*dx+E*dy+F | 224 * | G H I | | 0 0 1 | | G*sx H*sy G*dx+H*dy+I | 225 * 226 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 227 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 228 * @param sx Horizontal scale factor. 229 * @param sy Vertical scale factor. 230 * @param px Pivot on x-axis. 231 * @param py Pivot on y-axis. 232 * @since 12 233 * @version 1.0 234 */ 235 void OH_Drawing_MatrixPreScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py); 236 237 /** 238 * @brief Sets forward matrix to translate by dx and dy. 239 * Given: 240 * | A B C | | 1 0 dx | 241 * Matrix = | D E F |, T(dx, dy) = | 0 1 dy | 242 * | G H I | | 0 0 1 | 243 * sets Matrix to: 244 * | A B C | | 1 0 dx | | A B A*dx+B*dy+C | 245 * Matrix * T(dx, dy) = | D E F | | 0 1 dy | = | D E D*dx+E*dy+F | 246 * | G H I | | 0 0 1 | | G H G*dx+H*dy+I | 247 * 248 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 249 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 250 * @param dx Indicates the horizontal translation. 251 * @param dy Indicates the vertical translation. 252 * @since 12 253 * @version 1.0 254 */ 255 void OH_Drawing_MatrixPreTranslate(OH_Drawing_Matrix* matrix, float dx, float dy); 256 257 /** 258 * @brief Sets matrix to matrix constructed from rotating by degrees about pivot point(px, py), 259 * multiplied by matrix, positive degrees rotates clockwise. 260 * Given: 261 * 262 * | J K L | | c -s dx | 263 * Matrix = | M N O |, R(degrees, px, py) = | s c dy | 264 * | P Q R | | 0 0 1 | 265 * 266 * where: 267 * 268 * c = cos(degrees) 269 * s = sin(degrees) 270 * dx = s * py + (1 - c) * px 271 * dy = -s * px + (1 - c) * py 272 * 273 * sets Matrix to: 274 * 275 * |c -s dx| |J K L| |cJ-sM+dx*P cK-sN+dx*Q cL-sO+dx+R| 276 * R(degrees, px, py) * Matrix = |s c dy| |M N O| = |sJ+cM+dy*P sK+cN+dy*Q sL+cO+dy*R| 277 * |0 0 1| |P Q R| | P Q R| 278 * 279 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 280 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 281 * @param degree Indicates the angle of axes relative to upright axes. 282 * @param px Indicates the pivot on x-axis. 283 * @param py Indicates the pivot on y-axis. 284 * @since 12 285 * @version 1.0 286 */ 287 void OH_Drawing_MatrixPostRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py); 288 289 /** 290 * @brief Sets matrix to backward scale by sx and sy, about a pivot point at (px, py). 291 * Given: 292 * | J K L | | sx 0 dx | 293 * Matrix = | M N O |, S(sx, sy, px, py) = | 0 sy dy | 294 * | P Q R | | 0 0 1 | 295 * where: 296 * dx = px - sx * px 297 * dy = py - sy * py 298 * sets Matrix to: 299 * | sx 0 dx | | J K L | | sx*J+dx*P sx*K+dx*Q sx*L+dx+R | 300 * S(sx, sy, px, py) * Matrix = | 0 sy dy | | M N O | = | sy*M+dy*P sy*N+dy*Q sy*O+dy*R | 301 * | 0 0 1 | | P Q R | | P Q R | 302 * 303 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 304 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 305 * @param sx Horizontal scale factor. 306 * @param sy Vertical scale factor. 307 * @param px Pivot on x-axis. 308 * @param py Pivot on y-axis. 309 * @since 12 310 * @version 1.0 311 */ 312 void OH_Drawing_MatrixPostScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py); 313 314 /** 315 * @brief Sets backward matrix to translate by (dx, dy). 316 * Given: 317 * 318 * | J K L | | 1 0 dx | 319 * Matrix = | M N O |, T(dx, dy) = | 0 1 dy | 320 * | P Q R | | 0 0 1 | 321 * 322 * sets Matrix to: 323 * 324 * | 1 0 dx | | J K L | | J+dx*P K+dx*Q L+dx*R | 325 * T(dx, dy) * Matrix = | 0 1 dy | | M N O | = | M+dy*P N+dy*Q O+dy*R | 326 * | 0 0 1 | | P Q R | | P Q R | 327 * 328 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 329 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 330 * @param dx Indicates the horizontal translation. 331 * @param dy Indicates the vertical translation. 332 * @since 12 333 * @version 1.0 334 */ 335 void OH_Drawing_MatrixPostTranslate(OH_Drawing_Matrix* matrix, float dx, float dy); 336 337 /** 338 * @brief Reset matrix to identity, which has no effect on mapped point, sets matrix to: 339 * | 1 0 0 | 340 * | 0 1 0 | 341 * | 0 0 1 | 342 * 343 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 344 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 345 * @since 12 346 * @version 1.0 347 */ 348 void OH_Drawing_MatrixReset(OH_Drawing_Matrix* matrix); 349 350 /** 351 * @brief Sets matrix total to matrix a multiplied by matrix b. 352 * Given: 353 * | A B C | | J K L | 354 * a = | D E F |, b = | M N O | 355 * | G H I | | P Q R | 356 * sets Matrix total to: 357 * | A B C | | J K L | | AJ+BM+CP AK+BN+CQ AL+BO+CR | 358 * total = a * b = | D E F | * | M N O | = | DJ+EM+FP DK+EN+FQ DL+EO+FR | 359 * | G H I | | P Q R | | GJ+HM+IP GK+HN+IQ GL+HO+IR | 360 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 361 * @param total Indicates the pointer to an <b>OH_Drawing_Matrix</b> object that a * b. 362 * @param a Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 363 * @param b Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 364 * @since 12 365 * @version 1.0 366 */ 367 void OH_Drawing_MatrixConcat(OH_Drawing_Matrix* total, const OH_Drawing_Matrix* a, 368 const OH_Drawing_Matrix* b); 369 370 /** 371 * @brief Gets nine matrix values contained by matrix into array. 372 * 373 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 374 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 375 * @param value Storages for nine matrix values. 376 * @return Returns the error code. 377 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 378 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if matrix or value is nullptr. 379 * @since 12 380 * @version 1.0 381 */ 382 OH_Drawing_ErrorCode OH_Drawing_MatrixGetAll(OH_Drawing_Matrix* matrix, float value[9]); 383 384 /** 385 * @brief Get one matrix value. Index is between the range of 0-8. 386 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 387 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 388 * @param index one of 0-8. 389 * @return Returns value corresponding to index.Returns 0 if out of range. 390 * @since 12 391 * @version 1.0 392 */ 393 float OH_Drawing_MatrixGetValue(OH_Drawing_Matrix* matrix, int index); 394 395 /** 396 * @brief Sets matrix to rotate by degrees about a pivot point at (px, py). The pivot point is unchanged 397 * when mapped with matrix. Positive degrees rotates clockwise. 398 * 399 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 400 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 401 * @param degree Indicates the angle of axes relative to upright axes. 402 * @param px Indicates the pivot on x-axis. 403 * @param py Indicates the pivot on y-axis. 404 * @since 12 405 * @version 1.0 406 */ 407 void OH_Drawing_MatrixRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py); 408 409 /** 410 * @brief Sets matrix to translate by (dx, dy) 411 * 412 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 413 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 414 * @param dx Indicates the horizontal translation. 415 * @param dy Indicates the vertical translation. 416 * @since 12 417 * @version 1.0 418 */ 419 void OH_Drawing_MatrixTranslate(OH_Drawing_Matrix* matrix, float dx, float dy); 420 421 /** 422 * @brief Sets matrix to scale by sx and sy, about a pivot point at (px, py). 423 * 424 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 425 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 426 * @param sx Indicates the horizontal scale factor. 427 * @param sy Indicates the vertical scale factor. 428 * @param px Indicates the pivot on x-axis. 429 * @param py Indicates the pivot on y-axis. 430 * @since 12 431 * @version 1.0 432 */ 433 void OH_Drawing_MatrixScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py); 434 435 /** 436 * @brief Sets inverse to reciprocal matrix, returning true if matrix can be inverted. 437 * 438 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 439 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 440 * @param inverse Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 441 * @return Returns true if the matrix is not nullptr and can be inverted; 442 * returns false if the matrix is nullptr or cannot be inverted. 443 * @since 12 444 * @version 1.0 445 */ 446 bool OH_Drawing_MatrixInvert(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* inverse); 447 448 /** 449 * @brief Sets the params of matrix to map src to dst. 450 * Count must greater than or equal to zero, and less than or equal to four. 451 * 452 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 453 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 454 * @param src Points to map from. 455 * @param dst Points to map to. 456 * @param count Number of point in src and dst. 457 * @return Returns true if matrix is constructed successfully. 458 * @since 12 459 * @version 1.0 460 */ 461 bool OH_Drawing_MatrixSetPolyToPoly(OH_Drawing_Matrix* matrix, const OH_Drawing_Point2D* src, 462 const OH_Drawing_Point2D* dst, uint32_t count); 463 464 /** 465 * @brief Maps the src point array to the dst point array by matrix transformation. 466 * 467 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 468 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 469 * @param src Points to map from. 470 * @param dst Points to map to. 471 * @param count Number of point in src and dst. 472 * @since 12 473 * @version 1.0 474 */ 475 void OH_Drawing_MatrixMapPoints(const OH_Drawing_Matrix* matrix, const OH_Drawing_Point2D* src, 476 OH_Drawing_Point2D* dst, int count); 477 478 /** 479 * @brief Sets dst to bounds of src corners mapped by matrix transformation. 480 * 481 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 482 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 483 * @param src Rect to map from. 484 * @param dst Rect to map to. 485 * @return Returns true if the mapped src is equal to the dst; returns false is not equal. 486 * @since 12 487 * @version 1.0 488 */ 489 bool OH_Drawing_MatrixMapRect(const OH_Drawing_Matrix* matrix, const OH_Drawing_Rect* src, OH_Drawing_Rect* dst); 490 491 /** 492 * @brief Returns true if the first matrix equals the second matrix. 493 * 494 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 495 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 496 * @param other Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 497 * @return Returns true if the two matrices are equal; returns false if not equal. 498 * @since 12 499 * @version 1.0 500 */ 501 bool OH_Drawing_MatrixIsEqual(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* other); 502 503 /** 504 * @brief Returns true if matrix is identity. 505 * Identity matrix is : | 1 0 0 | 506 * | 0 1 0 | 507 * | 0 0 1 | 508 * 509 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 510 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 511 * @return Returns true if matrix is identity; returns false if not identity. 512 * @since 12 513 * @version 1.0 514 */ 515 bool OH_Drawing_MatrixIsIdentity(OH_Drawing_Matrix* matrix); 516 517 /** 518 * @brief Destroys an <b>OH_Drawing_Matrix</b> object and reclaims the memory occupied by the object. 519 * 520 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 521 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 522 * @since 11 523 * @version 1.0 524 */ 525 void OH_Drawing_MatrixDestroy(OH_Drawing_Matrix* matrix); 526 527 #ifdef __cplusplus 528 } 529 #endif 530 /** @} */ 531 #endif 532