net.rim.device.api.math
Class Vector3f

java.lang.Object
  extended by net.rim.device.api.math.Vector3f
All Implemented Interfaces:
Animatable

public class Vector3f
extends Object
implements Animatable

Defines a 3-element floating point vector.

When using a vector to represent a surface normal, the vector should typically be normalized. Other uses of directional vectors may wish to leave the magnitude of the vector in-tact. When used as a point, the elements of the vector represent a position in 3D space.

Since:
BlackBerry API 5.0.0

Field Summary
static int ANIMATION_PROPERTY_X
          Used to animate the x component.
static int ANIMATION_PROPERTY_XY
          Used to animate the x and y components.
static int ANIMATION_PROPERTY_XYZ
          Used to animate the x, y and z components.
static int ANIMATION_PROPERTY_XZ
          Used to animate the x and z components.
static int ANIMATION_PROPERTY_Y
          Used to animate the y component.
static int ANIMATION_PROPERTY_YZ
          Used to animate the y and z components.
static int ANIMATION_PROPERTY_Z
          Used to animate the z component.
static Vector3f ONE
          The 3-element vector of 1s.
static Vector3f UNIT_X
          The 3-element unit vector along the x axis.
static Vector3f UNIT_Y
          The 3-element unit vector along the y axis.
static Vector3f UNIT_Z
          The 3-element unit vector along the z axis.
static Vector3f ZERO
          The 3-element zero vector.
 float x
          The x-coordinate.
 float y
          The y-coordinate.
 float z
          The z-coordinate.
 
Constructor Summary
Vector3f()
          Constructs a new vector initialized to all zeros.
Vector3f(float x, float y, float z)
          Constructs a new vector initialized to the specified values.
Vector3f(float[] array, int offset)
          Constructs a new vector from the values in the specified array.
Vector3f(Vector3f v)
          Constructs a new vector that is a copy of the specified vector.
Vector3f(Vector3f p1, Vector3f p2)
          Constructs a vector that describes the direction between the given points.
 
Method Summary
 void add(Vector3f v)
          Adds the elements of the specified vector to this one.
static void add(Vector3f v1, Vector3f v2, Vector3f dst)
          Adds the specified vectors and stores the result in dst.
static float angle(Vector3f v1, Vector3f v2)
          Returns the angle (in radians) between the specified vectors.
 void cross(Vector3f v)
          Sets this vector to the cross product between itself and the specified vector.
static void cross(Vector3f v1, Vector3f v2, Vector3f dst)
          Computes the cross product of the specified vectors and stores the result in dst.
 float distance(Vector3f v)
          Returns the distance between this vector and v.
 float distanceSquared(Vector3f v)
          Returns the squared distance between this vector and v.
 float dot(Vector3f v)
          Returns the dot product of this vector and the specified vector.
static float dot(Vector3f v1, Vector3f v2)
          Returns the dot produce between the specified vectors.
 boolean equals(Object obj)
          Determines if the specified object is of type Vector3f and all of its elements are equal to the elements of this Vector3f.
 boolean equals(Vector3f v)
          Returns true if all elements of the specified Vector3f are equal to the elements of this Vector3f.
 int hashCode()
          Returns a hash code based on the elements of this vector.
 float length()
          Computes the length of this vector.
 float lengthSquared()
          Returns the squared length of this vector.
 void negate()
          Negates this vector.
 void normalize()
          Normalizes this vector.
 void normalize(Vector3f dst)
          Normalizes this vector and stores the result in dst.
 void scale(float scalar)
          Scales all elements of this vector by the specified value.
 void set(float x, float y, float z)
          Sets the elements of this vector to the specified values.
 void set(float[] array, int offset)
          Sets the elements of this vector from the values in the specified array.
 void set(Vector3f v)
          Sets the elements of this vector to those in the specified vector.
 void set(Vector3f p1, Vector3f p2)
          Sets this vector to the directional vector between the given points.
 void subtract(Vector3f v)
          Subtracts this vector and the specified vector as (this - v) and stores the result in this.
