com.jogamp.opengl.util
Class PMVMatrix

java.lang.Object
  extended by com.jogamp.opengl.util.PMVMatrix
All Implemented Interfaces:
GLMatrixFunc

public class PMVMatrix
extends Object
implements GLMatrixFunc

PMVMatrix implements a subset of the fixed function pipeline regarding the projection (P), modelview (Mv) matrix operation which is specified in GLMatrixFunc.

Further more, PMVMatrix provides the inverse modelview matrix (Mvi) and inverse transposed modelview matrix (Mvit). Frustum is also provided by glGetFrustum(). To keep these derived values synchronized after mutable Mv operations like glRotatef(..) in glMatrixMode(GL_MODELVIEW), users have to call update() before using Mvi and Mvit.

All matrices are provided in column-major order, as specified in the OpenGL fixed function pipeline, i.e. compatibility profile.

PMVMatrix can supplement GL2ES2 applications w/ the lack of the described matrix functionality.

Matrix storage details

All matrices use a common FloatBuffer storage and are a sliced representation of it. The common FloatBuffer and hence all matrices may use NIO direct storage or a backing float array, depending how the instance if being constructed.

Note:


Field Summary
static int DIRTY_ALL
          Bit value stating all is dirty
static int DIRTY_FRUSTUM
          Bit value stating a dirty frustum.
static int DIRTY_INVERSE_MODELVIEW
          Bit value stating a dirty inverse modelview matrix (Mvi).
static int DIRTY_INVERSE_TRANSPOSED_MODELVIEW
          Bit value stating a dirty inverse transposed modelview matrix (Mvit).
static int MODIFIED_ALL
          Bit value stating all is modified
static int MODIFIED_MODELVIEW
          Bit value stating a modified modelview matrix (Mv), since last update() call.
static int MODIFIED_PROJECTION
          Bit value stating a modified projection matrix (P), since last update() call.
static int MODIFIED_TEXTURE
          Bit value stating a modified texture matrix (T), since last update() call.
 
Fields inherited from interface javax.media.opengl.fixedfunc.GLMatrixFunc
GL_MATRIX_MODE, GL_MODELVIEW, GL_MODELVIEW_MATRIX, GL_PROJECTION, GL_PROJECTION_MATRIX, GL_TEXTURE_MATRIX
 
Constructor Summary
PMVMatrix()
          Creates an instance of PMVMatrix PMVMatrix(boolean useBackingArray), with useBackingArray = true.
PMVMatrix(boolean useBackingArray)
          Creates an instance of PMVMatrix.
 
