Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.math
Class Quaternion4f

java.lang.Object
  extended by net.rim.device.api.math.Quaternion4f
All Implemented Interfaces:
Animatable
public class Quaternion4f
extends Object
implements Animatable

Defines a 4-element quaternion that represents the orientation of an object in space.

Quaternions are typically used as a replacement for euler angles and rotation matrices as a way to achieve smooth interpolation and avoid gimbal lock.

Note that this quaternion class does not automatically keep the quaternion normalized. Therefore, care must be taken to normalize the quaternion when neccessary, by calling the normalize method.

The package provides three methods for doing quaternion interpolation: lerp, slerp, and squad.

  1. lerp (linear interpolation): the interpolation curve gives a straight line in quaternion space. It is simple and fast to compute. The only problem is that it does not provide constant angular velocity. Note that a constant velocity is not necessarily a requirement for a curve;
  2. slerp (spherical linear interpolation): the interpolation curve forms a great arc on the quaternion unit sphere. Slerp provides constant angular velocity;
  3. squad (spherical spline interpolation): interpolating between a series of rotations using slerp leads to the following problems:
    1. the curve is not smooth at the control points;
    2. the angular velocity is not constant;
    3. the angular velocity is not continuous at the control points.
    Since squad is continuously differentiable, it remedies the first and third problems mentioned above.

The slerp method provided here is intended for interpolation of principal rotations. It treats +q and -q as the same principal rotation and is at liberty to use the negative of either input. The resulting path is always the shorter arc.

The lerp method provided here interpolates strictly in quaternion space. Note that the resulting path may pass through the origin if interpolating between a quaternion and its exact negative.

As an example, consider the following quaternions

For the point p = (1.0, 1.0, 1.0), the following figures show the trajectories of p using lerp, slerp, and squad.

Since:
BlackBerry API 5.0.0
Field Summary
static int ANIMATION_PROPERTY_QUATERNION
          Used to animate the quaternion.
 float w
          The scalar component of the quaternion.
 float x
          The x-value of the quaternion's vector component.
 float y
          The y-value of the quaternion's vector component.
 float z
          The z-value of the quaternion's vector component.
 
Constructor Summary
Quaternion4f()
          Constructs a quaternion initialized to (0, 0, 0, 1).
Quaternion4f(float x, float y, float z, float w)
          Constructs a new quaternion.
Quaternion4f(float[] array, int offset)
          Constructs a new quaternion from the values in the specified array.
Quaternion4f(Matrix4f m)
          Constructs a new quaternion equal to the rotational part of the specified matrix.
Quaternion4f(Quaternion4f q)
          Constructs a new quaternion that is a copy of the specified one.
Quaternion4f(Vector3f axis, float angle)
          Constructs a new quaternion equal to the rotation from the specified axis and angle.
 
Method Summary
 void conjugate()
          Sets this quaternion to the conjugate of itself.
 void conjugate(Quaternion4f dst)
          Gets the conjugate of this quaternion in dst.
static void controlPoints(Quaternion4f[] quats, Quaternion4f[] cps)
          Computes the control points for the input Quaternion4f.
 boolean equals(Object obj)
          Determines if the specified object is equal to this quaternion.
 boolean equals(Quaternion4f q)
          Determines if the specified quaternion is equal to this one.
 int getAnimationPropertyComponentCount(int property)
           Gets the number of components of the specified property.
 void getAnimationValue(int property, AnimationValue value)
           Gets the value or values of the specified property.
 int hashCode()
          Returns the hash code of the quaternion, based on the values stored in it.
 boolean inverse()
          Sets this quaternion to the inverse of itself.
 boolean inverse(Quaternion4f dst)
          Gets the inverse of this quaternion in dst.
 boolean isIdentity()
          Determines if this quaterion is equal to the identity quaternion.
static void lerp(Quaternion4f q1, Quaternion4f q2, float t, Quaternion4f dst)
          Interpolates between two quaternions using linear interpolation.
 void multiply(Quaternion4f q)
          Multiplies this quaternion by the specified one and stores the result in this quaternion.
