net.risingworld.api.utils

Class Quaternion

java.lang.Object

net.risingworld.api.utils.Quaternion

public class Quaternion
extends java.lang.Object

A quaternion can be used to describe rotations.

See Also:

http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/index.htm

Field Summary

Fields

Modifier and Type	Field and Description
static Quaternion	IDENTITY A quaternion representing no rotation
float	w The W value of this Quaternion (scalar part)
float	x The X value of this Quaternion (vector part)
float	y The Y value of this Quaternion (vector part)
float	z The Z value of this Quaternion (vector part)
static Quaternion	ZERO An "empty" quaternion.

Constructor Summary

Constructors

Constructor and Description
Quaternion()
Quaternion(float x, float y, float z, float w)
Quaternion(Quaternion copy)

Method Summary

Modifier and Type	Method and Description
float	dot(Quaternion quaternion) Gets the dot product of this quaternion with the provided quaternion.
boolean	equals(float x, float y, float z, float w)
boolean	equals(java.lang.Object o) Gets whether or not this quaternion is equal to another object.
Quaternion	fromAngles(float[] angles) Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z).
Quaternion	fromAngles(float pitch, float yaw, float roll) Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z).
Quaternion	fromRotationMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22) Builds this quaternion from a rotational matrix.
Quaternion	fromString(java.lang.String input)
float	getW() Returns the W value of this Quaternion.
float	getX() Returns the X value of this Quaternion.
float	getY() Returns the Y value of this Quaternion.
float	getZ() Returns the Z value of this Quaternion.
int	hashCode() Gets a unique* hash code for this quaternion, based on its values.
boolean	isNaN() Checks if this quaternion is invalid, or more precisely, if any of its values is NaN (not a number).
Quaternion	loadIdentity() Sets this quaternion to 0, 0, 0, 1.
Quaternion	lookAt(float directionx, float directiony, float directionz) "Looks at" a given direction, i.e. the quaternion will be set based on the direction.
Quaternion	lookAt(Vector3f direction) "Looks at" a given direction, i.e. the quaternion will be set based on the direction.
Quaternion	lookAt(Vector3f direction, Vector3f up) "Looks at" a given direction, i.e. the quaternion will be set based on the direction and an up vector.
Quaternion	multLocal(float scalar) Multiplies the quaternion by a scalar.
Quaternion	multLocal(float qx, float qy, float qz, float qw) Multiplies this quaternion by the provided values.
Quaternion	multLocal(Quaternion quaternion) Multiplies this quaternion by the provided quaternion.
Vector3f	multLocal(Vector3f vector) Multiplies the quaternion by a Vector3f.
Quaternion	negateLocal() Negates the values of this quaternion.
float	norm() Gets the norm of this quaternion, i.e. the dot product of this quaternion with itself.
Quaternion	normalizeLocal() Normalizes this quaternion.
Quaternion	set(float x, float y, float z, float w) Sets the X, Y, Z and W values of this Quaternion to the provided values.
Quaternion	set(Quaternion quaternion) Sets the X, Y, Z and W values of this Quaternion to the values of the provided quaternion.
Quaternion	setW(float w) Sets the Z value of this Quaternion.
Quaternion	setX(float x) Sets the X value of this Vector3f.
Quaternion	setY(float y) Sets the Y value of this Vector3f.
Quaternion	setZ(float z) Sets the Z value of this Quaternion.
float[]	toAngles() Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array.
float[]	toAngles(float[] storeTo) Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array.
java.lang.String	toString() Gets a String representation of this quaternion, for example (0.0, 1.25, -0.7, 1.0)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

IDENTITY

public static final Quaternion IDENTITY

A quaternion representing no rotation

ZERO

public static final Quaternion ZERO

An "empty" quaternion. If you're looking for a quaternion with no rotation instead, check out IDENTITY

x

public float x

The X value of this Quaternion (vector part)

y

public float y

The Y value of this Quaternion (vector part)

z