static void subtract(Vector3f v1, Vector3f v2, Vector3f dst)
          Subtracts the specified vectors and stores the result in dst.
 String toString()
          Returns a String representation of the elements of this vector.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.rim.device.api.animation.Animatable
getAnimationPropertyComponentCount, getAnimationValue, setAnimationValue
 



Field Detail

x

public float x
The x-coordinate.

Since:
BlackBerry API 5.0.0

y

public float y
The y-coordinate.

Since:
BlackBerry API 5.0.0

z

public float z
The z-coordinate.

Since:
BlackBerry API 5.0.0

ANIMATION_PROPERTY_X

public static final int ANIMATION_PROPERTY_X
Used to animate the x component.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ANIMATION_PROPERTY_Y

public static final int ANIMATION_PROPERTY_Y
Used to animate the y component.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ANIMATION_PROPERTY_Z

public static final int ANIMATION_PROPERTY_Z
Used to animate the z component.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ANIMATION_PROPERTY_XY

public static final int ANIMATION_PROPERTY_XY
Used to animate the x and y components.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ANIMATION_PROPERTY_YZ

public static final int ANIMATION_PROPERTY_YZ
Used to animate the y and z components.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ANIMATION_PROPERTY_XZ

public static final int ANIMATION_PROPERTY_XZ
Used to animate the x and z components.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ANIMATION_PROPERTY_XYZ

public static final int ANIMATION_PROPERTY_XYZ
Used to animate the x, y and z components.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ONE

public static final Vector3f ONE
The 3-element vector of 1s.

Since:
BlackBerry API 6.0.0

UNIT_X

public static final Vector3f UNIT_X
The 3-element unit vector along the x axis.

Since:
BlackBerry API 6.0.0

UNIT_Y

public static final Vector3f UNIT_Y
The 3-element unit vector along the y axis.

Since:
BlackBerry API 6.0.0

UNIT_Z

public static final Vector3f UNIT_Z
The 3-element unit vector along the z axis.

Since:
BlackBerry API 6.0.0

ZERO

public static final Vector3f ZERO
The 3-element zero vector.

Since:
BlackBerry API 6.0.0


Constructor Detail

Vector3f

public Vector3f()
Constructs a new vector initialized to all zeros.

Since:
BlackBerry API 5.0.0

Vector3f

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

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

Vector3f

public Vector3f(float x,
                float y,
                float z)
Constructs a new vector initialized to the specified values.

Parameters:
x - the x-coordiante
y - the y-coordinate
z - the z-coordinate
Since:
BlackBerry API 5.0.0

Vector3f

public Vector3f(Vector3f p1,
                Vector3f p2)
Constructs a vector that describes the direction between the given points.

The new vector describes the direction vector from p1 to p2, computed as p2 - p1.

Parameters:
p1 - the first point
p2 - the second point
Throws:
NullPointerException - If p1 or p2 is null.
Since:
BlackBerry API 5.0.0

Vector3f

public Vector3f(Vector3f v)
Constructs a new vector that is a copy of the specified vector.

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


Method Detail

angle

public static float angle(Vector3f v1,
                          Vector3f v2)
Returns the angle (in radians) between the specified vectors.

Parameters:
v1 - the first vector
v2 - the second vector
Returns:
the angle between the two vectors, in radians
Throws:
NullPointerException - If v1 or v2 is null.
Since:
BlackBerry API 5.0.0

add

public final void add(Vector3f v)
Adds the elements of the specified vector to this one.

Parameters:
v - the vector to add
Throws:
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

add

public static void add(Vector3f v1,
                       Vector3f v2,
                       Vector3f dst)
Adds the specified vectors and stores the result in dst.

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

cross

public final void cross(Vector3f v)
Sets this vector to the cross product between itself and the specified vector.

Parameters:
v - the vector to compute the cross product with
Throws:
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

cross

public static void cross(Vector3f v1,
                         Vector3f v2,
                         Vector3f dst)
Computes the cross product of the specified vectors and stores the result in dst.

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

distance

public final float distance(Vector3f v)
Returns the distance between this vector and v.

