1 #ifndef __DALI_QUATERNION_H__
2 #define __DALI_QUATERNION_H__
5 * Copyright (c) 2015 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.
25 #include <dali/public-api/common/constants.h>
26 #include <dali/public-api/common/dali-common.h>
27 #include <dali/public-api/common/type-traits.h>
28 #include <dali/public-api/math/radian.h>
29 #include <dali/public-api/math/vector4.h>
34 // Forward declaration
38 * @brief The Quaternion class encapsulates the mathematics of the quaternion.
40 class DALI_IMPORT_API Quaternion
45 * @brief Default Constructor
50 * @brief Construct from a quaternion represented by floats.
52 * @param[in] cosThetaBy2
53 * @param[in] iBySineTheta
54 * @param[in] jBySineTheta
55 * @param[in] kBySineTheta
57 Quaternion( float cosThetaBy2, float iBySineTheta, float jBySineTheta, float kBySineTheta );
60 * @brief Construct from a quaternion represented by a vector.
62 * @param[in] vector - x,y,z fields represent i,j,k coefficients, w represents cos(theta/2)
64 explicit Quaternion( const Vector4& vector );
67 * @brief Constructor from an axis and angle.
69 * @param[in] angle - the angle around the axis
70 * @param[in] axis - the vector of the axis
72 Quaternion( Radian angle, const Vector3& axis );
75 * @brief Construct from Euler angles.
81 Quaternion( Radian pitch, Radian yaw, Radian roll );
84 * @brief Construct from a matrix.
88 explicit Quaternion(const Matrix& matrix);
91 * @brief Construct from 3 orthonormal axes.
93 * @param[in] xAxis The X axis
94 * @param[in] yAxis The Y axis
95 * @param[in] zAxis The Z axis
97 explicit Quaternion( const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis );
100 * @brief Construct quaternion which describes minimum rotation to align v0 with v1
101 * @pre v0 and v1 should be normalized
103 * @param[in] v0 First normalized vector
104 * @param[in] v1 Second normalized vector
106 explicit Quaternion( const Vector3& v0, const Vector3& v1 );
109 * @brief Destructor, nonvirtual as this is not a base class.
116 static const Quaternion IDENTITY; ///< (0.0f,0.0f,0.0f,1.0f)
119 * @brief Helper to check if this is an identity quaternion
121 * @return true if this is identity quaternion
123 bool IsIdentity() const;
126 * @brief Convert the quaternion to an axis/angle pair.
129 * @param[out] angle in radians
130 * @return true if converted correctly
132 bool ToAxisAngle( Vector3& axis, Radian& angle ) const;
135 * @brief Return the quaternion as a vector.
137 * @return the vector representation of the quaternion
139 const Vector4& AsVector() const;
142 * @brief SetEuler sets the quaternion from the Euler angles applied in x, y, z order.
148 void SetEuler( Radian pitch, Radian yaw, Radian roll );
151 * @brief returns the Euler angles from a rotation Quaternion.
153 * @return a vector of Euler angles (x == pitch, y == yaw, z == roll)
155 Vector4 EulerAngles() const;
158 * @brief Addition operator.
160 * @param[in] other The quaternion to add
161 * @return A quaternion containing the result of the addition
163 const Quaternion operator+( const Quaternion& other ) const;
166 * @brief Subtraction operator.
168 * @param[in] other The quaternion to subtract
169 * @return A quaternion containing the result of the subtract
171 const Quaternion operator-( const Quaternion& other ) const;
174 * @brief Multiplication operator.
176 * @param[in] other The quaternion to multiply
177 * @return A quaternion containing the result
179 const Quaternion operator*( const Quaternion& other ) const;
182 * @brief Multiplication operator.
184 * @param[in] other The vector to multiply
185 * @return A vector containing the result of the multiplication
187 Vector3 operator*( const Vector3& other ) const;
190 * @brief Division operator.
192 * @param[in] other a quaternion to divide by
193 * @return A quaternion containing the result
195 const Quaternion operator/( const Quaternion& other ) const;
198 * @brief Scale operator.
200 * @param[in] scale A value to scale by
201 * @return A quaternion containing the result
203 const Quaternion operator*( float scale ) const;
206 * @brief Scale operator.
208 * @param[in] scale A value to scale by
209 * @return A quaternion containing the result
211 const Quaternion operator/( float scale ) const;
214 * @brief Unary Negation operator.
216 * @return A quaternion containing the negated result
218 Quaternion operator-() const;
221 * @brief Addition with Assignment operator.
223 * @param[in] other The quaternion to add
226 const Quaternion& operator+=( const Quaternion& other );
229 * @brief Subtraction with Assignment operator.
231 * @param[in] other The quaternion to subtract
234 const Quaternion& operator-=( const Quaternion& other );
237 * @brief Multiplication with Assignment operator.
239 * @param[in] other The quaternion to multiply
242 const Quaternion& operator*=( const Quaternion& other );
245 * @brief Scale with Assignment operator.
247 * @param[in] scale the value to scale by
250 const Quaternion& operator*=( float scale );
253 * @brief Scale with Assignment operator.
255 * @param[in] scale the value to scale by
258 const Quaternion& operator/=( float scale );
261 * @brief Equality operator.
263 * @param[in] rhs The quaterion to compare with.
264 * @return True if the quaternions are equal.
266 bool operator==( const Quaternion& rhs ) const;
269 * @brief Inequality operator.
271 * @param[in] rhs The quaterion to compare with.
272 * @return True if the quaternions are not equal.
274 bool operator!=( const Quaternion& rhs ) const;
277 * @brief Return the length of the quaternion.
279 * @return the length of the quaternion
281 float Length() const;
284 * @brief Return the squared length of the quaternion.
286 * @return the squared length of the quaternion
288 float LengthSquared() const;
291 * @brief Normalize this to unit length.
299 * @return a normalized version of this quaternion
301 Quaternion Normalized() const;
304 * @brief Conjugate this quaternion.
310 * @brief Invert this quaternion.
316 * @brief Performs the logarithm of a Quaternion = v*a where q = (cos(a),v*sin(a)).
318 * @return a quaternion representing the logarithm
320 Quaternion Log() const;
323 * @brief Performs an exponent e^Quaternion = Exp(v*a) = (cos(a),vsin(a)).
325 * @return a quaternion representing the exponent
327 Quaternion Exp() const;
330 * @brief Return the dot product of two quaternions.
332 * @param[in] q1 - the first quaternion
333 * @param[in] q2 - the second quaternion
334 * @return the dot product of the two quaternions
336 static float Dot( const Quaternion &q1, const Quaternion &q2 );
339 * @brief Linear Interpolation (using a straight line between the two quaternions).
341 * @param[in] q1 - the start quaternion
342 * @param[in] q2 - the end quaternion
343 * @param[in] t - a progress value between 0 and 1
344 * @return the interpolated quaternion
346 static Quaternion Lerp( const Quaternion &q1, const Quaternion &q2, float t );
349 * @brief Spherical Linear Interpolation (using the shortest arc of a great circle between
350 * the two quaternions).
352 * @param[in] q1 - the start quaternion
353 * @param[in] q2 - the end quaternion
354 * @param[in] progress - a progress value between 0 and 1
355 * @return the interpolated quaternion
357 static Quaternion Slerp( const Quaternion &q1, const Quaternion &q2, float progress );
360 * @brief This version of Slerp, used by Squad, does not check for theta > 90.
362 * @param[in] q1 - the start quaternion
363 * @param[in] q2 - the end quaternion
364 * @param[in] t - a progress value between 0 and 1
365 * @return the interpolated quaternion
367 static Quaternion SlerpNoInvert( const Quaternion &q1, const Quaternion &q2, float t );
370 * @brief Spherical Cubic Interpolation.
372 * @param[in] start - the start quaternion
373 * @param[in] end - the end quaternion
374 * @param[in] ctrl1 - the control quaternion for q1
375 * @param[in] ctrl2 - the control quaternion for q2
376 * @param[in] t - a progress value between 0 and 1
377 * @return the interpolated quaternion
379 static Quaternion Squad( const Quaternion& start, const Quaternion& end, const Quaternion& ctrl1, const Quaternion& ctrl2, float t );
382 * @brief Returns the shortest angle between two quaternions in Radians.
384 * @param[in] q1 - the first quaternion
385 * @param[in] q2 - the second quaternion
386 * @return the angle between the two quaternions.
388 static float AngleBetween( const Quaternion& q1, const Quaternion& q2 );
391 * @brief Rotate v by this Quaternion (Quaternion must be unit).
393 * @param[in] vector a vector to rotate
394 * @return the rotated vector
396 Vector4 Rotate( const Vector4& vector ) const;
399 * @brief Rotate v by this Quaternion (Quaternion must be unit).
401 * @param[in] vector a vector to rotate
402 * @return the rotated vector
404 Vector3 Rotate( const Vector3& vector ) const;
409 * @brief Set the quaternion from 3 orthonormal axes.
411 * @param[in] xAxis The X axis
412 * @param[in] yAxis The Y axis
413 * @param[in] zAxis The Z axis
415 DALI_INTERNAL void SetFromAxes( const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis );
419 Vector4 mVector; ///< w component is s ( = cos(theta/2.0) )
423 * @brief Print a Quaternion.
425 * @param [in] o The output stream operator.
426 * @param [in] quaternion The quaternion to print.
427 * @return The output stream operator.
429 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Quaternion& quaternion);
431 // Allow Quaternion to be treated as a POD type
432 template <> struct TypeTraits< Quaternion > : public BasicTypes< Quaternion > { enum { IS_TRIVIAL_TYPE = true }; };
436 #endif // __DALI_QUATERNION_H__