Method Summary
 void clearAllUpdateRequests()
          Clears all update() requests of the Mvi and Mvit matrix and Frustum after it has been enabled by one of the Mvi get, Mvit get or Frustum get methods.
 void destroy()
           
 int getDirtyBits()
          Deprecated. Function is exposed for debugging purposes only.
 int getModifiedBits(boolean clear)
          Returns the modified bits due to mutable operations..
 int getRequestMask()
          Deprecated. Function is exposed for debugging purposes only.
 void glFrustumf(float left, float right, float bottom, float top, float zNear, float zFar)
          Multiply the current matrix with the frustum matrix.
 void glGetFloatv(int matrixGetName, float[] params, int params_offset)
          Copy the named matrix to the given storage at offset.
 void glGetFloatv(int matrixGetName, FloatBuffer params)
          Copy the named matrix into the given storage.
 Frustum glGetFrustum()
          Returns the frustum, derived from projection * modelview
 void glGetIntegerv(int pname, int[] params, int params_offset)
           
 void glGetIntegerv(int pname, IntBuffer params)
          glGetIntegerv
 FloatBuffer glGetMatrixf()
           
 FloatBuffer glGetMatrixf(int matrixName)
           
 int glGetMatrixMode()
          Returns the current matrix-mode, one of GL_MODELVIEW, GL_PROJECTION or GL_TEXTURE.
 FloatBuffer glGetMviMatrixf()
          Returns the inverse modelview matrix (Mvi).
 FloatBuffer glGetMvitMatrixf()
          Returns the inverse transposed modelview matrix (Mvit).
 FloatBuffer glGetMvMatrixf()
          Returns the modelview matrix (Mv).
 FloatBuffer glGetPMatrixf()
          Returns the projection matrix (P).
 FloatBuffer glGetPMvMatrixf()
          Returns 2 matrices within one FloatBuffer: P and Mv.
 FloatBuffer glGetPMvMviMatrixf()
          Returns 3 matrices within one FloatBuffer: P, Mv and Mvi.
 FloatBuffer glGetPMvMvitMatrixf()
          Returns 4 matrices within one FloatBuffer: P, Mv, Mvi and Mvit.
 FloatBuffer glGetTMatrixf()
          Returns the texture matrix (T).
 void glLoadIdentity()
          Load the current matrix with the identity matrix
 void glLoadMatrixf(float[] values, int offset)
          Load the current matrix w/ the provided one.
 void glLoadMatrixf(FloatBuffer m)
          Load the current matrix w/ the provided one.
 void glMatrixMode(int matrixName)
          Sets the current matrix mode.
 void glMultMatrixf(float[] m, int m_offset)
          Multiply the current matrix
 void glMultMatrixf(FloatBuffer m)
          Multiply the current matrix
 void glOrthof(float left, float right, float bottom, float top, float zNear, float zFar)
          Multiply the current matrix with the orthogonal matrix.
 void glPopMatrix()
          Pop the current matrix from it's stack.
 void glPushMatrix()
          Push the current matrix to it's stack, while preserving it's values.
 void glRotatef(float angdeg, float x, float y, float z)
          Rotate the current matrix.
 void glScalef(float x, float y, float z)
          Scale the current matrix.
 void glTranslatef(float x, float y, float z)
          Translate the current matrix.
 void gluLookAt(float eyex, float eyey, float eyez, float centerx, float centery, float centerz, float upx, float upy, float upz)
          Multiply and translate the current matrix with the eye, object and orientation.
 void gluPerspective(float fovy, float aspect, float zNear, float zFar)
          Multiply the current matrix with the perspective/frustum matrix.
 void gluPickMatrix(float x, float y, float deltaX, float deltaY, int[] viewport, int viewport_offset)
           
 boolean gluProject(float objx, float objy, float objz, int[] viewport, int viewport_offset, float[] win_pos, int win_pos_offset)
          Map object coordinates to window coordinates.
 boolean gluUnProject(float winx, float winy, float winz, int[] viewport, int viewport_offset, float[] obj_pos, int obj_pos_offset)
          Map window coordinates to object coordinates.
static boolean isMatrixGetName(int matrixGetName)
           
static boolean isMatrixModeName(int matrixModeName)
           
static int matrixGetName2MatrixModeName(int matrixGetName)
           
static int matrixModeName2MatrixGetName(int matrixModeName)
           
static StringBuilder matrixToString(StringBuilder sb, String f, FloatBuffer a)
           
static StringBuilder matrixToString(StringBuilder sb, String f, FloatBuffer a, FloatBuffer b)
           
 String toString()
           
 StringBuilder toString(StringBuilder sb, String f)
           
 boolean update()
          Update the derived inverse modelview (Mvi), inverse transposed modelview (Mvit) matrices and Frustum if they are dirty and they were requested by one of the Mvi get, Mvit get or Frustum get methods.
 boolean usesBackingArray()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MODIFIED_PROJECTION

public static final int MODIFIED_PROJECTION
Bit value stating a modified projection matrix (P), since last update() call.

See Also:
Constant Field Values

MODIFIED_MODELVIEW

public static final int MODIFIED_MODELVIEW
Bit value stating a modified modelview matrix (Mv), since last update() call.

See Also:
Constant Field Values

MODIFIED_TEXTURE

public static final int MODIFIED_TEXTURE
Bit value stating a modified texture matrix (T), since last update() call.

See Also:
Constant Field Values

MODIFIED_ALL

public static final int MODIFIED_ALL
Bit value stating all is modified

See Also:
Constant Field Values

DIRTY_INVERSE_MODELVIEW

public static final int DIRTY_INVERSE_MODELVIEW
Bit value stating a dirty inverse modelview matrix (Mvi).

See Also:
Constant Field Values

