net.rim.device.api.math
Class Plane

java.lang.Object
  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. Note that if the normal vector is not a unit vector then the distance will be normalized.

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 (unit) normal to the origin. Note that if the normal vector is not a unit vector then the distance will be normalized.

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