1 /*!**************************************************************************** 2 3 @file PVRTQuaternion.h 4 @copyright Copyright (c) Imagination Technologies Limited. 5 @brief Quaternion functions for floating and fixed point math. 6 7 ******************************************************************************/ 8 #ifndef _PVRTQUATERNION_H_ 9 #define _PVRTQUATERNION_H_ 10 11 #include "PVRTGlobal.h" 12 #include "PVRTMatrix.h" 13 14 /**************************************************************************** 15 ** Typedefs 16 ****************************************************************************/ 17 /*!*************************************************************************** 18 @brief Floating point Quaternion 19 *****************************************************************************/ 20 typedef struct 21 { 22 float x; /*!< x coordinate */ 23 float y; /*!< y coordinate */ 24 float z; /*!< z coordinate */ 25 float w; /*!< w coordinate */ 26 } PVRTQUATERNIONf; 27 /*!*************************************************************************** 28 @brief Fixed point Quaternion 29 *****************************************************************************/ 30 typedef struct 31 { 32 int x; /*!< x coordinate */ 33 int y; /*!< y coordinate */ 34 int z; /*!< z coordinate */ 35 int w; /*!< w coordinate */ 36 } PVRTQUATERNIONx; 37 38 /**************************************************************************** 39 ** Float or fixed 40 ****************************************************************************/ 41 #ifdef PVRT_FIXED_POINT_ENABLE 42 typedef PVRTQUATERNIONx PVRTQUATERNION; 43 #define PVRTMatrixQuaternionIdentity PVRTMatrixQuaternionIdentityX 44 #define PVRTMatrixQuaternionRotationAxis PVRTMatrixQuaternionRotationAxisX 45 #define PVRTMatrixQuaternionToAxisAngle PVRTMatrixQuaternionToAxisAngleX 46 #define PVRTMatrixQuaternionSlerp PVRTMatrixQuaternionSlerpX 47 #define PVRTMatrixQuaternionNormalize PVRTMatrixQuaternionNormalizeX 48 #define PVRTMatrixRotationQuaternion PVRTMatrixRotationQuaternionX 49 #define PVRTMatrixQuaternionMultiply PVRTMatrixQuaternionMultiplyX 50 #else 51 typedef PVRTQUATERNIONf PVRTQUATERNION; 52 #define PVRTMatrixQuaternionIdentity PVRTMatrixQuaternionIdentityF 53 #define PVRTMatrixQuaternionRotationAxis PVRTMatrixQuaternionRotationAxisF 54 #define PVRTMatrixQuaternionToAxisAngle PVRTMatrixQuaternionToAxisAngleF 55 #define PVRTMatrixQuaternionSlerp PVRTMatrixQuaternionSlerpF 56 #define PVRTMatrixQuaternionNormalize PVRTMatrixQuaternionNormalizeF 57 #define PVRTMatrixRotationQuaternion PVRTMatrixRotationQuaternionF 58 #define PVRTMatrixQuaternionMultiply PVRTMatrixQuaternionMultiplyF 59 #endif 60 61 /**************************************************************************** 62 ** Functions 63 ****************************************************************************/ 64 65 /*!*************************************************************************** 66 @fn PVRTMatrixQuaternionIdentityF 67 @param[out] qOut Identity quaternion 68 @brief Sets the quaternion to (0, 0, 0, 1), the identity quaternion. 69 *****************************************************************************/ 70 void PVRTMatrixQuaternionIdentityF( 71 PVRTQUATERNIONf &qOut); 72 73 /*!*************************************************************************** 74 @fn PVRTMatrixQuaternionIdentityX 75 @param[out] qOut Identity quaternion 76 @brief Sets the quaternion to (0, 0, 0, 1), the identity quaternion. 77 *****************************************************************************/ 78 void PVRTMatrixQuaternionIdentityX( 79 PVRTQUATERNIONx &qOut); 80 81 /*!*************************************************************************** 82 @fn PVRTMatrixQuaternionRotationAxisF 83 @param[out] qOut Rotation quaternion 84 @param[in] vAxis Axis to rotate around 85 @param[in] fAngle Angle to rotate 86 @brief Create quaternion corresponding to a rotation of fAngle 87 radians around submitted vector. 88 *****************************************************************************/ 89 void PVRTMatrixQuaternionRotationAxisF( 90 PVRTQUATERNIONf &qOut, 91 const PVRTVECTOR3f &vAxis, 92 const float fAngle); 93 94 /*!*************************************************************************** 95 @fn PVRTMatrixQuaternionRotationAxisX 96 @param[out] qOut Rotation quaternion 97 @param[in] vAxis Axis to rotate around 98 @param[in] fAngle Angle to rotate 99 @brief Create quaternion corresponding to a rotation of fAngle 100 radians around submitted vector. 101 *****************************************************************************/ 102 void PVRTMatrixQuaternionRotationAxisX( 103 PVRTQUATERNIONx &qOut, 104 const PVRTVECTOR3x &vAxis, 105 const int fAngle); 106 107 108 /*!*************************************************************************** 109 @fn PVRTMatrixQuaternionToAxisAngleF 110 @param[in] qIn Quaternion to transform 111 @param[out] vAxis Axis of rotation 112 @param[out] fAngle Angle of rotation 113 @brief Convert a quaternion to an axis and angle. Expects a unit 114 quaternion. 115 *****************************************************************************/ 116 void PVRTMatrixQuaternionToAxisAngleF( 117 const PVRTQUATERNIONf &qIn, 118 PVRTVECTOR3f &vAxis, 119 float &fAngle); 120 121 /*!*************************************************************************** 122 @fn PVRTMatrixQuaternionToAxisAngleX 123 @param[in] qIn Quaternion to transform 124 @param[out] vAxis Axis of rotation 125 @param[out] fAngle Angle of rotation 126 @brief Convert a quaternion to an axis and angle. Expects a unit 127 quaternion. 128 *****************************************************************************/ 129 void PVRTMatrixQuaternionToAxisAngleX( 130 const PVRTQUATERNIONx &qIn, 131 PVRTVECTOR3x &vAxis, 132 int &fAngle); 133 134 /*!*************************************************************************** 135 @fn PVRTMatrixQuaternionSlerpF 136 @param[out] qOut Result of the interpolation 137 @param[in] qA First quaternion to interpolate from 138 @param[in] qB Second quaternion to interpolate from 139 @param[in] t Coefficient of interpolation 140 @brief Perform a Spherical Linear intERPolation between quaternion A 141 and quaternion B at time t. t must be between 0.0f and 1.0f 142 *****************************************************************************/ 143 void PVRTMatrixQuaternionSlerpF( 144 PVRTQUATERNIONf &qOut, 145 const PVRTQUATERNIONf &qA, 146 const PVRTQUATERNIONf &qB, 147 const float t); 148 149 /*!*************************************************************************** 150 @fn PVRTMatrixQuaternionSlerpX 151 @param[out] qOut Result of the interpolation 152 @param[in] qA First quaternion to interpolate from 153 @param[in] qB Second quaternion to interpolate from 154 @param[in] t Coefficient of interpolation 155 @brief Perform a Spherical Linear intERPolation between quaternion A 156 and quaternion B at time t. t must be between 0.0f and 1.0f 157 Requires input quaternions to be normalized 158 *****************************************************************************/ 159 void PVRTMatrixQuaternionSlerpX( 160 PVRTQUATERNIONx &qOut, 161 const PVRTQUATERNIONx &qA, 162 const PVRTQUATERNIONx &qB, 163 const int t); 164 165 /*!*************************************************************************** 166 @fn PVRTMatrixQuaternionNormalizeF 167 @param[in,out] quat Vector to normalize 168 @brief Normalize quaternion. 169 *****************************************************************************/ 170 void PVRTMatrixQuaternionNormalizeF(PVRTQUATERNIONf &quat); 171 172 /*!*************************************************************************** 173 @fn PVRTMatrixQuaternionNormalizeX 174 @param[in,out] quat Vector to normalize 175 @brief Normalize quaternion. 176 Original quaternion is scaled down prior to be normalized in 177 order to avoid overflow issues. 178 *****************************************************************************/ 179 void PVRTMatrixQuaternionNormalizeX(PVRTQUATERNIONx &quat); 180 181 /*!*************************************************************************** 182 @fn PVRTMatrixRotationQuaternionF 183 @param[out] mOut Resulting rotation matrix 184 @param[in] quat Quaternion to transform 185 @brief Create rotation matrix from submitted quaternion. 186 Assuming the quaternion is of the form [X Y Z W]: 187 188 | 2 2 | 189 | 1 - 2Y - 2Z 2XY - 2ZW 2XZ + 2YW 0 | 190 | | 191 | 2 2 | 192 M = | 2XY + 2ZW 1 - 2X - 2Z 2YZ - 2XW 0 | 193 | | 194 | 2 2 | 195 | 2XZ - 2YW 2YZ + 2XW 1 - 2X - 2Y 0 | 196 | | 197 | 0 0 0 1 | 198 *****************************************************************************/ 199 void PVRTMatrixRotationQuaternionF( 200 PVRTMATRIXf &mOut, 201 const PVRTQUATERNIONf &quat); 202 203 /*!*************************************************************************** 204 @fn PVRTMatrixRotationQuaternionX 205 @param[out] mOut Resulting rotation matrix 206 @param[in] quat Quaternion to transform 207 @brief Create rotation matrix from submitted quaternion. 208 Assuming the quaternion is of the form [X Y Z W]: 209 210 | 2 2 | 211 | 1 - 2Y - 2Z 2XY - 2ZW 2XZ + 2YW 0 | 212 | | 213 | 2 2 | 214 M = | 2XY + 2ZW 1 - 2X - 2Z 2YZ - 2XW 0 | 215 | | 216 | 2 2 | 217 | 2XZ - 2YW 2YZ + 2XW 1 - 2X - 2Y 0 | 218 | | 219 | 0 0 0 1 | 220 *****************************************************************************/ 221 void PVRTMatrixRotationQuaternionX( 222 PVRTMATRIXx &mOut, 223 const PVRTQUATERNIONx &quat); 224 225 /*!*************************************************************************** 226 @fn PVRTMatrixQuaternionMultiplyF 227 @param[out] qOut Resulting quaternion 228 @param[in] qA First quaternion to multiply 229 @param[in] qB Second quaternion to multiply 230 @brief Multiply quaternion A with quaternion B and return the 231 result in qOut. 232 *****************************************************************************/ 233 void PVRTMatrixQuaternionMultiplyF( 234 PVRTQUATERNIONf &qOut, 235 const PVRTQUATERNIONf &qA, 236 const PVRTQUATERNIONf &qB); 237 238 /*!*************************************************************************** 239 @fn PVRTMatrixQuaternionMultiplyX 240 @param[out] qOut Resulting quaternion 241 @param[in] qA First quaternion to multiply 242 @param[in] qB Second quaternion to multiply 243 @brief Multiply quaternion A with quaternion B and return the 244 result in qOut. 245 Input quaternions must be normalized. 246 *****************************************************************************/ 247 void PVRTMatrixQuaternionMultiplyX( 248 PVRTQUATERNIONx &qOut, 249 const PVRTQUATERNIONx &qA, 250 const PVRTQUATERNIONx &qB); 251 252 #endif 253 254 /***************************************************************************** 255 End of file (PVRTQuaternion.h) 256 *****************************************************************************/ 257 258