DIRTY_INVERSE_TRANSPOSED_MODELVIEW

public static final int DIRTY_INVERSE_TRANSPOSED_MODELVIEW
Bit value stating a dirty inverse transposed modelview matrix (Mvit).

See Also:
Constant Field Values

DIRTY_FRUSTUM

public static final int DIRTY_FRUSTUM
Bit value stating a dirty frustum.

See Also:
Constant Field Values

DIRTY_ALL

public static final int DIRTY_ALL
Bit value stating all is dirty

See Also:
Constant Field Values
Constructor Detail

PMVMatrix

public PMVMatrix()
Creates an instance of PMVMatrix PMVMatrix(boolean useBackingArray), with useBackingArray = true.


PMVMatrix

public PMVMatrix(boolean useBackingArray)
Creates an instance of PMVMatrix.

Parameters:
useBackingArray - true for non direct NIO Buffers with guaranteed backing array, which allows faster access in Java computation.

false for direct NIO buffers w/o a guaranteed backing array. In most Java implementations, direct NIO buffers have no backing array and hence the Java computation will be throttled down by direct IO get/put operations.

Depending on the application, ie. whether the Java computation or JNI invocation and hence native data transfer part is heavier, this flag shall be set to true or false

.
Method Detail

isMatrixModeName

public static final boolean isMatrixModeName(int matrixModeName)
Parameters:
matrixModeName - One of GL_MODELVIEW, GL_PROJECTION or GL_TEXTURE
Returns:
true if the given matrix-mode name is valid, otherwise false.

matrixModeName2MatrixGetName

public static final int matrixModeName2MatrixGetName(int matrixModeName)
Parameters:
matrixModeName - One of GL_MODELVIEW, GL_PROJECTION or GL_TEXTURE
Returns:
The corresponding matrix-get name, one of GL_MODELVIEW_MATRIX, GL_PROJECTION_MATRIX or GL_TEXTURE_MATRIX

isMatrixGetName

public static final boolean isMatrixGetName(int matrixGetName)
Parameters:
matrixGetName - One of GL_MODELVIEW_MATRIX, GL_PROJECTION_MATRIX or GL_TEXTURE_MATRIX
Returns:
true if the given matrix-get name is valid, otherwise false.

matrixGetName2MatrixModeName

public static final int matrixGetName2MatrixModeName(int matrixGetName)
Parameters:
matrixGetName - One of GL_MODELVIEW_MATRIX, GL_PROJECTION_MATRIX or GL_TEXTURE_MATRIX
Returns:
The corresponding matrix-mode name, one of GL_MODELVIEW, GL_PROJECTION or GL_TEXTURE

matrixToString

public static StringBuilder matrixToString(StringBuilder sb,
                                           String f,
                                           FloatBuffer a)
Parameters:
sb - optional passed StringBuilder instance to be used
f - the format string of one floating point, i.e. "%10.5f", see Formatter
a - 4x4 matrix in column major order (OpenGL)
Returns:
matrix string representation

matrixToString

public static StringBuilder matrixToString(StringBuilder sb,
                                           String f,
                                           FloatBuffer a,
                                           FloatBuffer b)
Parameters:
sb - optional passed StringBuilder instance to be used
f - the format string of one floating point, i.e. "%10.5f", see Formatter
a - 4x4 matrix in column major order (OpenGL)
b - 4x4 matrix in column major order (OpenGL)
Returns:
side by side representation

usesBackingArray

public final boolean usesBackingArray()
See Also:
PMVMatrix(boolean)

destroy

public final void destroy()

glGetMatrixMode

public final int glGetMatrixMode()
Returns the current matrix-mode, one of GL_MODELVIEW, GL_PROJECTION or GL_TEXTURE.


glGetTMatrixf

public final FloatBuffer glGetTMatrixf()
Returns the texture matrix (T).

See matrix storage details.


glGetPMatrixf

public final FloatBuffer glGetPMatrixf()
Returns the projection matrix (P).

See matrix storage details.


glGetMvMatrixf

public final FloatBuffer glGetMvMatrixf()
Returns the modelview matrix (Mv).

See matrix storage details.


glGetMviMatrixf

public final FloatBuffer glGetMviMatrixf()
Returns the inverse modelview matrix (Mvi).

Method enables the Mvi matrix update, and performs it's update w/o clearing the modified bits.

See update() and matrix storage details.

See Also:
update(), clearAllUpdateRequests()

glGetMvitMatrixf

public final FloatBuffer glGetMvitMatrixf()
Returns the inverse transposed modelview matrix (Mvit).

Method enables the Mvit matrix update, and performs it's update w/o clearing the modified bits.

See update() and matrix storage details.

See Also:
update(), clearAllUpdateRequests()

glGetPMvMatrixf

public final FloatBuffer glGetPMvMatrixf()
Returns 2 matrices within one FloatBuffer: P and Mv.

See matrix storage details.


glGetPMvMviMatrixf

public final FloatBuffer glGetPMvMviMatrixf()
Returns 3 matrices within one FloatBuffer: P, Mv and Mvi.

Method enables the Mvi matrix update, and performs it's update w/o clearing the modified bits.

See update() and matrix storage details.

See Also:
update(), clearAllUpdateRequests()

glGetPMvMvitMatrixf

public final FloatBuffer glGetPMvMvitMatrixf()
Returns 4 matrices within one FloatBuffer: P, Mv, Mvi and Mvit.

Method enables the Mvi and Mvit matrix update, and performs it's update w/o clearing the modified bits.

See update() and matrix storage details.

See Also:
update(), clearAllUpdateRequests()

glGetFrustum

public Frustum glGetFrustum()
Returns the frustum, derived from projection * modelview


glGetMatrixf

public final FloatBuffer glGetMatrixf()

glGetMatrixf

public final FloatBuffer glGetMatrixf(int matrixName)
Parameters:
matrixName - Either a matrix-get-name, i.e. GL_MODELVIEW_MATRIX, GL_PROJECTION_MATRIX or GL_TEXTURE_MATRIX, or a matrix-mode-name, i.e. GL_MODELVIEW, GL_PROJECTION or GL_TEXTURE
Returns:
the named matrix

glMatrixMode

public final void glMatrixMode(int matrixName)
Description copied from interface: GLMatrixFunc
Sets the current matrix mode.

Specified by:
glMatrixMode in interface GLMatrixFunc
Parameters:
matrixName - GLMatrixFunc.GL_MODELVIEW, GLMatrixFunc.GL_PROJECTION or GL_TEXTURE.

glGetFloatv

public final void glGetFloatv(int matrixGetName,
                              FloatBuffer params)
Description copied from interface: GLMatrixFunc
Copy the named matrix into the given storage.

Specified by:
glGetFloatv in interface GLMatrixFunc
Parameters:
matrixGetName - GLMatrixFunc.GL_MODELVIEW_MATRIX, GLMatrixFunc.GL_PROJECTION_MATRIX or GLMatrixFunc.GL_TEXTURE_MATRIX
params - the FloatBuffer's position remains unchanged, which is the same behavior than the native JOGL GL impl

glGetFloatv

public final void glGetFloatv(int matrixGetName,
                              float[] params,
                              int params_offset)
Description copied from interface: GLMatrixFunc
Copy the named matrix to the given storage at offset.

Specified by:
glGetFloatv in interface GLMatrixFunc
Parameters:
matrixGetName - GLMatrixFunc.GL_MODELVIEW_MATRIX, GLMatrixFunc.GL_PROJECTION_MATRIX or GLMatrixFunc.GL_TEXTURE_MATRIX
params - storage
params_offset - storage offset

glGetIntegerv

public final void glGetIntegerv(int pname,
                                IntBuffer params)
Description copied from interface: GLMatrixFunc
glGetIntegerv

Specified by:
glGetIntegerv in interface GLMatrixFunc
Parameters:
pname - GLMatrixFunc.GL_MATRIX_MODE to receive the current matrix mode
params - the FloatBuffer's position remains unchanged which is the same behavior than the native JOGL GL impl

glGetIntegerv

public final void glGetIntegerv(int pname,
                                int[] params,
                                int params_offset)
Specified by:
glGetIntegerv in interface GLMatrixFunc

glLoadMatrixf

public final void glLoadMatrixf(float[] values,
                                int offset)
Description copied from interface: GLMatrixFunc
Load the current matrix w/ the provided one.

Specified by:
glLoadMatrixf in interface GLMatrixFunc

glLoadMatrixf

public final void glLoadMatrixf(FloatBuffer m)
Description copied from interface: GLMatrixFunc
Load the current matrix w/ the provided one.

Specified by:
glLoadMatrixf in interface GLMatrixFunc

glPopMatrix

public final void glPopMatrix()
Description copied from interface: GLMatrixFunc
Pop the current matrix from it's stack.

Specified by:
glPopMatrix in interface GLMatrixFunc
See Also:
GLMatrixFunc.glPushMatrix()

glPushMatrix

public final void glPushMatrix()
Description copied from interface: GLMatrixFunc
Push the current matrix to it's stack, while preserving it's values.

There exist one stack per matrix mode, i.e. GLMatrixFunc.GL_MODELVIEW, GLMatrixFunc.GL_PROJECTION and GL_TEXTURE.

Specified by:
glPushMatrix in interface GLMatrixFunc

glLoadIdentity

public final void glLoadIdentity()
Description copied from interface: GLMatrixFunc
Load the current matrix with the identity matrix

Specified by:
glLoadIdentity in interface GLMatrixFunc

glMultMatrixf

public final void glMultMatrixf(FloatBuffer m)
Description copied from interface: GLMatrixFunc
Multiply the current matrix

Specified by:
glMultMatrixf in interface GLMatrixFunc
Parameters:
m - the FloatBuffer's position remains unchanged, which is the same behavior than the native JOGL GL impl

glMultMatrixf

public final void glMultMatrixf(float[] m,
                                int m_offset)
Description copied from interface: GLMatrixFunc
Multiply the current matrix

Specified by:
glMultMatrixf in interface GLMatrixFunc

glTranslatef

public final void glTranslatef(float x,
                               float y,
                               float z)
Description copied from interface: GLMatrixFunc
Translate the current matrix.

Specified by:
glTranslatef in interface GLMatrixFunc

glRotatef

public final void glRotatef(float angdeg,
                            float x,
                            float y,
                            float z)
Description copied from interface: GLMatrixFunc
Rotate the current matrix.

Specified by:
glRotatef in interface GLMatrixFunc

glScalef

public final void glScalef(float x,
                           float y,
                           float z)
Description copied from interface: GLMatrixFunc
Scale the current matrix.

Specified by:
glScalef in interface GLMatrixFunc

glOrthof

public final void glOrthof(float left,
                           float right,
                           float bottom,
                           float top,
                           float zNear,
                           float zFar)
Description copied from interface: GLMatrixFunc
Multiply the current matrix with the orthogonal matrix.

Specified by:
glOrthof in interface GLMatrixFunc

glFrustumf

public final void glFrustumf(float left,
                             float right,
                             float bottom,
                             float top,
                             float zNear,
                             float zFar)
Description copied from interface: GLMatrixFunc
Multiply the current matrix with the frustum matrix.

Specified by:
glFrustumf in interface GLMatrixFunc

gluPerspective

public final void gluPerspective(float fovy,
                                 float aspect,
                                 float zNear,
                                 float zFar)
Multiply the current matrix with the perspective/frustum matrix.


gluLookAt

public final void gluLookAt(float eyex,
                            float eyey,
                            float eyez,
                            float centerx,
                            float centery,
                            float centerz,
                            float upx,
                            float upy,
                            float upz)
Multiply and translate the current matrix with the eye, object and orientation.


gluProject

public final boolean gluProject(float objx,
                                float objy,
                                float objz,
                                int[] viewport,
                                int viewport_offset,
                                float[] win_pos,
                                int win_pos_offset)
Map object coordinates to window coordinates.

Parameters:
objx -
objy -
objz -
viewport -
viewport_offset -
win_pos -
win_pos_offset -
Returns:

gluUnProject

public final boolean gluUnProject(float winx,
                                  float winy,
                                  float winz,
                                  int[] viewport,
                                  int viewport_offset,
                                  float[] obj_pos,
                                  int obj_pos_offset)