static void multiply(Quaternion4f q1, Quaternion4f q2, Quaternion4f dst)
          Multiplies the specified quaternions and stores the result in dst.
 void normalize()
          Normalizes this quaternion to have unit length.
 void normalize(Quaternion4f dst)
          Normalizes this quaternion and stores the result in dst.
 void set(float x, float y, float z, float w)
          Sets the elements of the quaternion to the specified values.
 void set(float[] array, int offset)
          Sets the elements of the quaternion from the values in the specified array.
 void set(Matrix4f m)
          Sets this quaternion equal to the rotational part of the specified matrix.
 void set(Quaternion4f q)
          Sets the elements of this quaternion to a copy of the specified quaternion.
 void set(Vector3f axis, float angle)
          Sets this quaternion equal to the rotation from the specified axis and angle.
 void setAnimationValue(int property, AnimationValue value)
           Sets the value or values of the specified property.
 void setIdentity()
          Sets this quaternion to be equal to the identity quaternion.
static void slerp(Quaternion4f q1, Quaternion4f q2, float t, Quaternion4f dst)
          Interpolates between two quaternions using spherical linear interpolation.
static void squad(Quaternion4f q1, Quaternion4f q2, Quaternion4f s1, Quaternion4f s2, float t, Quaternion4f dst)
          Interpolates over a series of quaternions using spherical spline interpolation.
 float toAxisAngle(Vector3f e)
          Converts this Quaternion4f to axis-angle notation.
 String toString()
          Returns a String representation of the elements of this quaternion.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 



Field Detail

x

public float x
The x-value of the quaternion's vector component.

Since:
BlackBerry API 5.0.0

y

public float y
The y-value of the quaternion's vector component.

Since:
BlackBerry API 5.0.0

z

public float z
The z-value of the quaternion's vector component.

Since:
BlackBerry API 5.0.0

w

public float w
The scalar component of the quaternion.

Since:
BlackBerry API 5.0.0

ANIMATION_PROPERTY_QUATERNION

public static final int ANIMATION_PROPERTY_QUATERNION
Used to animate the quaternion.

Required AnimationKeyframeSequence data format: 

  float[] data = 
  {
      rotation.x, rotation.y, rotation.z, rotation.w
  }

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Constructor Detail

Quaternion4f

public Quaternion4f()
Constructs a quaternion initialized to (0, 0, 0, 1).

Since:
BlackBerry API 5.0.0

Quaternion4f

public Quaternion4f(float x,
                    float y,
                    float z,
                    float w)
Constructs a new quaternion.

Parameters:
x - the x-value
y - the y-value
z - the z-value
w - the w-value
Since:
BlackBerry API 5.0.0

Quaternion4f

public Quaternion4f(float[] array,
                    int offset)
Constructs a new quaternion from the values in the specified array.

Parameters:
array - an array containing the elements of the quaternion in the order x, y, z, w.
offset - the offset into the array of the x element
Throws:
IllegalArgumentException - If offset is less than zero or offset + 3 is greater than or equal to array.length.
NullPointerException - If array is null.
Since:
BlackBerry API 6.0.0

Quaternion4f

public Quaternion4f(Matrix4f m)
Constructs a new quaternion equal to the rotational part of the specified matrix.

Parameters:
m - the matrix
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 6.0.0

Quaternion4f

public Quaternion4f(Quaternion4f q)
Constructs a new quaternion that is a copy of the specified one.

Parameters:
q - the quaternion to copy
Throws:
NullPointerException - If q is null.
Since:
BlackBerry API 5.0.0

Quaternion4f

public Quaternion4f(Vector3f axis,
                    float angle)
Constructs a new quaternion equal to the rotation from the specified axis and angle.

Parameters:
axis - a vector describing the axis of rotation
angle - the angle of rotation, in radians
Throws:
NullPointerException - If axis is null.
Since:
BlackBerry API 6.0.0


Method Detail

conjugate

public final void conjugate()
Sets this quaternion to the conjugate of itself.

Since:
BlackBerry API 5.0.0

conjugate

public final void conjugate(Quaternion4f dst)
Gets the conjugate of this quaternion in dst.

Parameters:
dst - a quaternion to store the conjugate in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

inverse

public final boolean inverse()
Sets this quaternion to the inverse of itself.

Note that the inverse of a quaternion is equal to its conjugate when the quaternion is unit-length. For this reason, it is more efficient to use the conjugate method directly when you know your quaternion is already unit-length.

Returns:
true if the inverse can be computed, false otherwise
Since:
BlackBerry API 5.0.0

inverse

public final boolean inverse(Quaternion4f dst)
Gets the inverse of this quaternion in dst.

Note that the inverse of a quaternion is equal to its conjugate when the quaternion is unit-length. For this reason, it is more efficient to use the conjugate method directly when you know your quaternion is already unit-length.

