gov.nasa.worldwind.geom

Class Matrix4

java.lang.Object

gov.nasa.worldwind.geom.Matrix4

public class Matrix4
extends java.lang.Object

4 x 4 matrix in row-major order.

Field Summary

Fields

Modifier and Type	Field and Description
double[]	m The matrix's components, stored in row-major order.

Constructor Summary

Constructors

Constructor and Description
Matrix4() Constructs a 4 x 4 identity matrix.
Matrix4(double m11, double m12, double m13, double m14, double m21, double m22, double m23, double m24, double m31, double m32, double m33, double m34, double m41, double m42, double m43, double m44) Constructs a 4 x 4 matrix with specified components.
Matrix4(Matrix4 matrix) Constructs a 4 x 4 matrix with the components of a specified matrix.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o)
boolean	extractEigenvectors(Vec3 result1, Vec3 result2, Vec3 result3) Returns this symmetric matrix's eigenvectors.
Vec3	extractEyePoint(Vec3 result) Returns this viewing matrix's eye point.
Vec3	extractForwardVector(Vec3 result) Returns this viewing matrix's forward vector.
double	extractHeading(double roll) Returns this viewing matrix's heading angle in degrees.
double	extractTilt() Returns this viewing matrix's tilt angle in degrees.
int	hashCode()
Matrix4	invert() Inverts this matrix in place.
Matrix4	invertMatrix(Matrix4 matrix) Inverts the specified matrix and stores the result in this matrix.
Matrix4	invertOrthonormal() Inverts this orthonormal transform matrix in place.
Matrix4	invertOrthonormalMatrix(Matrix4 matrix) Inverts the specified orthonormal transform matrix and stores the result in 'this' matrix.
Matrix4	multiplyByMatrix(double m11, double m12, double m13, double m14, double m21, double m22, double m23, double m24, double m31, double m32, double m33, double m34, double m41, double m42, double m43, double m44) Multiplies this matrix by a matrix specified by individual components.
Matrix4	multiplyByMatrix(Matrix4 matrix) Multiplies this matrix by a specified matrix.
Matrix4	multiplyByRotation(double x, double y, double z, double angleDegrees) Multiplies this matrix by a rotation matrix about a specified axis and angle.
Matrix4	multiplyByScale(double xScale, double yScale, double zScale) Multiplies this matrix by a scale matrix with specified values.
Matrix4	multiplyByTranslation(double x, double y, double z) Multiplies this matrix by a translation matrix with specified translation values.
Matrix4	offsetProjectionDepth(double depthOffset) Applies a specified depth offset to this projection matrix.
boolean	project(double x, double y, double z, Viewport viewport, Vec3 result) Projects a Cartesian point to screen coordinates.
Matrix4	set(double m11, double m12, double m13, double m14, double m21, double m22, double m23, double m24, double m31, double m32, double m33, double m34, double m41, double m42, double m43, double m44) Sets this 4 x 4 matrix to specified components.
Matrix4	set(Matrix4 matrix) Sets this 4 x 4 matrix to the components of a specified matrix.
Matrix4	setRotation(double x, double y, double z, double angleDegrees) Sets the rotation components of this matrix to a specified axis and angle.
Matrix4	setScale(double xScale, double yScale, double zScale) Sets the scale components of this matrix to specified values.
Matrix4	setToCovarianceOfPoints(float[] array, int count, int stride) Sets this matrix to the symmetric covariance Matrix computed from an array of points.
Matrix4	setToIdentity() Sets this matrix to the 4 x 4 identity matrix.
Matrix4	setToInfiniteProjection(double viewportWidth, double viewportHeight, double fovyDegrees, double nearDistance) Sets this matrix to an infinite perspective projection matrix for the specified viewport dimensions, vertical field of view and near clip distance.
Matrix4	setToMultiply(Matrix4 a, Matrix4 b) Sets this matrix to the matrix product of two specified matrices.
Matrix4	setToPerspectiveProjection(double viewportWidth, double viewportHeight, double fovyDegrees, double nearDistance, double farDistance) Sets this matrix to a perspective projection matrix for the specified viewport dimensions, vertical field of view and clip distances.
Matrix4	setToRotation(double x, double y, double z, double angleDegrees) Sets this matrix to a rotation matrix with a specified axis and angle.
Matrix4	setToScale(double xScale, double yScale, double zScale) Sets this matrix to a scale matrix with specified scale components.
Matrix4	setToScreenProjection(double viewportWidth, double viewportHeight) Sets this matrix to a screen projection matrix for the specified viewport dimensions.
Matrix4	setToTranslation(double x, double y, double z) Sets this matrix to a translation matrix with specified translation components.
Matrix4	setTranslation(double x, double y, double z) Sets the translation components of this matrix to specified values.
java.lang.String	toString()
Matrix4	transpose() Transposes this matrix in place.
Matrix4	transposeMatrix(Matrix4 matrix) Sets this matrix to the transpose of a specified matrix.
float[]	transposeToArray(float[] result, int offset) Transposes this matrix, storing the result in the specified single precision array.
boolean	unProject(double x, double y, Viewport viewport, Vec3 nearResult, Vec3 farResult) Un-projects a screen coordinate point to Cartesian coordinates at the near clip plane and the far clip plane.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

