1 /*---------------------------------------------------------------------------* 2 Project: Matrix Vector Library 3 File: mtxVec.h 4 5 Copyright 1998-2011 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 *---------------------------------------------------------------------------*/ 14 15 /// @defgroup VEC VEC 16 /// @ingroup MTXL 17 18 /// @defgroup QUAT QUAT 19 /// @ingroup MTXL 20 21 /// @defgroup MTX MTX 22 /// @ingroup MTXL 23 24 /*---------------------------------------------------------------------------* 25 Matrix-Vector Library 26 *---------------------------------------------------------------------------*/ 27 28 #ifndef __MTXVEC_H__ 29 #define __MTXVEC_H__ 30 31 #if !defined(WIN32) && !defined(WIN64) 32 #include <cafe/os.h> 33 #else 34 #include <types.h> 35 #ifdef _DEBUG 36 #ifndef ASSERTMSG 37 #define ASSERTMSG(exp, msg) \ 38 (void) ((exp) || \ 39 (printf(msg, __FILE__, __LINE__))) 40 #endif 41 #else // _DEBUG 42 #ifndef ASSERTMSG 43 #define ASSERTMSG(exp, msg) ((void) 0) 44 #endif 45 46 #endif // _DEBUG 47 #define MTX_USE_C 48 #endif 49 50 #include <cafe/mtx/mtxGeoTypes.h> 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /*---------------------------------------------------------------------------* 57 Default function binding configuration 58 *---------------------------------------------------------------------------*/ 59 // [Binding Rule] 60 // 61 // "MTX_USE_ASM" -> When this flag is specified, it uses PS* (Paired-Single 62 // assembler code) functions for non-prefixed function calls. 63 // "MTX_USE_PS" -> When this flag is specified, it uses PS* (Paired-Single 64 // intrinsics code) functions for non-prefixed function calls. 65 // "MTX_USE_C " -> When this flag is specified, it uses C_* (C code) functions 66 // for non-prefixed function calls. 67 // 68 // The first binding specified in priority order listed will be used 69 // If nothing is specified, refers ASM* functions 70 71 #if ( !defined(MTX_USE_ASM) && !defined(MTX_USE_PS) && !defined(MTX_USE_C)) 72 #define MTX_USE_ASM 73 #endif 74 75 /*---------------------------------------------------------------------------* 76 Macro definitions 77 *---------------------------------------------------------------------------*/ 78 79 // MtxPtr offset to access next Mtx of an array 80 #define MTX_PTR_OFFSET 3 81 82 // Mtx44Ptr offset to access next Mtx44 of an array 83 #define MTX44_PTR_OFFSET 4 84 85 // "const" doesn't really work correctly for 2-dimensional mtx types 86 // If that changes, then redefine this as "const" (without quotes): 87 #define MTX_CONST 88 89 /// @addtogroup MTX 90 /// @{ 91 92 // Degree <--> radian conversion macros 93 /// \brief Convert Degrees to Radians. 94 /// \param a Degrees 95 /// \return Radians 96 /// 97 #define MTXDegToRad(a) ( (a) * 0.01745329252f ) 98 99 /// \brief Convert Radians to Degrees. 100 /// \param a Radians 101 /// \return Degrees 102 /// 103 #define MTXRadToDeg(a) ( (a) * 57.29577951f ) 104 105 /// \brief Matrix-element-referencing macro. 106 /// Insulates user from changes from row-major to column-major and vice-versa. 107 /// Fully documents which index is row, which index is column. 108 /// 109 /// \param m Matrix (\ref Mtx or \ref Mtx44) 110 /// \param r Row 111 /// \param c Column 112 /// \return Value of matrix at given row/column 113 /// 114 #define MTXRowCol(m,r,c) ((m)[(r)][(c)]) 115 116 /*---------------------------------------------------------------------------* 117 Typedefs 118 *---------------------------------------------------------------------------*/ 119 120 /// Matrix stack for the \ref Mtx type. 121 typedef struct _MtxStack 122 { 123 124 u32 numMtx; ///< Size of the matrix stack. 125 MtxPtr stackBase; ///< Base pointer of the matrix stack. 126 MtxPtr stackPtr; ///< Current stack pointer. NULL means an empty stack. 127 128 } MtxStack, *MtxStackPtr; 129 130 /// @} 131 132 /*---------------------------------------------------------------------------* 133 GENERAL MATRIX SECTION 134 *---------------------------------------------------------------------------*/ 135 136 /// @addtogroup MTX 137 /// @{ 138 139 // C version 140 141 /// \brief Set a 3x4 matrix to the identity. 142 /// 143 /// \param m Matrix to be set. 144 /// 145 /// \par Usage 146 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 147 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 148 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 149 /// 150 /// \donotcall \threadsafe \devonly \enddonotcall 151 /// 152 void C_MTXIdentity ( Mtx m ); 153 154 /// \brief Copies the contents of one 3x4 matrix into another 155 /// 156 /// \param src Source matrix for the copy. 157 /// \param dst Destination matrix for the copy. 158 /// 159 /// \par Usage 160 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 161 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 162 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 163 /// 164 /// \donotcall \threadsafe \devonly \enddonotcall 165 /// 166 void C_MTXCopy ( MTX_CONST Mtx src, Mtx dst ); 167 168 /// \brief Concatenates two 3x4 matrices 169 /// 170 /// Order of operations is A x B = AB. 171 /// This function can handle the case when ab == a == b. 172 /// 173 /// \param a First matrix to concatentate 174 /// \param b Second matrix to concatentate 175 /// \param ab Resulting matrix from concatentate 176 /// 177 /// \par Usage 178 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 179 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 180 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 181 /// 182 /// \donotcall \threadsafe \devonly \enddonotcall 183 /// 184 void C_MTXConcat ( MTX_CONST Mtx a, MTX_CONST Mtx b, Mtx ab ); 185 186 /// \brief Concatentates a 3x4 matrix to an array of 3x4 matrices. 187 /// The order of operations is A x B(array) = AB(array) 188 /// This routine is equivalent to: 189 /// 190 /// dstBase[i] = A x srcBase[i] for all i = 0 to count - 1 191 /// 192 /// \param a first matrix for concatenation 193 /// \param srcBase array base of second matrix for concatenation 194 /// \param dstBase array base of resulting matrix from concatenation 195 /// \param count number of matrices in srcBase and dstBase arrays 196 /// 197 /// \warning This routine cannot check for array overflow. 198 /// 199 /// \par Usage 200 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 201 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 202 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 203 /// 204 /// \donotcall \threadsafe \devonly \enddonotcall 205 /// 206 void C_MTXConcatArray ( MTX_CONST Mtx a, MTX_CONST Mtx* srcBase, Mtx* dstBase, u32 count ); 207 208 /// \brief Computes the transpose of a 3x4 matrix. 209 /// 210 /// \note It is safe for src == xPose 211 /// 212 /// \warning If the matrix is a 3x4 matrix, the fourth column (translation 213 /// component) is lost and becomes (0, 0, 0). This function is intended for 214 /// use in computing an inverse-transpose matrix to transform normals for 215 /// lighting. In this case, the loss of the translation component doesn't 216 /// matter. 217 /// 218 /// \param src Source matrix 219 /// \param xPose Destination (transposed) matrix 220 /// 221 /// \par Usage 222 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 223 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 224 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 225 /// 226 /// \donotcall \threadsafe \devonly \enddonotcall 227 /// 228 void C_MTXTranspose ( MTX_CONST Mtx src, Mtx xPose ); 229 230 /// \brief Computes a fast inverse of a 3x4 matrix. 231 /// This algorith works for matrices with a fourth row of (0, 0, 0, 1). 232 /// 233 /// For a matrix: 234 /// 235 /// M = | A C | 236 /// | 0 1 | 237 /// 238 /// Where A is the upper 3x3 submatrix and C is a 1x3 column vector: 239 /// 240 /// INV(M) = | inv(A) inv(A)*(-C) | 241 /// | 0 1 | 242 /// 243 /// \note It is safe for src == inv. 244 /// 245 /// \param src Source matrix 246 /// \param inv Destination (inverse) matrix 247 /// \return 0 if src is not invertible, 1 on success. 248 /// 249 /// \par Usage 250 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 251 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 252 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 253 /// 254 /// \donotcall \threadsafe \devonly \enddonotcall 255 /// 256 u32 C_MTXInverse ( MTX_CONST Mtx src, Mtx inv ); 257 258 /// \brief Computes a fast inverse-transpose of a 3x4 matrix. 259 /// 260 /// This algorithm works for matrices with a fourth row of (0, 0, 0, 1). 261 /// Commonly used for calculating normal transform matrices. 262 /// 263 /// This function is equivalent to the combination of two functions 264 /// \ref MTXInverse + \ref MTXTranspose 265 /// 266 /// \note It is safe to call this function if src == invX. 267 /// 268 /// \param src Source matrix 269 /// \param invX Destination (inverse-transpose) matrix. 270 /// \return 0 if src is not invertible, 1 on success. 271 /// 272 /// \par Usage 273 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 274 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 275 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 276 /// 277 /// \donotcall \threadsafe \devonly \enddonotcall 278 /// 279 u32 C_MTXInvXpose ( MTX_CONST Mtx src, Mtx invX ); 280 281 /// @} 282 283 // PS intrinsics version 284 void PSMTXIdentity ( Mtx m ); 285 void PSMTXCopy ( MTX_CONST Mtx src, Mtx dst ); 286 void PSMTXConcat ( MTX_CONST Mtx a, MTX_CONST Mtx b, Mtx ab ); 287 void PSMTXConcatArray ( MTX_CONST Mtx a, MTX_CONST Mtx* srcBase, Mtx* dstBase, u32 count ); 288 void PSMTXTranspose ( MTX_CONST Mtx src, Mtx xPose ); 289 u32 PSMTXInverse ( MTX_CONST Mtx src, Mtx inv ); 290 u32 PSMTXInvXpose ( MTX_CONST Mtx src, Mtx invX ); 291 292 // PS assembler version 293 void ASM_MTXIdentity ( Mtx m); 294 void ASM_MTXCopy ( MTX_CONST Mtx src, Mtx dst ); 295 void ASM_MTXConcat ( MTX_CONST Mtx mA, MTX_CONST Mtx mB, Mtx mAB ); 296 void ASM_MTXConcatArray ( MTX_CONST Mtx a, MTX_CONST Mtx* srcBase, Mtx* dstBase, u32 count ); 297 void ASM_MTXTranspose ( MTX_CONST Mtx src, Mtx xPose ); 298 u32 ASM_MTXInverse ( MTX_CONST Mtx src, Mtx inv ); 299 u32 ASM_MTXInvXpose ( MTX_CONST Mtx src, Mtx invX ); 300 301 // Bindings 302 #ifdef MTX_USE_ASM 303 #define MTXIdentity ASM_MTXIdentity 304 #define MTXCopy ASM_MTXCopy 305 #define MTXConcat ASM_MTXConcat 306 #define MTXConcatArray ASM_MTXConcatArray 307 #define MTXTranspose ASM_MTXTranspose 308 #define MTXInverse ASM_MTXInverse 309 #define MTXInvXpose ASM_MTXInvXpose 310 #else 311 #ifdef MTX_USE_PS 312 #define MTXIdentity PSMTXIdentity 313 #define MTXCopy PSMTXCopy 314 #define MTXConcat PSMTXConcat 315 #define MTXConcatArray PSMTXConcatArray 316 #define MTXTranspose PSMTXTranspose 317 #define MTXInverse PSMTXInverse 318 #define MTXInvXpose PSMTXInvXpose 319 #else // MTX_USE_C 320 #define MTXIdentity C_MTXIdentity 321 #define MTXCopy C_MTXCopy 322 #define MTXConcat C_MTXConcat 323 #define MTXConcatArray C_MTXConcatArray 324 #define MTXTranspose C_MTXTranspose 325 #define MTXInverse C_MTXInverse 326 #define MTXInvXpose C_MTXInvXpose 327 #endif 328 #endif 329 330 /*---------------------------------------------------------------------------* 331 MATRIX-VECTOR SECTION 332 *---------------------------------------------------------------------------*/ 333 334 /// @addtogroup MTX 335 /// @{ 336 337 // C version 338 339 /// \brief Multiplies a vector by a 3x4 matrix 340 /// 341 /// dst = m x src 342 /// 343 /// \note It is safe for src == dst. 344 /// 345 /// \param m Matrix to multiply by 346 /// \param src Source vector of multiply 347 /// \param dst Resulting vector from multiply 348 /// 349 /// \par Usage 350 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 351 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 352 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 353 /// 354 /// \donotcall \threadsafe \devonly \enddonotcall 355 /// 356 void C_MTXMultVec ( MTX_CONST Mtx m, const Vec *src, Vec *dst ); 357 358 /// \brief Multiplies an array of vectors by a 3x4 matrix. 359 /// 360 /// \note It is safe for srcBase == dstBase. 361 /// 362 /// \warning This function cannot check for array overflow. 363 /// 364 /// \param m Matrix to multiply by 365 /// \param srcBase Source vector array 366 /// \param dstBase Resulting vector array 367 /// \param count Number of vectors in srcBase and dstBase arrays. 368 /// 369 /// 370 /// \par Usage 371 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 372 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 373 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 374 /// 375 /// \donotcall \threadsafe \devonly \enddonotcall 376 /// 377 void C_MTXMultVecArray ( MTX_CONST Mtx m, const Vec *srcBase, Vec *dstBase, u32 count ); 378 379 /// \brief Multiply a vector by a 3x4 Scaling and Rotating matrix 380 /// \note It is assumed that the 4th column (translation) is 0. 381 /// 382 /// This is equivalent to: 383 /// 384 /// dst = m x src 385 /// 386 /// \note It is safe for src == dst. 387 /// 388 /// \param m Matrix to multiply by 389 /// \param src Source vector for multiply 390 /// \param dst Resulting vector from multiply 391 /// 392 /// \par Usage 393 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 394 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 395 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 396 /// 397 /// \donotcall \threadsafe \devonly \enddonotcall 398 /// 399 void C_MTXMultVecSR ( MTX_CONST Mtx m, const Vec *src, Vec *dst ); 400 401 /// \brief Multiply an array of vector by a 3x4 Scaling and Rotating matrix 402 /// \note It is assumed that the 4th column (translation) is 0. 403 /// 404 /// This is equivalent to: 405 /// 406 /// dstBase[i] = m x srcBase[i] 407 /// 408 /// \note It is safe for srcBase == dstBase. 409 /// 410 /// \warning This function cannot check for array overflow 411 /// 412 /// \param m Matrix to multiply by 413 /// \param srcBase Source vector array 414 /// \param dstBase Resulting vector array 415 /// \param count Number of vectors in srcBase and dstBase 416 /// 417 /// 418 /// \par Usage 419 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 420 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 421 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 422 /// 423 /// \donotcall \threadsafe \devonly \enddonotcall 424 /// 425 void C_MTXMultVecArraySR ( MTX_CONST Mtx m, const Vec *srcBase, Vec *dstBase, u32 count ); 426 427 /// @} 428 429 // PS intrisics version 430 void PSMTXMultVec ( MTX_CONST Mtx m, const Vec *src, Vec *dst ); 431 void PSMTXMultVecArray ( MTX_CONST Mtx m, const Vec *srcBase, Vec *dstBase, u32 count ); 432 void PSMTXMultVecSR ( MTX_CONST Mtx m, const Vec *src, Vec *dst ); 433 void PSMTXMultVecArraySR ( MTX_CONST Mtx m, const Vec *srcBase, Vec *dstBase, u32 count ); 434 435 // PS assembler version 436 void ASM_MTXMultVec ( MTX_CONST Mtx m, const Vec *src, Vec *dst ); 437 void ASM_MTXMultVecArray ( MTX_CONST Mtx m, const Vec *srcBase, Vec *dstBase, u32 count ); 438 void ASM_MTXMultVecArraySR ( MTX_CONST Mtx m, const Vec *srcBase, Vec *dstBase, u32 count ); 439 void ASM_MTXMultVecSR ( MTX_CONST Mtx m, const Vec *src, Vec *dst ); 440 441 // Bindings 442 #ifdef MTX_USE_ASM 443 #define MTXMultVec ASM_MTXMultVec 444 #define MTXMultVecArray ASM_MTXMultVecArray 445 #define MTXMultVecSR ASM_MTXMultVecSR 446 #define MTXMultVecArraySR ASM_MTXMultVecArraySR 447 #else 448 #ifdef MTX_USE_PS 449 #define MTXMultVec PSMTXMultVec 450 #define MTXMultVecArray PSMTXMultVecArray 451 #define MTXMultVecSR PSMTXMultVecSR 452 #define MTXMultVecArraySR PSMTXMultVecArraySR 453 #else // MTX_USE_C 454 #define MTXMultVec C_MTXMultVec 455 #define MTXMultVecArray C_MTXMultVecArray 456 #define MTXMultVecSR C_MTXMultVecSR 457 #define MTXMultVecArraySR C_MTXMultVecArraySR 458 #endif 459 #endif 460 461 /*---------------------------------------------------------------------------* 462 MODEL MATRIX SECTION 463 *---------------------------------------------------------------------------*/ 464 465 /// @addtogroup MTX 466 /// @{ 467 468 // C version 469 470 /// \brief Sets a rotation 3x4 matrix from a quaternion. 471 /// 472 /// \param m Matrix to be set. 473 /// \param q Pointer to Quaternion 474 /// 475 /// \par Usage 476 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 477 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 478 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 479 /// 480 /// \donotcall \threadsafe \devonly \enddonotcall 481 /// 482 void C_MTXQuat ( Mtx m, const Quaternion *q ); 483 484 /// \brief Reflect a rotation 3x4 matrix with respect to a plane. 485 /// 486 /// \param m Matrix to be set. 487 /// \param p point on the plane 488 /// \param n normal of the plane 489 /// 490 /// \par Usage 491 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 492 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 493 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 494 /// 495 /// \donotcall \threadsafe \devonly \enddonotcall 496 /// 497 void C_MTXReflect ( Mtx m, const Vec *p, const Vec *n ); 498 499 /// \brief Sets a translation 3x4 matrix 500 /// 501 /// \param m Matrix to be set 502 /// \param xT x component of translation 503 /// \param yT y component of translation 504 /// \param zT z component of translation 505 /// 506 /// \par Usage 507 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 508 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 509 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 510 /// 511 /// \donotcall \threadsafe \devonly \enddonotcall 512 /// 513 void C_MTXTrans ( Mtx m, f32 xT, f32 yT, f32 zT ); 514 515 /// \brief Apply a translation to a 3x4 matrix. 516 /// This function is equivalent to \ref MTXTrans + \ref MTXConcat. 517 /// 518 /// \note This is safe for the case where src == dst. 519 /// 520 /// \param src Matrix to multiply the translation by 521 /// \param dst Resulting matrix from concatenation 522 /// \param xT x component of translation 523 /// \param yT y component of translation 524 /// \param zT z component of translation 525 /// 526 /// \par Usage 527 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 528 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 529 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 530 /// 531 /// \donotcall \threadsafe \devonly \enddonotcall 532 /// 533 void C_MTXTransApply ( MTX_CONST Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT ); 534 535 /// \brief Sets a scale 3x4 matrix 536 /// 537 /// \param m Matrix to be set 538 /// \param xS x component of scale 539 /// \param yS y component of scale 540 /// \param zS z component of scale 541 /// 542 /// \par Usage 543 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 544 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 545 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 546 /// 547 /// \donotcall \threadsafe \devonly \enddonotcall 548 /// 549 void C_MTXScale ( Mtx m, f32 xS, f32 yS, f32 zS ); 550 551 /// \brief Apply a scale to a 3x4 matrix. 552 /// This function is equivalent to \ref MTXScale + \ref MTXConcat. 553 /// 554 /// \note This is safe for the case where src == dst. 555 /// 556 /// \param src Matrix to multiply the scale by 557 /// \param dst Resulting matrix from concatenation 558 /// \param xS x component of scale 559 /// \param yS y component of scale 560 /// \param zS z component of scale 561 /// 562 /// \par Usage 563 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 564 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 565 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 566 /// 567 /// \donotcall \threadsafe \devonly \enddonotcall 568 /// 569 void C_MTXScaleApply ( MTX_CONST Mtx src, Mtx dst, f32 xS, f32 yS, f32 zS ); 570 571 572 /// \brief Sets a rotation 3x4 matrix about one of the X, Y or Z axes. 573 /// 574 /// \note Counter clockwise rotation is positive. 575 /// 576 /// \param m Matrix to be set 577 /// \param axis Principal axis of rotation. Must be 'X', 'x', 'Y', 'y', 'Z', or 'z'. 578 /// \param rad Rotation angle in radians 579 /// 580 /// \par Usage 581 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 582 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 583 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 584 /// 585 /// \donotcall \threadsafe \devonly \enddonotcall 586 /// 587 void C_MTXRotRad ( Mtx m, char axis, f32 rad ); 588 589 /// \brief Sets a rotation 3x4 matrix about one of the X, Y, or Z axes from specified trig ratios. 590 /// 591 /// \note Counter clockwise rotation is positive. 592 /// 593 /// \param m Matrix to be set 594 /// \param axis Principal axis of rotation. Must be 'X', 'x', 'Y', 'y', 'Z', or 'z'. 595 /// \param sinA Sine of rotation angle 596 /// \param cosA Cosine of rotation angle 597 /// 598 /// \par Usage 599 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 600 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 601 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 602 /// 603 /// \donotcall \threadsafe \devonly \enddonotcall 604 /// 605 void C_MTXRotTrig ( Mtx m, char axis, f32 sinA, f32 cosA ); 606 607 /// \brief Sets a rotation 3x4 matrix about an arbitrary axis. 608 /// 609 /// \note Counter clockwise rotation is positive. 610 /// 611 /// \param m Matrix to be set 612 /// \param axis Pointer to a vector containing the (x, y, z) axis components 613 /// \param rad Rotation angle in radians 614 /// 615 /// \par Usage 616 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 617 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 618 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 619 /// 620 /// \donotcall \threadsafe \devonly \enddonotcall 621 /// 622 void C_MTXRotAxisRad ( Mtx m, const Vec *axis, f32 rad ); 623 624 /// @} 625 626 // PS intrisics version 627 void PSMTXQuat ( Mtx m, const Quaternion *q ); 628 void PSMTXReflect ( Mtx m, const Vec *p, const Vec *n ); 629 630 void PSMTXTrans ( Mtx m, f32 xT, f32 yT, f32 zT ); 631 void PSMTXTransApply( Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT ); 632 void PSMTXScale ( Mtx m, f32 xS, f32 yS, f32 zS ); 633 void PSMTXScaleApply ( MTX_CONST Mtx src, Mtx dst, f32 xS, f32 yS, f32 zS ); 634 635 void PSMTXRotRad ( Mtx m, char axis, f32 rad ); 636 void PSMTXRotTrig ( Mtx m, char axis, f32 sinA, f32 cosA ); 637 void PSMTXRotAxisRad ( Mtx m, const Vec *axis, f32 rad ); 638 639 // PS assembler version 640 void ASM_MTXQuat ( Mtx m, const Quaternion *q ); 641 void ASM_MTXReflect ( Mtx m, const Vec *p, const Vec *n ); 642 643 void ASM_MTXTrans ( Mtx m, f32 xT, f32 yT, f32 zT ); 644 void ASM_MTXTransApply ( MTX_CONST Mtx src, Mtx dst, f32 xT, f32 yT, f32 zT ); 645 void ASM_MTXScale ( Mtx m, f32 xS, f32 yS, f32 zS ); 646 void ASM_MTXScaleApply ( MTX_CONST Mtx src, Mtx dst, f32 xS, f32 yS, f32 zS ); 647 648 void ASM_MTXRotRad ( Mtx m, char axis, f32 rad ); 649 void ASM_MTXRotTrig ( Mtx m, char axis, f32 sinA, f32 cosA ); 650 void ASM_MTXRotAxisRad ( Mtx m, const Vec *axis, f32 rad ); 651 652 // Bindings 653 654 #ifdef MTX_USE_ASM 655 #define MTXTrans ASM_MTXTrans 656 #define MTXTransApply ASM_MTXTransApply 657 #define MTXQuat ASM_MTXQuat 658 #define MTXReflect ASM_MTXReflect 659 #define MTXScale ASM_MTXScale 660 #define MTXScaleApply ASM_MTXScaleApply 661 #define MTXRotRad ASM_MTXRotRad 662 #define MTXRotTrig ASM_MTXRotTrig 663 #define MTXRotDeg( m, axis, deg ) \ 664 ASM_MTXRotRad( m, axis, MTXDegToRad(deg) ) 665 #define MTXRotAxisRad ASM_MTXRotAxisRad 666 #define MTXRotAxisDeg( m, axis, deg ) \ 667 ASM_MTXRotAxisRad( m, axis, MTXDegToRad(deg) ) 668 #else 669 #ifdef MTX_USE_PS 670 #define MTXTrans PSMTXTrans 671 #define MTXTransApply PSMTXTransApply 672 #define MTXQuat PSMTXQuat 673 #define MTXReflect PSMTXReflect 674 #define MTXScale PSMTXScale 675 #define MTXScaleApply PSMTXScaleApply 676 #define MTXRotRad PSMTXRotRad 677 #define MTXRotTrig PSMTXRotTrig 678 #define MTXRotDeg( m, axis, deg ) \ 679 PSMTXRotRad( m, axis, MTXDegToRad(deg) ) 680 #define MTXRotAxisRad PSMTXRotAxisRad 681 #define MTXRotAxisDeg( m, axis, deg ) \ 682 PSMTXRotAxisRad( m, axis, MTXDegToRad(deg) ) 683 684 #else // MTX_USE_C 685 #define MTXTrans C_MTXTrans 686 #define MTXTransApply C_MTXTransApply 687 #define MTXQuat C_MTXQuat 688 #define MTXReflect C_MTXReflect 689 #define MTXScale C_MTXScale 690 #define MTXScaleApply C_MTXScaleApply 691 #define MTXRotRad C_MTXRotRad 692 #define MTXRotTrig C_MTXRotTrig 693 #define MTXRotDeg( m, axis, deg ) \ 694 C_MTXRotRad( m, axis, MTXDegToRad(deg) ) 695 #define MTXRotAxisRad C_MTXRotAxisRad 696 #define MTXRotAxisDeg( m, axis, deg ) \ 697 C_MTXRotAxisRad( m, axis, MTXDegToRad(deg) ) 698 699 #endif 700 #endif 701 702 // Obsolete. Don't use this if possible. 703 #define MTXRotAxis MTXRotAxisDeg 704 705 706 /*---------------------------------------------------------------------------* 707 VIEW MATRIX SECTION 708 *---------------------------------------------------------------------------*/ 709 710 /// @addtogroup MTX 711 /// @{ 712 713 // C version only so far 714 715 /// \brief Compute a 3x4 matrix to transform points to camera coordinates. 716 /// 717 /// \param m Matrix to be set 718 /// \param camPos Camera position 719 /// \param camUp Camera 'up' direction 720 /// \param target Camera aim point 721 /// 722 /// \par Usage 723 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 724 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 725 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 726 /// 727 /// \donotcall \threadsafe \devonly \enddonotcall 728 /// 729 void C_MTXLookAt ( Mtx m, 730 const Point3d *camPos, 731 const Vec *camUp, 732 const Point3d *target ); 733 734 /// @} 735 736 // Bindings 737 #define MTXLookAt C_MTXLookAt 738 739 /*---------------------------------------------------------------------------* 740 PROJECTION MATRIX SECTION 741 *---------------------------------------------------------------------------*/ 742 743 /// @addtogroup MTX 744 /// @{ 745 746 // C version only so far 747 748 /// \brief Compute a 4x4 perspective projection matrix from a specified view volume. 749 /// 750 /// \param m 4x4 Matrix to be set 751 /// \param t Top coordinate of the viewing volume at the near clipping plane 752 /// \param b Bottom coordinate of the viewing volume at the near clipping plane 753 /// \param lf Left coordinate of the viewing volume at the near clipping plane 754 /// \param r Right coordinate of the viewing volume at the near clipping plane 755 /// \param n Positive distance from camera to the near clipping plane 756 /// \param f Positive distance from camera to the far clipping plane 757 /// 758 /// \par Usage 759 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 760 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 761 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 762 /// 763 /// \donotcall \threadsafe \devonly \enddonotcall 764 /// 765 void C_MTXFrustum ( Mtx44 m, f32 t, f32 b, f32 lf, f32 r, f32 n, f32 f ); 766 767 /// \brief Compute a 4x4 perspective projection matrix from the field of view and aspect ratio. 768 /// 769 /// \param m 4x4 Matrix to be set 770 /// \param fovY Total field of view in degrees in the YZ plane 771 /// \param aspect Ratio of view window width:height (X / Y) 772 /// \param n Positive distance from camera to the near clipping plane 773 /// \param f Positive distance from camera to the far clipping plane 774 /// 775 /// \par Usage 776 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 777 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 778 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 779 /// 780 /// \donotcall \threadsafe \devonly \enddonotcall 781 /// 782 void C_MTXPerspective ( Mtx44 m, f32 fovY, f32 aspect, f32 n, f32 f ); 783 784 /// \brief Compute a 4x4 orthographic projection matrix. 785 /// 786 /// \param m 4x4 Matrix to be set 787 /// \param t Top coordinate of the parallel view volume. 788 /// \param b Bottom coordinate of the parallel view volume. 789 /// \param lf Left coordinate of the parallel view volume. 790 /// \param r Right coordinate of the parallel view volume. 791 /// \param n Positive distance from camera to the near clipping plane 792 /// \param f Positive distance from camera to the far clipping plane 793 /// 794 /// \par Usage 795 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 796 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 797 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 798 /// 799 /// \donotcall \threadsafe \devonly \enddonotcall 800 /// 801 void C_MTXOrtho ( Mtx44 m, f32 t, f32 b, f32 lf, f32 r, f32 n, f32 f ); 802 803 /// @} 804 805 // Bindings 806 #define MTXFrustum C_MTXFrustum 807 #define MTXPerspective C_MTXPerspective 808 #define MTXOrtho C_MTXOrtho 809 810 /*---------------------------------------------------------------------------* 811 TEXTURE PROJECTION MATRIX SECTION 812 *---------------------------------------------------------------------------*/ 813 814 /// @addtogroup MTX 815 /// @{ 816 817 // C version only so far 818 819 /// \brief Compute a 3x4 perspective projection matrix for texture projection. 820 /// 821 /// \param m Matrix to be set 822 /// \param t Top coordinate of the viewing volume at the near clipping plane 823 /// \param b Bottom coordinate of the viewing volume at the near clipping plane 824 /// \param lf Left coordinate of the viewing volume at the near clipping plane 825 /// \param r Right coordinate of the viewing volume at the near clipping plane 826 /// \param n Positive distance from camera to the near clipping plane 827 /// \param scaleS Scale in the S direction for projected coordinates (usually 0.5) 828 /// \param scaleT Scale in the T direction for projected coordinates (usually 0.5) 829 /// \param transS Translate in the S direction for projected coordinates (usually 0.5) 830 /// \param transT Translate in the T direction for projected coordinates (usually 0.5) 831 /// 832 /// \par Usage 833 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 834 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 835 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 836 /// 837 /// \donotcall \threadsafe \devonly \enddonotcall 838 /// 839 void C_MTXLightFrustum ( Mtx m, f32 t, f32 b, f32 lf, f32 r, f32 n, 840 f32 scaleS, f32 scaleT, f32 transS, 841 f32 transT ); 842 843 /// \brief Compute a 3x4 perspective projection matrix from field of view and aspect ratio for texture projection. 844 /// 845 /// \param m Matrix to be set 846 /// \param fovY Total field of view in degrees in the YZ plane 847 /// \param aspect Ratio of view window width:height (X / Y) 848 /// \param scaleS Scale in the S direction for projected coordinates (usually 0.5) 849 /// \param scaleT Scale in the T direction for projected coordinates (usually 0.5) 850 /// \param transS Translate in the S direction for projected coordinates (usually 0.5) 851 /// \param transT Translate in the T direction for projected coordinates (usually 0.5) 852 /// 853 /// \par Usage 854 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 855 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 856 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 857 /// 858 /// \donotcall \threadsafe \devonly \enddonotcall 859 /// 860 void C_MTXLightPerspective ( Mtx m, f32 fovY, f32 aspect, f32 scaleS, 861 f32 scaleT, f32 transS, f32 transT ); 862 863 /// \brief Compute a 3x4 orthographic projection matrix for texture projection. 864 /// 865 /// \param m Matrix to be set 866 /// \param t Top coordinate of the viewing volume at the near clipping plane 867 /// \param b Bottom coordinate of the viewing volume at the near clipping plane 868 /// \param lf Left coordinate of the viewing volume at the near clipping plane 869 /// \param r Right coordinate of the viewing volume at the near clipping plane 870 /// \param scaleS Scale in the S direction for projected coordinates (usually 0.5) 871 /// \param scaleT Scale in the T direction for projected coordinates (usually 0.5) 872 /// \param transS Translate in the S direction for projected coordinates (usually 0.5) 873 /// \param transT Translate in the T direction for projected coordinates (usually 0.5) 874 /// 875 /// \par Usage 876 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 877 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 878 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 879 /// 880 /// \donotcall \threadsafe \devonly \enddonotcall 881 /// 882 void C_MTXLightOrtho ( Mtx m, f32 t, f32 b, f32 lf, f32 r, f32 scaleS, 883 f32 scaleT, f32 transS, f32 transT ); 884 885 /// @} 886 887 // Bindings 888 #define MTXLightFrustum C_MTXLightFrustum 889 #define MTXLightPerspective C_MTXLightPerspective 890 #define MTXLightOrtho C_MTXLightOrtho 891 892 /*---------------------------------------------------------------------------* 893 VECTOR SECTION 894 *---------------------------------------------------------------------------*/ 895 896 /// @addtogroup VEC 897 /// @{ 898 899 // C version 900 901 /// \brief Add two vectors. 902 /// 903 /// \note It is safe for ab == a == b 904 /// 905 /// \param a First vector 906 /// \param b Second vector 907 /// \param ab Resulting vector (a + b) 908 /// 909 /// \par Usage 910 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 911 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 912 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 913 /// 914 /// \donotcall \threadsafe \devonly \enddonotcall 915 /// 916 void C_VECAdd ( const Vec *a, const Vec *b, Vec *ab ); 917 918 /// \brief Subtract two vectors. 919 /// 920 /// \note It is safe for a_b == a == b 921 /// 922 /// \param a First vector 923 /// \param b Second vector 924 /// \param a_b Resulting vector (a - b) 925 /// 926 /// \par Usage 927 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 928 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 929 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 930 /// 931 /// \donotcall \threadsafe \devonly \enddonotcall 932 /// 933 void C_VECSubtract ( const Vec *a, const Vec *b, Vec *a_b ); 934 935 /// \brief Scale a vector using a scalar. 936 /// 937 /// \note It is safe for src == dst. 938 /// 939 /// \param src Unscaled source vector 940 /// \param dst Scaled resultant vector (src * scale) 941 /// \param scale Scaling factor 942 /// 943 /// \par Usage 944 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 945 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 946 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 947 /// 948 /// \donotcall \threadsafe \devonly \enddonotcall 949 /// 950 void C_VECScale ( const Vec *src, Vec *dst, f32 scale ); 951 952 /// \brief Normalize a vector. 953 /// 954 /// \note It is safe for src == unit. 955 /// 956 /// \param src Non-unit source vector 957 /// \param unit Resulting unit vector (src / src magnitude) 958 /// 959 /// \par Usage 960 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 961 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 962 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 963 /// 964 /// \donotcall \threadsafe \devonly \enddonotcall 965 /// 966 void C_VECNormalize ( const Vec *src, Vec *unit ); 967 968 /// \brief Compute the square of the magnitude of a vector. 969 /// 970 /// \param v Source vector 971 /// \return Square magnitude of the vector 972 /// 973 /// \par Usage 974 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 975 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 976 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 977 /// 978 /// \donotcall \threadsafe \devonly \enddonotcall 979 /// 980 f32 C_VECSquareMag ( const Vec *v ); 981 982 /// \brief Compute the magnitude of a vector. 983 /// 984 /// \param v Source vector 985 /// \return Magnitude of the vector 986 /// 987 /// \par Usage 988 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 989 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 990 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 991 /// 992 /// \donotcall \threadsafe \devonly \enddonotcall 993 /// 994 f32 C_VECMag ( const Vec *v ); 995 996 /// \brief Compute the dot product of two vectors. 997 /// 998 /// \note Input vectors do not have to be normalized. 999 /// \note Input vectors are not normalized in the function. 1000 /// 1001 /// \warning If direct cosine computation of the angle between a and b is desired, a and b should be normalized prior to calling \ref VECDotProduct. 1002 /// 1003 /// \param a First vector 1004 /// \param b Second vector 1005 /// \result Dot product of the two vectors 1006 /// 1007 /// \par Usage 1008 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1009 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1010 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1011 /// 1012 /// \donotcall \threadsafe \devonly \enddonotcall 1013 /// 1014 f32 C_VECDotProduct ( const Vec *a, const Vec *b ); 1015 1016 /// \brief Compute the cross product of two vectors. 1017 /// 1018 /// \note It is safe for axb == a == b 1019 /// \note Input vectors do not have to be normalized. 1020 /// \note Input vectors are not normalized in the function. 1021 /// 1022 /// \param a First vector 1023 /// \param b Second vector 1024 /// \param axb Resulting cross product vector (a x b) 1025 /// 1026 /// \par Usage 1027 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1028 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1029 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1030 /// 1031 /// \donotcall \threadsafe \devonly \enddonotcall 1032 /// 1033 void C_VECCrossProduct ( const Vec *a, const Vec *b, Vec *axb ); 1034 1035 /// \brief Returns the square of the distance between vectors a and b. 1036 /// Distance can be calculated using the square root of the returned value. 1037 /// 1038 /// \note It is safe for ab == a == b 1039 /// 1040 /// \param a First vector 1041 /// \param b Second vector 1042 /// \return Square distance between the two vectors 1043 /// 1044 /// \par Usage 1045 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1046 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1047 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1048 /// 1049 /// \donotcall \threadsafe \devonly \enddonotcall 1050 /// 1051 f32 C_VECSquareDistance ( const Vec *a, const Vec *b ); 1052 1053 /// \brief Returns the distance between vectors a and b. 1054 /// 1055 /// \note It is safe for ab == a == b 1056 /// 1057 /// \param a First vector 1058 /// \param b Second vector 1059 /// \return Distance between the two vectors 1060 /// 1061 /// \par Usage 1062 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1063 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1064 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1065 /// 1066 /// \donotcall \threadsafe \devonly \enddonotcall 1067 /// 1068 f32 C_VECDistance ( const Vec *a, const Vec *b ); 1069 1070 /// \brief Reflect a vector about a normal to a surface. 1071 /// 1072 /// \note It is safe for dst == src. 1073 /// \note This function normalizes src and normal vectors. 1074 /// 1075 /// \param src Incident vector 1076 /// \param normal Normal to surface 1077 /// \param dst Normalized reflected vector 1078 /// 1079 /// \par Usage 1080 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1081 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1082 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1083 /// 1084 /// \donotcall \threadsafe \devonly \enddonotcall 1085 /// 1086 void C_VECReflect ( const Vec *src, const Vec *normal, Vec *dst ); 1087 1088 /// \brief Compute the vector halfway between two vectors. 1089 /// This is intended for use in computing specular highlights. 1090 /// 1091 /// \note It is safe for half == a == b 1092 /// \note Input vectors do not have to be normalized. 1093 /// 1094 /// \param a First vector. This must point FROM the light source (tail) TO the surface (head). 1095 /// \param b Second vector. This must point FROM the viewer (tail) TO the surface (head). 1096 /// \param half Resulting normalized 'half-angle' vector. 1097 /// 1098 /// \par Usage 1099 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1100 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1101 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1102 /// 1103 /// \donotcall \threadsafe \devonly \enddonotcall 1104 /// 1105 void C_VECHalfAngle ( const Vec *a, const Vec *b, Vec *half ); 1106 1107 /// @} 1108 1109 // PS intrisics version 1110 void PSVECAdd ( const Vec *a, const Vec *b, Vec *ab ); 1111 void PSVECSubtract ( const Vec *a, const Vec *b, Vec *a_b ); 1112 void PSVECScale ( const Vec *src, Vec *dst, f32 scale ); 1113 void PSVECNormalize ( const Vec *src, Vec *unit ); 1114 f32 PSVECSquareMag ( const Vec *v ); 1115 f32 PSVECMag ( const Vec *v ); 1116 f32 PSVECDotProduct ( const Vec *a, const Vec *b ); 1117 void PSVECCrossProduct ( const Vec *a, const Vec *b, Vec *axb ); 1118 f32 PSVECSquareDistance ( const Vec *a, const Vec *b ); 1119 f32 PSVECDistance ( const Vec *a, const Vec *b ); 1120 1121 // PS assembler version 1122 void ASM_VECAdd ( const Vec *vec1, const Vec *vec2, Vec *dst ); 1123 void ASM_VECSubtract ( const Vec *vec1, const Vec *vec2, Vec *dst ); 1124 void ASM_VECScale ( const Vec *src, Vec *dst, f32 mult ); 1125 void ASM_VECNormalize ( const Vec *src, Vec *unit ); 1126 f32 ASM_VECSquareMag ( const Vec *vec1 ); 1127 f32 ASM_VECMag ( const Vec *v ); 1128 f32 ASM_VECDotProduct ( const Vec *a, const Vec *b ); 1129 void ASM_VECCrossProduct ( const Vec *vec1, const Vec *vec2, Vec *dst ); 1130 f32 ASM_VECSquareDistance ( const Vec* a, const Vec* b ); 1131 f32 ASM_VECDistance ( const Vec *a, const Vec *b ); 1132 1133 // Bindings 1134 #ifdef MTX_USE_ASM 1135 #define VECNormalize ASM_VECNormalize 1136 #define VECDotProduct ASM_VECDotProduct 1137 #define VECAdd ASM_VECAdd 1138 #define VECSubtract ASM_VECSubtract 1139 #define VECScale ASM_VECScale 1140 #define VECSquareMag ASM_VECSquareMag 1141 #define VECMag ASM_VECMag 1142 #define VECCrossProduct ASM_VECCrossProduct 1143 #define VECSquareDistance ASM_VECSquareDistance 1144 #define VECDistance ASM_VECDistance 1145 #else 1146 #ifdef MTX_USE_PS 1147 #define VECNormalize PSVECNormalize 1148 #define VECDotProduct PSVECDotProduct 1149 #define VECAdd PSVECAdd 1150 #define VECSubtract PSVECSubtract 1151 #define VECScale PSVECScale 1152 #define VECSquareMag PSVECSquareMag 1153 #define VECMag PSVECMag 1154 #define VECCrossProduct PSVECCrossProduct 1155 #define VECSquareDistance PSVECSquareDistance 1156 #define VECDistance PSVECDistance 1157 #else // MTX_USE_C 1158 #define VECNormalize C_VECNormalize 1159 #define VECDotProduct C_VECDotProduct 1160 #define VECAdd C_VECAdd 1161 #define VECSubtract C_VECSubtract 1162 #define VECScale C_VECScale 1163 #define VECSquareMag C_VECSquareMag 1164 #define VECMag C_VECMag 1165 #define VECCrossProduct C_VECCrossProduct 1166 #define VECSquareDistance C_VECSquareDistance 1167 #define VECDistance C_VECDistance 1168 #endif 1169 #endif 1170 1171 #define VECReflect C_VECReflect 1172 #define VECHalfAngle C_VECHalfAngle 1173 1174 /*---------------------------------------------------------------------------* 1175 QUATERNION SECTION 1176 *---------------------------------------------------------------------------*/ 1177 1178 /// @addtogroup QUAT 1179 /// @{ 1180 1181 /// \brief Quaternion epsilon comparison used for compare against 0.0f. 1182 /// 1183 #define QUAT_EPSILON 0.00001F 1184 1185 // C version 1186 1187 /// \brief Returns the sum of two quaternions. 1188 /// 1189 /// \note It is safe for p == q == r 1190 /// 1191 /// \param p First quaternion 1192 /// \param q Second quaternion 1193 /// \param r Resulting quaternion (p + q) 1194 /// 1195 /// \par Usage 1196 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1197 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1198 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1199 /// 1200 /// \donotcall \threadsafe \devonly \enddonotcall 1201 /// 1202 void C_QUATAdd ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1203 1204 /// \brief Returns the difference of two quaternions p-q. 1205 /// 1206 /// \note It is safe for p == q == r 1207 /// 1208 /// \param p First quaternion 1209 /// \param q Second quaternion 1210 /// \param r Resulting quaternion (p - q) 1211 /// 1212 /// \par Usage 1213 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1214 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1215 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1216 /// 1217 /// \donotcall \threadsafe \devonly \enddonotcall 1218 /// 1219 void C_QUATSubtract ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1220 1221 /// \brief Returns the product of two quaternions. 1222 /// The order of multiplication is important. (p*q != q*p) 1223 /// 1224 /// \note It is safe for p == q == pq 1225 /// 1226 /// \param p Left quaternion 1227 /// \param q Right quaternion 1228 /// \param pq Resulting quaternion product (p * q) 1229 /// 1230 /// \par Usage 1231 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1232 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1233 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1234 /// 1235 /// \donotcall \threadsafe \devonly \enddonotcall 1236 /// 1237 void C_QUATMultiply ( const Quaternion *p, const Quaternion *q, Quaternion *pq ); 1238 1239 /// \brief Returns the ratio of two quaternions. 1240 /// Creates a result r = p/q such that q*r = p (order of multiplication is important). 1241 /// 1242 /// \note It is safe for p == q == r 1243 /// 1244 /// \param p Left quaternion 1245 /// \param q Right quaternion 1246 /// \param r Resulting quaternion ratio (p / q) 1247 /// 1248 /// \par Usage 1249 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1250 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1251 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1252 /// 1253 /// \donotcall \threadsafe \devonly \enddonotcall 1254 /// 1255 void C_QUATDivide ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1256 1257 /// \brief Scales a quaternion. 1258 /// 1259 /// \note It is safe for q == r 1260 /// 1261 /// \param q Quaternion 1262 /// \param r Resulting scaled quaternion 1263 /// \param scale Scaling factor 1264 /// 1265 /// \par Usage 1266 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1267 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1268 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1269 /// 1270 /// \donotcall \threadsafe \devonly \enddonotcall 1271 /// 1272 void C_QUATScale ( const Quaternion *q, Quaternion *r, f32 scale ); 1273 1274 /// \brief Returns the dot product of two quaternions. 1275 /// 1276 /// \param p First quaternion 1277 /// \param q Second quaternion 1278 /// \return Dot product of the two quaternions 1279 /// 1280 /// \par Usage 1281 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1282 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1283 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1284 /// 1285 /// \donotcall \threadsafe \devonly \enddonotcall 1286 /// 1287 f32 C_QUATDotProduct ( const Quaternion *p, const Quaternion *q ); 1288 1289 /// \brief Normalizes a quaternion. 1290 /// 1291 /// \note It is safe for src == unit 1292 /// \warning If using MTX_USE_C and the magnitude of the quaternion is < \ref QUAT_EPSILON then the resulting quaternion is 0. 1293 /// 1294 /// \param src Source quaternion 1295 /// \param unit Resulting unit quaternion 1296 /// 1297 /// \par Usage 1298 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1299 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1300 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1301 /// 1302 /// \donotcall \threadsafe \devonly \enddonotcall 1303 /// 1304 void C_QUATNormalize ( const Quaternion *src, Quaternion *unit ); 1305 1306 /// \brief Returns the inverse of a quaternion. 1307 /// 1308 /// \param src Source quaternion 1309 /// \param inv Resulting inverse quaternion 1310 /// 1311 /// \par Usage 1312 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1313 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1314 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1315 /// 1316 /// \donotcall \threadsafe \devonly \enddonotcall 1317 /// 1318 void C_QUATInverse ( const Quaternion *src, Quaternion *inv ); 1319 1320 /// \brief Exponentiate quaternion (where q.w == 0). 1321 /// 1322 /// \note It is safe for q == r 1323 /// 1324 /// \param q Pure quaternion 1325 /// \param r Resulting exponentiated quaternion (an unit quaternion) 1326 /// 1327 /// \par Usage 1328 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1329 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1330 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1331 /// 1332 /// \donotcall \threadsafe \devonly \enddonotcall 1333 /// 1334 void C_QUATExp ( const Quaternion *q, Quaternion *r ); 1335 1336 /// \brief Returns the natural logarithm of a UNIT quaternion. 1337 /// 1338 /// \note It is safe for q == r 1339 /// 1340 /// \param q Unit quaternion 1341 /// \param r Resulting logarithm quaternion (a pure quaternion) 1342 /// 1343 /// \par Usage 1344 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1345 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1346 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1347 /// 1348 /// \donotcall \threadsafe \devonly \enddonotcall 1349 /// 1350 void C_QUATLogN ( const Quaternion *q, Quaternion *r ); 1351 1352 /// \brief Modify q so it is on the same side of the hypersphere as qto 1353 /// 1354 /// \note It is safe for p == q == r 1355 /// 1356 /// \param q Quaternion 1357 /// \param qto Quaternion to be close to 1358 /// \param r Resulting modified quaternion 1359 /// 1360 /// \par Usage 1361 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1362 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1363 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1364 /// 1365 /// \donotcall \threadsafe \devonly \enddonotcall 1366 /// 1367 void C_QUATMakeClosest ( const Quaternion *q, const Quaternion *qto, Quaternion *r ); 1368 1369 /// \brief Returns the sum of two quaternions. 1370 /// 1371 /// \note It is safe for p == q == r 1372 /// 1373 /// \param r Resultng rotation quaternion 1374 /// \param axis Rotation axis 1375 /// \param rad Rotation angle in radians 1376 /// 1377 /// \par Usage 1378 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1379 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1380 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1381 /// 1382 /// \donotcall \threadsafe \devonly \enddonotcall 1383 /// 1384 void C_QUATRotAxisRad ( Quaternion *r, const Vec *axis, f32 rad ); 1385 1386 /// \brief Converts a matrix to a unit quaternion. 1387 /// 1388 /// \note It is safe for p == q == r 1389 /// 1390 /// \param r Resulting quaternion 1391 /// \param m Input matrix 1392 /// 1393 /// \par Usage 1394 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1395 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1396 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1397 /// 1398 /// \donotcall \threadsafe \devonly \enddonotcall 1399 /// 1400 void C_QUATMtx ( Quaternion *r, MTX_CONST Mtx m ); 1401 1402 /// \brief Linear interpolation between two quaternions. 1403 /// 1404 /// \note It is safe for p == q == r 1405 /// 1406 /// \param p First quaternion 1407 /// \param q Second quaternion 1408 /// \param r Resulting quaternion (q*t + (1 - t) * p) 1409 /// \param t Interpolation parameter 1410 /// 1411 /// \par Usage 1412 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1413 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1414 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1415 /// 1416 /// \donotcall \threadsafe \devonly \enddonotcall 1417 /// 1418 void C_QUATLerp ( const Quaternion *p, const Quaternion *q, Quaternion *r, f32 t ); 1419 1420 /// \brief Spherical linear interpolation of two quaternions 1421 /// 1422 /// \note It is safe for p == q == r 1423 /// 1424 /// \param p First quaternion 1425 /// \param q Second quaternion 1426 /// \param r Resulting interpolated quaternion (p + q) 1427 /// \param t Interpolation parameter 1428 /// 1429 /// \par Usage 1430 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1431 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1432 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1433 /// 1434 /// \donotcall \threadsafe \devonly \enddonotcall 1435 /// 1436 void C_QUATSlerp ( const Quaternion *p, const Quaternion *q, Quaternion *r, f32 t ); 1437 1438 /// \brief Spherical cubic quadrangle interpolation of two quaternions with derrived inner-quadrangle quaternions. 1439 /// This will be used with the function \ref QUATCompA. 1440 /// 1441 /// \note It is safe for p == q == r 1442 /// 1443 /// \param p First quaternion 1444 /// \param a Derrived inner-quadrangle quaternion 1445 /// \param b Derrived inner-quadrangle quaternion 1446 /// \param q Second quaternion 1447 /// \param r Resulting quaternion (p + q) 1448 /// \param t Interpolation value 1449 /// 1450 /// \par Usage 1451 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1452 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1453 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1454 /// 1455 /// \donotcall \threadsafe \devonly \enddonotcall 1456 /// 1457 void C_QUATSquad ( const Quaternion *p, const Quaternion *a, const Quaternion *b, 1458 const Quaternion *q, Quaternion *r, f32 t ); 1459 1460 /// \brief Compute a, the term used in Boehm-type interpolation. 1461 /// 1462 /// a[n] = q[n] * qexp(-(1/4) * (logN(qinv(q[n])*q[n+1]) + logN(qinv(q[n])*q[n-1]))) 1463 /// 1464 /// \note This is safe for the case where qprev == q == qnext == a. 1465 /// 1466 /// \param qprev Previous quaternion 1467 /// \param q Current quaternion 1468 /// \param qnext Next quaternion 1469 /// \param a Resulting quaternion A 1470 /// 1471 /// \par Usage 1472 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1473 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1474 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1475 /// 1476 /// \donotcall \threadsafe \devonly \enddonotcall 1477 /// 1478 void C_QUATCompA ( const Quaternion *qprev, const Quaternion *q, 1479 const Quaternion *qnext, Quaternion *a ); 1480 1481 /// @} 1482 1483 // PS intrisics version 1484 void PSQUATAdd ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1485 void PSQUATSubtract ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1486 void PSQUATMultiply ( const Quaternion *p, const Quaternion *q, Quaternion *pq ); 1487 void PSQUATDivide ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1488 void PSQUATScale ( const Quaternion *q, Quaternion *r, f32 scale ); 1489 f32 PSQUATDotProduct ( const Quaternion *p, const Quaternion *q ); 1490 void PSQUATNormalize ( const Quaternion *src, Quaternion *unit ); 1491 void PSQUATInverse ( const Quaternion *src, Quaternion *inv ); 1492 1493 // PS assembler version 1494 void ASM_QUATAdd ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1495 void ASM_QUATDivide ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1496 f32 ASM_QUATDotProduct ( const Quaternion *p, const Quaternion *q ); 1497 void ASM_QUATInverse ( const Quaternion *src, Quaternion *inv ); 1498 void ASM_QUATMultiply ( const Quaternion *p, const Quaternion *q, Quaternion *pq ); 1499 void ASM_QUATNormalize ( const Quaternion *src, Quaternion *unit ); 1500 void ASM_QUATScale ( const Quaternion *q, Quaternion *r, f32 scale ); 1501 void ASM_QUATSubtract ( const Quaternion *p, const Quaternion *q, Quaternion *r ); 1502 1503 // Bindings 1504 #ifdef MTX_USE_ASM 1505 #define QUATAdd ASM_QUATAdd 1506 #define QUATSubtract ASM_QUATSubtract 1507 #define QUATMultiply ASM_QUATMultiply 1508 #define QUATDivide ASM_QUATDivide 1509 #define QUATScale ASM_QUATScale 1510 #define QUATDotProduct ASM_QUATDotProduct 1511 #define QUATNormalize ASM_QUATNormalize 1512 #define QUATInverse ASM_QUATInverse 1513 #else 1514 #ifdef MTX_USE_PS 1515 #define QUATAdd PSQUATAdd 1516 #define QUATSubtract PSQUATSubtract 1517 #define QUATMultiply PSQUATMultiply 1518 #define QUATDivide PSQUATDivide 1519 #define QUATScale PSQUATScale 1520 #define QUATDotProduct PSQUATDotProduct 1521 #define QUATNormalize PSQUATNormalize 1522 #define QUATInverse PSQUATInverse 1523 #else // MTX_USE_C 1524 #define QUATAdd C_QUATAdd 1525 #define QUATSubtract C_QUATSubtract 1526 #define QUATMultiply C_QUATMultiply 1527 #define QUATDivide C_QUATDivide 1528 #define QUATScale C_QUATScale 1529 #define QUATDotProduct C_QUATDotProduct 1530 #define QUATNormalize C_QUATNormalize 1531 #define QUATInverse C_QUATInverse 1532 #endif 1533 #endif 1534 1535 #define QUATExp C_QUATExp 1536 #define QUATLogN C_QUATLogN 1537 #define QUATMakeClosest C_QUATMakeClosest 1538 #define QUATRotAxisRad C_QUATRotAxisRad 1539 #define QUATMtx C_QUATMtx 1540 #define QUATLerp C_QUATLerp 1541 #define QUATSlerp C_QUATSlerp 1542 #define QUATSquad C_QUATSquad 1543 #define QUATCompA C_QUATCompA 1544 1545 /*---------------------------------------------------------------------------* 1546 MATRIX STACK SECTION 1547 *---------------------------------------------------------------------------*/ 1548 1549 /// @addtogroup MTX 1550 /// @{ 1551 1552 1553 /// \brief Initializes a matrix stack size and stack ptr from a previously allocated stack 1554 /// This resets the stack pointer to NULL(empty) and updates the stack size. 1555 /// 1556 /// \note The stack (array) memory must have been previously allocated. Use \ref MTXAllocStack and \ref MTXFreeStack to create/destroy the stack. 1557 /// 1558 /// \param sPtr Pointer to \ref MtxStack structure to be initialized 1559 /// \param numMtx Number of matrices in the stack 1560 /// 1561 /// \par Usage 1562 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1563 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1564 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1565 /// 1566 /// \donotcall \threadsafe \devonly \enddonotcall 1567 /// 1568 void MTXInitStack ( MtxStack *sPtr, u32 numMtx ); 1569 1570 /// \brief Copy a matrix to stack pointer + 1. 1571 /// Increment the stack pointer. 1572 /// 1573 /// \param sPtr Pointer to MtxStack structure 1574 /// \param m Matrix to copy into (stack pointer + 1) location 1575 /// \return Returns the resulting stack pointer 1576 /// 1577 /// \par Usage 1578 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1579 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1580 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1581 /// 1582 /// \donotcall \threadsafe \devonly \enddonotcall 1583 /// 1584 MtxPtr MTXPush ( MtxStack *sPtr, MTX_CONST Mtx m ); 1585 1586 /// \brief Concatenate a matrix with the current top of the stack push 1587 /// the resulting matrix onto the stack. 1588 /// This is intended for use in building forward transformations, so 1589 /// concatentation is post-order: 1590 /// 1591 /// (top of stack + 1) = (top of stack x m); 1592 /// 1593 /// \param sPtr Pointer to MtxStack structure 1594 /// \param m Matrix to concatenate with stack pointer and push to (stack pointer + 1) 1595 /// \return Returns the resulting stack pointer 1596 /// 1597 /// \par Usage 1598 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1599 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1600 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1601 /// 1602 /// \donotcall \threadsafe \devonly \enddonotcall 1603 /// 1604 MtxPtr MTXPushFwd ( MtxStack *sPtr, MTX_CONST Mtx m ); 1605 1606 /// \brief Concatenate the inverse of a matrix with the top of the stack 1607 /// and push the resulting matrix onto the stack. 1608 /// This is intended for building inverse transformations so concatenation 1609 /// is pre-order: 1610 /// 1611 /// (top of stack + 1) = (m x top of stack); 1612 /// 1613 /// \note m is not modified by this function. 1614 /// 1615 /// \param sPtr Pointer to MtxStack structure 1616 /// \param m Matrix to inverse-concatenate with stack pointer and push to (stack pointer + 1) 1617 /// \return Returns the resulting stack pointer 1618 /// 1619 /// \par Usage 1620 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1621 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1622 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1623 /// 1624 /// \donotcall \threadsafe \devonly \enddonotcall 1625 /// 1626 MtxPtr MTXPushInv ( MtxStack *sPtr, MTX_CONST Mtx m ); 1627 1628 /// \brief Concatenate the inverse-transpose of a matrix with the top of the 1629 /// stack and push the resulting matrix onto the stack. 1630 /// This is intended for building inverse-transpose matrix for forward 1631 /// transformations of normals, so concatenation is post-order: 1632 /// 1633 /// (top of stack + 1) = (top of stack x m); 1634 /// 1635 /// \param sPtr Pointer to MtxStack structure 1636 /// \param m Matrix to inverse-concatenate with stack pointer and push to (stack pointer + 1) 1637 /// \return Returns the resulting stack pointer 1638 /// 1639 /// \par Usage 1640 /// \note m is not modified by this function. 1641 /// 1642 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1643 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1644 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1645 /// 1646 /// \donotcall \threadsafe \devonly \enddonotcall 1647 /// 1648 MtxPtr MTXPushInvXpose ( MtxStack *sPtr, MTX_CONST Mtx m ); 1649 1650 /// \brief Decrement the stack pointer. 1651 /// 1652 /// \param sPtr Pointer to MtxStack structure 1653 /// \return Returns the stack pointer. 1654 /// 1655 /// \par Usage 1656 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1657 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1658 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1659 /// 1660 /// \donotcall \threadsafe \devonly \enddonotcall 1661 /// 1662 MtxPtr MTXPop ( MtxStack *sPtr ); 1663 1664 /// \brief Return the stack pointer. 1665 /// 1666 /// \param sPtr Pointer to MtxStack structure 1667 /// \return Returns the current stack pointer 1668 /// 1669 /// \par Usage 1670 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1671 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1672 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1673 /// 1674 /// \donotcall \threadsafe \devonly \enddonotcall 1675 /// 1676 MtxPtr MTXGetStackPtr ( const MtxStack *sPtr ); 1677 1678 /// \brief Macro to create a matrix stack. 1679 /// \note This allocates using MEMAllocFromDefaultHeap. This can be modified 1680 /// by the user. 1681 /// 1682 /// \param sPtr Pointer to MtxStack structure 1683 /// \param numMtx Number of \ref Mtx structures to allocate for the stack. 1684 /// 1685 /// \par Usage 1686 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1687 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1688 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1689 /// 1690 /// \donotcall \notthreadsafe \userheap \devonly \enddonotcall 1691 /// 1692 #define MTXAllocStack( sPtr, numMtx ) ( ((MtxStackPtr)(sPtr))->stackBase = (MtxPtr)MEMAllocFromDefaultHeap( ( (numMtx) * sizeof(Mtx) ) ) ) 1693 1694 /// \brief Macro to free a matrix stack. 1695 /// \note This allocates using MEMFreeToDefaultHeap. This can be modified 1696 /// by the user. 1697 /// 1698 /// \param sPtr Pointer to MtxStack structure 1699 /// 1700 /// \par Usage 1701 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1702 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1703 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1704 /// 1705 /// \donotcall \notthreadsafe \userheap \devonly \enddonotcall 1706 /// 1707 #define MTXFreeStack( sPtr ) ( MEMFreeToDefaultHeap( (void*)( ((MtxStackPtr)(sPtr))->stackBase ) ) ) 1708 1709 /// @} 1710 1711 /*---------------------------------------------------------------------------* 1712 SPECIAL PURPOSE MATRIX SECTION 1713 *---------------------------------------------------------------------------*/ 1714 1715 /// @addtogroup MTX 1716 /// @{ 1717 1718 /// \brief Creates a reordered (column-major) matrix from a row-major matrix. 1719 /// This is useful for getting better performance for the MTXRO* functions. 1720 /// 1721 /// \warning It is not safe to have src == dst. 1722 /// 1723 /// \param src Source matrix 1724 /// \param dest Destination matrix, note type is ROMtx. 1725 /// 1726 /// \par Usage 1727 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1728 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1729 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1730 /// 1731 /// \donotcall \threadsafe \devonly \enddonotcall 1732 /// 1733 void C_MTXReorder ( MTX_CONST Mtx src, ROMtx dest ); 1734 1735 /// \brief Multiplies an array of vectors by a reordered matrix. 1736 /// 1737 /// \note It is ok for source == destination. 1738 /// \note Number of vertices transformed cannot be less than 2. 1739 /// 1740 /// \param m Reordered matrix 1741 /// \param srcBase Start of source vector array 1742 /// \param dstBase Start of the resulting vector array 1743 /// \param count Number of vectors in srcBase and dstBase arrays. Count must be greater than 2. 1744 /// 1745 /// \par Usage 1746 /// - Add "#define MTX_USE_ASM" prior to including the mtx header to use PPC Assembly based version 1747 /// - Add "#define MTX_USE_PS" prior to including the mtx header to use PPC Paired-Single instruction based version 1748 /// - Add "#define MTX_USE_C" prior to including the mtx header to use C implementation (default). This is useful for debugging. 1749 /// 1750 /// \donotcall \threadsafe \devonly \enddonotcall 1751 /// 1752 void C_MTXROMultVecArray( MTX_CONST ROMtx m, const Vec *srcBase, Vec *dstBase, u32 count ); 1753 1754 /// @} 1755 1756 void PSMTXReorder ( MTX_CONST Mtx src, ROMtx dest ); 1757 void ASM_MTXReorder ( MTX_CONST Mtx src, ROMtx dest ); 1758 1759 // Bindings 1760 #ifdef MTX_USE_ASM 1761 #define MTXReorder ASM_MTXReorder 1762 #else 1763 #ifdef MTX_USE_PS 1764 #define MTXReorder PSMTXReorder 1765 #else 1766 #define MTXReorder C_MTXReorder 1767 #endif 1768 #endif 1769 1770 #define MTXROMultVecArray C_MTXROMultVecArray 1771 1772 /*---------------------------------------------------------------------------*/ 1773 1774 #ifdef __cplusplus 1775 } 1776 #endif 1777 1778 #endif // __MTXVEC_H__ 1779 1780 /*===========================================================================*/ 1781 1782