public float z

The Z value of this Quaternion (vector part)

w

public float w

The W value of this Quaternion (scalar part)

Constructor Detail

Quaternion

public Quaternion()

Quaternion

public Quaternion(float x,
                  float y,
                  float z,
                  float w)

Quaternion

public Quaternion(Quaternion copy)

Method Detail

set

public Quaternion set(Quaternion quaternion)

Sets the X, Y, Z and W values of this Quaternion to the values of the provided quaternion.

Parameters:

quaternion - the Quaternion to copy.

Returns:

this Quaternion.

set

public Quaternion set(float x,
                      float y,
                      float z,
                      float w)

Sets the X, Y, Z and W values of this Quaternion to the provided values.

Parameters:

x - the X value.

y - the Y value.

z - the Z value.

w - the W value.

Returns:

this Quaternion.

setX

public Quaternion setX(float x)

Sets the X value of this Vector3f.

Parameters:

x - the new X value.

Returns:

this Vector3f.

setY

public Quaternion setY(float y)

Sets the Y value of this Vector3f.

Parameters:

y - the new Y value.

Returns:

this Vector3f.

setZ

public Quaternion setZ(float z)

Sets the Z value of this Quaternion.

Parameters:

z - the new Z value.

Returns:

this Quaternion.

setW

public Quaternion setW(float w)

Sets the Z value of this Quaternion.

Parameters:

w - the new W value.

Returns:

this Quaternion.

getX

public float getX()

Returns the X value of this Quaternion.

Returns:

the current X value.

getY

public float getY()

Returns the Y value of this Quaternion.

Returns:

the current Y value.

getZ

public float getZ()

Returns the Z value of this Quaternion.

Returns:

the current Z value.

getW

public float getW()

Returns the W value of this Quaternion.

Returns:

the current W value.

loadIdentity

public Quaternion loadIdentity()

Sets this quaternion to 0, 0, 0, 1. I.e. it does no longer represent any rotation.

Returns:

this quaternion.

fromAngles

public Quaternion fromAngles(float[] angles)

Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z). The rotation will be applied in the order: y, z, x

Parameters:

angles - Euler rotation angles (pitch, yaw, roll) as a float array.

Returns:

this quaternion.

fromAngles

public Quaternion fromAngles(float pitch,
                             float yaw,
                             float roll)

Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z). The rotation will be applied in the order: y, z, x

Parameters:

pitch - Euler pitch (attitude) rotation in radians.

yaw - Euler yaw (heading) rotation in radians.

roll - Euler roll (bank) rotation in radians.

Returns:

this quaternion.

See Also:

http://www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToQuaternion/index.htm

toAngles

public float[] toAngles()

Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array.

Returns:

a float array containing the Euler angles (pitch, yaw, roll).

toAngles

public float[] toAngles(float[] storeTo)

Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array.

Parameters:

storeTo - the float array in which the angles should be stored. This array needs to be able to hold at least three elements. If null is provided, a new float array will be created.

Returns:

the float array containing the Euler angles (in radians).

See Also:

http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToEuler/index.htm

multLocal

public Quaternion multLocal(Quaternion quaternion)

Multiplies this quaternion by the provided quaternion. The result is stored in this quaternion.

Parameters:

quaternion - the quaternion to multiply this one by.

Returns:

this quaternion.

multLocal

public Quaternion multLocal(float qx,
                            float qy,
                            float qz,
                            float qw)

Multiplies this quaternion by the provided values. The result is stored in this quaternion.

Parameters:

qx - the x compontent to multiply this quaternion by.

qy - the y compontent to multiply this quaternion by.

qz - the z compontent to multiply this quaternion by.

qw - the w compontent to multiply this quaternion by.

Returns:

this quaternion.

multLocal

public Vector3f multLocal(Vector3f vector)

Multiplies the quaternion by a Vector3f. The result is stored in the vector. You can use this method to apply a rotation (represented by the quaternion) to a vector.

