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