net.rim.device.api.math
Class Vector2f

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

All Implemented Interfaces:

Animatable

public class Vector2f
extends Object
implements Animatable

Defines a 2-element floating point vector.

Since:

BlackBerry API 6.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_Y Used to animate the y component.
static Vector2f	ONE The 2-element vector of 1s.
static Vector2f	UNIT_X The 2-element unit vector along the x axis.
static Vector2f	ZERO The 2-element zero vector.
float	x The x coordinate.
float	y The y coordinate.

Constructor Summary

Vector2f()
Constructs a new vector initialized to all zeros.

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

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

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

Vector2f(Vector2f p1, Vector2f p2)
Constructs a vector that describes the direction between the specified points.

Method Summary
void	add(Vector2f v) Adds the elements of the specified vector to this one.
static void	add(Vector2f v1, Vector2f v2, Vector2f dst) Adds the specified vectors and stores the result in dst.
static float	angle(Vector2f v1, Vector2f v2) Returns the angle (in radians) between the specified vectors.
void	clamp(Vector2f min, Vector2f max) Clamps this vector within the specified range.
static void	clamp(Vector2f v, Vector2f min, Vector2f max, Vector2f dst) Clamps the specified vector within the specified range and returns it in dst.
float	distance(Vector2f v) Returns the distance between this vector and v.
float	distanceSquared(Vector2f v) Returns the squared distance between this vector and v.
float	dot(Vector2f v) Returns the dot product of this vector and the specified vector.
static float	dot(Vector2f v1, Vector2f v2) Returns the dot product between the specified vectors.
boolean	equals(Object obj) Determines if the specified object is of type Vector2f and all of its elements are equal to the elements of this Vector2f.
boolean	equals(Vector2f vector) Returns true if all elements of the specified Vector2f are equal to the elements of this Vector2f.
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 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(Vector2f 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) 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(Vector2f v) Sets the elements of this vector to those in the specified vector.
void	set(Vector2f p1, Vector2f p2) Sets this vector to the directional vector between the specified points.
void	setAnimationValue(int property, AnimationValue value) Sets the value or values of the specified property.
void	subtract(Vector2f v) Subtracts this vector and the specified vector as (this - v) and stores the result in this.
static void	subtract(Vector2f v1, Vector2f v2, Vector2f 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

Field Detail

x

public float x

The x coordinate.

Since:

BlackBerry API 6.0.0

y

public float y

The y coordinate.

Since:

BlackBerry API 6.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_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

ONE

public static final Vector2f ONE

The 2-element vector of 1s.

Since:

BlackBerry API 6.0.0

UNIT_X

public static final Vector2f UNIT_X

The 2-element unit vector along the x axis.

Since:

BlackBerry API 6.0.0

ZERO

public static final Vector2f ZERO

The 2-element zero vector.

Since:

BlackBerry API 6.0.0

Constructor Detail

Vector2f

public Vector2f()

Constructs a new vector initialized to all zeros.

Since:

BlackBerry API 6.0.0

Vector2f

public Vector2f(float x,
                float y)

Constructs a new vector initialized to the specified values.

Parameters:

x - The x coordinate.

y - The y coordinate.

Since:

BlackBerry API 6.0.0

Vector2f

public Vector2f(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.

offset - The offset into the array of the x element.

Throws:

IllegalArgumentException - If offset is less than zero or offset + 1 is greater than or equal to array.length.

NullPointerException - If array is null.

Since:

BlackBerry API 6.0.0

Vector2f

public Vector2f(Vector2f p1,
                Vector2f p2)

Constructs a vector that describes the direction between the specified 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 6.0.0

Vector2f

public Vector2f(Vector2f 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 6.0.0

Method Detail

angle

public static float angle(Vector2f v1,
                          Vector2f 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 6.0.0

add

public final void add(Vector2f 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 6.0.0

add

public static void add(Vector2f v1,
                       Vector2f v2,
                       Vector2f 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 6.0.0

clamp

public final void clamp(Vector2f min,
                        Vector2f max)

Clamps this vector within the specified range.

Parameters:

min - The minimum value.

max - The maximum value.

Throws:

IllegalArgumentException - If min is greater than max.

NullPointerException - If min or max is null.

Since:

BlackBerry API 6.0.0

clamp

public static void clamp(Vector2f v,
                         Vector2f min,
                         Vector2f max,
                         Vector2f dst)

Clamps the specified vector within the specified range and returns it in dst.

Parameters:

v - The vector to clamp.

min - The minimum value.

max - The maximum value.

dst - A vector to store the result in.

Throws:

IllegalArgumentException - If min is greater than max.

NullPointerException - If min, max, or dst is null.

Since:

BlackBerry API 6.0.0

distance

public final float distance(Vector2f 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 6.0.0

distanceSquared

public final float distanceSquared(Vector2f 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 6.0.0

dot

public final float dot(Vector2f 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 6.0.0

dot

public static float dot(Vector2f v1,
                        Vector2f v2)

Returns the dot product 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 6.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 6.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 6.0.0

negate

public final void negate()

Negates this vector.

Since:

BlackBerry API 6.0.0

normalize

public final void normalize()

Normalizes this vector.

This method normalizes this Vector2f 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 6.0.0

normalize

public final void normalize(Vector2f 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 6.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 6.0.0

set

public final void set(float x,
                      float y)

Sets the elements of this vector to the specified values.

Parameters:

x - The new x coordinate.

y - The new y coordinate.

Since:

BlackBerry API 6.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.

offset - The offset into the array of the x element.

Throws:

NullPointerException - If array is null.

ArrayIndexOutOfBoundsException - If offset is less than zero or offset + 1 is greater than or equal to array.length.

Since:

BlackBerry API 6.0.0

set

public final void set(Vector2f 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 6.0.0

set

public final void set(Vector2f p1,
                      Vector2f p2)

Sets this vector to the directional vector between the specified 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 6.0.0

subtract

public final void subtract(Vector2f 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 6.0.0

subtract

public static void subtract(Vector2f v1,
                            Vector2f v2,
                            Vector2f 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 6.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

equals

public boolean equals(Object obj)

Determines if the specified object is of type Vector2f and all of its elements are equal to the elements of this Vector2f.

Overrides:

equals in class Object

Parameters:

obj - The object to compare.

Returns:

true if this vector is equal to obj; false otherwise.

Throws:

NullPointerException - If obj is null.

See Also:

Boolean.hashCode(), Hashtable

Since:

BlackBerry API 6.0.0

equals

public boolean equals(Vector2f vector)

Returns true if all elements of the specified Vector2f are equal to the elements of this Vector2f.

Parameters:

vector - The vector to compare.

Returns:

true if this vector is equal to vector; false otherwise.

Throws:

NullPointerException - If vector is null.

Since:

BlackBerry API 6.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 Vector2f.

See Also:

Object.equals(java.lang.Object), Hashtable

Since:

BlackBerry API 6.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 6.0.0