m

public final double[] m

The matrix's components, stored in row-major order. Initialized to the 4 x 4 identity matrix.

Constructor Detail

Matrix4

public Matrix4()

Constructs a 4 x 4 identity matrix.

Matrix4

public Matrix4(double m11,
               double m12,
               double m13,
               double m14,
               double m21,
               double m22,
               double m23,
               double m24,
               double m31,
               double m32,
               double m33,
               double m34,
               double m41,
               double m42,
               double m43,
               double m44)

Constructs a 4 x 4 matrix with specified components.

Parameters:

m11 - matrix element at row 1, column 1

m12 - matrix element at row 1, column 2

m13 - matrix element at row 1, column 3

m14 - matrix element at row 1, column 4

m21 - matrix element at row 2, column 1

m22 - matrix element at row 2, column 2

m23 - matrix element at row 2, column 3

m24 - matrix element at row 2, column 4

m31 - matrix element at row 3, column 1

m32 - matrix element at row 3, column 2

m33 - matrix element at row 3, column 3

m34 - matrix element at row 3, column 4

m41 - matrix element at row 4, column 1

m42 - matrix element at row 4, column 2

m43 - matrix element at row 4, column 3

m44 - matrix element at row 4, column 4

Matrix4

public Matrix4(Matrix4 matrix)

Constructs a 4 x 4 matrix with the components of a specified matrix.

Parameters:

matrix - the matrix specifying the new components

Throws:

java.lang.IllegalArgumentException - If the matrix is null

Method Detail

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

set

public Matrix4 set(double m11,
                   double m12,
                   double m13,
                   double m14,
                   double m21,
                   double m22,
                   double m23,
                   double m24,
                   double m31,
                   double m32,
                   double m33,
                   double m34,
                   double m41,
                   double m42,
                   double m43,
                   double m44)

Sets this 4 x 4 matrix to specified components.

Parameters:

m11 - matrix element at row 1, column 1

m12 - matrix element at row 1, column 2

m13 - matrix element at row 1, column 3

m14 - matrix element at row 1, column 4

m21 - matrix element at row 2, column 1

m22 - matrix element at row 2, column 2

m23 - matrix element at row 2, column 3

m24 - matrix element at row 2, column 4

m31 - matrix element at row 3, column 1

m32 - matrix element at row 3, column 2

m33 - matrix element at row 3, column 3

m34 - matrix element at row 3, column 4

m41 - matrix element at row 4, column 1

m42 - matrix element at row 4, column 2

m43 - matrix element at row 4, column 3

m44 - matrix element at row 4, column 4

Returns:

this matrix set to the specified components

set

public Matrix4 set(Matrix4 matrix)

Sets this 4 x 4 matrix to the components of a specified matrix.

Parameters:

matrix - the matrix specifying the new components

Returns:

this matrix with its components set to that of the specified matrix

Throws:

java.lang.IllegalArgumentException - If the matrix is null

setTranslation

public Matrix4 setTranslation(double x,
                              double y,
                              double z)

Sets the translation components of this matrix to specified values.

Parameters:

x - the X translation component

y - the Y translation component

z - the Z translation component

Returns:

this matrix with its translation components set to the specified values and all other components unmodified

setRotation

public Matrix4 setRotation(double x,
                           double y,
                           double z,
                           double angleDegrees)

Sets the rotation components of this matrix to a specified axis and angle. Positive angles are interpreted as counter-clockwise rotation about the axis when viewed when viewed from the positive end of the axis, looking toward the negative end of the axis.

The result of this method is undefined if the axis components are not a unit vector.

Parameters:

x - the X component of the rotation axis unit vector

y - the Y component of the rotation axis unit vector

z - the Z component of the rotation axis unit vector

angleDegrees - the angle of rotation in degrees

Returns:

this matrix with its rotation components set to the specified values and all other components unmodified

setScale

public Matrix4 setScale(double xScale,
                        double yScale,
                        double zScale)

Sets the scale components of this matrix to specified values.

Parameters:

xScale - the X scale component

yScale - the Y scale component

zScale - the Z scale component

Returns:

this matrix with its scale components set to the specified values and all other components unmodified

setToIdentity

public Matrix4 setToIdentity()

Sets this matrix to the 4 x 4 identity matrix.

Returns:

this matrix, set to the identity matrix

setToTranslation

public Matrix4 setToTranslation(double x,
                                double y,
                                double z)

Sets this matrix to a translation matrix with specified translation components.

Parameters:

x - the X translation component

y - the Y translation component

z - the Z translation component

Returns:

this matrix with its translation components set to those specified and all other components set to that of an identity matrix

setToRotation

public Matrix4 setToRotation(double x,
                             double y,
                             double z,
                             double angleDegrees)

Sets this matrix to a rotation matrix with a specified axis and angle. Positive angles are interpreted as counter-clockwise rotation about the axis when viewed when viewed from the positive end of the axis, looking toward the negative end of the axis.

The result of this method is undefined if the axis components are not a unit vector.

Parameters:

x - the X component of the rotation axis unit vector

y - the Y component of the rotation axis unit vector

z - the Z component of the rotation axis unit vector

angleDegrees - the angle of rotation in degrees

Returns:

this matrix with its rotation components set to those specified and all other components set to that of an identity matrix

setToScale

public Matrix4 setToScale(double xScale,
                          double yScale,
                          double zScale)

Sets this matrix to a scale matrix with specified scale components.

Parameters:

xScale - the X scale component

yScale - the Y scale component

zScale - the Z scale component

Returns:

this matrix with its scale components set to those specified and all other components set to that of an identity matrix

setToMultiply

public Matrix4 setToMultiply(Matrix4 a,
                             Matrix4 b)

Sets this matrix to the matrix product of two specified matrices.

Parameters:

a - the first matrix multiplicand

b - The second matrix multiplicand

Returns:

this matrix set to the product of a x b

Throws:

java.lang.IllegalArgumentException - If either matrix is null

setToInfiniteProjection

public Matrix4 setToInfiniteProjection(double viewportWidth,
                                       double viewportHeight,
                                       double fovyDegrees,
                                       double nearDistance)

Sets this matrix to an infinite perspective projection matrix for the specified viewport dimensions, vertical field of view and near clip distance.

An infinite perspective projection matrix maps points in a manner similar to a standard projection matrix, but is not bounded by depth. Objects at any depth greater than or equal to the near distance may be rendered. In addition, this matrix interprets vertices with a w-coordinate of 0 as infinitely far from the camera in the direction indicated by the point's coordinates.

The field of view must be positive and less than 180. The near distance must be positive.

Parameters:

viewportWidth - the viewport width in screen coordinates

viewportHeight - the viewport height in screen coordinates

fovyDegrees - the vertical field of view in degrees

nearDistance - the near clip plane distance in model coordinates

Throws:

java.lang.IllegalArgumentException - If either the width or the height is less than or equal to zero, if the field of view is less than or equal to zero or greater than 180, if the near distance is less than or equal to zero

setToPerspectiveProjection

public Matrix4 setToPerspectiveProjection(double viewportWidth,
                                          double viewportHeight,
                                          double fovyDegrees,
                                          double nearDistance,
                                          double farDistance)

Sets this matrix to a perspective projection matrix for the specified viewport dimensions, vertical field of view and clip distances.

A perspective projection matrix maps points in eye coordinates into clip coordinates in a way that causes distant objects to appear smaller, and preserves the appropriate depth information for each point. In model coordinates, a perspective projection is defined by frustum originating at the eye position and extending outward in the viewer's direction. The near distance and the far distance identify the minimum and maximum distance, respectively, at which an object in the scene is visible.

The field of view must be positive and less than 180. Near and far distances must be positive and must not be equal to one another.

Parameters:

viewportWidth - the viewport width in screen coordinates

viewportHeight - the viewport height in screen coordinates

fovyDegrees - the vertical field of view in degrees

nearDistance - the near clip plane distance in model coordinates

farDistance - the far clip plane distance in model coordinates

Throws:

java.lang.IllegalArgumentException - If either the width or the height is less than or equal to zero, if the field of view is less than or equal to zero or greater than 180, if the near and far distances are equal, or if either the near or far distance are less than or equal to zero

setToScreenProjection

public Matrix4 setToScreenProjection(double viewportWidth,
                                     double viewportHeight)

Sets this matrix to a screen projection matrix for the specified viewport dimensions.

A screen projection matrix is an orthographic projection that interprets points in model coordinates as representing a screen XY and a Z depth. Screen projection matrices therefore map coordinates directly into screen coordinates without modification. A point's XY coordinates are interpreted as literal screen coordinates and must be in the viewport to be visible. A point's Z coordinate is interpreted as a depth value that ranges from 0 to 1. Additionally, the screen projection matrix preserves the depth value returned by RenderContext.project.

Parameters:

viewportWidth - the viewport width in screen coordinates

viewportHeight - the viewport height in screen coordinates

Throws:

java.lang.IllegalArgumentException - If either the width or the height is less than or equal to zero

setToCovarianceOfPoints

public Matrix4 setToCovarianceOfPoints(float[] array,
                                       int count,
                                       int stride)

Sets this matrix to the symmetric covariance Matrix computed from an array of points.

The computed covariance matrix represents the correlation between each pair of x-, y-, and z-coordinates as they're distributed about the point array's arithmetic mean. Its layout is as follows:

C(x, x) C(x, y) C(x, z)
C(x, y) C(y, y) C(y, z)
C(x, z) C(y, z) C(z, z)

C(i, j) is the covariance of coordinates i and j, where i or j are a coordinate's dispersion about its mean value. If any entry is zero, then there's no correlation between the two coordinates defining that entry. If the returned matrix is diagonal, then all three coordinates are uncorrelated, and the specified point is distributed evenly about its mean point.

Parameters:

array - the array of points to consider

count - the number of array elements to consider

stride - the number of coordinates between the first coordinate of adjacent points - must be at least 3

Returns:

this matrix set to the covariance matrix for the specified array of points

Throws:

java.lang.IllegalArgumentException - If the array is null or empty, if the count is less than 0, or if the stride is less than 3

multiplyByTranslation

public Matrix4 multiplyByTranslation(double x,
                                     double y,
                                     double z)

Multiplies this matrix by a translation matrix with specified translation values.

Parameters:

x - the X translation component

y - the Y translation component

z - the Z translation component

Returns:

this matrix multiplied by the translation matrix implied by the specified values

multiplyByRotation

public Matrix4 multiplyByRotation(double x,
                                  double y,
                                  double z,
                                  double angleDegrees)

Multiplies this matrix by a rotation matrix about a specified axis and angle. Positive angles are interpreted as counter-clockwise rotation about the axis.

Parameters:

x - the X component of the rotation axis

y - the Y component of the rotation axis

z - the Z component of the rotation axis

angleDegrees - the angle of rotation in degrees

Returns:

this matrix multiplied by the rotation matrix implied by the specified values

multiplyByScale

public Matrix4 multiplyByScale(double xScale,
                               double yScale,
                               double zScale)

Multiplies this matrix by a scale matrix with specified values.

Parameters:

xScale - the X scale component

yScale - the Y scale component

zScale - the Z scale component

Returns:

this matrix multiplied by the scale matrix implied by the specified values

multiplyByMatrix

public Matrix4 multiplyByMatrix(Matrix4 matrix)

Multiplies this matrix by a specified matrix.

Parameters:

matrix - the matrix to multiply with this matrix

Returns:

this matrix after multiplying it by the specified matrix

Throws:

java.lang.IllegalArgumentException - If the matrix is null

multiplyByMatrix

public Matrix4 multiplyByMatrix(double m11,
                                double m12,
                                double m13,
                                double m14,
                                double m21,
                                double m22,
                                double m23,
                                double m24,
                                double m31,
                                double m32,
                                double m33,
                                double m34,
                                double m41,
                                double m42,
                                double m43,
                                double m44)

Multiplies this matrix by a matrix specified by individual components.

Parameters:

m11 - matrix element at row 1, column 1

m12 - matrix element at row 1, column 2

m13 - matrix element at row 1, column 3

m14 - matrix element at row 1, column 4

m21 - matrix element at row 2, column 1

m22 - matrix element at row 2, column 2

m23 - matrix element at row 2, column 3

m24 - matrix element at row 2, column 4

m31 - matrix element at row 3, column 1

m32 - matrix element at row 3, column 2

m33 - matrix element at row 3, column 3

m34 - matrix element at row 3, column 4

m41 - matrix element at row 4, column 1

m42 - matrix element at row 4, column 2

m43 - matrix element at row 4, column 3

m44 - matrix element at row 4, column 4

Returns:

this matrix with its components multiplied by the specified values

transpose

public Matrix4 transpose()

Transposes this matrix in place.

Returns:

this matrix, transposed.

transposeMatrix

public Matrix4 transposeMatrix(Matrix4 matrix)

Sets this matrix to the transpose of a specified matrix.

Parameters:

matrix - the matrix whose transpose is to be computed

Returns:

this matrix with its values set to the transpose of the specified matrix

Throws:

java.lang.IllegalArgumentException - If the matrix in null

transposeToArray

public float[] transposeToArray(float[] result,
                                int offset)

Transposes this matrix, storing the result in the specified single precision array. The result is compatible with GLSL uniform matrices, and can be passed to the function glUniformMatrix4fv.

Parameters:

result - a pre-allocated array of length 16 in which to return the transposed components

Returns:

the result argument set to the transponsed components

invert

public Matrix4 invert()

Inverts this matrix in place.

This throws an exception if this matrix is singular.

Returns:

this matrix, inverted

Throws:

java.lang.IllegalArgumentException - If this matrix cannot be inverted

invertMatrix

public Matrix4 invertMatrix(Matrix4 matrix)

Inverts the specified matrix and stores the result in this matrix.

This throws an exception if the specified matrix is singular.

The result of this method is undefined if this matrix is passed in as the matrix to invert.

Parameters:

matrix - the matrix whose inverse is computed

Returns:

this matrix set to the inverse of the specified matrix

Throws:

java.lang.IllegalArgumentException - If the matrix is null or cannot be inverted

invertOrthonormal

public Matrix4 invertOrthonormal()

Inverts this orthonormal transform matrix in place. This matrix's upper 3x3 is transposed, then its fourth column is transformed by the transposed upper 3x3 and negated.

The result of this method is undefined if this matrix's values are not consistent with those of an orthonormal transform.

Returns:

this matrix, inverted

invertOrthonormalMatrix

public Matrix4 invertOrthonormalMatrix(Matrix4 matrix)

Inverts the specified orthonormal transform matrix and stores the result in 'this' matrix. The specified matrix's upper 3x3 is transposed, then its fourth column is transformed by the transposed upper 3x3 and negated. The result is stored in 'this' matrix.

The result of this method is undefined if this matrix is passed in as the matrix to invert, or if the matrix's values are not consistent with those of an orthonormal transform.

Parameters:

matrix - the matrix whose inverse is computed. The matrix is assumed to represent an orthonormal transform matrix.

Returns:

this matrix set to the inverse of the specified matrix

Throws:

java.lang.IllegalArgumentException - If the matrix is null

offsetProjectionDepth

public Matrix4 offsetProjectionDepth(double depthOffset)

Applies a specified depth offset to this projection matrix. The depth offset may be any real number and is typically used to draw geometry slightly closer to the user's eye in order to give those shapes visual priority over nearby or geometry. An offset of zero has no effect. An offset less than zero brings depth values closer to the eye, while an offset greater than zero pushes depth values away from the eye.

The result of this method is undefined if this matrix is not a projection matrix. Projection matrices can be created by calling setToPerspectiveProjection or setToScreenProjection

Depth offset may be applied to both perspective and screen projection matrices. The effect on each type is outlined here:

Perspective Projection

The effect of depth offset on a perspective projection increases exponentially with distance from the eye. This has the effect of adjusting the offset for the loss in depth precision with geometry drawn further from the eye. Distant geometry requires a greater offset to differentiate itself from nearby geometry, while close geometry does not.

Screen Projection

The effect of depth offset on an screen projection increases linearly with distance from the eye. While it is reasonable to apply a depth offset to an screen projection, the effect is most appropriate when applied to the projection used to draw the scene. For example, when an object's coordinates are projected by a perspective projection into screen coordinates then drawn using a screen projection, it is best to apply the offset to the original perspective projection. The method RenderContext.project performs the correct behavior for the projection type used to draw the scene.

Parameters:

depthOffset - the amount of offset to apply

Returns:

this matrix with its components adjusted to account for the specified depth offset

extractEyePoint

public Vec3 extractEyePoint(Vec3 result)

Returns this viewing matrix's eye point. In model coordinates, a viewing matrix's eye point is the point the viewer is looking from and maps to the center of the screen.

The result of this method is undefined if this matrix is not a viewing matrix.

Parameters:

result - a pre-allocated Vec3 in which to return the extracted value

Returns:

the specified result argument containing the viewing matrix's eye point

Throws:

java.lang.IllegalArgumentException - If the result argument is null

extractForwardVector

public Vec3 extractForwardVector(Vec3 result)

Returns this viewing matrix's forward vector.

The result of this method is undefined if this matrix is not a viewing matrix.

Parameters:

result - a pre-allocated Vec3 in which to return the extracted value

Returns:

the specified result argument containing the viewing matrix's forward vector

Throws:

java.lang.IllegalArgumentException - If the result argument is null

extractHeading

public double extractHeading(double roll)

Returns this viewing matrix's heading angle in degrees. The roll argument enables the caller to disambiguate heading and roll when the two rotation axes for heading and roll are parallel, causing gimbal lock.

The result of this method is undefined if this matrix is not a viewing matrix.

Parameters:

roll - the viewing matrix's roll angle in degrees, or 0 if the roll angle is unknown

Returns:

the extracted heading angle in degrees

extractTilt

public double extractTilt()

Returns this viewing matrix's tilt angle in degrees.

The result of this method is undefined if this matrix is not a viewing matrix.

Returns:

the extracted heading angle in degrees

extractEigenvectors

public boolean extractEigenvectors(Vec3 result1,
                                   Vec3 result2,
                                   Vec3 result3)

Returns this symmetric matrix's eigenvectors. The eigenvectors are returned in the specified result arguments in order of descending magnitude (most prominent to least prominent). Each eigenvector has length equal to its corresponding eigenvalue.

This method returns false if this matrix is not a symmetric matrix.

Parameters:

result1 - a pre-allocated Vec3 in which to return the most prominent eigenvector

result2 - a pre-allocated Vec3 in which to return the second most prominent eigenvector

result3 - a pre-allocated Vec3 in which to return the least prominent eigenvector

Returns:

true if this matrix is symmetric and its eigenvectors can be determined, otherwise false

Throws:

java.lang.IllegalArgumentException - If any argument is null or if this matrix is not symmetric

project

public boolean project(double x,
                       double y,
                       double z,
                       Viewport viewport,
                       Vec3 result)

Projects a Cartesian point to screen coordinates. This method assumes this matrix represents an inverse modelview-projection matrix. The result of this method is undefined if this matrix is not an inverse modelview-projection matrix.

The resultant screen point is in OpenGL screen coordinates, with the origin in the bottom-left corner and axes that extend up and to the right from the origin.

This stores the projected point in the result argument, and returns a boolean value indicating whether or not the projection is successful. This returns false if the Cartesian point is clipped by the near clipping plane or the far clipping plane.

Parameters:

x - the Cartesian point's X component

y - the Cartesian point's y component

z - the Cartesian point's z component

viewport - the viewport defining the screen point's coordinate system

result - a pre-allocated Vec3 in which to return the projected point

Returns:

true if the transformation is successful, otherwise false

Throws:

java.lang.IllegalArgumentException - If any argument is null

unProject

public boolean unProject(double x,
                         double y,
                         Viewport viewport,
                         Vec3 nearResult,
                         Vec3 farResult)

Un-projects a screen coordinate point to Cartesian coordinates at the near clip plane and the far clip plane. This method assumes this matrix represents an inverse modelview-projection matrix. The result of this method is undefined if this matrix is not an inverse modelview-projection matrix.

The screen point is understood to be in OpenGL screen coordinates, with the origin in the bottom-left corner and axes that extend up and to the right from the origin.

This function stores the un-projected points in the result argument, and a boolean value indicating whether the un-projection is successful.

Parameters:

x - the screen point's X component

y - the screen point's Y component

viewport - the viewport defining the screen point's coordinate system

nearResult - a pre-allocated Vec3 in which to return the un-projected near clip plane point

farResult - a pre-allocated Vec3 in which to return the un-projected far clip plane point

Returns:

true if the transformation is successful, otherwise false

Throws:

java.lang.IllegalArgumentException - If any argument is null