shout3d.math
Class Quaternion

java.lang.Object
  |
  +--shout3d.math.Quaternion
public class Quaternion
extends java.lang.Object

A class that handles rotations in quaternion form. The Quaternion class provides ways to construct rotations based on euler angles and axis/angle pairs. These quaternions may then be used to set rotations in field of Transform nodes. (see getAxisAngle() and setAxisAngle())

Constructor Summary
Quaternion()
          Construct a new quaternion, with identity values corresponding to no rotation.
 
Method Summary
 void getAxisAngle(float[] axis_angle)
          Gets the axis + angle equivalent of this quaternion.
 void getAxisAngle(float[] axis_angle, int offset)
          Gets the axis + angle equivalent of this quaternion and loads it into a selected location within the axis_angle.
 void getEulers(float[] hpr)
          Returns a set of three 'euler rotations' equivalent to this quaternion's rotation.
 float[] getMat()
          Returns a 16-float array equivalent to the 4 by 4 matrix rotation matrix specified by this quaternion
 void getQuat(float[] quat)
          Copies the values from this quaternion into a pre-allocated array of 4 floats.
 void getQuat(Quaternion quat)
          Copies the value of this quaternion into another.
 float[] getValue()
          Gets the array of 4 floats defining this quaternion by reference.
 void makeIdent()
          Sets this quaternion to identity (no rotation)
 void mult(Quaternion quat1, Quaternion quat2)
          Sets this quaternion to be the product of the two input quaternions.
 void setAxisAngle(float[] axis_angle)
          Sets this quaternion based on an axis + angle combination.
 void setAxisAngle(float[] axis_angle, int offset)
          Sets this quaternion based on an axis + angle combination.
 void setEulers(float[] hpr)
          Sets the quaternion from a set of three 'euler rotations,' a method preferred by many animators for specifying rotations.
 void setEulers(float h, float p, float r)
          Sets the quaternion from a set of three 'euler rotations,' a method preferred by many animators for specifying rotations.
 void setQuat(float[] quat)
          Sets this quaternion based on the value of another.
 void setQuat(Quaternion quat)
          Sets this quaternion to match the values in another.
 void slerp(Quaternion q0, Quaternion q1, float t)
          Places result of spherical linear interpolation between q0 and q1 in this.
 void xform(float[] v)
          Transforms the given vector by this quaternion.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Quaternion

public Quaternion()
Construct a new quaternion, with identity values corresponding to no rotation.
Method Detail

getValue

public float[] getValue()
Gets the array of 4 floats defining this quaternion by reference.
Returns:
the array of 4 floats, by reference

setEulers

public void setEulers(float[] hpr)
Sets the quaternion from a set of three 'euler rotations,' a method preferred by many animators for specifying rotations. The euler rotations are a sequence of three rotations applied using a sequence known alternatively as "yxz" or "heading/pitch/roll" or "yaw/pitch/roll" It is equivalent to doing the following: [1] apply the first rotation about the +Y axis. This rotates the X and Z axis into a new orientation. [2] apply the second rotation about the new +X axis. This rotates the Y axis to a second orientation and the Z axis to a third orientation. [3] apply the third rotation about the new (third) +Z axis. Example: To construct a rotation of 1.5 radians about the X axis: Quaternion q = new Quaternion(); float[] eulers = { 0, 1.5f, 0 }; q.setEulers(eulers); myTransform.rotation.setValue( q.getValue());
Parameters:
hpr - an array of 3 values specifying the new euler rotations.

setEulers

public void setEulers(float h,
                      float p,
                      float r)
Sets the quaternion from a set of three 'euler rotations,' a method preferred by many animators for specifying rotations. The euler rotations are a sequence of three rotations applied using a sequence known alternatively as "yxz" or "heading/pitch/roll" or "yaw/pitch/roll" It is equivalent to doing the following: [1] apply the first rotation about the +Y axis. This rotates the X and Z axis into a new orientation. [2] apply the second rotation about the new +X axis. This rotates the Y axis to a second orientation and the Z axis to a third orientation. [3] apply the third rotation about the new (third) +Z axis. Example: To construct a rotation of 1.5 radians about the X axis: Quaternion q = new Quaternion(); float[] eulers = { 0, 1.5f, 0 }; q.setEulers(eulers); float[] axisAngle = new float[4]; q.getAxisAngle(axisAngle); myTransform.rotation.setValue( axisAngle );
Parameters:
h - the heading (y rotation) of the euler angles
p - the pitch (x rotation) of the euler angles
r - the roll (z rotation) of the euler angles

