NAME

       SbRotation -

       The SbRotation class represents a rotation in 3D space.

       SbRotation is used extensively throughout the Coin library.

SYNOPSIS

   Public Member Functions
       SbRotation (void)
       SbRotation (const SbVec3f &axis, const float radians)
       SbRotation (const float q[4])
       SbRotation (const float q0, const float q1, const float q2, const float q3)
       SbRotation (const SbMatrix &m)
       SbRotation (const SbVec3f &rotateFrom, const SbVec3f &rotateTo)
       const float * getValue (void) const
       void getValue (float &q0, float &q1, float &q2, float &q3) const
       SbRotation & setValue (const float q0, const float q1, const float q2, const float q3)
       void getValue (SbVec3f &axis, float &radians) const
       void getValue (SbMatrix &matrix) const
       SbRotation & invert (void)
       SbRotation inverse (void) const
       SbRotation & setValue (const float q[4])
       SbRotation & setValue (const SbMatrix &m)
       SbRotation & setValue (const SbVec3f &axis, const float radians)
       SbRotation & setValue (const SbVec3f &rotateFrom, const SbVec3f &rotateTo)
       SbRotation & operator*= (const SbRotation &q)
       SbRotation & operator*= (const float s)
       float operator[] (size_t n) const
           returns the n'th quaternion of this rotation
       SbBool equals (const SbRotation &r, float tolerance) const
       void multVec (const SbVec3f &src, SbVec3f &dst) const
       void scaleAngle (const float scaleFactor)
       SbString toString () const
       SbBool fromString (const SbString &str)
       void print (FILE *fp) const

   Static Public Member Functions
       static SbRotation slerp (const SbRotation &rot0, const SbRotation &rot1, float t)
       static SbRotation identity (void)

   Friends
       int operator== (const SbRotation &q1, const SbRotation &q2)
       int operator!= (const SbRotation &q1, const SbRotation &q2)
       SbRotation operator* (const SbRotation &q1, const SbRotation &q2)

Detailed Description

       The SbRotation class represents a rotation in 3D space.

       SbRotation is used extensively throughout the Coin library.

       An SbRotation is stored internally as a quaternion for speed and storage reasons, but
       inquiries can be done to get and set axis and angle values for convenience.

       Note that there is one very common mistake that is easy to make when setting the value of
       an SbRotation, and that is to inadvertently use the wrong SbRotation constructor. This
       example should clarify the problem:

       SbRotation rotation(0, 0, 1, 1.5707963f);

       The programmer clearly tries to set a PI/2 rotation around the Z axis, but this will fail,
       as the SbRotation constructor invoked above is the one that takes as arguments the 4
       floats of a quaternion. What the programmer almost certainly wanted to do was to use the
       SbRotation constructor that takes a rotation vector and a rotation angle, which is invoked
       like this:

       SbRotation rotation(SbVec3f(0, 0, 1), 1.5707963f);

       Another common problem is to set the rotation value to exactly 0.0, while wanting to store
       just the information about a rotation angle: rotations are internally handled as
       quaternions, and when converting from an angle and a rotation value to a quaternion
       representation, the information about the angle 'gets lost' if there is no actual
       rotation.

       See Also:
           SbMatrix

