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: