com.jogamp.opengl.util

Class PMVMatrix

java.lang.Object

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:

• The matrix is a sliced part of a host matrix and it's start position has been marked.
• Use reset() to rewind it to it's start position after relative operations, like get().
• If using absolute operations like get(int), use it's reset position as it's offset.

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
PMVMatrix() Creates an instance of PMVMatrix PMVMatrix(boolean useBackingArray), with useBackingArray = true.
PMVMatrix(boolean useBackingArray) Creates an instance of PMVMatrix.

Method Summary

Methods

Modifier and Type	Method and Description
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()