openvrml::rotation Struct Reference

A POD-struct comprising a rotation. More...

#include <openvrml/basetypes.h>

Public Member Functions

rotationoperator*= (const rotation &rot) throw ()
 Multiply rotations.
const float & operator[] (std::size_t index) const throw ()
 Index-based element access.
float x () const throw ()
 Get the x axis component.
float y () const throw ()
 Get the y axis component.
float z () const throw ()
 Get the z axis component.
const vec3f axis () const throw ()
 Get the axis of rotation.
float angle () const throw ()
 Get the rotation angle.
void x (float value) throw ()
 Set the x axis component.
void y (float value) throw ()
 Set the y axis component.
void z (float value) throw ()
 Set the z axis component.
void axis (const vec3f &axis) throw ()
 Set the axis of rotation.
void angle (float value) throw ()
 Set the rotation angle.
const rotation inverse () const throw ()
 Inverse rotation.
const rotation slerp (const rotation &dest_rot, float t) const throw ()
 Spherical Linear intERPolation.

Public Attributes

float rot [4]
 Rotation components.

Related Functions

(Note that these are not member functions.)

const openvrml::rotation make_rotation () throw()
 Create a default rotation.
const openvrml::rotation make_rotation (const float(&rot)[4]) throw()
 Create a rotation from an array.
const openvrml::rotation make_rotation (const float x, const float y, const float z, const float angle) throw()
 Create a rotation from x, y, z, and angle components.
const openvrml::rotation make_rotation (const vec3f &axis, const float angle) throw()
 Create a rotation from an axis vector and an angle.
const openvrml::rotation make_rotation (const vec3f &from_vec, const vec3f &to_vec) throw()
 Create a rotation equal to the rotation between two different vectors.
const openvrml::rotation make_rotation (const quatf &quat) throw()
 Create a rotation from a quaternion.
const openvrml::rotation operator* (const rotation &lhs, const rotation &rhs) throw()
 Multiply rotations.
bool operator== (const rotation &lhs, const rotation &rhs) throw()
 Compare for equality.
bool operator!= (const rotation &lhs, const rotation &rhs) throw()
 Compare for inequality.
std::istream & operator>> (std::istream &in, rotation &rot)
 Stream input.
std::ostream & operator<< (std::ostream &out, const rotation &r)
 Stream output.

Detailed Description

A POD-struct comprising a rotation.

VRML rotations are represented with four single-precision floating point components. The first three are an axis of rotation, and the last is rotation in radians.

Per the VRML97 specification, the axis of a rotation is a normalized vector (5.8). The specification leaves undefined how to deal with an attempt to construct a rotation from an axis vector that is not normalized. In order to allow users of the library to minimize the number of normalizations, OpenVRML takes the following approach:

  • Attempts to construct a rotation axis from a vector that is not normalized will yield an assertion failure (abort) unless NDEBUG is defined when compiling the library (in which case truly wacky behavior could result).
  • Assignment to individual components of the axis will result in the axis being renormalized upon each assignment.

Member Function Documentation

openvrml::rotation & openvrml::rotation::operator*= ( const rotation rot) throw ()

Multiply rotations.

Parameters
[in]rotthe rotation by which to multiply.
Returns
a reference to the object.
const float & openvrml::rotation::operator[] ( std::size_t  index) const throw ()
inline

Index-based element access.

Parameters
[in]index0 is the x axis component, 1 is the y axis component, 2 is the z axis component, and 3 is the angle.
float openvrml::rotation::x ( ) const throw ()
inline

Get the x axis component.

Returns
the x axis component.
float openvrml::rotation::y ( ) const throw ()
inline

Get the y axis component.

Returns
the y axis component.
float openvrml::rotation::z ( ) const throw ()
inline

Get the z axis component.

Returns
the z axis component.
const vec3f openvrml::rotation::axis ( ) const throw ()
inline

Get the axis of rotation.

Returns
the axis of rotation.
float openvrml::rotation::angle ( ) const throw ()
inline

Get the rotation angle.

Returns
the rotation angle.
void openvrml::rotation::x ( float  value) throw ()

Set the x axis component.

