net.rim.device.api.math
Class Plane

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

public class Plane
extends Object

Defines a 3-dimensional plane.

This class guarantees that the normal vector of the plane is always normalized. (The plane's distance is the distance to the origin along the normal vector once the normal vector is normalized.)

Since:
BlackBerry API 6.0.0

Field Summary
static float INTERSECTS_BACK
          Represents when a 3d entity is behind (in the negative half-space of) a plane.
static float INTERSECTS_FRONT
          Represents when a 3d entity is in front of (in the positive half-space of) a plane.
static float INTERSECTS_INTERSECTING
          Represents when a 3d entity intersects a plane.
 
Constructor Summary
Plane(Plane plane)
          Constructs a new plane from the given plane.
Plane(Vector3f normal, float distance)
          Constructs a new plane from the specified values.
 
Method Summary
 float distance(Vector3f point)
          Calculates the distance from this plane to the specified point.
 boolean equals(Object obj)
          Determines if the specified object is of type Plane and all of its elements are equal to the elements of this plane.
 boolean equals(Plane plane)
          Returns true if all elements of the specified plane are equal to the elements of this plane.
 float getDistance()
          Gets the plane's distance to the origin along its normal.
 void getNormal(Vector3f normal)
          Gets the plane's normal in the given vector.
 int hashCode()
          Returns a hash code based on the elements of this plane.
static void intersection(Plane p1, Plane p2, Plane p3, Vector3f point)
          Calculates the point of intersection of the given three planes and stores it in the given point.
 float intersects(Bounds bounds)
          Tests whether this plane intersects the specified bounds.
 float intersects(Frustum frustum)
          Tests whether this plane intersects the specified frustum.
 float intersects(Plane plane)
          Tests whether this plane intersects the specified plane.
 float intersects(Ray ray)
          Tests whether this plane intersects the specified ray.
 void set(Plane plane)
          Sets this plane to the given plane.
 void set(Vector3f normal, float distance)
          Sets this plane to the specified values.
 void setDistance(float distance)
          Sets the plane's distance to the origin along its normal.
 void setNormal(float nx, float ny, float nz)
          Sets the plane's normal to the given values.
 void setNormal(Vector3f normal)
          Sets the plane's normal to the given vector.
 String toString()
          Returns a String representation of this plane.
 void transform(Matrix4f matrix)
          Transforms this plane by the given transformation matrix.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 



Field Detail

INTERSECTS_BACK

public static final float INTERSECTS_BACK
Represents when a 3d entity is behind (in the negative half-space of) a plane.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

INTERSECTS_FRONT

public static final float INTERSECTS_FRONT
Represents when a 3d entity is in front of (in the positive half-space of) a plane.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

INTERSECTS_INTERSECTING

public static final float INTERSECTS_INTERSECTING
Represents when a 3d entity intersects a plane.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Constructor Detail

Plane

public Plane(Vector3f normal,
             float distance)
Constructs a new plane from the specified values.

Parameters:
normal - The normal vector of this plane.
distance - The distance to this plane along its (unit) normal to the origin.
Throws:
IllegalArgumentException - If normal is the zero vector.
NullPointerException - If normal is null.
Since:
BlackBerry API 6.0.0

Plane

public Plane(Plane plane)
Constructs a new plane from the given plane.

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


Method Detail

distance

public float distance(Vector3f point)
Calculates the distance from this plane to the specified point.

Parameters:
point - The point to calculate distance to.
Returns:
The distance to the specified point.
Throws:
NullPointerException - If point is null.
Since:
BlackBerry API 6.0.0

getDistance

public float getDistance()
Gets the plane's distance to the origin along its normal.

Returns:
The plane's distance to the origin along its normal.
Since:
BlackBerry API 6.0.0

getNormal

public void getNormal(Vector3f normal)
Gets the plane's normal in the given vector.

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

intersection

public static void intersection(Plane p1,
                                Plane p2,
                                Plane p3,
                                Vector3f point)
Calculates the point of intersection of the given three planes and stores it in the given point.

Parameters:
p1 - The first plane.
p2 - The second plane.
p3 - The third plane.
point - The point to store the point of intersection in (this is left unmodified if the planes do not all intersect or if they are all parallel along one vector and intersect along a line).
Throws:
NullPointerException - If p1, p2, p3 or point is null.
Since:
BlackBerry API 6.0.0

intersects

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

Parameters:
bounds - The bounding object to test intersection with.
Returns:
Plane.INTERSECTS_BACK if the specified bounding object is in the negative half-space of this plane, Plane.INTERSECTS_FRONT if it is in the positive half-space of this plane, and Plane.INTERSECTS_INTERSECTING if it intersects this plane.
Throws:
NullPointerException - If bounds is null.
Since:
BlackBerry API 6.0.0

intersects

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

Parameters:
frustum - The frustum to test intersection with.
Returns:
Plane.INTERSECTS_BACK if the specified frustum is in the negative half-space of this plane, Plane.INTERSECTS_FRONT if it is in the positive half-space of this plane, and Plane.INTERSECTS_INTERSECTING if it intersects this plane.
Throws:
NullPointerException - If frustum is null.
Since:
BlackBerry API 6.0.0

intersects

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

Parameters:
plane - The plane to test intersection with.
Returns:
Plane.INTERSECTS_BACK if the specified plane is in the negative half-space of this plane, Plane.INTERSECTS_FRONT if it is in the positive half-space of this plane, and Plane.INTERSECTS_INTERSECTING if it intersects this plane.
Throws:
NullPointerException - If plane is null.
Since:
BlackBerry API 6.0.0

intersects

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

Parameters:
ray - The ray to test intersection with.
Returns:
Plane.INTERSECTS_BACK if the specified ray is in the negative half-space of this plane, Plane.INTERSECTS_FRONT if it is in the positive half-space of this plane, and Plane.INTERSECTS_INTERSECTING if it intersects this plane.
Throws:
NullPointerException - If ray is null.
Since:
BlackBerry API 6.0.0

set

public void set(Vector3f normal,
                float distance)
Sets this plane to the specified values.

Parameters:
normal - The normal vector of this plane.
distance - The distance to this plane along its normal to the origin.
Throws:
IllegalArgumentException - If normal is the zero vector.
NullPointerException - If normal is null.
Since:
BlackBerry API 6.0.0

set

public void set(Plane plane)
Sets this plane to the given plane.

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

setDistance

public void setDistance(float distance)
Sets the plane's distance to the origin along its normal.

Parameters:
distance - The new distance.
Since:
BlackBerry API 6.0.0

setNormal

public void setNormal(Vector3f normal)
Sets the plane's normal to the given vector.

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

setNormal

public void setNormal(float nx,
                      float ny,
                      float nz)
Sets the plane's normal to the given values.

Parameters:
nx - The x coordinate of the new normal vector.
ny - The y coordinate of the new normal vector.
nz - The z coordinate of the new normal vector.
Throws:
IllegalArgumentException - If nx, ny, and nz are all equal to zero.
Since:
BlackBerry API 6.0.0

transform

public void transform(Matrix4f matrix)
Transforms this plane 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 Plane and all of its elements are equal to the elements of this plane.

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

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

hashCode

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

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

toString

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

Overrides:
toString in class Object
Returns:
A String representation of this plane.
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.