net.rim.device.api.math
Class Quaternion4f

java.lang.Object
  net.rim.device.api.math.Quaternion4f

public class Quaternion4f
extends Object

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.

Since:

BlackBerry API 5.0.0

Field Summary
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(Quaternion4f q)
Constructs a new quaternion that is a copy of the specified one.

Method Summary
void	conjugate() Sets this quaternion to the conjugate of itself.
void	conjugate(Quaternion4f dst) Stores the conjugate of this quaternion in dst.
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	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) Stores the inverse of this quaternion in dst.
boolean	isIdentity() Determines if this quaterion is equal to the identity quaternion.
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	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.
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

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(Quaternion4f q)

Constructs a new quaternion that is a copy of the specified one.

Parameters:

q - the quaternion to copy

Since:

BlackBerry API 5.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)

Stores the conjugate of this quaternion in dst.

Parameters:

dst - a quaternion to store the conjugate in

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

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

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

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)

Stores 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

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

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

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

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

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

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

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

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

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