Parameters:
v - the other vector
Returns:
the distance between this vector and v
Throws:
NullPointerException - If v is null.
See Also:
distanceSquared
Since:
BlackBerry API 5.0.0

distanceSquared

public final float distanceSquared(Vector3f v)
Returns the squared distance between this vector and v.

When it is not neccessary to get the exact distance between two vectors (for example, when simply comparing the distance between different vectors), it is advised to use this method instead of distance.

Parameters:
v - the other vector
Returns:
the squared distance between this vector and v.
Throws:
NullPointerException - If v is null.
See Also:
distance
Since:
BlackBerry API 5.0.0

dot

public final float dot(Vector3f v)
Returns the dot product of this vector and the specified vector.

Parameters:
v - the vector to compute the dot product with
Returns:
the dot product
Throws:
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

dot

public static float dot(Vector3f v1,
                        Vector3f v2)
Returns the dot produce between the specified vectors.

Parameters:
v1 - the first vector
v2 - the second vector
Returns:
the dot product between the vectors
Throws:
NullPointerException - If v1 or v2 is null.
Since:
BlackBerry API 5.0.0

length

public final float length()
Computes the length of this vector.

Returns:
the length of the vector
See Also:
lengthSquared
Since:
BlackBerry API 5.0.0

lengthSquared

public final float lengthSquared()
Returns the squared length of this vector.

When it is not neccessary to get the exact length of a vector (for example, when simply comparing the lengths of different vectors), it is advised to use this method instead of length.

Returns:
the squared length of the vector
See Also:
length
Since:
BlackBerry API 5.0.0

negate

public final void negate()
Negates this vector.

Since:
BlackBerry API 5.0.0

normalize

public final void normalize()
Normalizes this vector.

This method normalizes this Vector3f so that it is of unit length (in other words, the length of the vector after calling this method will be 1.0f). If the vector already has unit length or if the length of the vector is zero, this method does nothing.

Since:
BlackBerry API 5.0.0

normalize

public final void normalize(Vector3f dst)
Normalizes this vector and stores the result in dst.

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

Parameters:
dst - the destination vector
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

scale

public final void scale(float scalar)
Scales all elements of this vector by the specified value.

Parameters:
scalar - the scalar value
Since:
BlackBerry API 5.0.0

set

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

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

set

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

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

set

public final void set(Vector3f v)
Sets the elements of this vector to those in the specified vector.

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

set

public final void set(Vector3f p1,
                      Vector3f p2)
Sets this vector to the directional vector between the given points.

This result of this vector describes the direction from p1 to p2, computed as p2 - p1.

Parameters:
p1 - the first point
p2 - the second point
Throws:
NullPointerException - If p1 or p2 is null.
Since:
BlackBerry API 5.0.0

subtract

public final void subtract(Vector3f v)
Subtracts this vector and the specified vector as (this - v) and stores the result in this.

Parameters:
v - the vector to subtract
Throws:
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

subtract

public static void subtract(Vector3f v1,
                            Vector3f v2,
                            Vector3f dst)
Subtracts the specified vectors and stores the result in dst.

The resulting vector is computed as (v1 - v2).

Parameters:
v1 - the first vector
v2 - the second vector
dst - the destination vector
Throws:
NullPointerException - If v1, v2, or dst is null.
Since:
BlackBerry API 5.0.0

equals

public boolean equals(Object obj)
Determines if the specified object is of type Vector3f and all of its elements are equal to the elements of this Vector3f.

Overrides:
equals in class Object
Parameters:
obj - the object to compare
Returns:
true or false
Throws:
NullPointerException - If obj is null.
See Also:
Boolean.hashCode(), Hashtable
Since:
BlackBerry API 5.0.0

equals

public boolean equals(Vector3f v)
Returns true if all elements of the specified Vector3f are equal to the elements of this Vector3f.

Parameters:
v - the vector to compare
Returns:
true or false
Throws:
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

hashCode

public int hashCode()
Returns a hash code based on the elements of this vector.

Overrides:
hashCode in class Object
Returns:
the hash code for this Vector3f
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 vector.

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.