1/****************************************************************************************
2
3 Copyright (C) 2015 Autodesk, Inc.
4 All rights reserved.
5
6 Use of this software is subject to the terms of the Autodesk license agreement
7 provided at the time of installation or download, or which otherwise accompanies
8 this software in either electronic or hard copy form.
9
10****************************************************************************************/
11
12//! \file fbxquaternion.h
13#ifndef _FBXSDK_CORE_MATH_QUATERNION_H_
14#define _FBXSDK_CORE_MATH_QUATERNION_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/core/math/fbxvector4.h>
19
20#include <fbxsdk/fbxsdk_nsbegin.h>
21
22/** FBX SDK quaternion class.
23 * \nosubgrouping
24 * Quaternions form a four-dimensional normed division algebra over the real numbers.
25 * It is for calculations involving three-dimensional rotations.
26 */
27class FBXSDK_DLL FbxQuaternion : public FbxDouble4
28{
29public:
30 /**
31 * \name Constructors and Destructor
32 */
33 //@{
34 /** Constructor.
35 * Initialize to the multiplicative identity.
36 */
37 FbxQuaternion();
38
39 /** Copy constructor.
40 * \param pV FbxQuaternion object copied to this one.
41 */
42 FbxQuaternion(const FbxQuaternion& pV);
43
44 /** Constructor.
45 * \param pX The X component.
46 * \param pY The Y component.
47 * \param pZ The Z component.
48 * \param pW The W component.
49 */
50 FbxQuaternion(double pX, double pY, double pZ, double pW = 1.0);
51
52 /** From axis degree constructor
53 * \param pAxis The axis to rotate around.
54 * \param pDegree The amount of degree to rotate around the axis. */
55 FbxQuaternion(const FbxVector4& pAxis, double pDegree);
56
57 //! Destructor.
58 ~FbxQuaternion();
59 //@}
60
61 /**
62 * \name Access
63 */
64 //@{
65 /** Assignment operation.
66 * \param pQuaternion FbxQuaternion object assigned to this one.
67 */
68 FbxQuaternion& operator=(const FbxQuaternion& pQuaternion);
69
70 /** Accessor.
71 * \param pIndex The index of the component to access.
72 * \return The reference to the indexed component.
73 * \remarks The index parameter is not checked for values out of bounds. The valid range is [0,3].
74 */
75 double& operator[](int pIndex);
76
77 /** Accessor.
78 * \param pIndex The index of the component to access.
79 * \return The const reference to the indexed component.
80 * \remarks The index parameter is not checked for values out of bounds. The valid range is [0,3].
81 */
82 const double& operator[](int pIndex) const;
83
84 /** Get a vector element.
85 * \param pIndex The index of the component to access.
86 * \return The value of the indexed component.
87 * \remarks The index parameter is not checked for values out of bounds. The valid range is [0,3].
88 */
89 double GetAt(int pIndex) const;
90
91 /** Set a vector element.
92 * \param pIndex The index of the component to set.
93 * \param pValue The new value to set the component.
94 * \remarks The index parameter is not checked for values out of bounds. The valid range is [0,3].
95 */
96 void SetAt(int pIndex, double pValue);
97
98 /** Set vector.
99 * \param pX The X component value.
100 * \param pY The Y component value.
101 * \param pZ The Z component value.
102 * \param pW The W component value.
103 */
104 void Set(double pX, double pY, double pZ, double pW = 1.0);
105 //@}
106
107 /**
108 * \name Scalar Operations
109 */
110 //@{
111 /** The addition operator between the scalar part of this quaternion and a scalar value, no influence on the vector part of the quaternion.
112 * \param pValue The scalar value to be added.
113 * \return The sum of addition.
114 */
115 FbxQuaternion operator+(double pValue) const;
116
117 /** The subtraction operator between the scalar part of this quaternion and a scalar value, no influence on the vector part of the quaternion.
118 * \param pValue The scalar subtrahend.
119 * \return The difference of subtraction.
120 */
121 FbxQuaternion operator-(double pValue) const;
122
123 /** Multiply all vector components by a value.
124 * \param pValue The value multiplying each component of the vector.
125 * \return New vector.
126 * \remarks The passed value is not checked.
127 */
128 FbxQuaternion operator*(double pValue) const;
129
130 /** Divide all vector components by a value.
131 * \param pValue The value dividing each component of the vector.
132 * \return New vector.
133 * \remarks The passed value is not checked.
134 */
135 FbxQuaternion operator/(double pValue) const;
136
137 /** The in place addition operator between the real part of this quaternion and a scalar value.
138 * \param pValue The value to be added.
139 * \return The sum of addition.
140 */
141 FbxQuaternion& operator+=(double pValue);
142
143 /** The subtraction operator between the real part of this quaternion and a scalar value.
144 * \param pValue The scalar subtrahend.
145 * \return The difference of subtraction.
146 */
147 FbxQuaternion& operator-=(double pValue);
148
149 /** Multiply a value to all vector elements.
150 * \param pValue The value multiplying each component of the vector.
151 * \return The result of multiplying each component of the vector by pValue, replacing this quaternion.
152 * \remarks The passed value is not checked.
153 */
154 FbxQuaternion& operator*=(double pValue);
155
156 /** Divide all vector elements by a value.
157 * \param pValue The value dividing each component of the vector.
158 * \return The result of dividing each component of the vector by pValue, replacing this quaternion.
159 * \remarks The passed value is not checked.
160 */
161 FbxQuaternion& operator/=(double pValue);
162 //@}
163
164 /**
165 * \name Vector Operations
166 */
167 //@{
168 /** Unary minus operator.
169 * \return A quaternion where each component is multiplied by -1.
170 */
171 FbxQuaternion operator-() const;
172
173 /** Add two vectors together.
174 * \param pQuaternion Quaternion to add.
175 * \return The quaternion v' = this + pQuaternion.
176 * \remarks The values in pQuaternion are not checked.
177 */
178 FbxQuaternion operator+(const FbxQuaternion& pQuaternion) const;
179
180 /** Subtract a quaternion from another quaternion.
181 * \param pQuaternion Quaternion to subtract.
182 * \return The quaternion v' = this - pQuaternion.
183 * \remarks The values in pQuaternion are not checked.
184 */
185 FbxQuaternion operator-(const FbxQuaternion& pQuaternion) const;
186
187 /** The quaternion multiplication operator.
188 * \param pOther The quaternion to be multiplied with this quaternion.
189 * \return The product of two quaternions.
190 * \remarks In general, quaternion multiplication does not commute.
191 */
192 FbxQuaternion operator*(const FbxQuaternion& pOther) const;
193
194 /** The quaternion division operator.
195 * \param pOther The divisor quaternion.
196 * \return The quotient quaternion.
197 * \remarks If the divisor has a zero length, return zero quaternion.
198 */
199 FbxQuaternion operator/(const FbxQuaternion& pOther) const;
200
201 /** Add two quaternions together.
202 * \param pQuaternion Quaternion to add.
203 * \return The quaternion v' = this + pQuaternion, replacing this quaternion.
204 * \remarks The values in pQuaternion are not checked.
205 */
206 FbxQuaternion& operator+=(const FbxQuaternion& pQuaternion);
207
208 /** Subtract a quaternion from another vector.
209 * \param pQuaternion Quaternion to subtract.
210 * \return The quaternion v' = this - pQuaternion, replacing this quaternion.
211 * \remarks The values in pQuaternion are not checked.
212 */
213 FbxQuaternion& operator-=(const FbxQuaternion& pQuaternion);
214
215 /** The in place quaternion multiplication operator.
216 * \param pOther The quaternion to be multiplied with this quaternion.
217 * \return The product of two quaternions.
218 * \remarks In general, quaternion multiplication does not commute.
219 */
220 FbxQuaternion& operator*=(const FbxQuaternion& pOther);
221
222 /** The in place quaternion division operator.
223 * \param pOther The divisor quaternion.
224 * \return The quotient quaternion.
225 * \remarks If the divisor has a zero length, return zero quaternion.
226 */
227 FbxQuaternion& operator/=(const FbxQuaternion& pOther);
228
229 /** Return quaternion product.
230 * \param pOther The quaternion to be multiplied with this quaternion.
231 * \return The product of two quaternions.
232 */
233 FbxQuaternion Product(const FbxQuaternion& pOther) const;
234
235 /** Return quaternion dot product.
236 * \param pQuaternion Dot product quaternion.
237 * \return The dot product of this quaternion and pQuaternion.
238 */
239 double DotProduct(const FbxQuaternion& pQuaternion) const;
240
241 /** Normalize the quaternion, length set to 1.
242 */
243 void Normalize();
244
245 /** Calculate the quaternion conjugate.
246 * \return The conjugate of this quaternion.
247 */
248 void Conjugate();
249
250 /** Calculate the length (norm) of the quaternion.
251 * \return The length of the quaternion.
252 */
253 double Length();
254
255 /** Calculate the inverse of the quaternion.
256 * \return The inverse of this quaternion.
257 * \remarks If this quaternion has a zero length, retain the original value.
258 * \remarks If the quaternion is normalized, then its inverse is equal to its conjugate.
259 */
260 void Inverse();
261
262 /** Set the quaternion rotation from an axis degree angle.
263 * \param pAxis The axis to rotate around.
264 * \param pDegree The amount of degree to rotate around the axis. */
265 void SetAxisAngle(const FbxVector4& pAxis, double pDegree);
266
267 /** Calculate a spherical linear interpolation quaternion.
268 * \param pOther The other quaternion to interpolate with.
269 * \param pWeight A value between 0.0 and 1.0 to specify the interpolation amount. */
270 FbxQuaternion Slerp(const FbxQuaternion& pOther, double pWeight) const;
271
272 /** Create a Quaternion equivalent to the supplied Euler XYZ in spherical coordinate.
273 * \param pEuler The Euler XYZ angle (in degrees).
274 */
275 void ComposeSphericalXYZ(const FbxVector4 pEuler);
276
277 /** Create an Euler XYZ equivalent to the current quaternion.
278 * \return The Euler XYZ angle (in degrees) equivalent to the current quaternion in spherical coordinate.
279 */
280 FbxVector4 DecomposeSphericalXYZ() const;
281 //@}
282
283 /**
284 * \name Boolean Operations
285 */
286 //@{
287 /** Equivalence operator.
288 * \param pV The quaternion to be compared to this quaternion.
289 * \return \c true if the two quaternions are equal (each element is within a FBXSDK_TOLERANCE tolerance), \c false otherwise.
290 */
291 bool operator==(const FbxQuaternion & pV) const;
292
293 /** Non equivalence operator.
294 * \param pV The quaternion to be compared to \e this.
295 * \return \c false if the two quaternions are equal (each element is within a FBXSDK_TOLERANCE tolerance), \c true otherwise.
296 */
297 bool operator!=(const FbxQuaternion & pV) const;
298 //@}
299
300 /**
301 * \name Casting
302 */
303 //@{
304 //! Cast the vector in a double pointer.
305 operator double* ();
306
307 //! Cast the vector in a const double pointer.
308 operator const double* () const;
309 //@}
310
311 /**
312 * \name Comparison methods
313 */
314 //@{
315 /** Comparison method.
316 * \param pQ2 Quaternion to compare with this
317 * \param pThreshold Epsilon for small number comparison
318 * \return 0 if quaternions are equal, non-zero value otherwise.
319 */
320 int Compare(const FbxQuaternion &pQ2, const double pThreshold = FBXSDK_TOLERANCE) const;
321 //@}
322
323/*****************************************************************************************************************************
324** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
325*****************************************************************************************************************************/
326#ifndef DOXYGEN_SHOULD_SKIP_THIS
327 void GetQuaternionFromPositionToPosition(const FbxVector4 &pP0, const FbxVector4 &pP1);
328#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
329};
330
331#include <fbxsdk/fbxsdk_nsend.h>
332
333#endif /* _FBXSDK_CORE_MATH_QUATERNION_H_ */
334