Home | Download | Screen shots | Discussion | Documentation
--- | --- | --- | --- | ---

# openvrml::rotation Struct Reference

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

`#include <openvrml/basetypes.h>`

List of all members.

## Public Member Functions

rotation & | operator*= (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]` | rot | the 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]` | index | 0 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]` | value | new x axis component value.

void openvrml::rotation::y | ( | float | value | ) | throw ()

Set the y axis component.

Parameters:

  `[in]` | value | new y axis component value.

void openvrml::rotation::z | ( | float | value | ) | throw ()

Set the z axis component.

Parameters:

  `[in]` | value | new z axis component value.

void openvrml::rotation::axis | ( | const vec3f & | axis | ) | throw ()

Set the axis of rotation.

Parameters:

  `[in]` | axis | new axis of rotation.

void openvrml::rotation::angle | ( | float | value | ) | throw ()`[inline]`

Set the rotation angle.

Parameters:

  `[in]` | value | new 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_rot | destination rotation.
  `[in]` | t | fraction 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]` | rot | an 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]` | x | x-component of the rotation axis.
  `[in]` | y | y-component of the rotation axis.
  `[in]` | z | z-component of the rotation axis.
  `[in]` | angle | rotation 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]` | axis | rotation axis.
  `[in]` | angle | rotation 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_vec | the starting vector.
  `[in]` | to_vec | the 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]` | quat | a quaternion.

Returns:
  a `rotation` corresponding to `quat`.

const openvrml::rotation operator* | ( | const rotation & | lhs,
|  | const rotation & | rhs |
| ) |  |  | throw()`[related]`

Multiply rotations.

Parameters:

  `[in]` | lhs | left-hand operand.
  `[in]` | rhs | right-hand operand.

Returns:
  the product of `lhs` and `rhs`.

bool operator== | ( | const rotation & | lhs,
|  | const rotation & | rhs |
| ) |  |  | throw()`[related]`

Compare for equality.

Parameters:

  `[in]` | lhs | left-hand operand.
  `[in]` | rhs | right-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]` | lhs | left-hand operand.
  `[in]` | rhs | right-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]` | in | input stream.
  `[out]` | rot | a `rotation`.

Returns:
  `in`.

std::ostream & operator<< | ( | std::ostream & | out,
|  | const rotation & | r |
| ) |  |  | `[related]`

Stream output.

Parameters:

  `[in,out]` | out | output stream.
  `[in]` | r | a 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.