Parameters:
dst - a quaternion to store the inverse in
Returns:
true if the inverse can be computed, false otherwise
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

isIdentity

public final boolean isIdentity()
Determines if this quaterion is equal to the identity quaternion.

Returns:
true or false
Since:
BlackBerry API 5.0.0

multiply

public final void multiply(Quaternion4f q)
Multiplies this quaternion by the specified one and stores the result in this quaternion.

Parameters:
q - the quaternion to multiply
Throws:
NullPointerException - If q is null.
Since:
BlackBerry API 5.0.0

multiply

public static void multiply(Quaternion4f q1,
                            Quaternion4f q2,
                            Quaternion4f dst)
Multiplies the specified quaternions and stores the result in dst.

Parameters:
q1 - the first quaternion
q2 - the second quaternion
dst - a quaternion to store the result in
Throws:
NullPointerException - If q1, q2, or dst is null.
Since:
BlackBerry API 5.0.0

normalize

public final void normalize()
Normalizes this quaternion to have unit length.

If the quaternion already has unit length or if the length of the quaternion is zero, this method does nothing.

Since:
BlackBerry API 5.0.0

normalize

public final void normalize(Quaternion4f dst)
Normalizes this quaternion and stores the result in dst.

If the quaternion already has unit length or if the length of the quaternion is zero, this method simply copies this vector into dst.

Parameters:
dst - a quaternion to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

set

public final void set(float x,
                      float y,
                      float z,
                      float w)
Sets the elements of the quaternion to the specified values.

Parameters:
x - the new x-value
y - the new y-value
z - the new z-value
w - the new w-value
Since:
BlackBerry API 5.0.0

set

public final void set(float[] array,
                      int offset)
Sets the elements of the quaternion from the values in the specified array.

Parameters:
array - an array containing the elements of the quaternion in the order x, y, z, w.
offset - the offset into the array of the x element
Throws:
IllegalArgumentException - If offset is less than zero or offset + 3 is greater than or equal to array.length.
NullPointerException - If array is null.
Since:
BlackBerry API 5.0.0

set

public final void set(Matrix4f m)
Sets this quaternion equal to the rotational part of the specified matrix.

Parameters:
m - the matrix
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

set

public final void set(Quaternion4f q)
Sets the elements of this quaternion to a copy of the specified quaternion.

Parameters:
q - the quaternion to copy
Throws:
NullPointerException - If q is null.
Since:
BlackBerry API 5.0.0

set

public final void set(Vector3f axis,
                      float angle)
Sets this quaternion equal to the rotation from the specified axis and angle.

Parameters:
axis - a vector describing the axis of rotation
angle - the angle of rotation, in radians
Throws:
NullPointerException - If axis is null.
Since:
BlackBerry API 5.0.0

setIdentity

public final void setIdentity()
Sets this quaternion to be equal to the identity quaternion.

Since:
BlackBerry API 5.0.0

slerp

public static void slerp(Quaternion4f q1,
                         Quaternion4f q2,
                         float t,
                         Quaternion4f dst)
Interpolates between two quaternions using spherical linear interpolation.

Spherical linear interpolation provides smooth transitions between different orientations and is often useful for animating models or cameras in 3D.

Note: For accurate interpolation, the input quaternions must be at (or close to) unit length. This method does not automatically normalize the input quaternions, so it is up to the caller to ensure they call normalize beforehand, if necessary.

Parameters:
q1 - the first quaternion
q2 - the second quaternion
t - the interpolation coefficient
dst - a quaternion to store the result in
Throws:
NullPointerException - If q1, q2, or dst is null.
Since:
BlackBerry API 5.0.0

equals

public boolean equals(Object obj)
Determines if the specified object is equal to this quaternion.

Overrides:
equals in class Object
Parameters:
obj - the object to compare
Returns:
true if obj is an instance of Quaternion4f and if all its components equal this one
Throws:
NullPointerException - If obj is null.
See Also:
Boolean.hashCode(), Hashtable
Since:
BlackBerry API 5.0.0

equals

public boolean equals(Quaternion4f q)
Determines if the specified quaternion is equal to this one.

Parameters:
q - the quaternion to compare
Returns:
true if all componenets of the specified quaternion equal this one
Throws:
NullPointerException - If q is null.
Since:
BlackBerry API 5.0.0

hashCode

public int hashCode()
Returns the hash code of the quaternion, based on the values stored in it.