Parameters:

vector - the Vector3f to multiply this quaternion by.

Returns:

the vector.

multLocal

public Quaternion multLocal(float scalar)

Multiplies the quaternion by a scalar. The result is stored in this quaternion.

Parameters:

scalar - the scalar value.

Returns:

this quaternion.

negateLocal

public Quaternion negateLocal()

Negates the values of this quaternion.

Returns:

this quaternion.

normalizeLocal

public Quaternion normalizeLocal()

Normalizes this quaternion.

Returns:

this quaternion.

dot

public float dot(Quaternion quaternion)

Gets the dot product of this quaternion with the provided quaternion.

Parameters:

quaternion - the quaternion to calculate the dot product with.

Returns:

the dot product.

norm

public float norm()

Gets the norm of this quaternion, i.e. the dot product of this quaternion with itself.

Returns:

the norm of this quaternion.

lookAt

public Quaternion lookAt(Vector3f direction)

"Looks at" a given direction, i.e. the quaternion will be set based on the direction. The resulting quaternion represents the rotation for transforming a z-axis to point into the given direction.

Parameters:

direction - the direction (where to "look at").

Returns:

this quaternion.

lookAt

public Quaternion lookAt(float directionx,
                         float directiony,
                         float directionz)

"Looks at" a given direction, i.e. the quaternion will be set based on the direction. The resulting quaternion represents the rotation for transforming a z-axis to point into the given direction.

Parameters:

directionx - the x component of the direction vector.

directiony - the y component of the direction vector.

directionz - the z component of the direction vector.

Returns:

this quaternion.

lookAt

public Quaternion lookAt(Vector3f direction,
                         Vector3f up)

"Looks at" a given direction, i.e. the quaternion will be set based on the direction and an up vector. The resulting quaternion represents the rotation for transforming a z-axis to point into the given direction.

Parameters:

direction - the direction (where to "look at").

up - the according up-vector, typically (0, 1, 0);

Returns:

this quaternion.

fromRotationMatrix

public Quaternion fromRotationMatrix(float m00,
                                     float m01,
                                     float m02,
                                     float m10,
                                     float m11,
                                     float m12,
                                     float m20,
                                     float m21,
                                     float m22)

Builds this quaternion from a rotational matrix.

Parameters:

m00 - 0x0 in the rotational matrix.

m01 - 0x1 in the rotational matrix.

m02 - 0x2 in the rotational matrix.

m10 - 1x0 in the rotational matrix.

m11 - 1x1 in the rotational matrix.

m12 - 1x2 in the rotational matrix.

m20 - 2x0 in the rotational matrix.

m21 - 2x1 in the rotational matrix.

m22 - 2x2 in the rotational matrix.

Returns:

this quaternion.

isNaN

public boolean isNaN()

Checks if this quaternion is invalid, or more precisely, if any of its values is NaN (not a number).

Returns:

true if this quaternion contains any NaN values, false if not.

equals

public boolean equals(float x,
                      float y,
                      float z,
                      float w)

equals

public boolean equals(java.lang.Object o)

Gets whether or not this quaternion is equal to another object. This function returns true, if the other object is a Quaternion and if it has exactly the same x, y, z and w values.

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare for equality.

Returns:

true if the other object is a Quaternion and has the same values as this quaternion, false if not.

hashCode

public int hashCode()

Gets a unique* hash code for this quaternion, based on its values. If two quaternions have the same x, y, z and w values, they will return the same hash code.

* Please keep in mind that the uniqueness is not fully reliable. There is always a small chance that collisions occur (i.e. two completely different quaternions return the same hash code). But usually the reliability is sufficient.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code for this quaternion.

toString

public java.lang.String toString()

Gets a String representation of this quaternion, for example (0.0, 1.25, -0.7, 1.0)

Overrides:

toString in class java.lang.Object

Returns:

a string representing the values of this quaternion.

fromString

public Quaternion fromString(java.lang.String input)