1 #ifndef __DALI_QUATERNION_H__
2 #define __DALI_QUATERNION_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
26 #include <dali/public-api/common/dali-common.h>
27 #include <dali/public-api/common/constants.h>
28 #include <dali/public-api/math/vector4.h>
30 namespace Dali DALI_IMPORT_API
33 // Forward declaration
37 * @brief The Quaternion class encapsulates the mathematics of the quaternion.
39 class DALI_IMPORT_API Quaternion
44 * @brief Default Constructor
49 * @brief Construct from a quaternion represented by floats.
51 * @param[in] cosThetaBy2
52 * @param[in] iBySineTheta
53 * @param[in] jBySineTheta
54 * @param[in] kBySineTheta
56 Quaternion(float cosThetaBy2, float iBySineTheta, float jBySineTheta, float kBySineTheta);
59 * @brief Construct from a quaternion represented by a vector.
61 * @param[in] vector - x,y,z fields represent i,j,k coefficients, w represents cos(theta/2)
63 explicit Quaternion(const Vector4& vector);
66 * @brief Constructor from an axis and angle.
68 * @param[in] angle - the angle around the axis
69 * @param[in] axis - the vector of the axis
71 Quaternion(float angle, const Vector3 &axis);
74 * @brief Constructor from an axis and angle.
76 * @param[in] theta - the angle of the axis
77 * @param[in] axis - the unit vector of the axis
79 Quaternion(float theta, const Vector4 &axis);
82 * @brief Construct from Euler angles.
84 * @param[in] x - the X axis euler angle (pitch)
85 * @param[in] y - the Y axis euler angle (yaw)
86 * @param[in] z - the Z axis euler angle (roll)
88 Quaternion(float x, float y, float z);
91 * @brief Construct from a matrix.
95 explicit Quaternion(const Matrix& matrix);
98 * @brief Construct from 3 orthonormal axes.
100 * @param[in] xAxis The X axis
101 * @param[in] yAxis The Y axis
102 * @param[in] zAxis The Z axis
104 explicit Quaternion( const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis );
107 * @brief Converts an axis + angle pair rotation to a Quaternion.
111 * @return the represented quaternion
113 static Quaternion FromAxisAngle(const Vector4 &axis, float angle);
116 * @brief Destructor, nonvirtual as this is not a base class.
123 static const Quaternion IDENTITY; ///< (0.0f,0.0f,0.0f,1.0f)
126 * @brief Helper to check if this is an identity quaternion
128 * @return true if this is identity quaternion
130 bool IsIdentity() const
132 // start from w as its unlikely that any real rotation has w == 1
133 // Uses a relaxed epsilon, as composition of rotation introduces error
134 return ( ( fabsf( mVector.w - 1.0f ) < Math::MACHINE_EPSILON_10 )&&
135 ( fabsf( mVector.x ) < Math::MACHINE_EPSILON_10 )&&
136 ( fabsf( mVector.y ) < Math::MACHINE_EPSILON_10 )&&
137 ( fabsf( mVector.z ) < Math::MACHINE_EPSILON_10 ) );
141 * @brief Convert the quaternion to an axis/angle pair.
145 * @return true if converted correctly
147 bool ToAxisAngle(Vector3 &axis, float &angle) const;
150 * @brief Convert the quaternion to an axis/angle pair.
154 * @return true if converted correctly
156 bool ToAxisAngle(Vector4 &axis, float &angle) const;
159 * @brief Return the quaternion as a vector.
161 * @return the vector representation of the quaternion
163 const Vector4& AsVector() const;
166 * @brief SetEuler sets the quaternion from the Euler angles applied in x, y, z order.
168 * @param[in] x - the X axis euler angle (pitch)
169 * @param[in] y - the Y axis euler angle (yaw)
170 * @param[in] z - the Z axis euler angle (roll)
172 void SetEuler(float x, float y, float z);
175 * @brief returns the Euler angles from a rotation Quaternion.
177 * @return a vector of Euler angles (x == pitch, y == yaw, z == roll)
179 Vector4 EulerAngles() const;
182 * @brief Addition operator.
184 * @param[in] other The quaternion to add
185 * @return A quaternion containing the result of the addition
187 const Quaternion operator +(const Quaternion &other) const;
190 * @brief Subtraction operator.
192 * @param[in] other The quaternion to subtract
193 * @return A quaternion containing the result of the subtract
195 const Quaternion operator -(const Quaternion &other) const;
198 * @brief Multiplication operator.
200 * @param[in] other The quaternion to multiply
201 * @return A quaternion containing the result
203 const Quaternion operator *(const Quaternion &other) const;
206 * @brief Multiplication operator.
208 * @param[in] v The vector to multiply
209 * @return A vector containing the result of the multiplication
211 Vector3 operator *(const Vector3& v) const;
214 * @brief Division operator.
216 * @param[in] other a quaternion to divide by
217 * @return A quaternion containing the result
219 const Quaternion operator /(const Quaternion &other) const;
222 * @brief Scale operator.
224 * @param[in] scale A value to scale by
225 * @return A quaternion containing the result
227 const Quaternion operator *(float scale) const;
230 * @brief Scale operator.
232 * @param[in] scale A value to scale by
233 * @return A quaternion containing the result
235 const Quaternion operator /(float scale) const;
238 * @brief Unary Negation operator.
240 * @return A quaternion containing the negated result
242 Quaternion operator -() const;
245 * @brief Addition with Assignment operator.
247 * @param[in] other The quaternion to add
250 const Quaternion &operator +=(const Quaternion &other);
253 * @brief Subtraction with Assignment operator.
255 * @param[in] other The quaternion to subtract
258 const Quaternion &operator -=(const Quaternion &other);
261 * @brief Multiplication with Assignment operator.
263 * @param[in] other The quaternion to multiply
266 const Quaternion &operator *=(const Quaternion &other);
269 * @brief Scale with Assignment operator.
271 * @param[in] scale the value to scale by
274 const Quaternion &operator *= (float scale);
277 * @brief Scale with Assignment operator.
279 * @param[in] scale the value to scale by
282 const Quaternion &operator /= (float scale);
285 * @brief Equality operator.
287 * @param[in] rhs The quaterion to compare with.
288 * @return True if the quaternions are equal.
290 bool operator== (const Quaternion& rhs) const;
293 * @brief Inequality operator.
295 * @param[in] rhs The quaterion to compare with.
296 * @return True if the quaternions are not equal.
298 bool operator!= (const Quaternion& rhs) const;
301 * @brief Return the length of the quaternion.
303 * @return the length of the quaternion
305 float Length() const;
308 * @brief Return the squared length of the quaternion.
310 * @return the squared length of the quaternion
312 float LengthSquared() const;
315 * @brief Normalize this to unit length.
323 * @return a normalized version of this quaternion
325 Quaternion Normalized() const;
328 * @brief Conjugate this quaternion.
334 * @brief Invert this quaternion.
340 * @brief Performs the logarithm of a Quaternion = v*a where q = (cos(a),v*sin(a)).
342 * @return a quaternion representing the logarithm
344 Quaternion Log() const;
347 * @brief Performs an exponent e^Quaternion = Exp(v*a) = (cos(a),vsin(a)).
349 * @return a quaternion representing the exponent
351 Quaternion Exp() const;
354 * @brief Return the dot product of two quaternions.
356 * @param[in] q1 - the first quaternion
357 * @param[in] q2 - the second quaternion
358 * @return the dot product of the two quaternions
360 static float Dot(const Quaternion &q1, const Quaternion &q2);
363 * @brief Linear Interpolation (using a straight line between the two quaternions).
365 * @param[in] q1 - the start quaternion
366 * @param[in] q2 - the end quaternion
367 * @param[in] t - a progress value between 0 and 1
368 * @return the interpolated quaternion
370 static Quaternion Lerp(const Quaternion &q1, const Quaternion &q2, float t);
373 * @brief Spherical Linear Interpolation (using the shortest arc of a great circle between
374 * the two quaternions).
376 * @param[in] q1 - the start quaternion
377 * @param[in] q2 - the end quaternion
378 * @param[in] progress - a progress value between 0 and 1
379 * @return the interpolated quaternion
381 static Quaternion Slerp(const Quaternion &q1, const Quaternion &q2, float progress);
384 * @brief This version of Slerp, used by Squad, does not check for theta > 90.
386 * @param[in] q1 - the start quaternion
387 * @param[in] q2 - the end quaternion
388 * @param[in] t - a progress value between 0 and 1
389 * @return the interpolated quaternion
391 static Quaternion SlerpNoInvert(const Quaternion &q1, const Quaternion &q2, float t);
394 * @brief Spherical Cubic Interpolation.
396 * @param[in] q1 - the start quaternion
397 * @param[in] q2 - the end quaternion
398 * @param[in] a - the control quaternion for q1
399 * @param[in] b - the control quaternion for q2
400 * @param[in] t - a progress value between 0 and 1
401 * @return the interpolated quaternion
403 static Quaternion Squad(const Quaternion &q1,const Quaternion &q2,const Quaternion &a,const Quaternion &b,float t);
406 * @brief Returns the shortest angle between two quaternions in Radians.
408 * @param[in] q1 - the first quaternion
409 * @param[in] q2 - the second quaternion
410 * @return the angle between the two quaternions.
412 static float AngleBetween(const Quaternion &q1, const Quaternion &q2);
415 * @brief Rotate v by this Quaternion (Quaternion must be unit).
417 * @param[in] v - a vector to rotate
418 * @return the rotated vector
420 Vector4 Rotate(const Vector4 &v) const;
423 * @brief Rotate v by this Quaternion (Quaternion must be unit).
425 * @param[in] v - a vector to rotate
426 * @return the rotated vector
428 Vector3 Rotate(const Vector3 &v) const;
433 * @brief Set the quaternion from 3 orthonormal axes.
435 * @param[in] xAxis The X axis
436 * @param[in] yAxis The Y axis
437 * @param[in] zAxis The Z axis
439 DALI_INTERNAL void SetFromAxes( const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis );
443 Vector4 mVector; ///< w component is s ( = cos(theta/2.0) )
447 * @brief Print a Quaternion.
449 * @param [in] o The output stream operator.
450 * @param [in] quaternion The quaternion to print.
451 * @return The output stream operator.
453 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Quaternion& quaternion);
457 #endif // __DALI_QUATERNION_H__