net.rim.device.api.math
Class Ray

java.lang.Object
  extended by net.rim.device.api.math.Ray

public class Ray
extends Object

Defines a 3-dimensional ray.

This class guarantees that its direction vector is always normalized.

Since:
BlackBerry API 6.0.0

Field Summary
static float INTERSECTS_NONE
          Represents when a 3d entity does not intersect a ray.
 
Constructor Summary
Ray(Ray ray)
          Constructs a new ray from the given ray.
Ray(Vector3f origin, Vector3f direction)
          Constructs a new ray initialized to the specified values.
 
Method Summary
 boolean equals(Object obj)
          Determines if the specified object is of type Ray and all of its elements are equal to the elements of this ray.
 boolean equals(Ray ray)
          Returns true if all elements of the specified ray are equal to the elements of this ray.
 void getDirection(Vector3f direction)
          Gets the ray's direction in the given vector.
 void getOrigin(Vector3f origin)
          Gets the ray's origin in the given point.
 int hashCode()
          Returns a hash code based on the elements of this ray.
 float intersects(Bounds bounds)
          Tests whether this ray intersects the specified bounds.
 float intersects(Frustum frustum)
          Tests whether this ray intersects the specified frustum.
 float intersects(Plane plane)
          Tests whether this ray intersects the specified plane.
 void set(Ray ray)
          Sets this ray to the given ray.
 void set(Vector3f origin, Vector3f direction)
          Sets this ray to the specified values.
 void setDirection(float dx, float dy, float dz)
          Sets the ray's direction to the specified values.
 void setDirection(Vector3f direction)
          Sets the ray's direction to the given vector.
 void setOrigin(float ox, float oy, float oz)
          Sets the ray's origin to the specified values.
 void setOrigin(Vector3f origin)
          Sets the ray's origin to the given point.
 String toString()
          Returns a String representation of this ray.
 void transform(Matrix4f matrix)
          Transforms this ray by the given transformation matrix.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 



Field Detail

INTERSECTS_NONE

public static final float INTERSECTS_NONE
Represents when a 3d entity does not intersect a ray.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Constructor Detail

Ray

public Ray(Vector3f origin,
           Vector3f direction)
Constructs a new ray initialized to the specified values.

Parameters:
origin - The ray's origin.
direction - The ray's direction.
Throws:
NullPointerException - If origin or direction is null.
IllegalArgumentException - If direction is equal to the zero vector.
Since:
BlackBerry API 6.0.0

Ray

public Ray(Ray ray)
Constructs a new ray from the given ray.

Parameters:
ray - The ray to copy.
Throws:
NullPointerException - If ray is null.
Since:
BlackBerry API 6.0.0


Method Detail

getDirection

public void getDirection(Vector3f direction)
Gets the ray's direction in the given vector.

Parameters:
direction - The vector to store the ray's direction in.
Throws:
NullPointerException - If direction is null.
Since:
BlackBerry API 6.0.0

getOrigin

public void getOrigin(Vector3f origin)
Gets the ray's origin in the given point.

Parameters:
origin - The point to store the ray's origin in.
Throws:
NullPointerException - If origin is null.
Since:
BlackBerry API 6.0.0

intersects

public float intersects(Bounds bounds)
Tests whether this ray intersects the specified bounds.

Parameters:
bounds - The bounding object to test intersection with.
Returns:
The distance from the origin of this ray to the bounding object or Ray.INTERSECTS_NONE if this ray does not intersect the bounding object.
Throws:
NullPointerException - If bounds is null.
Since:
BlackBerry API 6.0.0

intersects

public float intersects(Frustum frustum)
Tests whether this ray intersects the specified frustum.

Parameters:
frustum - The frustum to test intersection with.
Returns:
The distance from the origin of this ray to the frustum or Ray.INTERSECTS_NONE if this ray does not intersect the frustum.
Throws:
NullPointerException - If frustum is null.
Since:
BlackBerry API 6.0.0

intersects

public float intersects(Plane plane)
Tests whether this ray intersects the specified plane.

Parameters:
plane - The plane to test intersection with.
Returns:
The distance from the origin of this ray to the plane or Ray.INTERSECTS_NONE if this ray does not intersect the plane.
Throws:
NullPointerException - If plane is null.
Since:
BlackBerry API 6.0.0

set

public void set(Vector3f origin,
                Vector3f direction)
Sets this ray to the specified values.

Parameters:
origin - The ray's origin.
direction - The ray's direction.
Throws:
NullPointerException - If origin or direction is null.
IllegalArgumentException - If direction is equal to the zero vector.
Since:
BlackBerry API 6.0.0

set

public void set(Ray ray)
Sets this ray to the given ray.

Parameters:
ray - The ray to set to.
Throws:
NullPointerException - If ray is null.
Since:
BlackBerry API 6.0.0

setDirection

public void setDirection(Vector3f direction)
Sets the ray's direction to the given vector.

Parameters:
direction - The new direction vector.
Throws:
NullPointerException - If direction is null.
IllegalArgumentException - If direction is equal to the zero vector.
Since:
BlackBerry API 6.0.0

setDirection

public void setDirection(float dx,
                         float dy,
                         float dz)
Sets the ray's direction to the specified values.

Parameters:
dx - The x coordinate of the new direction vector.
dy - The y coordinate of the new direction vector.
dz - The z coordinate of the new direction vector.
Throws:
IllegalArgumentException - If the given direction vector is equal to the zero vector.
Since:
BlackBerry API 6.0.0

setOrigin

public void setOrigin(Vector3f origin)
Sets the ray's origin to the given point.

Parameters:
origin - The new origin.
Throws:
NullPointerException - If origin is null.
Since:
BlackBerry API 6.0.0

setOrigin

public void setOrigin(float ox,
                      float oy,
                      float oz)
Sets the ray's origin to the specified values.

Parameters:
ox - The x coordinate of the new origin.
oy - The y coordinate of the new origin.
oz - The z coordinate of the new origin.
Since:
BlackBerry API 6.0.0

transform

public void transform(Matrix4f matrix)
Transforms this ray by the given transformation matrix.

Parameters:
matrix - The transformation matrix to transform by.
Throws:
NullPointerException - If matrix is null.
Since:
BlackBerry API 6.0.0

equals

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

Overrides:
equals in class Object
Parameters:
obj - The object to compare.
Returns:
true if this ray 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(Ray ray)
Returns true if all elements of the specified ray are equal to the elements of this ray.

Parameters:
ray - The ray to compare.
Returns:
true if this ray is equal to ray; false otherwise.
Throws:
NullPointerException - If ray is null.
Since:
BlackBerry API 6.0.0

hashCode

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

Overrides:
hashCode in class Object
Returns:
The hash code for this ray.
See Also:
Object.equals(java.lang.Object), Hashtable
Since:
BlackBerry API 6.0.0

toString

public String toString()
Returns a String representation of this ray.

Overrides:
toString in class Object
Returns:
A String representation of this ray.
Since:
BlackBerry API 6.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.