Parameters
[in]valuenew x axis component value.
void openvrml::rotation::y ( float  value) throw ()

Set the y axis component.

Parameters
[in]valuenew y axis component value.
void openvrml::rotation::z ( float  value) throw ()

Set the z axis component.

Parameters
[in]valuenew z axis component value.
void openvrml::rotation::axis ( const vec3f axis) throw ()

Set the axis of rotation.

Parameters
[in]axisnew axis of rotation.
void openvrml::rotation::angle ( float  value) throw ()
inline

Set the rotation angle.

Parameters
[in]valuenew rotation angle value.
const openvrml::rotation openvrml::rotation::inverse ( ) const throw ()

Inverse rotation.

Returns
the inverse rotation.
const openvrml::rotation openvrml::rotation::slerp ( const rotation dest_rot,
float  t 
) const throw ()

Spherical Linear intERPolation.

Parameters
[in]dest_rotdestination rotation.
[in]tfraction representing the desired position between the rotation and dest_rot.
Returns
the rotation corresponding to t between the rotation and dest_rot.

Friends And Related Function Documentation

const openvrml::rotation make_rotation ( ) throw()
related

Create a default rotation.

Returns
a default rotation.
const openvrml::rotation make_rotation ( const float(&)  rot[4]) throw()
related

Create a rotation from an array.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]rotan array comprising the rotation components.
Precondition
The vector represented by the first three components of rot is normalized.
Returns
a rotation initialized to the values in rot.
const openvrml::rotation make_rotation ( const float  x,
const float  y,
const float  z,
const float  angle 
) throw()
related

Create a rotation from x, y, z, and angle components.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]xx-component of the rotation axis.
[in]yy-component of the rotation axis.
[in]zz-component of the rotation axis.
[in]anglerotation angle.
Precondition
The vector represented by x, y, and z is normalized.
Returns
a rotation initialized to [ x, y, z, angle ].
const openvrml::rotation make_rotation ( const vec3f axis,
const float  angle 
) throw()
related

Create a rotation from an axis vector and an angle.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]axisrotation axis.
[in]anglerotation angle.
Precondition
axis is a normalized vector.
Returns
a rotation initialized using axis and angle.
const openvrml::rotation make_rotation ( const vec3f from_vec,
const vec3f to_vec 
) throw()
related

Create a rotation equal to the rotation between two different vectors.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]from_vecthe starting vector.
[in]to_vecthe ending vector.
Returns
a rotation equal to the rotation between from_vec and to_vec.
const openvrml::rotation make_rotation ( const quatf quat) throw()
related

Create a rotation from a quaternion.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]quata quaternion.
Returns
a rotation corresponding to quat.
const openvrml::rotation operator* ( const rotation lhs,
const rotation rhs 
) throw()
related

Multiply rotations.

Parameters
[in]lhsleft-hand operand.
[in]rhsright-hand operand.
Returns
the product of lhs and rhs.
bool operator== ( const rotation lhs,
const rotation rhs 
) throw()
related

Compare for equality.

Parameters
[in]lhsleft-hand operand.
[in]rhsright-hand operand.
Returns
true if lhs is equal to rhs; false otherwise.
bool operator!= ( const rotation lhs,
const rotation rhs 
) throw()
related

Compare for inequality.

Parameters
[in]lhsleft-hand operand.
[in]rhsright-hand operand.
Returns
true if lhs is not equal to rhs; false otherwise.
std::istream & operator>> ( std::istream &  in,
rotation rot 
)
related

Stream input.

Consistent with the VRML97 convention, commas (“,”) in the input are treated as whitespace.

If the axis components of the rotation do not represent a normalized vector, the failbit will be set on in and rot will not be modified.

Parameters
[in,out]ininput stream.
[out]rota rotation.
Returns
in.
std::ostream & operator<< ( std::ostream &  out,
const rotation r 
)
related

Stream output.

Parameters
[in,out]outoutput stream.
[in]ra rotation.
Returns
out.

Member Data Documentation

float openvrml::rotation::rot[4]

Rotation components.

The first three components define an axis through the origin. The fourth component is a rotation around the axis.