Map window coordinates to object coordinates.

Parameters:
winx -
winy -
winz -
viewport -
viewport_offset -
obj_pos -
obj_pos_offset -
Returns:

gluPickMatrix

public final void gluPickMatrix(float x,
                                float y,
                                float deltaX,
                                float deltaY,
                                int[] viewport,
                                int viewport_offset)

toString

public StringBuilder toString(StringBuilder sb,
                              String f)

toString

public String toString()
Overrides:
toString in class Object

getModifiedBits

public final int getModifiedBits(boolean clear)
Returns the modified bits due to mutable operations..

A modified bit is set, if the corresponding matrix had been modified by a mutable operation since last update() or getModifiedBits(true) call.

Parameters:
clear - if true, clears the modified bits, otherwise leaves them untouched.
See Also:
MODIFIED_PROJECTION, MODIFIED_MODELVIEW, MODIFIED_TEXTURE

getDirtyBits

public final int getDirtyBits()
Deprecated. Function is exposed for debugging purposes only.

Returns the dirty bits due to mutable operations.

A dirty bit is set , if the corresponding matrix had been modified by a mutable operation since last update() call. The latter clears the dirty state only if the dirty matrix (Mvi or Mvit) or Frustum has been requested by one of the Mvi get, Mvit get or Frustum get methods.

See Also:
DIRTY_INVERSE_MODELVIEW, DIRTY_INVERSE_TRANSPOSED_MODELVIEW, DIRTY_FRUSTUM, glGetMviMatrixf(), glGetMvitMatrixf(), glGetPMvMviMatrixf(), glGetPMvMvitMatrixf(), glGetFrustum()

getRequestMask

public final int getRequestMask()
Deprecated. Function is exposed for debugging purposes only.

Returns the request bit mask, which uses bit values equal to the dirty mask.

The request bit mask is set by one of the Mvi get, Mvit get or Frustum get methods.

See Also:
clearAllUpdateRequests(), DIRTY_INVERSE_MODELVIEW, DIRTY_INVERSE_TRANSPOSED_MODELVIEW, DIRTY_FRUSTUM, glGetMviMatrixf(), glGetMvitMatrixf(), glGetPMvMviMatrixf(), glGetPMvMvitMatrixf(), glGetFrustum()

clearAllUpdateRequests

public final void clearAllUpdateRequests()
Clears all update() requests of the Mvi and Mvit matrix and Frustum after it has been enabled by one of the Mvi get, Mvit get or Frustum get methods.

Allows user to disable subsequent Mvi, Mvit and Frustum updates if no more required.

See Also:
glGetMviMatrixf(), glGetMvitMatrixf(), glGetPMvMviMatrixf(), glGetPMvMvitMatrixf(), glGetFrustum(), getRequestMask()

update

public final boolean update()
Update the derived inverse modelview (Mvi), inverse transposed modelview (Mvit) matrices and Frustum if they are dirty and they were requested by one of the Mvi get, Mvit get or Frustum get methods.

The Mvi and Mvit matrices and Frustum are considered dirty, if their corresponding Mv matrix has been modified since their last update.

Method should be called manually in case mutable operations has been called and caller operates on already fetched references, i.e. not calling Mvi get, Mvit get or Frustum get etc anymore.

This method clears the modified bits like getModifiedBits(true), which are set by any mutable operation. The modified bits have no impact on this method, but the return value.

Returns:
true if any matrix has been modified since last update call or if the derived matrices Mvi and Mvit or Frustum were updated, otherwise false. In other words, method returns true if any matrix used by the caller must be updated, e.g. uniforms in a shader program.
See Also:
getModifiedBits(boolean), MODIFIED_PROJECTION, MODIFIED_MODELVIEW, MODIFIED_TEXTURE, DIRTY_INVERSE_MODELVIEW, DIRTY_INVERSE_TRANSPOSED_MODELVIEW, DIRTY_FRUSTUM, glGetMviMatrixf(), glGetMvitMatrixf(), glGetPMvMviMatrixf(), glGetPMvMvitMatrixf(), glGetFrustum(), clearAllUpdateRequests()


Copyright 2010 JogAmp Community.