Overrides:
hashCode in class Object
Returns:
the hash code
See Also:
Object.equals(java.lang.Object), Hashtable
Since:
BlackBerry API 5.0.0

toString

public String toString()
Returns a String representation of the elements of this quaternion.

Overrides:
toString in class Object
Returns:
a String representation of this quaternion
Since:
BlackBerry API 5.0.0

getAnimationValue

public void getAnimationValue(int property,
                              AnimationValue value)
Description copied from interface: Animatable

Gets the value or values of the specified property.

Used by the Animation framework to get the values of the specified property on the Animatable. The implementer must set the value of the specified target property in the AnimationValue parameter.

Specified by:
getAnimationValue in interface Animatable
Parameters:
property - The property to get the current value or values of.
value - An AnimationValue used to store the returned property values.
See Also:
Animatable.getAnimationValue(int,AnimationValue)
Since:
BlackBerry API 6.0.0

setAnimationValue

public void setAnimationValue(int property,
                              AnimationValue value)
Description copied from interface: Animatable

Sets the value or values of the specified property.

Used by the Animation framework to update the value or values of the specified target property on the Animatable with the currently calculated animation value. The implementer must update the current value or values of the given target property with the values in the AnimationValue parameter.

Specified by:
setAnimationValue in interface Animatable
Parameters:
property - The property to set the current value or values of.
value - The AnimationValue used to specify the value or values to set.
See Also:
Animatable.setAnimationValue(int,AnimationValue)
Since:
BlackBerry API 6.0.0

getAnimationPropertyComponentCount

public int getAnimationPropertyComponentCount(int property)
Description copied from interface: Animatable

Gets the number of components of the specified property.

The implementer must define the component size of every animatable property defined for the Animatable.

Specified by:
getAnimationPropertyComponentCount in interface Animatable
Parameters:
property - The property to retrieve the component count for.
Returns:
The number of components comprising the specified property.
See Also:
Animatable.getAnimationPropertyComponentCount(int)
Since:
BlackBerry API 6.0.0

toAxisAngle

public float toAxisAngle(Vector3f e)
Converts this Quaternion4f to axis-angle notation. The axis is normalized.

Parameters:
e - the Vector3f which stores the axis.
Returns:
the angle (in radians).
Throws:
NullPointerException - If e is null.
Since:
BlackBerry API 6.0.0

lerp

public static void lerp(Quaternion4f q1,
                        Quaternion4f q2,
                        float t,
                        Quaternion4f dst)
Interpolates between two quaternions using linear interpolation.

The interpolation curve for linear interpolation between quaternions gives a straight line in quaternion space.

Parameters:
q1 - the first quaternion
q2 - the second quaternion
t - the interpolation coefficient
dst - a quaternion to store the result in
Throws:
NullPointerException - If q1, q2, or dst is null.
Since:
BlackBerry API 6.0.0

squad

public static void squad(Quaternion4f q1,
                         Quaternion4f q2,
                         Quaternion4f s1,
                         Quaternion4f s2,
                         float t,
                         Quaternion4f dst)
Interpolates over a series of quaternions using spherical spline interpolation.

Spherical spline interpolation provides smooth transitions between different orientations and is often useful for animating models or cameras in 3D.

Note: For accurate interpolation, the input quaternions must be unit. This method does not automatically normalize the input quaternions, so it is up to the caller to ensure they call normalize beforehand, if necessary.

Parameters:
q1 - the first quaternion
q2 - the second quaternion
s1 - the first control point
s2 - the second control point
t - the interpolation coefficient
dst - a quaternion to store the result in
Throws:
NullPointerException - If q1, q2, s1, s2, or dst is null.

See Also:
Quaternion4f.controlPoints(Quaternion4f[], Quaternion4f[])
Since:
BlackBerry API 6.0.0

controlPoints

public static void controlPoints(Quaternion4f[] quats,
                                 Quaternion4f[] cps)
Computes the control points for the input Quaternion4f. These control points are needed in squad computation.

Parameters:
quats - the array storing the Quarternion4f's
cps - the array storing the computed control points each of which is a Quaternion4f
Throws:
NullPointerException - if either quats or cps is null
IllegalArgumentException - if the quats.length < 3 or if quats.length != cps.length

Note that cps[0] = quats[0], and cps[n-1] = quats[n-1] where n = quats.length.

Since:
BlackBerry API 6.0.0



Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal