1 // 2 // Copyright 2016 Pixar 3 // 4 // Licensed under the Apache License, Version 2.0 (the "Apache License") 5 // with the following modification; you may not use this file except in 6 // compliance with the Apache License and the following modification to it: 7 // Section 6. Trademarks. is deleted and replaced with: 8 // 9 // 6. Trademarks. This License does not grant permission to use the trade 10 // names, trademarks, service marks, or product names of the Licensor 11 // and its affiliates, except as required to comply with Section 4(c) of 12 // the License and to reproduce the content of the NOTICE file. 13 // 14 // You may obtain a copy of the Apache License at 15 // 16 // http://www.apache.org/licenses/LICENSE-2.0 17 // 18 // Unless required by applicable law or agreed to in writing, software 19 // distributed under the Apache License with the above modification is 20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 21 // KIND, either express or implied. See the Apache License for the specific 22 // language governing permissions and limitations under the Apache License. 23 // 24 //////////////////////////////////////////////////////////////////////// 25 // This file is generated by a script. Do not edit directly. Edit the 26 // matrix4.template.h file to make changes. 27 28 #ifndef PXR_BASE_GF_MATRIX4F_H 29 #define PXR_BASE_GF_MATRIX4F_H 30 31 /// \file gf/matrix4f.h 32 /// \ingroup group_gf_LinearAlgebra 33 34 #include "pxr/pxr.h" 35 #include "pxr/base/gf/api.h" 36 #include "pxr/base/gf/declare.h" 37 #include "pxr/base/gf/matrixData.h" 38 #include "pxr/base/gf/vec4f.h" 39 #include "pxr/base/gf/traits.h" 40 #include "pxr/base/gf/homogeneous.h" 41 #include "pxr/base/gf/limits.h" 42 #include "pxr/base/gf/math.h" 43 #include "pxr/base/gf/vec3f.h" 44 45 #include <boost/functional/hash.hpp> 46 47 #include <iosfwd> 48 #include <vector> 49 50 PXR_NAMESPACE_OPEN_SCOPE 51 52 template <> 53 struct GfIsGfMatrix<class GfMatrix4f> { static const bool value = true; }; 54 55 class GfMatrix4d; 56 class GfMatrix4f; 57 class GfQuatf; 58 class GfRotation; 59 class GfMatrix3f; 60 61 /// \class GfMatrix4f 62 /// \ingroup group_gf_LinearAlgebra 63 /// 64 /// Stores a 4x4 matrix of \c float elements. A basic type. 65 /// 66 /// Matrices are defined to be in row-major order, so <c>matrix[i][j]</c> 67 /// indexes the element in the \e i th row and the \e j th column. 68 /// 69 /// <h3>3D Transformations</h3> 70 /// 71 /// The following methods interpret a GfMatrix4f as a 3D 72 /// transformation: SetRotate(), SetScale(), SetTranslate(), SetLookAt(), 73 /// Factor(), ExtractTranslation(), ExtractRotation(), Transform(), TransformDir(). 74 /// By convention, vectors are treated primarily as row vectors, 75 /// implying the following: 76 /// \li Transformation matrices are organized to deal with row 77 /// vectors, not column vectors. For example, the last row of a matrix 78 /// contains the translation amounts. 79 /// \li Each of the Set() methods below completely rewrites the 80 /// matrix; for example, SetTranslate() yields a matrix 81 /// which does nothing but translate. 82 /// \li When multiplying two transformation matrices, the matrix 83 /// on the left applies a more local transformation to a row 84 /// vector. For example, if R represents a rotation 85 /// matrix and T represents a translation matrix, the 86 /// product R*T will rotate a row vector, then translate 87 /// it. 88 class GfMatrix4f 89 { 90 public: 91 typedef float ScalarType; 92 93 static const size_t numRows = 4; 94 static const size_t numColumns = 4; 95 96 /// Default constructor. Leaves the matrix component values undefined. 97 GfMatrix4f() = default; 98 99 /// Constructor. Initializes the matrix from 16 independent 100 /// \c float values, specified in row-major order. For example, 101 /// parameter \e m10 specifies the value in row 1 and column 0. 102 GfMatrix4f(float m00, float m01, float m02, float m03, 103 float m10, float m11, float m12, float m13, 104 float m20, float m21, float m22, float m23, 105 float m30, float m31, float m32, float m33) { 106 Set(m00, m01, m02, m03, 107 m10, m11, m12, m13, 108 m20, m21, m22, m23, 109 m30, m31, m32, m33); 110 } 111 112 /// Constructor. Initializes the matrix from a 4x4 array 113 /// of \c float values, specified in row-major order. 114 GfMatrix4f(const float m[4][4]) { 115 Set(m); 116 } 117 118 /// Constructor. Explicitly initializes the matrix to \e s times the 119 /// identity matrix. 120 explicit GfMatrix4f(float s) { 121 SetDiagonal(s); 122 } 123 124 /// Constructor. Explicitly initializes the matrix to diagonal form, 125 /// with the \e i th element on the diagonal set to <c>v[i]</c>. 126 explicit GfMatrix4f(const GfVec4f& v) { 127 SetDiagonal(v); 128 } 129 130 /// Constructor. Initialize the matrix from a vector of vectors of 131 /// double. The vector is expected to be 4x4. If it is 132 /// too big, only the first 4 rows and/or columns will be used. 133 /// If it is too small, uninitialized elements will be filled in with 134 /// the corresponding elements from an identity matrix. 135 /// 136 GF_API 137 explicit GfMatrix4f(const std::vector< std::vector<double> >& v); 138 139 /// Constructor. Initialize the matrix from a vector of vectors of 140 /// float. The vector is expected to be 4x4. If it is 141 /// too big, only the first 4 rows and/or columns will be used. 142 /// If it is too small, uninitialized elements will be filled in with 143 /// the corresponding elements from an identity matrix. 144 /// 145 GF_API 146 explicit GfMatrix4f(const std::vector< std::vector<float> >& v); 147 148 /// Constructor. Initialize the matrix from 4 row vectors of 149 /// double. Each vector is expected to length 4. If it is too 150 /// big, only the first 4 items will be used. If it is too small, 151 /// uninitialized elements will be filled in with the 152 /// corresponding elements from an identity matrix. 153 /// 154 GF_API 155 explicit GfMatrix4f(const std::vector<double>& r0, 156 const std::vector<double>& r1, 157 const std::vector<double>& r2, 158 const std::vector<double>& r3); 159 160 /// Constructor. Initialize the matrix from 4 row vectors of 161 /// float. Each vector is expected to length 4. If it is too 162 /// big, only the first 4 items will be used. If it is too small, 163 /// uninitialized elements will be filled in with the 164 /// corresponding elements from an identity matrix. 165 /// 166 GF_API 167 explicit GfMatrix4f(const std::vector<float>& r0, 168 const std::vector<float>& r1, 169 const std::vector<float>& r2, 170 const std::vector<float>& r3); 171 172 /// Constructor. Initializes a transformation matrix to perform the 173 /// indicated rotation and translation. 174 GF_API 175 GfMatrix4f(const GfRotation& rotate, 176 const GfVec3f& translate); 177 178 /// Constructor. Initializes a transformation matrix to perform the 179 /// indicated rotation and translation. 180 GF_API 181 GfMatrix4f(const GfMatrix3f& rotmx, 182 const GfVec3f& translate); 183 /// This explicit constructor converts a "double" matrix to a "float" matrix. 184 GF_API 185 explicit GfMatrix4f(const class GfMatrix4d& m); 186 187 /// Sets a row of the matrix from a Vec4. 188 void SetRow(int i, const GfVec4f & v) { 189 _mtx[i][0] = v[0]; 190 _mtx[i][1] = v[1]; 191 _mtx[i][2] = v[2]; 192 _mtx[i][3] = v[3]; 193 } 194 195 /// Sets a column of the matrix from a Vec4. 196 void SetColumn(int i, const GfVec4f & v) { 197 _mtx[0][i] = v[0]; 198 _mtx[1][i] = v[1]; 199 _mtx[2][i] = v[2]; 200 _mtx[3][i] = v[3]; 201 } 202 203 /// Gets a row of the matrix as a Vec4. 204 GfVec4f GetRow(int i) const { 205 return GfVec4f(_mtx[i][0], _mtx[i][1], _mtx[i][2], _mtx[i][3]); 206 } 207 208 /// Gets a column of the matrix as a Vec4. 209 GfVec4f GetColumn(int i) const { 210 return GfVec4f(_mtx[0][i], _mtx[1][i], _mtx[2][i], _mtx[3][i]); 211 } 212 213 /// Sets the matrix from 16 independent \c float values, 214 /// specified in row-major order. For example, parameter \e m10 specifies 215 /// the value in row 1 and column 0. 216 GfMatrix4f& Set(float m00, float m01, float m02, float m03, 217 float m10, float m11, float m12, float m13, 218 float m20, float m21, float m22, float m23, 219 float m30, float m31, float m32, float m33) { 220 _mtx[0][0] = m00; _mtx[0][1] = m01; _mtx[0][2] = m02; _mtx[0][3] = m03; 221 _mtx[1][0] = m10; _mtx[1][1] = m11; _mtx[1][2] = m12; _mtx[1][3] = m13; 222 _mtx[2][0] = m20; _mtx[2][1] = m21; _mtx[2][2] = m22; _mtx[2][3] = m23; 223 _mtx[3][0] = m30; _mtx[3][1] = m31; _mtx[3][2] = m32; _mtx[3][3] = m33; 224 return *this; 225 } 226 227 /// Sets the matrix from a 4x4 array of \c float 228 /// values, specified in row-major order. 229 GfMatrix4f& Set(const float m[4][4]) { 230 _mtx[0][0] = m[0][0]; 231 _mtx[0][1] = m[0][1]; 232 _mtx[0][2] = m[0][2]; 233 _mtx[0][3] = m[0][3]; 234 _mtx[1][0] = m[1][0]; 235 _mtx[1][1] = m[1][1]; 236 _mtx[1][2] = m[1][2]; 237 _mtx[1][3] = m[1][3]; 238 _mtx[2][0] = m[2][0]; 239 _mtx[2][1] = m[2][1]; 240 _mtx[2][2] = m[2][2]; 241 _mtx[2][3] = m[2][3]; 242 _mtx[3][0] = m[3][0]; 243 _mtx[3][1] = m[3][1]; 244 _mtx[3][2] = m[3][2]; 245 _mtx[3][3] = m[3][3]; 246 return *this; 247 } 248 249 /// Sets the matrix to the identity matrix. 250 GfMatrix4f& SetIdentity() { 251 return SetDiagonal(1); 252 } 253 254 /// Sets the matrix to zero. 255 GfMatrix4f& SetZero() { 256 return SetDiagonal(0); 257 } 258 259 /// Sets the matrix to \e s times the identity matrix. 260 GF_API 261 GfMatrix4f& SetDiagonal(float s); 262 263 /// Sets the matrix to have diagonal (<c>v[0], v[1], v[2], v[3]</c>). 264 GF_API 265 GfMatrix4f& SetDiagonal(const GfVec4f&); 266 267 /// Fills a 4x4 array of \c float values with the values in 268 /// the matrix, specified in row-major order. 269 GF_API 270 float* Get(float m[4][4]) const; 271 272 /// Returns raw access to components of matrix as an array of 273 /// \c float values. Components are in row-major order. 274 float* data() { 275 return _mtx.GetData(); 276 } 277 278 /// Returns const raw access to components of matrix as an array of 279 /// \c float values. Components are in row-major order. 280 const float* data() const { 281 return _mtx.GetData(); 282 } 283 284 /// Returns vector components as an array of \c float values. 285 float* GetArray() { 286 return _mtx.GetData(); 287 } 288 289 /// Returns vector components as a const array of \c float values. 290 const float* GetArray() const { 291 return _mtx.GetData(); 292 } 293 294 /// Accesses an indexed row \e i of the matrix as an array of 4 \c 295 /// float values so that standard indexing (such as <c>m[0][1]</c>) 296 /// works correctly. 297 float* operator [](int i) { return _mtx[i]; } 298 299 /// Accesses an indexed row \e i of the matrix as an array of 4 \c 300 /// float values so that standard indexing (such as <c>m[0][1]</c>) 301 /// works correctly. 302 const float* operator [](int i) const { return _mtx[i]; } 303 304 /// Hash. 305 friend inline size_t hash_value(GfMatrix4f const &m) { 306 int nElems = 4 * 4; 307 size_t h = 0; 308 const float *p = m.GetArray(); 309 while (nElems--) 310 boost::hash_combine(h, *p++); 311 return h; 312 } 313 314 /// Tests for element-wise matrix equality. All elements must match 315 /// exactly for matrices to be considered equal. 316 GF_API 317 bool operator ==(const GfMatrix4d& m) const; 318 319 /// Tests for element-wise matrix equality. All elements must match 320 /// exactly for matrices to be considered equal. 321 GF_API 322 bool operator ==(const GfMatrix4f& m) const; 323 324 /// Tests for element-wise matrix inequality. All elements must match 325 /// exactly for matrices to be considered equal. 326 bool operator !=(const GfMatrix4d& m) const { 327 return !(*this == m); 328 } 329 330 /// Tests for element-wise matrix inequality. All elements must match 331 /// exactly for matrices to be considered equal. 332 bool operator !=(const GfMatrix4f& m) const { 333 return !(*this == m); 334 } 335 336 /// Returns the transpose of the matrix. 337 GF_API 338 GfMatrix4f GetTranspose() const; 339 340 /// Returns the inverse of the matrix, or FLT_MAX * SetIdentity() if the 341 /// matrix is singular. (FLT_MAX is the largest value a \c float can have, 342 /// as defined by the system.) The matrix is considered singular if the 343 /// determinant is less than or equal to the optional parameter \e eps. If 344 /// \e det is non-null, <c>*det</c> is set to the determinant. 345 GF_API 346 GfMatrix4f GetInverse(double* det = NULL, double eps = 0) const; 347 348 /// Returns the determinant of the matrix. 349 GF_API 350 double GetDeterminant() const; 351 352 /// Sets a row of the matrix from a Vec3. 353 /// The fourth element of the row is ignored. 354 void SetRow3(int i, const GfVec3f & v) { 355 _mtx[i][0] = v[0]; 356 _mtx[i][1] = v[1]; 357 _mtx[i][2] = v[2]; 358 } 359 360 /// Gets a row of the matrix as a Vec3. 361 GfVec3f GetRow3(int i) const { 362 return GfVec3f(_mtx[i][0], _mtx[i][1], _mtx[i][2]); 363 } 364 365 /// Returns the determinant of the upper 3x3 matrix. This method is useful 366 /// when the matrix describes a linear transformation such as a rotation or 367 /// scale because the other values in the 4x4 matrix are not important. 368 double GetDeterminant3() const { 369 return _GetDeterminant3(0, 1, 2, 0, 1, 2); 370 } 371 372 /// Returns true, if the row vectors of the upper 3x3 matrix form an 373 /// orthogonal basis. Note they do not have to be unit length for this 374 /// test to return true. 375 bool HasOrthogonalRows3() const { 376 // XXX Should add GfAreOrthogonal(v0, v1, v2) (which also 377 // GfRotation::Decompose() could use). 378 GfVec3f axis0(GetRow3(0)), axis1(GetRow3(1)), axis2(GetRow3(2)); 379 return (GfAbs(GfDot(axis0, axis1)) < GF_MIN_ORTHO_TOLERANCE && 380 GfAbs(GfDot(axis0, axis2)) < GF_MIN_ORTHO_TOLERANCE && 381 GfAbs(GfDot(axis1, axis2)) < GF_MIN_ORTHO_TOLERANCE); 382 } 383 384 /// Makes the matrix orthonormal in place. This is an iterative method 385 /// that is much more stable than the previous cross/cross method. If the 386 /// iterative method does not converge, a warning is issued. 387 /// 388 /// Returns true if the iteration converged, false otherwise. Leaves any 389 /// translation part of the matrix unchanged. If \a issueWarning is true, 390 /// this method will issue a warning if the iteration does not converge, 391 /// otherwise it will be silent. 392 GF_API 393 bool Orthonormalize(bool issueWarning=true); 394 395 /// Returns an orthonormalized copy of the matrix. 396 GF_API 397 GfMatrix4f GetOrthonormalized(bool issueWarning=true) const; 398 399 /// Returns the sign of the determinant of the upper 3x3 matrix, i.e. 1 400 /// for a right-handed matrix, -1 for a left-handed matrix, and 0 for a 401 /// singular matrix. 402 GF_API 403 double GetHandedness() const; 404 405 /// Returns true if the vectors in the upper 3x3 matrix form a 406 /// right-handed coordinate system. 407 bool IsRightHanded() const { 408 return GetHandedness() == 1.0; 409 } 410 411 /// Returns true if the vectors in the upper 3x3 matrix form a left-handed 412 /// coordinate system. 413 bool IsLeftHanded() const { 414 return GetHandedness() == -1.0; 415 } 416 417 /// Post-multiplies matrix \e m into this matrix. 418 GF_API 419 GfMatrix4f& operator *=(const GfMatrix4f& m); 420 421 /// Multiplies the matrix by a float. 422 GF_API 423 GfMatrix4f& operator *=(double); 424 425 /// Returns the product of a matrix and a float. 426 friend GfMatrix4f operator *(const GfMatrix4f& m1, double d) 427 { 428 GfMatrix4f m = m1; 429 return m *= d; 430 } 431 432 /// 433 // Returns the product of a matrix and a float. 434 friend GfMatrix4f operator *(double d, const GfMatrix4f& m) 435 { 436 return m * d; 437 } 438 439 /// Adds matrix \e m to this matrix. 440 GF_API 441 GfMatrix4f& operator +=(const GfMatrix4f& m); 442 443 /// Subtracts matrix \e m from this matrix. 444 GF_API 445 GfMatrix4f& operator -=(const GfMatrix4f& m); 446 447 /// Returns the unary negation of matrix \e m. 448 GF_API 449 friend GfMatrix4f operator -(const GfMatrix4f& m); 450 451 /// Adds matrix \e m2 to \e m1 452 friend GfMatrix4f operator +(const GfMatrix4f& m1, const GfMatrix4f& m2) 453 { 454 GfMatrix4f tmp(m1); 455 tmp += m2; 456 return tmp; 457 } 458 459 /// Subtracts matrix \e m2 from \e m1. 460 friend GfMatrix4f operator -(const GfMatrix4f& m1, const GfMatrix4f& m2) 461 { 462 GfMatrix4f tmp(m1); 463 tmp -= m2; 464 return tmp; 465 } 466 467 /// Multiplies matrix \e m1 by \e m2. 468 friend GfMatrix4f operator *(const GfMatrix4f& m1, const GfMatrix4f& m2) 469 { 470 GfMatrix4f tmp(m1); 471 tmp *= m2; 472 return tmp; 473 } 474 475 /// Divides matrix \e m1 by \e m2 (that is, <c>m1 * inv(m2)</c>). 476 friend GfMatrix4f operator /(const GfMatrix4f& m1, const GfMatrix4f& m2) 477 { 478 return(m1 * m2.GetInverse()); 479 } 480 481 /// Returns the product of a matrix \e m and a column vector \e vec. 482 friend inline GfVec4f operator *(const GfMatrix4f& m, const GfVec4f& vec) { 483 return GfVec4f(vec[0] * m._mtx[0][0] + vec[1] * m._mtx[0][1] + vec[2] * m._mtx[0][2] + vec[3] * m._mtx[0][3], 484 vec[0] * m._mtx[1][0] + vec[1] * m._mtx[1][1] + vec[2] * m._mtx[1][2] + vec[3] * m._mtx[1][3], 485 vec[0] * m._mtx[2][0] + vec[1] * m._mtx[2][1] + vec[2] * m._mtx[2][2] + vec[3] * m._mtx[2][3], 486 vec[0] * m._mtx[3][0] + vec[1] * m._mtx[3][1] + vec[2] * m._mtx[3][2] + vec[3] * m._mtx[3][3]); 487 } 488 489 /// Returns the product of row vector \e vec and a matrix \e m. 490 friend inline GfVec4f operator *(const GfVec4f &vec, const GfMatrix4f& m) { 491 return GfVec4f(vec[0] * m._mtx[0][0] + vec[1] * m._mtx[1][0] + vec[2] * m._mtx[2][0] + vec[3] * m._mtx[3][0], 492 vec[0] * m._mtx[0][1] + vec[1] * m._mtx[1][1] + vec[2] * m._mtx[2][1] + vec[3] * m._mtx[3][1], 493 vec[0] * m._mtx[0][2] + vec[1] * m._mtx[1][2] + vec[2] * m._mtx[2][2] + vec[3] * m._mtx[3][2], 494 vec[0] * m._mtx[0][3] + vec[1] * m._mtx[1][3] + vec[2] * m._mtx[2][3] + vec[3] * m._mtx[3][3]); 495 } 496 497 /// Sets matrix to specify a uniform scaling by \e scaleFactor. 498 GF_API 499 GfMatrix4f& SetScale(float scaleFactor); 500 501 /// Returns the matrix with any scaling or shearing removed, 502 /// leaving only the rotation and translation. 503 /// If the matrix cannot be decomposed, returns the original matrix. 504 GF_API 505 GfMatrix4f RemoveScaleShear() const; 506 507 /// \name 3D Transformation Utilities 508 /// @{ 509 510 /// Sets the matrix to specify a rotation equivalent to \e rot, 511 /// and clears the translation. 512 GF_API 513 GfMatrix4f& SetRotate(const GfQuatf &rot); 514 515 /// Sets the matrix to specify a rotation equivalent to \e rot, 516 /// without clearing the translation. 517 GF_API 518 GfMatrix4f& SetRotateOnly(const GfQuatf &rot); 519 520 /// Sets the matrix to specify a rotation equivalent to \e rot, 521 /// and clears the translation. 522 GF_API 523 GfMatrix4f& SetRotate(const GfRotation &rot); 524 525 /// Sets the matrix to specify a rotation equivalent to \e rot, 526 /// without clearing the translation. 527 GF_API 528 GfMatrix4f& SetRotateOnly(const GfRotation &rot); 529 530 /// Sets the matrix to specify a rotation equivalent to \e mx, 531 /// and clears the translation. 532 GF_API 533 GfMatrix4f& SetRotate(const GfMatrix3f &mx); 534 535 /// Sets the matrix to specify a rotation equivalent to \e mx, 536 /// without clearing the translation. 537 GF_API 538 GfMatrix4f& SetRotateOnly(const GfMatrix3f &mx); 539 540 /// Sets the matrix to specify a nonuniform scaling in x, y, and z by 541 /// the factors in vector \e scaleFactors. 542 GF_API 543 GfMatrix4f& SetScale(const GfVec3f &scaleFactors); 544 545 /// Sets matrix to specify a translation by the vector \e trans, 546 /// and clears the rotation. 547 GF_API 548 GfMatrix4f& SetTranslate(const GfVec3f &trans); 549 550 /// Sets matrix to specify a translation by the vector \e trans, 551 /// without clearing the rotation. 552 GF_API 553 GfMatrix4f& SetTranslateOnly(const GfVec3f &t); 554 555 /// Sets matrix to specify a rotation by \e rotate and a 556 /// translation by \e translate. 557 GF_API 558 GfMatrix4f& SetTransform(const GfRotation& rotate, 559 const GfVec3f& translate); 560 561 /// Sets matrix to specify a rotation by \e rotmx and a 562 /// translation by \e translate. 563 GF_API 564 GfMatrix4f& SetTransform(const GfMatrix3f& rotmx, 565 const GfVec3f& translate); 566 567 /// Sets the matrix to specify a viewing matrix from parameters 568 /// similar to those used by <c>gluLookAt(3G)</c>. \e eyePoint 569 /// represents the eye point in world space. \e centerPoint 570 /// represents the world-space center of attention. \e upDirection 571 /// is a vector indicating which way is up. 572 GF_API 573 GfMatrix4f& SetLookAt(const GfVec3f &eyePoint, 574 const GfVec3f ¢erPoint, 575 const GfVec3f &upDirection); 576 577 /// Sets the matrix to specify a viewing matrix from a world-space 578 /// \e eyePoint and a world-space rotation that rigidly rotates the 579 /// orientation from its canonical frame, which is defined to be 580 /// looking along the <c>-z</c> axis with the <c>+y</c> axis as the up 581 /// direction. 582 GF_API 583 GfMatrix4f& SetLookAt(const GfVec3f &eyePoint, 584 const GfRotation &orientation); 585 586 /// Factors the matrix into 5 components: 587 /// \li <c>\e M = r * s * -r * u * t</c> 588 /// where 589 /// \li \e t is a translation. 590 /// \li \e u and \e r are rotations, and \e -r is the transpose 591 /// (inverse) of \e r. The \e u matrix may contain shear 592 /// information. 593 /// \li \e s is a scale. 594 /// Any projection information could be returned in matrix \e p, 595 /// but currently p is never modified. 596 /// 597 /// Returns \c false if the matrix is singular (as determined by \e eps). 598 /// In that case, any zero scales in \e s are clamped to \e eps 599 /// to allow computation of \e u. 600 GF_API 601 bool Factor(GfMatrix4f* r, GfVec3f* s, GfMatrix4f* u, 602 GfVec3f* t, GfMatrix4f* p, 603 float eps = 1e-5) const; 604 605 /// Returns the translation part of the matrix, defined as the first three 606 /// elements of the last row. 607 GfVec3f ExtractTranslation() const { 608 return GfVec3f(_mtx[3][0], _mtx[3][1], _mtx[3][2]); 609 } 610 611 /// Returns the rotation corresponding to this matrix. This works well 612 /// only if the matrix represents a rotation. 613 /// 614 /// For good results, consider calling Orthonormalize() before calling 615 /// this method. 616 GF_API 617 GfRotation ExtractRotation() const; 618 619 /// Return the rotation corresponding to this matrix as a quaternion. 620 /// This works well only if the matrix represents a rotation. 621 /// 622 /// For good results, consider calling Orthonormalize() before calling 623 /// this method. 624 GF_API 625 GfQuatf ExtractRotationQuat() const; 626 627 /// Decompose the rotation corresponding to this matrix about 3 orthogonal 628 /// axes. If the axes are not orthogonal, warnings will be spewed. 629 /// 630 /// This is a convenience method that is equivalent to calling 631 /// ExtractRotation().Decompose(). 632 GF_API 633 GfVec3f DecomposeRotation(const GfVec3f &axis0, 634 const GfVec3f &axis1, 635 const GfVec3f &axis2) const; 636 637 /// Returns the rotation corresponding to this matrix. This works well 638 /// only if the matrix represents a rotation. 639 /// 640 /// For good results, consider calling Orthonormalize() before calling 641 /// this method. 642 GF_API 643 GfMatrix3f ExtractRotationMatrix() const; 644 645 /// Transforms the row vector \e vec by the matrix, returning the result. 646 /// This treats the vector as a 4-component vector whose fourth component 647 /// is 1. 648 GfVec3d Transform(const GfVec3d &vec) const { 649 return GfProject(GfVec4d( 650 vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0], 651 vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1], 652 vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2], 653 vec[0] * _mtx[0][3] + vec[1] * _mtx[1][3] + vec[2] * _mtx[2][3] + _mtx[3][3])); 654 } 655 656 /// Transforms the row vector \e vec by the matrix, returning the result. 657 /// This treats the vector as a 4-component vector whose fourth component 658 /// is 1. This is an overloaded method; it differs from the other version 659 /// in that it returns a different value type. 660 GfVec3f Transform(const GfVec3f &vec) const { 661 return (GfProject(GfVec4f( 662 vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0], 663 vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1], 664 vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2], 665 vec[0] * _mtx[0][3] + vec[1] * _mtx[1][3] + vec[2] * _mtx[2][3] + _mtx[3][3]))); 666 } 667 668 /// Transforms row vector \e vec by the matrix, returning the result. This 669 /// treats the vector as a direction vector, so the translation 670 /// information in the matrix is ignored. That is, it treats the vector as 671 /// a 4-component vector whose fourth component is 0. 672 GfVec3d TransformDir(const GfVec3d &vec) const { 673 return GfVec3d( 674 vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0], 675 vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1], 676 vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2]); 677 } 678 679 /// Transforms row vector \e vec by the matrix, returning the result. This 680 /// treats the vector as a direction vector, so the translation 681 /// information in the matrix is ignored. That is, it treats the vector as 682 /// a 4-component vector whose fourth component is 0. This is an 683 /// overloaded method; it differs from the other version in that it 684 /// returns a different value type. 685 GfVec3f TransformDir(const GfVec3f &vec) const { 686 return GfVec3f( 687 vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0], 688 vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1], 689 vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2]); 690 } 691 692 /// Transforms the row vector \e vec by the matrix, returning the result. 693 /// This treats the vector as a 4-component vector whose fourth component 694 /// is 1 and ignores the fourth column of the matrix (i.e. assumes it is 695 /// (0, 0, 0, 1)). 696 GfVec3d TransformAffine(const GfVec3d &vec) const { 697 return GfVec3d( 698 vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0], 699 vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1], 700 vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2]); 701 } 702 703 /// Transforms the row vector \e vec by the matrix, returning the result. 704 /// This treats the vector as a 4-component vector whose fourth component 705 /// is 1 and ignores the fourth column of the matrix (i.e. assumes it is 706 /// (0, 0, 0, 1)). 707 GfVec3f TransformAffine(const GfVec3f &vec) const { 708 return GfVec3f( 709 vec[0] * _mtx[0][0] + vec[1] * _mtx[1][0] + vec[2] * _mtx[2][0] + _mtx[3][0], 710 vec[0] * _mtx[0][1] + vec[1] * _mtx[1][1] + vec[2] * _mtx[2][1] + _mtx[3][1], 711 vec[0] * _mtx[0][2] + vec[1] * _mtx[1][2] + vec[2] * _mtx[2][2] + _mtx[3][2]); 712 } 713 /// @} 714 715 private: 716 /// Returns the determinant of the 3x3 submatrix specified by the three 717 /// given row and column indices (0-3 for each). 718 GF_API 719 double _GetDeterminant3(size_t row1, size_t row2, size_t row3, 720 size_t col1, size_t col2, size_t col3) const; 721 722 /// Diagonalizes the upper 3x3 matrix of a matrix known to be symmetric. 723 void _Jacobi3(GfVec3d *eigenvalues, GfVec3d eigenvectors[3]) const; 724 725 /// Set the 3x3 submatrix to the rotation given by a quaternion, 726 /// defined by the real component \p r and imaginary components \p i. 727 void _SetRotateFromQuat(float r, const GfVec3f& i); 728 729 730 private: 731 /// Matrix storage, in row-major order. 732 GfMatrixData<float, 4, 4> _mtx; 733 734 // Friend declarations 735 friend class GfMatrix4d; 736 }; 737 738 739 /// Tests for equality within a given tolerance, returning \c true if the 740 /// difference between each component of the matrix is less than or equal 741 /// to \p tolerance, or false otherwise. 742 GF_API 743 bool GfIsClose(GfMatrix4f const &m1, GfMatrix4f const &m2, double tolerance); 744 745 /// Output a GfMatrix4f 746 /// \ingroup group_gf_DebuggingOutput 747 GF_API std::ostream& operator<<(std::ostream &, GfMatrix4f const &); 748 749 PXR_NAMESPACE_CLOSE_SCOPE 750 751 #endif // PXR_BASE_GF_MATRIX4F_H 752