Constructor & Destructor Documentation

   SbRotation::SbRotation (void)
       The default constructor just initializes a valid rotation. The actual value is
       unspecified, and you should not depend on it.

   SbRotation::SbRotation (const SbVec3f &axis, const floatradians)
       Construct a new SbRotation object initialized with the given axis-of-rotation and rotation
       angle.

   SbRotation::SbRotation (const floatq[4])
       Construct a new SbRotation object initialized with the given quaternion components.

       The array must be ordered as follows:

       q[0] = x, q[1] = y, q[2] = z and q[3] = w, where the quaternion is specified by
       q=w+xi+yj+zk.

   SbRotation::SbRotation (const floatq0, const floatq1, const floatq2, const floatq3)
       Construct a new SbRotation object initialized with the given quaternion components.

   SbRotation::SbRotation (const SbMatrix &m)
       Construct a new SbRotation object initialized with the given rotation matrix.

   SbRotation::SbRotation (const SbVec3f &rotateFrom, const SbVec3f &rotateTo)
       Construct a rotation which is the minimum rotation necessary to make vector rotateFrom
       point in the direction of vector rotateTo.

       Example:

       #include <Inventor/SbRotation.h>
       #include <Inventor/SbVec3f.h>
       #include <cstdio>

       int
       main(void)
       {
         SbVec3f from(10, 0, 0);
         SbVec3f to(0, 10, 0);

         SbRotation rot(from, to);

         SbVec3f axis;
         float angle;
         rot.getValue(axis, angle);
         axis.print(stdout);
         printf("  angle==%f0, angle);

         return 0;
       }

Member Function Documentation

   const float * SbRotation::getValue (void) const
       Return pointer to an array with the rotation expressed as four quaternion values.

       See Also:
           setValue().

   void SbRotation::getValue (float &q0, float &q1, float &q2, float &q3) const
       Return the four quaternion components representing the rotation.

       See Also:
           setValue().

   SbRotation & SbRotation::setValue (const floatq0, const floatq1, const floatq2, const floatq3)
       Set the rotation.

       See Also:
           getValue().

   void SbRotation::getValue (SbVec3f &axis, float &radians) const
       Return the rotation in the form of an axis-of-rotation and a rotation angle.

       See Also:
           setValue().

   void SbRotation::getValue (SbMatrix &matrix) const
       Return this rotation in the form of a matrix.

       See Also:
           setValue().

   SbRotation & SbRotation::invert (void)
       Invert the rotation. Returns reference to self.

       See Also:
           inverse()

   SbRotation SbRotation::inverse (void) const
       Non-destructively inverses the rotation and returns the result.

       See Also:
           invert()

   SbRotation & SbRotation::setValue (const floatq[4])
       Reset the rotation by the four quaternions in the array.

       See Also:
           getValue().

   SbRotation & SbRotation::setValue (const SbMatrix &m)
       Set the rotation from the components of the given matrix. Returns reference to self.

       See Also:
           getValue().

   SbRotation & SbRotation::setValue (const SbVec3f &axis, const floatradians)
       Reset rotation with the given axis-of-rotation and rotation angle. Returns reference to
       self.

       Make sure axis is not the null vector when calling this method.

       See Also:
           getValue().

   SbRotation & SbRotation::setValue (const SbVec3f &rotateFrom, const SbVec3f &rotateTo)
       Construct a rotation which is the minimum rotation necessary to make vector rotateFrom
       point in the direction of vector rotateTo.

       Returns reference to self.

       See SbRotation constructor with corresponding input arguments for a simple code example.

       See Also:
           getValue().

   SbRotation & SbRotation::operator*= (const SbRotation &q)
       Multiplies the quaternions.

       Note that order is important when combining quaternions with the multiplication operator.

   SbRotation & SbRotation::operator*= (const floats)
       Multiplies components of quaternion with scalar value s. Returns reference to self.

   SbBool SbRotation::equals (const SbRotation &r, floattolerance) const
       Check the internal quaternion representation vectors for equality within the given
       tolerance.

   void SbRotation::multVec (const SbVec3f &src, SbVec3f &dst) const
       Rotate the src vector and put the result in dst.

       It is safe to let src and dst be the same SbVec3f instance.

   void SbRotation::scaleAngle (const floatscaleFactor)
       Scale the angle of rotation by scaleFactor.

   SbRotation slerp (const SbRotation &rot0, const SbRotation &rot1, floatt) [static]
       Interpolates along the shortest path between the two rotation positions (from rot0 to
       rot1).

       Returns the SbRotation which will rotate rot0 the given part t of the spherical distance
       towards rot1, where t=0 will yield rot0 and t=1 will yield rot1.

       t should be in the interval [0, 1].

   SbRotation SbRotation::identity (void) [static]
       Returns an identity rotation.

   SbString SbRotation::toString () const
       Return a string representation of this object

   SbBool SbRotation::fromString (const SbString &str)
       Convert from a string representation, return wether this is a valid conversion

   void SbRotation::print (FILE *fp) const
       Dump the state of this object to the fp file stream. Only works in debug version of
       library, method does nothing in an optimized compile.

Friends And Related Function Documentation

   int operator== (const SbRotation &q1, const SbRotation &q2) [friend]
       Check if the two rotations are equal.

       See Also:
           equals().

   int operator!= (const SbRotation &q1, const SbRotation &q2) [friend]
       Check if the two rotations are unequal.

       See Also:
           equals().

   SbRotation operator* (const SbRotation &q1, const SbRotation &q2) [friend]
       Multiplies the two rotations and returns the result.

       Note that order is important when combining quaternions with the multiplication operator.

Author

       Generated automatically by Doxygen for Coin from the source code.