Public Member Functions
CQuaternion Class Reference

## Detailed Description

Implementation of a quaternion q=a+bi+cj+dk.

A quaternion is often noted q=(s,v) where s is a scalar and v is a 3D vector, or either noted q=(W,X,Y,Z), where W, X, Y and Z are scalar, and X, Y and Z are the components of vector v in previous notation.

You can set a quaternion using various rotation representation with the help of the CRotation class.

See also:
  CRotation, CTransformation

Example:
  Using CRotation to construct a CQuaternion from various rotation representations.

              using namespace XSI;
              using namespace MATH;

              CVector3 eulerAngles( PI, PI * 2.0, PI / 2.0 );
              CRotation eulerAnglesRot( eulerAngles, CRotation::siXYZ );
              CQuaternion quat( eulerAnglesRot );

              CVector3 axis( 1.0, 2.0, 3.0 );
              CRotation axisAngleRot( axis, PI );
              quat = axisAngleRot;

              CMatrix3 identityMatrix;
              quat.SetFromRotation( CRotation(identityMatrix) );

Example: Performing linear extrapolation using quaternions

            // Quaternion linear extrapolation example
            using namespace XSI;
            using namespace MATH;

            Application app;
            Model root = app.GetActiveSceneRoot();

            // define start and end point for rotation
            CQuaternion startQuat;
            CRotation rotationEnd( CVector3( PI, 0.0, 0.0 ) );
            CQuaternion endQuat( rotationEnd );

            // number of interpolation to perform + interpolation increment
            const size_t nbInterpolations = 10;
            const double interpolationIncrement = 1.0 / nbInterpolations;

            CQuaternion interpolatedQuaternion;
            CRotation currentRotation;
            X3DObject currentObject;
            CVector3 rotationAngles;

            // Create cubes rotated using interpolated values
            for ( double i = 0.0; i < 1.0; i += interpolationIncrement )
            {
                // interpolate values
                interpolatedQuaternion.Slerp( startQuat, endQuat, i );

                // create cube
                root.AddGeometry( L"Cube", L"MeshSurface", L"", currentObject );

                // apply interpolated value in X
                currentRotation = interpolatedQuaternion;
                rotationAngles = currentRotation.GetXYZAngles();
                KinematicState globalKS = currentObject.GetKinematics().GetGlobal();
                globalKS.PutParameterValue( L"rotx",
                    (double)RadiansToDegrees(rotationAngles.GetX()));
            }

`#include <xsi_quaternion.h>`

List of all members.

## Public Member Functions
SICPPSDK_INLINE | CQuaternion ()
SICPPSDK_INLINE | CQuaternion (const CQuaternion &in_quaternion)
| ~CQuaternion ()
SICPPSDK_INLINE CQuaternion & | operator= (const CQuaternion &in_quaternion)
SICPPSDK_INLINE | CQuaternion (const double in_dW, const double in_dX, const double in_dY, const double in_dZ)
SICPPSDK_INLINE | CQuaternion (const CVector3 &in_vct)
SICPPSDK_INLINE | CQuaternion (const CVector4 &in_vct)
SICPPSDK_INLINE | CQuaternion (const CRotation &in_Rot)
CQuaternion & | operator= (const CRotation &in_Rot)
CQuaternion & | SetFromRotation (const CRotation &in_Rot)
CRotation | GetRotation () const
CQuaternion & | Normalize ()
bool | EpsilonEquals (const CQuaternion &in_Quat, double in_dEpsilon) const
SICPPSDK_INLINE bool | Equals (const CQuaternion &in_Quat) const
SICPPSDK_INLINE bool | operator== (const CQuaternion &in_Quat) const
CQuaternion & | Slerp (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2, double in_dU)
SICPPSDK_INLINE CQuaternion & | operator*= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | MulInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | Mul (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternion & | operator-= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | SubInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | Sub (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternion & | NegateInPlace ()
SICPPSDK_INLINE CQuaternion & | Negate (const CQuaternion &in_Quat)
double | GetLengthSquared () const
double | GetLength () const
SICPPSDK_INLINE CQuaternion & | operator+= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | AddInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | Add (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternion & | ConjugateInPlace ()
SICPPSDK_INLINE CQuaternion & | Conjugate (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | InvertInPlace ()
SICPPSDK_INLINE CQuaternion & | Invert (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion & | SetIdentity ()
SICPPSDK_INLINE CQuaternion & | Copy (const CQuaternion &in_Quat)
SICPPSDK_INLINE void | Get (double &out_dW, double &out_dX, double &out_dY, double &out_dZ) const
CVector3 | Get () const
SICPPSDK_INLINE void | Get (CVector4 &io_XYZWVector) const
SICPPSDK_INLINE CQuaternion & | Set (double in_dW, double in_dX, double in_dY, double in_dZ)
SICPPSDK_INLINE CQuaternion & | Set (const CVector3 &in_XYZVector)
SICPPSDK_INLINE CQuaternion & | Set (const CVector4 &in_XYZWVector)
SICPPSDK_INLINE double | GetValue (short in_nIndex) const
SICPPSDK_INLINE CQuaternion & | PutValue (short in_nIndex, double newVal)
SICPPSDK_INLINE double | GetW () const
SICPPSDK_INLINE CQuaternion & | PutW (double newVal)
SICPPSDK_INLINE double | GetZ () const
SICPPSDK_INLINE CQuaternion & | PutZ (double newVal)
SICPPSDK_INLINE double | GetY () const
SICPPSDK_INLINE CQuaternion & | PutY (double newVal)
SICPPSDK_INLINE double | GetX () const
SICPPSDK_INLINE CQuaternion & | PutX (double newVal)
CQuaternion & | SetFromXYZAnglesValues (double x, double y, double z)
void | GetXYZAnglesValues (double &x, double &y, double &z) const
SICPPSDK_INLINE bool | operator!= (const CQuaternion &in_quat) const

## Constructor & Destructor Documentation

SICPPSDK_INLINE CQuaternion | ( |  | ) |

Default constructor. Constructs the identity quaternion.

See also:
  CQuaternion::SetIdentity

SICPPSDK_INLINE CQuaternion | ( | const CQuaternion & | in_quaternion | ) |

Copy constructor.

Parameters:

  in_quaternion | constant class object.

~CQuaternion | ( |  | ) | `[inline]`

Default destructor.

SICPPSDK_INLINE CQuaternion | ( | const double | in_dW,
|  | const double | in_dX,
|  | const double | in_dY,
|  | const double | in_dZ
| ) |  |

Constructor.

Parameters:

  in_dW | W component
  in_dX | X component of the quaternion's vector
  in_dY | Y component of the quaternion's vector
  in_dZ | Z component of the quaternion's vector

SICPPSDK_INLINE CQuaternion | ( | const CVector3 & | in_vct | ) |

Constructor.

Note:
  The W component of the quaternion will be set to 1.0

Parameters:

  in_vct | Vector containing the X, Y and Z values

SICPPSDK_INLINE CQuaternion | ( | const CVector4 & | in_vct | ) |

Constructor.

Parameters:

  in_vct | Vector containing the X, Y, Z and W values

SICPPSDK_INLINE CQuaternion | ( | const CRotation & | in_Rot | ) |

Constructor (from a rotation).

Parameters:

  in_Rot | Rotation to construct from

## Member Function Documentation

SICPPSDK_INLINE CQuaternion & operator= | ( | const CQuaternion & | in_quaternion | ) |

Assignment operator.

Parameters:

  in_quaternion | constant class object.

Returns:
  This quaternion

CQuaternion& operator= | ( | const CRotation & | in_Rot | ) |

Sets the quaternion from a rotation

Parameters:

  in_Rot | Rotation to set from

Returns:
  This quaternion

CQuaternion& SetFromRotation | ( | const CRotation & | in_Rot | ) |

Sets the quaternion from a rotation

Parameters:

  in_Rot | Rotation to set from

Returns:
  This quaternion

CRotation GetRotation | ( |  | ) | const

Returns a rotation that represents the current quaternion

Returns:
  CRotation

CQuaternion& Normalize | ( |  | ) |

Normalizes the quaternion

bool EpsilonEquals | ( | const CQuaternion & | in_Quat,
|  | double | in_dEpsilon
| ) |  | const

Tests the equality of this quaternion against in_Quat, with a tolerance of in_dEpsilon.

Parameters:

  in_Quat | Quaternion to compare against
  in_dEpsilon | Tolerance. Quaternions are considered equal if each parameter pair have a difference lower than in_dEpsilon.

Returns:
  true Quaternions are approximately equal
  false Quarternions are not equal

SICPPSDK_INLINE bool Equals | ( | const CQuaternion & | in_Quat | ) | const

Performs an exact comparison of two quaternions.

Note:
  Each parameter of both quaternions must be exactly the same fora match.

Parameters:

  in_Quat | Quaternion to compare against

See also:
  CQuaternion::EpsilonEquals

SICPPSDK_INLINE bool operator== | ( | const CQuaternion & | in_Quat | ) | const

Performs a comparison.

Note:
  Each parameter of both quaternions must be exactly the same for a match.

Parameters:

  in_Quat | Quaternion to compare against

See also:
  CQuaternion::EpsilonEquals, CQuaternion::Equals

CQuaternion& Slerp | ( | const CQuaternion & | in_Quat1,
|  | const CQuaternion & | in_Quat2,
|  | double | in_dU
| ) |  |

Performs spherical linear interpolation of two unit quaternions whithin this quaternion.

Parameters:

  in_Quat1 | First quaternion
  in_Quat2 | Second quaternion
  in_dU | Interpolation factor within [0.0 .. 1.0].

Returns:
  This quaternion

SICPPSDK_INLINE CQuaternion & operator*= | ( | const CQuaternion & | in_Quat | ) |

Multiplies this quaternion with another one in place.

Parameters:

  in_Quat | Quaternion to multiply

Returns:
  This quaternion

See also:
  CQuaternion::Mul, CQuaternion::MulInPlace

SICPPSDK_INLINE CQuaternion & MulInPlace | ( | const CQuaternion & | in_Quat | ) |

Multiplies this quaternion with another one in place.

Parameters:

  in_Quat | Quaternion to multiply

Returns:
  This quaternion

See also:
  CQuaternion::Mul

SICPPSDK_INLINE CQuaternion & Mul | ( | const CQuaternion & | in_Quat1,
|  | const CQuaternion & | in_Quat2
| ) |  |

Stores the result of the multiplication of two quaternions.

Parameters:

  in_Quat1 | First quaternion
  in_Quat2 | Second quaternion

Returns:
  This quaternion

SICPPSDK_INLINE CQuaternion & operator-= | ( | const CQuaternion & | in_Quat | ) |

Subtracts a quaternion from the current quaternion in place.

Parameters:

  in_Quat | Quaternion to subtract

Returns:
  This quaternion

See also:
  CQuaternion::SubInPlace, CQuaternion::Sub

SICPPSDK_INLINE CQuaternion & SubInPlace | ( | const CQuaternion & | in_Quat | ) |

Subtracts a quaternion from the current quaternion in place.

Parameters:

  in_Quat | Quaternion to subtract

Returns:
  This quaternion

See also:
  CQuaternion::Sub

SICPPSDK_INLINE CQuaternion & Sub | ( | const CQuaternion & | in_Quat1,
|  | const CQuaternion & | in_Quat2
| ) |  |

Stores the result of the subtraction of two quaternions.

Parameters:

  in_Quat1 | First quaternion
  in_Quat2 | Second quaternion

Returns:
  This quaternion

See also:
  CQuaternion::SubInPlace

SICPPSDK_INLINE CQuaternion & NegateInPlace | ( |  | ) |

Negates all the components of this quaternion.

Returns:
  This quaternion

See also:
  CQuaternion::Negate

SICPPSDK_INLINE CQuaternion & Negate | ( | const CQuaternion & | in_Quat | ) |

Stores the result of the negation of a given quaternion without changing it.

Parameters:

  in_Quat | Quaternion to negate

Returns:
  This quaternion

See also:
  CQuaternion::NegateInPlace

SICPPSDK_INLINE double GetLengthSquared | ( |  | ) | const

Returns the squared length of this quaternion.

Returns:
  The squared length

See also:
  CQuaternion::GetLength

double GetLength | ( |  | ) | const

Returns the length of this quaternion.

Returns:
  Length of this quaternion

See also:
  CQuaternion::GetLengthSquared

SICPPSDK_INLINE CQuaternion & operator+= | ( | const CQuaternion & | in_Quat | ) |

Adds a quaternion to this quaternion.

Parameters:

  in_Quat | Quaternion to add

See also:
  CQuaternion::AddInPlace, CQuaternion::Add

SICPPSDK_INLINE CQuaternion & AddInPlace | ( | const CQuaternion & | in_Quat | ) |

Adds a quaternion to this quaternion.

Parameters:

  in_Quat | Quaternion to add

See also:
  CQuaternion::Add

SICPPSDK_INLINE CQuaternion & Add | ( | const CQuaternion & | in_Quat1,
|  | const CQuaternion & | in_Quat2
| ) |  |

Stores the result of the addition of two quaternions.

Parameters:

  in_Quat1 | First quaternion
  in_Quat2 | Second quaternion

Returns:
  This quaternion

See also:
  CQuaternion::AddInPlace

SICPPSDK_INLINE CQuaternion & ConjugateInPlace | ( |  | ) |

Conjugates this quaternion.

Returns:
  This quaternion

See also:
  CQuaternion::ConjugateInPlace

SICPPSDK_INLINE CQuaternion & Conjugate | ( | const CQuaternion & | in_Quat | ) |

Stores the conjugate of a quaternion without changing it.

Parameters:

  in_Quat | Quaternion to conjugate.

Returns:
  This quaternion

See also:
  CQuaternion::ConjugateInPlace

SICPPSDK_INLINE CQuaternion & InvertInPlace | ( |  | ) |

Inverts this quaternion.

Returns:
  This quaternion

See also:
  CQuaternion::Invert

SICPPSDK_INLINE CQuaternion & Invert | ( | const CQuaternion & | in_Quat | ) |

Stores the invert of a quaternion without changing it.

Parameters:

  in_Quat | Quaternion to invert

Returns:
  This quaternion

See also:
  CQuaternion::Invert

SICPPSDK_INLINE CQuaternion & SetIdentity | ( |  | ) |

Sets this quaternion to identity quaternion.

Returns:
  This quaternion

SICPPSDK_INLINE CQuaternion & Copy | ( | const CQuaternion & | in_Quat | ) |

Copies the content of a quaternion.

Parameters:

  in_Quat | Quaternion to copy

Returns:
  This quaternion

SICPPSDK_INLINE void Get | ( | double & | out_dW,
|  | double & | out_dX,
|  | double & | out_dY,
|  | double & | out_dZ
| ) |  | const

Returns the components of this quaternion.

Return values:

  out_dW | The current value of the W component
  out_dX | The current value of the X component
  out_dY | The current value of the Y component
  out_dZ | The current value of the Z component

CVector3 Get | ( |  | ) | const

Returns the components of this quaternion.

Returns:
  Vector that holds the values of the X, Y and Z components

SICPPSDK_INLINE void Get | ( | CVector4 & | io_XYZWVector | ) | const

Returns the components of this quaternion.

Parameters:

  io_XYZWVector | Vector that holds the values of the X, Y, Z and W components

SICPPSDK_INLINE CQuaternion & Set | ( | double | in_dW,
|  | double | in_dX,
|  | double | in_dY,
|  | double | in_dZ
| ) |  |

Sets the quaternion's components.

Parameters:

  in_dW | New value for the W component
  in_dX | New value for the X component
  in_dY | New value for the Y component
  in_dZ | New value for the Z component

Returns:
  This quaternion

SICPPSDK_INLINE CQuaternion & Set | ( | const CVector3 & | in_XYZVector | ) |

Sets the quaternion's components.

Note:
  The W value is left as is.

Parameters:

  in_XYZVector | Vector that holds the new values for the X, Y and Z components

Returns:
  This quaternion

SICPPSDK_INLINE CQuaternion & Set | ( | const CVector4 & | in_XYZWVector | ) |

Sets the quaternion's components.

Parameters:

  in_XYZWVector | Vector that holds the new values for the X, Y and Z components. The W component is set to 1.0.

Returns:
  This quaternion

SICPPSDK_INLINE double GetValue | ( | short | in_nIndex | ) | const

Gets the value of a single component.

Parameters:

  in_nIndex | 0-based index of the component to get. This value can be 0 (W), 1(X), 2(Y) or 3(Z).

Returns:
  The requested value
  0.0 if an invalid index was provided.

See also:
  CQuaternion::PutValue

SICPPSDK_INLINE CQuaternion & PutValue | ( | short | in_nIndex,
|  | double | newVal
| ) |  |

Sets the value of a single component.

Note:
  The quaternion is unchanged if the provided index is invalid

Parameters:

  in_nIndex | 0-based index of the component to set. This value can be 0 (W), 1(X), 2(Y) or 3(Z).
  newVal | new value

Returns:
  This quaternion

See also:
  CQuaternion::SetValue

SICPPSDK_INLINE double GetW | ( |  | ) | const

Returns the W component.

Returns:
  The W component

SICPPSDK_INLINE CQuaternion & PutW | ( | double | newVal | ) |

Sets the W component.

Parameters:

  newVal | The new value for the component

Returns:
  This quaternion

SICPPSDK_INLINE double GetZ | ( |  | ) | const

Returns the Z component.

Returns:
  The Z component

SICPPSDK_INLINE CQuaternion & PutZ | ( | double | newVal | ) |

Sets the Z component.

Parameters:

  newVal | The new value for the component

Returns:
  This quaternion

SICPPSDK_INLINE double GetY | ( |  | ) | const

Returns the Y component.

Returns:
  The Y component

SICPPSDK_INLINE CQuaternion & PutY | ( | double | newVal | ) |

Sets the Y component.

Parameters:

  newVal | The new value for the component

Returns:
  This quaternion

SICPPSDK_INLINE double GetX | ( |  | ) | const

Returns the X component.

Returns:
  The X component

SICPPSDK_INLINE CQuaternion & PutX | ( | double | newVal | ) |

Sets the X component.

Parameters:

  newVal | The new value for the component

Returns:
  This quaternion

CQuaternion& SetFromXYZAnglesValues | ( | double | x,
|  | double | y,
|  | double | z
| ) |  |

Sets the quaternion using X,Y,Z Euler angles (in radians).

Parameters:

  x | The Euler X value in radians
  y | The Euler Y value in radians
  z | The Euler Z value in radians

Returns:
  This quaternion

void GetXYZAnglesValues | ( | double & | x,
|  | double & | y,
|  | double & | z
| ) |  | const

Returns the X,Y,Z Euler angles (in radians) for this quaternion.

Return values:

  x | The Euler X value in radians
  y | The Euler Y value in radians
  z | The Euler Z value in radians

SICPPSDK_INLINE bool operator!= | ( | const CQuaternion & | in_quat | ) | const

Inequality operator (tests the strict inequality of this quaternion with the quaternion in_quat).

Parameters:

  in_quat | Operand quaternion.

Returns:
  true if equal else false.

See also:
  CQuaternion::Equals

The documentation for this class was generated from the following file:

- xsi_quaternion.h