 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:08:58 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: Quaternion.h * 00003 * 00004 * Copyright (C) 2002-2012 The PixelLight Team (http://www.pixellight.org/) 00005 * 00006 * This file is part of PixelLight. 00007 * 00008 * PixelLight is free software: you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation, either version 3 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * PixelLight is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with PixelLight. If not, see <http://www.gnu.org/licenses/>. 00020 \*********************************************************/ 00021 00022 00023 #ifndef __PLMATH_QUATERNION_H__ 00024 #define __PLMATH_QUATERNION_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLMath/Vector4.h" 00032 00033 00034 //[-------------------------------------------------------] 00035 //[ Namespace ] 00036 //[-------------------------------------------------------] 00037 namespace PLMath { 00038 00039 00040 //[-------------------------------------------------------] 00041 //[ Classes ] 00042 //[-------------------------------------------------------] 00043 /** 00044 * @brief 00045 * Quaternion 00046 * 00047 * @note 00048 * - Orientation quaternions are unit quaternions 00049 */ 00050 class Quaternion { 00051 00052 00053 //[-------------------------------------------------------] 00054 //[ Public definitions ] 00055 //[-------------------------------------------------------] 00056 public: 00057 /** 00058 * @brief 00059 * Component 00060 */ 00061 enum Component { 00062 W = 0, /**< W component */ 00063 X = 1, /**< X component */ 00064 Y = 2, /**< Y component */ 00065 Z = 3 /**< Z component */ 00066 }; 00067 00068 00069 //[-------------------------------------------------------] 00070 //[ Public static data ] 00071 //[-------------------------------------------------------] 00072 public: 00073 static PLMATH_API const Quaternion Zero; /**< 0.0, 0.0, 0.0, 0.0 */ 00074 static PLMATH_API const Quaternion Identity; /**< 1.0, 0.0, 0.0, 0.0 */ 00075 00076 00077 //[-------------------------------------------------------] 00078 //[ Public data ] 00079 //[-------------------------------------------------------] 00080 public: 00081 /** 00082 * @brief 00083 * Some direct quaternion element accesses 00084 */ 00085 union { 00086 /* 00087 * @brief 00088 * 0 = scalar (w), >0 = vector 00089 */ 00090 float fQ[4]; 00091 00092 /* 00093 * @brief 00094 * w = scalar, x&y&z = vector 00095 */ 00096 struct { 00097 float w, x, y, z; 00098 }; 00099 }; 00100 00101 00102 //[-------------------------------------------------------] 00103 //[ Public functions ] 00104 //[-------------------------------------------------------] 00105 public: 00106 //[-------------------------------------------------------] 00107 //[ Constructors ] 00108 //[-------------------------------------------------------] 00109 /** 00110 * @brief 00111 * Default constructor setting an identity quaternion 00112 */ 00113 inline Quaternion(); 00114 00115 inline Quaternion(float fW, float fX, float fY, float fZ); 00116 inline Quaternion(const float fQ[]); 00117 inline Quaternion(const Quaternion &qQ); 00118 inline Quaternion(const Vector3 &vAxis, float fAngle); 00119 PLMATH_API Quaternion(const Matrix3x3 &mRot); 00120 PLMATH_API Quaternion(const Matrix3x4 &mRot); 00121 PLMATH_API Quaternion(const Matrix4x4 &mRot); 00122 00123 //[-------------------------------------------------------] 00124 //[ Destructor ] 00125 //[-------------------------------------------------------] 00126 inline ~Quaternion(); 00127 00128 //[-------------------------------------------------------] 00129 //[ Operators ] 00130 //[-------------------------------------------------------] 00131 inline Quaternion operator +(const Quaternion &qQ) const; 00132 inline Quaternion &operator +=(const Quaternion &qQ); 00133 inline Quaternion operator -() const; 00134 inline Quaternion operator -(const Quaternion &qQ) const; 00135 inline Quaternion &operator -=(const Quaternion &qQ); 00136 inline Quaternion operator *(float f) const; 00137 inline Quaternion &operator *=(float f); 00138 inline Quaternion operator *(const Quaternion &qQ) const; 00139 inline Quaternion &operator *=(const Quaternion &qQ); 00140 inline Vector3 operator *(const Vector3 &vV) const; 00141 inline Vector4 operator *(const Vector4 &vV) const; 00142 inline Quaternion operator /(float f) const; 00143 inline Quaternion &operator /=(float f); 00144 inline Quaternion &operator =(const Quaternion &qQ); 00145 inline bool operator ==(const Quaternion &qQ) const; 00146 inline bool operator !=(const Quaternion &qQ) const; 00147 inline operator float *(); 00148 inline operator const float *() const; 00149 00150 //[-------------------------------------------------------] 00151 //[ Get and set functions ] 00152 //[-------------------------------------------------------] 00153 /** 00154 * @brief 00155 * Sets the component of the quaternion 00156 * 00157 * @param[in] fW 00158 * W component 00159 * @param[in] fX 00160 * X component 00161 * @param[in] fY 00162 * Y component 00163 * @param[in] fZ 00164 * Z component 00165 * 00166 * @return 00167 * This quaternion 00168 */ 00169 inline Quaternion &SetWXYZ(float fW, float fX, float fY, float fZ); 00170 00171 /** 00172 * @brief 00173 * Sets the component of the quaternion 00174 * 00175 * @param[in] fValues 00176 * Array of at least 4 floats 00177 * 00178 * @return 00179 * This quaternion 00180 */ 00181 inline Quaternion &SetWXYZ(const float fValues[]); 00182 00183 /** 00184 * @brief 00185 * Returns a selected axis and angle from the rotation quaternion 00186 * 00187 * @param[out] fX 00188 * Will receive the x component of the selected axis 00189 * @param[out] fY 00190 * Will receive the y component of the selected axis 00191 * @param[out] fZ 00192 * Will receive the z component of the selected axis 00193 * @param[out] fAngle 00194 * Will receive the rotation angle around the selected axis (in radian, between [0, Math::Pi]) 00195 * 00196 * @note 00197 * - The quaternion must be normalized 00198 */ 00199 PLMATH_API void ToAxisAngle(float &fX, float &fY, float &fZ, float &fAngle) const; 00200 00201 /** 00202 * @brief 00203 * Sets a rotation quaternion by using a selected axis and angle 00204 * 00205 * @param[in] fX 00206 * X component of the selected axis 00207 * @param[in] fY 00208 * Y component of the selected axis 00209 * @param[in] fZ 00210 * Z component of the selected axis 00211 * @param[in] fAngle 00212 * Rotation angle around the selected axis (in radian, between [0, Math::Pi]) 00213 * 00214 * @return 00215 * This quaternion 00216 * 00217 * @note 00218 * - The given selected axis must be normalized! 00219 */ 00220 PLMATH_API Quaternion &FromAxisAngle(float fX, float fY, float fZ, float fAngle); 00221 00222 /** 00223 * @brief 00224 * Returns the x (left) axis 00225 * 00226 * @return 00227 * The x (left) axis, already normalized for rotation quaternions 00228 */ 00229 PLMATH_API Vector3 GetXAxis() const; 00230 00231 /** 00232 * @brief 00233 * Returns the y (up) axis 00234 * 00235 * @return 00236 * The y (up) axis, already normalized for rotation quaternions 00237 */ 00238 PLMATH_API Vector3 GetYAxis() const; 00239 00240 /** 00241 * @brief 00242 * Returns the z (forward) axis 00243 * 00244 * @return 00245 * The z (forward) axis, already normalized for rotation quaternions 00246 */ 00247 PLMATH_API Vector3 GetZAxis() const; 00248 00249 /** 00250 * @brief 00251 * Returns the rotation quaternion as 3x3 matrix 00252 * 00253 * @param[out] mRot 00254 * Will receive the rotation matrix 00255 */ 00256 PLMATH_API void ToRotationMatrix(Matrix3x3 &mRot) const; 00257 00258 /** 00259 * @brief 00260 * Sets a rotation quaternion by using a 3x3 rotation matrix 00261 * 00262 * @param[in] mRot 00263 * Rotation matrix 00264 * 00265 * @return 00266 * This quaternion 00267 */ 00268 PLMATH_API Quaternion &FromRotationMatrix(const Matrix3x3 &mRot); 00269 00270 /** 00271 * @brief 00272 * Returns the rotation quaternion as 3x4 matrix 00273 * 00274 * @param[out] mRot 00275 * Will receive the rotation matrix 00276 */ 00277 PLMATH_API void ToRotationMatrix(Matrix3x4 &mRot) const; 00278 00279 /** 00280 * @brief 00281 * Sets a rotation quaternion by using a 3x4 rotation matrix 00282 * 00283 * @param[in] mRot 00284 * Rotation matrix 00285 * 00286 * @return 00287 * This quaternion 00288 */ 00289 PLMATH_API Quaternion &FromRotationMatrix(const Matrix3x4 &mRot); 00290 00291 /** 00292 * @brief 00293 * Returns the rotation quaternion as 4x4 matrix 00294 * 00295 * @param[out] mRot 00296 * Will receive the rotation matrix 00297 */ 00298 PLMATH_API void ToRotationMatrix(Matrix4x4 &mRot) const; 00299 00300 /** 00301 * @brief 00302 * Sets a rotation quaternion by using a 4x4 rotation matrix 00303 * 00304 * @param[in] mRot 00305 * Rotation matrix 00306 * 00307 * @return 00308 * This quaternion 00309 */ 00310 PLMATH_API Quaternion &FromRotationMatrix(const Matrix4x4 &mRot); 00311 00312 //[-------------------------------------------------------] 00313 //[ Misc ] 00314 //[-------------------------------------------------------] 00315 /** 00316 * @brief 00317 * Compares two quaternions using an epsilon environment 00318 * 00319 * @param[in] qQ 00320 * Quaternion to compare with 00321 * @param[in] fEpsilon 00322 * Epsilon environment 00323 * 00324 * @return 00325 * 'true' if the both quaternions are equal, else 'false' 00326 */ 00327 inline bool Compare(const Quaternion &qQ, float fEpsilon = Math::Epsilon) const; 00328 00329 /** 00330 * @brief 00331 * Returns the length (also called magnitude) of the quaternion 00332 * 00333 * @return 00334 * The length (also called magnitude) of the quaternion 00335 */ 00336 inline float GetLength() const; 00337 00338 /** 00339 * @brief 00340 * Returns the squared length (norm) of the quaternion 00341 * 00342 * @return 00343 * The squared length (norm) of the quaternion 00344 */ 00345 inline float GetSquaredLength() const; 00346 00347 /** 00348 * @brief 00349 * Returns the dot product of this quaternion and another one 00350 * 00351 * @param[in] qQ 00352 * Second quaternion 00353 * 00354 * @return 00355 * The dot product of the two quaternions 00356 */ 00357 inline float DotProduct(const Quaternion &qQ) const; 00358 00359 /** 00360 * @brief 00361 * Normalizes the quaternion 00362 * 00363 * @return 00364 * This quaternion 00365 */ 00366 inline Quaternion &Normalize(); 00367 00368 /** 00369 * @brief 00370 * Returns a normalized quaternion 00371 * 00372 * @return 00373 * Normalized quaternion 00374 */ 00375 inline Quaternion GetNormalized() const; 00376 00377 /** 00378 * @brief 00379 * Conjugates the quaternion 00380 */ 00381 inline void Conjugate(); 00382 00383 /** 00384 * @brief 00385 * Returns the conjugated of the quaternion 00386 * 00387 * @return 00388 * The conjugated of the quaternion 00389 */ 00390 inline Quaternion GetConjugated() const; 00391 00392 /** 00393 * @brief 00394 * Inverts the quaternion 00395 */ 00396 inline void Invert(); 00397 00398 /** 00399 * @brief 00400 * Returns the inverted quaternion 00401 * 00402 * @return 00403 * Inverted quaternion 00404 */ 00405 inline Quaternion GetInverted() const; 00406 00407 /** 00408 * @brief 00409 * Inverts the normalized quaternion 00410 * 00411 * @remarks 00412 * This function can only be used if the quaternion is normalized! 00413 * (rotation quaternions are normally always normalized) 00414 * If the quaternion is not normalized, use Invert() instead. 00415 */ 00416 inline void UnitInvert(); 00417 00418 /** 00419 * @brief 00420 * Returns the inverted normalized quaternion 00421 * 00422 * @return 00423 * Inverted normalized quaternion 00424 * 00425 * @see 00426 * - UnitInvert() 00427 */ 00428 inline Quaternion GetUnitInverted() const; 00429 00430 /** 00431 * @brief 00432 * Calculates the exponential of the quaternion 00433 * 00434 * @return 00435 * This quaternion 00436 */ 00437 inline Quaternion &Exp(); 00438 00439 /** 00440 * @brief 00441 * Returns the exponential of the quaternion 00442 * 00443 * @return 00444 * The exponential of the quaternion 00445 */ 00446 inline Quaternion GetExp() const; 00447 00448 /* 00449 * @brief 00450 * Calculates the logarithm of a unit quaternion 00451 * 00452 * @return 00453 * This quaternion 00454 */ 00455 inline Quaternion &Log(); 00456 00457 /* 00458 * @brief 00459 * Returns the logarithm of a unit quaternion 00460 * 00461 * @return 00462 * The logarithm of a unit quaternion 00463 */ 00464 inline Quaternion GetLog() const; 00465 00466 /** 00467 * @brief 00468 * Calculates the power of the quaternion 00469 * 00470 * @param[in] fPower 00471 * Power to calculate 00472 * 00473 * @return 00474 * This quaternion 00475 */ 00476 inline Quaternion &Power(float fPower); 00477 00478 /** 00479 * @brief 00480 * Returns the power of the quaternion 00481 * 00482 * @param[in] fPower 00483 * Power to calculate 00484 * 00485 * @return 00486 * The power of the quaternion 00487 */ 00488 inline Quaternion GetPower(float fPower) const; 00489 00490 /** 00491 * @brief 00492 * Computes spherical linear interpolation between qQ1 and qQ2 with time 0-1 00493 * 00494 * @param[in] qQ1 00495 * Start quaternion (time: 0) 00496 * @param[in] qQ2 00497 * End quaternion (time: 1) 00498 * @param[in] fTime 00499 * Time from 0-1 00500 */ 00501 PLMATH_API void Slerp(const Quaternion &qQ1, const Quaternion &qQ2, float fTime); 00502 00503 /** 00504 * @brief 00505 * To string 00506 * 00507 * @return 00508 * String with the data 00509 */ 00510 PLMATH_API PLCore::String ToString() const; 00511 00512 /** 00513 * @brief 00514 * From string 00515 * 00516 * @param[in] sString 00517 * String with the data 00518 */ 00519 PLMATH_API bool FromString(const PLCore::String &sString); 00520 00521 00522 }; 00523 00524 00525 //[-------------------------------------------------------] 00526 //[ Namespace ] 00527 //[-------------------------------------------------------] 00528 } // PLMath 00529 00530 00531 //[-------------------------------------------------------] 00532 //[ Implementation ] 00533 //[-------------------------------------------------------] 00534 #include "PLMath/Quaternion.inl" 00535 00536 00537 #endif // __PLMATH_QUATERNION_H__
|