getEulers

public void getEulers(float[] hpr)
Returns a set of three 'euler rotations' equivalent to this quaternion's rotation. See setEulers for more information.
Parameters:
hpr - a pre-allocated array of 3 floats into which the 3 euler angles will be loaded.

getMat

public float[] getMat()
Returns a 16-float array equivalent to the 4 by 4 matrix rotation matrix specified by this quaternion
Returns:
the 4 by 4 matrix as an array of 16 floats.

setQuat

public void setQuat(float[] quat)
Sets this quaternion based on the value of another. The values can be taken from another quaternion with: newQ.setQuat( q.getValue());
Parameters:
quat - the quaternion value from which this should be set.

getQuat

public void getQuat(float[] quat)
Copies the values from this quaternion into a pre-allocated array of 4 floats.
Parameters:
quat - the array into which the values will be copied.

setQuat

public void setQuat(Quaternion quat)
Sets this quaternion to match the values in another.
Parameters:
quat - the quaternion from which to copy values.

getQuat

public void getQuat(Quaternion quat)
Copies the value of this quaternion into another.
Parameters:
quat - the quaternion into which to copy values.

makeIdent

public void makeIdent()
Sets this quaternion to identity (no rotation)

mult

public void mult(Quaternion quat1,
                 Quaternion quat2)
Sets this quaternion to be the product of the two input quaternions. This is the equivalent of performing one rotation followed by the other.
Parameters:
quat1 - the first quaternion to be multiplied
quat2 - the second quaternion to be multiplied

xform

public void xform(float[] v)
Transforms the given vector by this quaternion.
Parameters:
v - an array of 3 floats specifying the point to transform.

getAxisAngle

public void getAxisAngle(float[] axis_angle)
Gets the axis + angle equivalent of this quaternion. The results are put into the axis_angle paramater, which should be pre-allocated as an array of 4 floats. Upon completion, the first three elements of axis_angle will specify the axis, and the 4th element will specify an angle about that axis. Rotating by the angle about the axis will produce a rotation equivalent to that of this quaternion. To set a rotation field directly from a quaternion, use this method: float rotVal = myTransform.rotation.getValue(); myQuat.getAxisAngle( rotVal ); myTransform.rotation.setValue(rotVal);
Parameters:
axis_angle - a pre-allocated array of 4 floats into which the results are placed.

getAxisAngle

public void getAxisAngle(float[] axis_angle,
                         int offset)
Gets the axis + angle equivalent of this quaternion and loads it into a selected location within the axis_angle. The axis_angle parameter is assumed pre-allocated with at least offset+3 floats. The resulting 4 values (calculated as with the getAxisAngle(float axis_angle[]) method) will be placed in the entries: axis_angle[offset] axis_angle[offset+1] axis_angle[offset+2] axis_angle[offset+3]
Parameters:
axis_angle - a pre-allocated array containing a multiple of 4 floats into which the results are placed.
offset - offset of the first of the 4 floats within axis_angle array

setAxisAngle

public void setAxisAngle(float[] axis_angle)
Sets this quaternion based on an axis + angle combination. The first three elements of axis_angle specify an axis, and the 4th element specifies an angle about that axis. This quaternion will be set to equal a rotation of that angle about that axis. To set a quaternion directly from a rotation field, use this method: myQuat.setAxisAngle( myTransform.rotation.getValue() );
Parameters:
axis_angle - an array of 4 floats containing the axis and angle

setAxisAngle

public void setAxisAngle(float[] axis_angle,
                         int offset)
Sets this quaternion based on an axis + angle combination. The axis_angle parameter is assumed pre-allocated with at least offset+3 floats. The 4 axis angle values (interpreted as with the getAxisAngle(float axis_angle[]) method) will be taken from the entries: axis_angle[offset] axis_angle[offset+1] axis_angle[offset+2] axis_angle[offset+3]
Parameters:
axis_angle - a pre-allocated array containing a multiple of 4 floats into which the results are placed.
offset - offset of the first of the 4 floats within axis_angle array

slerp

public void slerp(Quaternion q0,
                  Quaternion q1,
                  float t)
Places result of spherical linear interpolation between q0 and q1 in this.
Parameters:
t - interpolation fraction [0, 1] maps result to [q0, q1].