1 /* EINA - EFL data type library 2 * Copyright (C) 2007-2014 Jorge Luis Zapata 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library. 16 * If not, see <http://www.gnu.org/licenses/>. 17 */ 18 #ifndef EINA_MATRIX_H_ 19 #define EINA_MATRIX_H_ 20 21 #include "eina_quad.h" 22 23 /** 24 * @file 25 */ 26 27 /** 28 * @addtogroup Eina_Data_Types_Group Data Types 29 * 30 * @{ 31 */ 32 33 /** 34 * @defgroup Eina_Matrix_Group Matrix 35 * 36 * Eina includes a family of matrix types of different dimension sizes 37 * and underlying data types. Dimensions supported include 2x2, 3x3, 38 * and 4x4. A fixed point variation of the 3x3 matrix is also 39 * supported, which uses the Eina_F16p16 (Q16.16) data type. 40 * 41 * @{ 42 */ 43 44 /** 45 * @typedef Eina_Matrix_Type 46 * Matrix types 47 */ 48 typedef enum _Eina_Matrix_Type 49 { 50 EINA_MATRIX_TYPE_IDENTITY, /**< Identity matrix type */ 51 EINA_MATRIX_TYPE_AFFINE, /**< Affine matrix type */ 52 EINA_MATRIX_TYPE_PROJECTIVE, /**< Projective matrix type */ 53 EINA_MATRIX_TYPE_LAST /**< The total number of matrix types */ 54 } Eina_Matrix_Type; 55 56 /** 57 * @typedef Eina_Matrix_Axis 58 * Matrix Axes 59 */ 60 typedef enum _Eina_Matrix_Axis 61 { 62 EINA_MATRIX_AXIS_X, /**< X-Axis */ 63 EINA_MATRIX_AXIS_Y, /**< Y-Axis */ 64 EINA_MATRIX_AXIS_Z, /**< Z-Axis */ 65 } Eina_Matrix_Axis; 66 67 /** 68 * @defgroup Eina_Matrix3_Group 3x3 floating point matrices 69 * 70 * @brief Definition and operations for 3x3 matrices. 71 * 72 * @{ 73 */ 74 75 /** 76 * @typedef Eina_Matrix3 77 * A 3x3 floating point matrix. 78 */ 79 typedef struct _Eina_Matrix3 Eina_Matrix3; 80 81 /** 82 * @struct _Eina_Matrix3 83 * A 3x3 floating point matrix. 84 */ 85 struct _Eina_Matrix3 86 { 87 double xx; /**< xx in x' = (x * xx) + (y * xy) + xz */ 88 double xy; /**< xy in x' = (x * xx) + (y * xy) + xz */ 89 double xz; /**< xz in x' = (x * xx) + (y * xy) + xz */ 90 91 double yx; /**< yx in y' = (x * yx) + (y * yy) + yz */ 92 double yy; /**< yy in y' = (x * yx) + (y * yy) + yz */ 93 double yz; /**< yz in y' = (x * yx) + (y * yy) + yz */ 94 95 double zx; /**< zx in z' = (x * zx) + (y * zy) + zz */ 96 double zy; /**< zy in z' = (x * zx) + (y * zy) + zz */ 97 double zz; /**< zz in z' = (x * zx) + (y * zy) + zz */ 98 }; 99 100 /** 101 * @} 102 */ 103 104 /** 105 * @defgroup Eina_Matrix4_Group 4x4 Matrices in floating point 106 * 107 * @brief Definition and operations for 4x4 matrices. 108 * 109 * @{ 110 */ 111 112 /** 113 * @typedef Eina_Matrix4 114 * A 4x4 floating point matrix. 115 */ 116 typedef struct _Eina_Matrix4 Eina_Matrix4; 117 118 /** 119 * @struct Eina_Matrix4 120 * A 4x4 floating point matrix. 121 */ 122 struct _Eina_Matrix4 123 { 124 double xx; /**< xx in x' = (x * xx) + (y * xy) + (z * xz) + xw */ 125 double xy; /**< xy in x' = (x * xx) + (y * xy) + (z * xz) + xw */ 126 double xz; /**< xz in x' = (x * xx) + (y * xy) + (z * xz) + xw */ 127 double xw; /**< xw in x' = (x * xx) + (y * xy) + (z * xz) + xw */ 128 129 double yx; /**< yx in y' = (x * yx) + (y * yy) + (z * yz) + yw */ 130 double yy; /**< yy in y' = (x * yx) + (y * yy) + (z * yz) + yw */ 131 double yz; /**< yz in y' = (x * yx) + (y * yy) + (z * yz) + yw */ 132 double yw; /**< yw in y' = (x * yx) + (y * yy) + (z * yz) + yw */ 133 134 double zx; /**< zx in z' = (x * zx) + (y * zy) + (z * zz) + zw */ 135 double zy; /**< zy in z' = (x * zx) + (y * zy) + (z * zz) + zw */ 136 double zz; /**< zz in z' = (x * zx) + (y * zy) + (z * zz) + zw */ 137 double zw; /**< zw in z' = (x * zx) + (y * zy) + (z * zz) + zw */ 138 139 double wx; /**< wx in w' = (x * wx) + (y * wy) + (z * wz) + ww */ 140 double wy; /**< wy in w' = (x * wx) + (y * wy) + (z * wz) + ww */ 141 double wz; /**< wz in w' = (x * wx) + (y * wy) + (z * wz) + ww */ 142 double ww; /**< ww in w' = (x * wx) + (y * wy) + (z * wz) + ww */ 143 }; 144 145 /** 146 * @} 147 */ 148 149 /** 150 * @defgroup Eina_Matrix3_F16p16_Group 3x3 Matrices in fixed point 151 * 152 * @brief Definition and operations for 3x3 fixed point matrices. 153 * @{ 154 */ 155 156 /** 157 * @typedef Eina_Matrix3_F16p16 158 * A 3x3 fixed point (Q16.16) matrix. 159 */ 160 typedef struct _Eina_Matrix3_F16p16 Eina_Matrix3_F16p16; 161 162 /** 163 * @struct Eina_Matrix3_F16p16 164 * A 3x3 fixed point (Q16.16) matrix. 165 */ 166 struct _Eina_Matrix3_F16p16 167 { 168 Eina_F16p16 xx; /**< xx in x' = (x * xx) + (y * xy) + xz */ 169 Eina_F16p16 xy; /**< xy in x' = (x * xx) + (y * xy) + xz */ 170 Eina_F16p16 xz; /**< xz in x' = (x * xx) + (y * xy) + xz */ 171 172 Eina_F16p16 yx; /**< yx in y' = (x * yx) + (y * yy) + yz */ 173 Eina_F16p16 yy; /**< yy in y' = (x * yx) + (y * yy) + yz */ 174 Eina_F16p16 yz; /**< yz in y' = (x * yx) + (y * yy) + yz */ 175 176 Eina_F16p16 zx; /**< zx in z' = (x * zx) + (y * zy) + zz */ 177 Eina_F16p16 zy; /**< zy in z' = (x * zx) + (y * zy) + zz */ 178 Eina_F16p16 zz; /**< zz in z' = (x * zx) + (y * zy) + zz */ 179 }; 180 181 /** 182 * @brief Sets the given fixed point matrix to the identity matrix. 183 * 184 * @param[in] m The fixed point matrix to set. 185 * 186 * This function sets @p m to the identity matrix. No check is done on 187 * @p m. 188 * 189 * @since 1.14 190 */ 191 EAPI void eina_matrix3_f16p16_identity(Eina_Matrix3_F16p16 *m); 192 193 /** 194 * @brief Sets dst as the matrix multiplication (composition) of two 195 * Eina_F16p16 matrices. 196 * 197 * @param[in] m1 The first matrix. Must be non-NULL. 198 * @param[in] m2 The second matrix. Must be non-NULL. 199 * @param[out] dst The results matrix. 200 * 201 * In matrix multiplication, AB, the resultant matrix is created from 202 * the rows of A multiplied against the columns of B and summed. This 203 * is not a commutative; i.e. AB != BA, so the ordering of arguments 204 * @p m1 and @p m2 matters. 205 * 206 * @since 1.14 207 */ 208 EAPI void eina_matrix3_f16p16_compose(const Eina_Matrix3_F16p16 *m1, 209 const Eina_Matrix3_F16p16 *m2, 210 Eina_Matrix3_F16p16 *dst); 211 212 /** 213 * @brief Returns the type of the given fixed point matrix. 214 * 215 * @param[in] m The fixed point matrix. 216 * @return The type of the matrix. 217 * 218 * This function returns the type of the matrix @p m. No check is done 219 * on @p m. 220 * 221 * @since 1.14 222 */ 223 EAPI Eina_Matrix_Type eina_matrix3_f16p16_type_get(const Eina_Matrix3_F16p16 *m); 224 225 /** 226 * @} 227 */ 228 229 /** 230 * @addtogroup Eina_Matrix3_Group 231 * 232 * @{ 233 */ 234 235 /** Helper macro for printf formatting */ 236 #define EINA_MATRIX3_FORMAT "g %g %g | %g %g %g | %g %g %g" 237 /** Helper macro for printf formatting arg */ 238 #define EINA_MATRIX3_ARGS(m) (m)->xx, (m)->xy, (m)->xz, \ 239 (m)->yx, (m)->yy, (m)->yz, \ 240 (m)->zx, (m)->zy, (m)->zz 241 242 243 244 /** 245 * @brief Returns the type of the given floating point matrix. 246 * 247 * @param[in] m The floating point matrix. 248 * @return The type of the matrix. 249 * 250 * This function returns the type of the matrix @p m. No check is done 251 * on @p m. 252 * 253 * @since 1.14 254 */ 255 EAPI Eina_Matrix_Type eina_matrix3_type_get(const Eina_Matrix3 *m); 256 257 /** 258 * @brief Sets the values of the coefficients of the given floating 259 * point matrix. 260 * 261 * @param[out] m The floating point matrix. 262 * @param[in] xx The first coefficient value. 263 * @param[in] xy The second coefficient value. 264 * @param[in] xz The third coefficient value. 265 * @param[in] yx The fourth coefficient value. 266 * @param[in] yy The fifth coefficient value. 267 * @param[in] yz The sixth coefficient value. 268 * @param[in] zx The seventh coefficient value. 269 * @param[in] zy The eighth coefficient value. 270 * @param[in] zz The ninth coefficient value. 271 * 272 * This function sets the values of the coefficients of the matrix 273 * @p m. No check is done on @p m. 274 * 275 * @see eina_matrix3_values_get() 276 * 277 * @since 1.14 278 */ 279 EAPI void eina_matrix3_values_set(Eina_Matrix3 *m, 280 double xx, double xy, double xz, 281 double yx, double yy, double yz, 282 double zx, double zy, double zz); 283 284 /** 285 * @brief Gets the values of the coefficients of the given floating 286 * point matrix. 287 * 288 * @param[in] m The floating point matrix. 289 * @param[out] xx The first coefficient value. 290 * @param[out] xy The second coefficient value. 291 * @param[out] xz The third coefficient value. 292 * @param[out] yx The fourth coefficient value. 293 * @param[out] yy The fifth coefficient value. 294 * @param[out] yz The sixth coefficient value. 295 * @param[out] zx The seventh coefficient value. 296 * @param[out] zy The eighth coefficient value. 297 * @param[out] zz The ninth coefficient value. 298 * 299 * This function gets the values of the coefficients of the matrix 300 * @p m. No check is done on @p m. 301 * 302 * @see eina_matrix3_values_set() 303 * 304 * @since 1.14 305 */ 306 EAPI void eina_matrix3_values_get(const Eina_Matrix3 *m, 307 double *xx, double *xy, double *xz, 308 double *yx, double *yy, double *yz, 309 double *zx, double *zy, double *zz); 310 311 /** 312 * @brief Gets the values of the coefficients of the given fixed 313 * point matrix. 314 * 315 * @param[in] m The fixed point matrix. 316 * @param[out] xx The first coefficient value. 317 * @param[out] xy The second coefficient value. 318 * @param[out] xz The third coefficient value. 319 * @param[out] yx The fourth coefficient value. 320 * @param[out] yy The fifth coefficient value. 321 * @param[out] yz The sixth coefficient value. 322 * @param[out] zx The seventh coefficient value. 323 * @param[out] zy The eighth coefficient value. 324 * @param[out] zz The nine-th coefficient value. 325 * 326 * This function gets the values of the coefficients of the matrix 327 * @p m. No check is done on @p m. 328 * 329 * @see eina_matrix3_values_set() 330 * 331 * @since 1.14 332 */ 333 EAPI void eina_matrix3_fixed_values_get(const Eina_Matrix3 *m, 334 Eina_F16p16 *xx, Eina_F16p16 *xy, Eina_F16p16 *xz, 335 Eina_F16p16 *yx, Eina_F16p16 *yy, Eina_F16p16 *yz, 336 Eina_F16p16 *zx, Eina_F16p16 *zy, Eina_F16p16 *zz); 337 338 /** 339 * @brief Transforms the given floating point matrix to the given fixed 340 * point matrix. 341 * 342 * @param[in] m The floating point matrix. 343 * @param[out] fm The fixed point matrix. 344 * 345 * This function transforms the floating point matrix @p m to a fixed 346 * point matrix and stores the coefficients into the fixed point matrix 347 * @p fm. 348 * 349 * @since 1.14 350 */ 351 EAPI void eina_matrix3_matrix3_f16p16_to(const Eina_Matrix3 *m, 352 Eina_Matrix3_F16p16 *fm); 353 354 /** 355 * @brief Checks whether the two matrices are equivalent. 356 * 357 * @param[in] m1 The first matrix. 358 * @param[in] m2 The second matrix. 359 * @return @c EINA_TRUE if the two matrices are equal, @c EINA_FALSE otherwise. 360 * 361 * This function returns @c EINA_TRUE if the matrices @p m1 and @p m2 362 * are equal, @c EINA_FALSE otherwise. No check is done on the matrices. 363 * 364 * @since 1.14 365 */ 366 EAPI Eina_Bool eina_matrix3_equal(const Eina_Matrix3 *m1, const Eina_Matrix3 *m2); 367 368 /** 369 * @brief Sets dst as the matrix multiplication (composition) of two matrices. 370 * 371 * @param[in] m1 The first matrix. Must be non-NULL. 372 * @param[in] m2 The second matrix. Must be non-NULL. 373 * @param[out] dst The results matrix. 374 * 375 * In matrix multiplication, AB, the resultant matrix is created from 376 * the rows of A multiplied against the columns of B and summed. This 377 * is not commutative; i.e. AB != BA, so the ordering of arguments 378 * @p m1 and @p m2 matters. 379 * 380 * @since 1.14 381 */ 382 EAPI void eina_matrix3_compose(const Eina_Matrix3 *m1, 383 const Eina_Matrix3 *m2, 384 Eina_Matrix3 *dst); 385 386 /** 387 * @brief Sets the matrix values for a translation operation. 388 * 389 * @param[out] m The matrix. 390 * @param[in] tx The X coordinate translation. 391 * @param[in] ty The Y coordinate translation. 392 * 393 * @since 1.14 394 */ 395 EAPI void eina_matrix3_translate(Eina_Matrix3 *m, double tx, double ty); 396 397 /** 398 * @brief Sets the matrix values for a scaling operation. 399 * 400 * @param[out] m The matrix. 401 * @param[in] sx The X coordinate scaling factor. 402 * @param[in] sy The Y coordinate scaling factor. 403 * 404 * @since 1.14 405 */ 406 EAPI void eina_matrix3_scale(Eina_Matrix3 *m, double sx, double sy); 407 408 /** 409 * @brief Sets the matrix values for a rotation operation. 410 * @param[out] m The matrix. 411 * @param[in] rad The number of radians to rotate. 412 * 413 * @since 1.14 414 */ 415 EAPI void eina_matrix3_rotate(Eina_Matrix3 *m, double rad); 416 417 /** 418 * @brief Sets the given floating point matrix to the identity matrix. 419 * 420 * @param[out] m The matrix to set to identity. 421 * 422 * This function sets @p m to the identity matrix. No check is done on 423 * @p m. 424 * 425 * @since 1.14 426 */ 427 EAPI void eina_matrix3_identity(Eina_Matrix3 *m); 428 429 /** 430 * @brief Calculates the determinant of the given matrix. 431 * 432 * @param[in] m The matrix. 433 * @return The determinant. 434 * 435 * This function returns the determinant of the matrix @p m. No check 436 * is done on @p m. 437 * 438 * @since 1.14 439 */ 440 EAPI double eina_matrix3_determinant(const Eina_Matrix3 *m); 441 442 /** 443 * @brief Divides the given matrix by a scalar number. 444 * 445 * @param[in,out] m The matrix. 446 * @param[in] scalar The scalar number. 447 * 448 * This function divides the matrix @p m by @p scalar. No check 449 * is done on @p m. 450 * 451 * @since 1.14 452 */ 453 EAPI void eina_matrix3_divide(Eina_Matrix3 *m, double scalar); 454 455 /** 456 * @brief Computes the inverse of the given matrix. 457 * 458 * @param[in] m The source matrix. 459 * @param[out] m2 The inverse matrix. 460 * 461 * This function inverts the matrix @p m and stores the result in 462 * @p m2. No check is done on @p m or @p m2. If @p m cannot be 463 * inverted, then @p m2 is set to the identity matrix. 464 * 465 * @since 1.14 466 */ 467 EAPI void eina_matrix3_inverse(const Eina_Matrix3 *m, Eina_Matrix3 *m2); 468 469 /** 470 * @brief Computes the transpose of the given matrix. 471 * 472 * @param[in] m The source matrix. 473 * @param[out] a The transposed matrix. 474 * 475 * This function transposes the matrix @p m and stores the result in 476 * @p a. No check is done on @p m or @p a. The transpose of a matrix 477 * essentially flips a matrix over its diagonal. 478 * 479 * @since 1.14 480 */ 481 EAPI void eina_matrix3_transpose(const Eina_Matrix3 *m, Eina_Matrix3 *a); 482 483 /** 484 * @brief Computes the cofactor of the given matrix. 485 * 486 * @param[in] m The source matrix. 487 * @param[out] a The cofactored matrix. 488 * 489 * This function cofactors the matrix @p m and stores the result in 490 * @p a. No check is done on @p m or @p a. The cofactor of a matrix3 at 491 * row i, column j is computed by taking the determinant of the 492 * submatrix formed by deleting the i-th row and j-th column, and then 493 * multiplying by (-1)^(i+j). 494 * 495 * @since 1.14 496 */ 497 EAPI void eina_matrix3_cofactor(const Eina_Matrix3 *m, Eina_Matrix3 *a); 498 499 /** 500 * @brief Computes the adjoint of the given matrix. 501 * 502 * @param[in] m The matrix to be adjointed. 503 * @param[out] a The adjoint matrix. 504 * 505 * This function finds the adjoint of the matrix @p m and stores the 506 * result in @p a. No check is done on @p m or @p a. The adjoint of a 507 * matrix3 is effectively the transpose of its cofactor. 508 * 509 * @since 1.14 510 */ 511 EAPI void eina_matrix3_adjoint(const Eina_Matrix3 *m, Eina_Matrix3 *a); 512 513 /** 514 * @brief Computes the transform of a 2D point using the given matrix. 515 * 516 * @param[in] m The transformation matrix to apply. 517 * @param[in] x The x point to be transformed. 518 * @param[in] y The y point to be transformed. 519 * @param[out] xr The transformed x point. 520 * @param[out] yr The transformed y point. 521 * 522 * Applies the transformation matrix @p m to the point (x,y), and stores 523 * the result in (*xr,*yr). No check is done on @p m; @p xr and @p yr 524 * must point to valid memory. A fast-path is included for if the zx 525 * and zy components of the matrix are zero. 526 * 527 * @since 1.14 528 */ 529 EAPI void eina_matrix3_point_transform(const Eina_Matrix3 *m, 530 double x, double y, 531 double *xr, double *yr); 532 /** 533 * @brief Computes the transformation of a rectangle using the given matrix. 534 * 535 * @param[in] m The transformation matrix to apply. 536 * @param[in] r The rectangle to be transformed. 537 * @param[out] q The resultant transformed points. 538 * 539 * Performs a point transformation of each corner of the rectangle @p r, 540 * and stores the result in the quadrangle @p q. No checks are done on the 541 * inputs, and @p q must point to valid memory. 542 * 543 * @since 1.14 544 */ 545 EAPI void eina_matrix3_rectangle_transform(const Eina_Matrix3 *m, 546 const Eina_Rectangle *r, 547 const Eina_Quad *q); 548 549 /** 550 * @brief Creates a projective matrix that maps a quadrangle to a quadrangle. 551 * 552 * @param[out] m The transformation matrix to create. 553 * @param[in] src The source quadrangle. 554 * @param[in] dst The destination quadrangle. 555 * @return @c EINA_TRUE if matrix could be successfully created, @c EINA_FALSE otherwise. 556 * 557 * Calculates a matrix @p m that can be used to transform from an arbitrary 558 * source quadrangle @p src to another arbitrary quadrangle @p dst. 559 */ 560 EAPI Eina_Bool eina_matrix3_quad_quad_map(Eina_Matrix3 *m, 561 const Eina_Quad *src, 562 const Eina_Quad *dst); 563 564 /** 565 * @brief Creates a matrix for unit-square to quad mapping. 566 * 567 * @param[out] m The transformation matrix to create. 568 * @param[in] q The source quadrangle. 569 * @return @c EINA_TRUE if matrix could be successfully created, @c EINA_FALSE otherwise. 570 * 571 * Calculates a matrix @p m that can be used to transform an arbitrary 572 * quadrangle @p q into a square. If @p q is a parallelogram, then a 573 * fast path affine transformation is used, otherwise it computes the 574 * matrix using a full projective transformation operation. No other 575 * checks are done on @p m or @p q. 576 * 577 * @since 1.14 578 */ 579 EAPI Eina_Bool eina_matrix3_square_quad_map(Eina_Matrix3 *m, 580 const Eina_Quad *q); 581 582 /** 583 * @brief Creates a matrix for mapping squares to match quad. 584 * 585 * @param[out] m The transformation matrix to create. 586 * @param[in] q The source quadrangle. 587 * @return @c EINA_FALSE on successful transform creation, @c EINA_FALSE otherwise. 588 * 589 * Calculates a matrix @p m that can be used to transform a square to 590 * fit a given quadrangle. The created matrix will always have its zz 591 * element equal to 1.0. The @p m matrix and @p q quad must be valid 592 * memory. 593 * 594 * @since 1.14 595 */ 596 EAPI Eina_Bool eina_matrix3_quad_square_map(Eina_Matrix3 *m, 597 const Eina_Quad *q); 598 599 /** 600 * @brief Sets matrix values using an array. 601 * 602 * @param[out] m The result matrix. 603 * @param[in] v The array[9] of values. 604 * 605 * Uses the first 9 elements in the given C array @p v to set the 606 * values in the matrix @p m. The values will be set in the order 607 * of the elements in the Eina_Matrix3 structure. 608 * 609 * @since 1.17 610 */ 611 EAPI void eina_matrix3_array_set(Eina_Matrix3 *m, const double *v); 612 613 /** 614 * @brief Copies a matrix. 615 * 616 * @param[out] dst Copy of the matrix. 617 * @param[in] src The matrix to copy. 618 * 619 * @since 1.16 620 */ 621 EAPI void eina_matrix3_copy(Eina_Matrix3 *dst, const Eina_Matrix3 *src); 622 623 /** 624 * @brief Multiplies two matrices. 625 * 626 * @param[out] out The resulting matrix. 627 * @param[in] mat_a The first member of the multiplication. 628 * @param[in] mat_b The second member of the multiplication. 629 * 630 * @p out must not point to the same structure as @p mat_a or @p mat_b, 631 * else the calculation results will be incorrect. Use 632 * eina_matrix3_multiply_copy() instead in this case. 633 * 634 * @since 1.17 635 */ 636 EAPI void eina_matrix3_multiply(Eina_Matrix3 *out, const Eina_Matrix3 *mat_a, 637 const Eina_Matrix3 *mat_b); 638 639 /** 640 * @brief Multiplies two matrices without overwriting them. 641 * 642 * @param[out] out The resulting matrix. 643 * @param[in] mat_a The first member of the multiplication. 644 * @param[in] mat_b The second member of the multiplication. 645 * 646 * Safely multiplies @p mat_a and @p mat_b by checking if the @p out 647 * parameter points to either of them, and if so uses a temporary matrix 648 * for the intermediary calculations. 649 * 650 * @since 1.17 651 */ 652 EAPI void eina_matrix3_multiply_copy(Eina_Matrix3 *out, const Eina_Matrix3 *mat_a, 653 const Eina_Matrix3 *mat_b); 654 655 /** 656 * @brief Sets the scale parameters (XX, YY) of a matrix. 657 * 658 * @param[out] out The resulting matrix. 659 * @param[in] s_x The scale value for x. 660 * @param[in] s_y The scale value for y. 661 * 662 * Sets only the XX and YY components of the matrix, leaving the rest of 663 * the matrix as it was. 664 * 665 * @since 1.17 666 */ 667 EAPI void eina_matrix3_scale_transform_set(Eina_Matrix3 *out, double s_x, double s_y); 668 669 /** 670 * @brief Sets the positional parameters (XZ, YZ) of a matrix. 671 * 672 * @param[out] out The resulting matrix. 673 * @param[in] p_x The position value for x. 674 * @param[in] p_y The position value for y. 675 * 676 * Sets only the XZ and YZ components of the matrix, leaving the rest of 677 * the matrix as it was. 678 679 * @since 1.17 680 */ 681 EAPI void eina_matrix3_position_transform_set(Eina_Matrix3 *out, const double p_x, 682 const double p_y); 683 684 /** 685 * @brief Sets normal of the given matrix. 686 * 687 * @param[out] out The resulting matrix. 688 * @param[in] m The matrix. 689 * 690 * @since 1.17 691 */ 692 EAPI void eina_normal3_matrix_get(Eina_Matrix3 *out, const Eina_Matrix4 *m); 693 694 /** 695 * @brief Converts an Eina_Matrix3 into an Eina_Matrix4. 696 * 697 * @param[out] m3 The destination Eina_Matrix3. 698 * @param[in] m4 The source Eina_Matrix4. 699 * 700 * @since 1.15 701 */ 702 EAPI void eina_matrix3_matrix4_to(Eina_Matrix4 *m4, const Eina_Matrix3 *m3); 703 704 /** 705 * @} 706 */ 707 708 /** 709 * @addtogroup Eina_Matrix4_Group 710 * 711 * @{ 712 */ 713 714 /** 715 * @brief Returns the type of the given floating point matrix. 716 * 717 * @param[in] m The floating point matrix. 718 * @return The type of the matrix. 719 * 720 * This function returns the type of the matrix @p m. No check is done 721 * on @p m. 722 * 723 * @since 1.15 724 */ 725 EAPI Eina_Matrix_Type eina_matrix4_type_get(const Eina_Matrix4 *m); 726 727 /** 728 * @brief Sets the values of the coefficients of the given floating 729 * point matrix. 730 * 731 * @param[out] m The floating point matrix. 732 * @param[in] xx The first coefficient value. 733 * @param[in] xy The second coefficient value. 734 * @param[in] xz The third coefficient value. 735 * @param[in] xw The fourth coefficient value. 736 * @param[in] yx The fifth coefficient value. 737 * @param[in] yy The sixth coefficient value. 738 * @param[in] yz The seventh coefficient value. 739 * @param[in] yw The eighth coefficient value. 740 * @param[in] zx The ninth coefficient value. 741 * @param[in] zy The tenth coefficient value. 742 * @param[in] zz The eleventh coefficient value. 743 * @param[in] zw The twelfth coefficient value. 744 * @param[in] wx The thirteenth coefficient value. 745 * @param[in] wy The fourteenth coefficient value. 746 * @param[in] wz The fifteenth coefficient value. 747 * @param[in] ww The sixteenth coefficient value. 748 * 749 * This function sets the values of the coefficients of the matrix 750 * @p m. No check is done on @p m. 751 * 752 * @see eina_matrix4_values_get() 753 * 754 * @since 1.15 755 */ 756 EAPI void eina_matrix4_values_set(Eina_Matrix4 *m, 757 double xx, double xy, double xz, double xw, 758 double yx, double yy, double yz, double yw, 759 double zx, double zy, double zz, double zw, 760 double wx, double wy, double wz, double ww); 761 762 /** 763 * @brief Gets the values of the coefficients of the given floating 764 * point matrix. 765 * 766 * @param[in] m The floating point matrix. 767 * @param[out] xx The first coefficient value. 768 * @param[out] xy The second coefficient value. 769 * @param[out] xz The third coefficient value. 770 * @param[out] xw The fourth coefficient value. 771 * @param[out] yx The fifth coefficient value. 772 * @param[out] yy The sixth coefficient value. 773 * @param[out] yz The seventh coefficient value. 774 * @param[out] yw The eighth coefficient value. 775 * @param[out] zx The ninth coefficient value. 776 * @param[out] zy The tenth coefficient value. 777 * @param[out] zz The eleventh coefficient value. 778 * @param[out] zw The twelfth coefficient value. 779 * @param[out] wx The thirteenth coefficient value. 780 * @param[out] wy The fourteenth coefficient value. 781 * @param[out] wz The fifteenth coefficient value. 782 * @param[out] ww The sixteenth coefficient value. 783 * 784 * This function gets the values of the coefficients of the matrix 785 * @p m. No check is done on @p m. 786 * 787 * @see eina_matrix4_values_set() 788 * 789 * @since 1.15 790 */ 791 EAPI void eina_matrix4_values_get(const Eina_Matrix4 *m, 792 double *xx, double *xy, double *xz, double *xw, 793 double *yx, double *yy, double *yz, double *yw, 794 double *zx, double *zy, double *zz, double *zw, 795 double *wx, double *wy, double *wz, double *ww); 796 797 /** 798 * @brief Calculates the determinant of the given matrix. 799 * 800 * @param[in] m The matrix. 801 * @return The determinant. 802 * 803 * This function returns the determinant of the matrix @p m. No check 804 * is done on @p m. 805 * 806 * @since 1.16 807 */ 808 EAPI double eina_matrix4_determinant(const Eina_Matrix4 *m); 809 810 /** 811 * @brief Normalizes the given matrix. 812 * 813 * @param[out] out The normalized matrix. 814 * @param[in] in The matrix. 815 * @return @c EINA_FALSE if matrix could not be normalized, @c EINA_TRUE 816 * otherwise. 817 * 818 * This function returns the determinant of the matrix @p in. No check 819 * is done on @p in. 820 * 821 * @since 1.16 822 */ 823 EAPI Eina_Bool eina_matrix4_normalized(Eina_Matrix4 *out, 824 const Eina_Matrix4 *in); 825 826 /** 827 * @brief Computes the inverse of the given matrix. 828 * 829 * @param[out] out The inverse matrix. 830 * @param[in] in The matrix. 831 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. 832 * 833 * This function inverts the matrix @p in and stores the result in 834 * @p out. No check is done on @p in or @p out. If @p in cannot be 835 * inverted, then @c EINA_FALSE is returned. 836 * 837 * @since 1.16 838 */ 839 EAPI Eina_Bool eina_matrix4_inverse(Eina_Matrix4 *out, const Eina_Matrix4 *in); 840 841 /** 842 * @brief Computes the transpose of the given matrix. 843 * 844 * @param[out] out The transposed matrix. 845 * @param[in] in The source matrix. 846 * 847 * This function transposes the matrix @p in and stores the result in 848 * @p out. No check is done on @p in or @p out. The transpose of a matrix 849 * essentially flips a matrix over its diagonal. 850 * 851 * @since 1.16 852 */ 853 EAPI void eina_matrix4_transpose(Eina_Matrix4 *out, const Eina_Matrix4 *in); 854 855 /** 856 * @brief Converts an Eina_Matrix4 into an Eina_Matrix3. 857 * 858 * @param[out] m3 The destination Eina_Matrix3. 859 * @param[in] m4 The source Eina_Matrix4. 860 * 861 * @since 1.15 862 */ 863 EAPI void eina_matrix4_matrix3_to(Eina_Matrix3 *m3, const Eina_Matrix4 *m4); 864 865 /** 866 * @brief Sets the given matrix to identity. 867 * 868 * @param[out] out The matrix to set. 869 * 870 * @since 1.16 871 */ 872 EAPI void eina_matrix4_identity(Eina_Matrix4 *out); 873 874 /** 875 * @brief Multiplies two matrix. 876 * 877 * @param[out] out The resulting matrix. 878 * @param[in] mat_a The first member of the multiplication. 879 * @param[in] mat_b The second member of the multiplication. 880 * 881 * Safely multiplies @p mat_a and @p mat_b by checking if the @p out 882 * parameter points to either of them, and if so uses a temporary matrix 883 * for the intermediary calculations. 884 * 885 * @since 1.17 886 */ 887 EAPI void eina_matrix4_multiply_copy(Eina_Matrix4 *out, 888 const Eina_Matrix4 *mat_a, const Eina_Matrix4 *mat_b); 889 890 /** 891 * @brief Sets matrix values using an array. 892 * 893 * @param[out] m The result matrix. 894 * @param[in] v The the array[16] of values. 895 * 896 * Uses the first 16 elements in the given C array @p v to set the 897 * values in the matrix @p m. The values will be set in the order 898 * of the elements in the Eina_Matrix4 structure. 899 * 900 * @since 1.17 901 */ 902 EAPI void eina_matrix4_array_set(Eina_Matrix4 *m, const double *v); 903 904 /** 905 * @brief Copies matrix. 906 * 907 * @param[out] dst The matrix copy. 908 * @param[in] src The matrix to copy. 909 * 910 * @since 1.17 911 */ 912 EAPI void eina_matrix4_copy(Eina_Matrix4 *dst, const Eina_Matrix4 *src); 913 914 /** 915 * @brief Multiplies two matrices with check. 916 * 917 * @param[out] out The resulting matrix. 918 * @param[in] mat_a The first member of the multiplication. 919 * @param[in] mat_b The second member of the multiplication. 920 * 921 * @since 1.17 922 */ 923 EAPI void eina_matrix4_multiply(Eina_Matrix4 *out, const Eina_Matrix4 *mat_a, 924 const Eina_Matrix4 *mat_b); 925 926 /** 927 * @brief Sets orthogonality matrix. 928 * 929 * @param[out] m The resulting matrix. 930 * @param[in] right The right value. 931 * @param[in] left The left value. 932 * @param[in] bottom The bottom value. 933 * @param[in] top The top value. 934 * @param[in] dnear The dnear value. 935 * @param[in] dfar The dfar value. 936 * 937 * @since 1.17 938 */ 939 EAPI void eina_matrix4_ortho_set(Eina_Matrix4 *m, 940 double left, double right, double bottom, double top, 941 double dnear, double dfar); 942 943 944 /** 945 * @brief Sets out as the matrix multiplication (composition) of two matrices. 946 * 947 * @param[in] mat_a The first matrix. Must be non-NULL. 948 * @param[in] mat_b The second matrix. Must be non-NULL. 949 * @param[out] out The results matrix. 950 * 951 * In matrix multiplication, AB, the resultant matrix is created from 952 * the rows of A multiplied against the columns of B and summed. This 953 * is not commutative; i.e. AB != BA, so the ordering of arguments 954 * @p m1 and @p m2 matters. 955 * 956 * @since 1.24 957 */ 958 EAPI void eina_matrix4_compose(const Eina_Matrix4 *mat_a, 959 const Eina_Matrix4 *mat_b, 960 Eina_Matrix4 *out); 961 962 /** 963 * @brief Sets the matrix values for a translation operation. 964 * 965 * @param[out] t Where to store the resulting matrix. 966 * @param[in] tx The X coordinate translation. 967 * @param[in] ty The Y coordinate translation. 968 * @param[in] tz The Z coordinate translation. 969 * 970 * @since 1.24 971 */ 972 EAPI void eina_matrix4_translate(Eina_Matrix4 *t, double tx, double ty, double tz); 973 974 /** 975 * @brief Sets the matrix values for a scaling operation. 976 * 977 * @param[out] t Where to store the resulting matrix. 978 * @param[in] sx The X coordinate scaling factor. 979 * @param[in] sy The Y coordinate scaling factor. 980 * @param[in] sz The Z coordinate scaling factor. 981 * 982 * @since 1.24 983 */ 984 EAPI void eina_matrix4_scale(Eina_Matrix4 *t, double sx, double sy, double sz); 985 986 /** 987 * @brief Sets the matrix values for a rotation operation. 988 * @param[out] t Where to store the resulting matrix. 989 * @param[in] rad The number of radians to rotate. 990 * @param[in] axis The Axis of rotation. 991 * 992 * @since 1.24 993 */ 994 EAPI void eina_matrix4_rotate(Eina_Matrix4 *t, double rad, Eina_Matrix_Axis axis); 995 996 /** 997 * @} 998 */ 999 1000 1001 /** 1002 * @defgroup Eina_Matrix2_Group 2x2 Matrices in floating point 1003 * 1004 * @brief Definition and operations for 2x3 matrices. 1005 * @{ 1006 */ 1007 1008 /** 1009 * @typedef Eina_Matrix2 1010 * A 2x2 floating point matrix. 1011 */ 1012 typedef struct _Eina_Matrix2 Eina_Matrix2; 1013 1014 /** 1015 * @struct Eina_Matrix2 1016 * A 2x2 floating point matrix. 1017 */ 1018 struct _Eina_Matrix2 1019 { 1020 double xx; 1021 double xy; 1022 1023 double yx; 1024 double yy; 1025 }; 1026 1027 /** 1028 * @brief Sets the values of the coefficients of the given floating 1029 * point matrix. 1030 * 1031 * @param[out] m The floating point matrix. 1032 * @param[in] xx The first coefficient value. 1033 * @param[in] xy The second coefficient value. 1034 * @param[in] yx The fourth coefficient value. 1035 * @param[in] yy The fifth coefficient value. 1036 * 1037 * This function sets the values of the coefficients of the matrix 1038 * @p m. No check is done on @p m. 1039 * 1040 * @see eina_matrix2_values_get() 1041 * 1042 * @since 1.17 1043 */ 1044 EAPI void eina_matrix2_values_set(Eina_Matrix2 *m, double xx, double xy, 1045 double yx, double yy); 1046 1047 /** 1048 * @brief Gets the values of the coefficients of the given floating 1049 * point matrix. 1050 * 1051 * @param[out] m The floating point matrix. 1052 * @param[in] xx The first coefficient value. 1053 * @param[in] xy The second coefficient value. 1054 * @param[in] yx The fourth coefficient value. 1055 * @param[in] yy The fifth coefficient value. 1056 * 1057 * This function gets the values of the coefficients of the matrix 1058 * @p m. No check is done on @p m. 1059 * 1060 * @see eina_matrix2_values_set() 1061 * 1062 * @since 1.17 1063 */ 1064 EAPI void eina_matrix2_values_get(const Eina_Matrix2 *m, double *xx, double *xy, 1065 double *yx, double *yy); 1066 1067 /** 1068 * @brief Computes the inverse with check of the given matrix. 1069 * 1070 * @param[out] out The matrix to inverse. 1071 * @param[in] mat The inverse matrix. 1072 * 1073 * This function inverse the matrix @p out and stores the result in 1074 * @p mat. No check is done on @p out or @p mat. If @p out can not be 1075 * invertible, then @p mat is set to the identity matrix. 1076 * 1077 * @since 1.17 1078 */ 1079 EAPI void eina_matrix2_inverse(Eina_Matrix2 *out, const Eina_Matrix2 *mat); 1080 1081 /** 1082 * @brief Sets the given floating point matrix to the identity matrix. 1083 * 1084 * @param[out] m The floating point matrix to set. 1085 * 1086 * This function sets @p m to the identity matrix. No check is done on 1087 * @p m. 1088 * 1089 * @since 1.17 1090 */ 1091 EAPI void eina_matrix2_identity(Eina_Matrix2 *m); 1092 1093 /** 1094 * @brief Sets array to matrix. 1095 * 1096 * @param[out] m The result matrix. 1097 * @param[in] v The the array[4] for set. 1098 * 1099 * Set to matrix first 4 elements from array 1100 * 1101 * @since 1.17 1102 */ 1103 EAPI void eina_matrix2_array_set(Eina_Matrix2 *m, const double *v); 1104 1105 /** 1106 * @brief Copies matrix. 1107 * 1108 * @param[out] dst The matrix copy. 1109 * @param[in] src The matrix to copy. 1110 * 1111 * @since 1.17 1112 */ 1113 EAPI void eina_matrix2_copy(Eina_Matrix2 *dst, const Eina_Matrix2 *src); 1114 1115 /** 1116 * @brief Multiplies two matrices. 1117 * 1118 * @param[out] out The resulting matrix. 1119 * @param[in] mat_a The first member of the multiplication. 1120 * @param[in] mat_b The second member of the multiplication. 1121 * 1122 * @since 1.17 1123 */ 1124 EAPI void eina_matrix2_multiply(Eina_Matrix2 *out, const Eina_Matrix2 *mat_a, 1125 const Eina_Matrix2 *mat_b); 1126 1127 /** 1128 * @brief Multiplies two matrices with check. 1129 * 1130 * @param[out] out The resulting matrix. 1131 * @param[in] mat_a The first member of the multiplication. 1132 * @param[in] mat_b The second member of the multiplication. 1133 * 1134 * @since 1.17 1135 */ 1136 EAPI void eina_matrix2_multiply_copy(Eina_Matrix2 *out, const Eina_Matrix2 *mat_a, 1137 const Eina_Matrix2 *mat_b); 1138 1139 /** 1140 * @brief Returns the type of the given floating point matrix. 1141 * 1142 * @param[in] m The floating point matrix. 1143 * @return The type of the matrix. 1144 * 1145 * This function returns the type of the matrix @p m. No check is done 1146 * on @p m. 1147 * 1148 * @since 1.17 1149 */ 1150 EAPI Eina_Matrix_Type eina_matrix2_type_get(const Eina_Matrix2 *m); 1151 1152 /** 1153 * @} 1154 */ 1155 1156 /** 1157 * @} 1158 */ 1159 1160 /** 1161 * @} 1162 */ 1163 1164 #endif /*EINA_MATRIX_H_*/ 1165