Update PMVMatrix/GLMatrixFunc API doc and refine PMVMatrix update / get-Mvi/Mvit-Matrix operation. (Minor API change)

Using bitmask for requested Mvi and Mvit matrices,
same as dirty-bits to ease matching and update operation.

Update of Mvi and Mvit will be performed only if it's dirty-bit and request-bit set within update().
The individual dirty bit is cleared only if it's matrix update is performed.

Update is also issued at get-Mvi/Mvit-Matrix operations
to ensure proper values w/o update call w/o clearing the modified-bits.

update() returns true if the Mvi or Mvit matrix got updated
_or_ one of the modified bits is set. update() clears the modified-bits.

Adding explicit getModifiedBits() to get and clear it's state.

Adding unit test.

Lots of API docs ..

1 files changed, 114 insertions, 61 deletions

diff --git a/src/jogl/classes/javax/media/opengl/fixedfunc/GLMatrixFunc.java b/src/jogl/classes/javax/media/opengl/fixedfunc/GLMatrixFunc.java
index a34d490c0..9fee0a2e2 100644
--- a/src/jogl/classes/javax/media/opengl/fixedfunc/GLMatrixFunc.java
+++ b/src/jogl/classes/javax/media/opengl/fixedfunc/GLMatrixFunc.java
@@ -31,69 +31,122 @@ package javax.media.opengl.fixedfunc;
 
 import java.nio.*;
 
+import javax.media.opengl.GL;
+
+/**
+ * Subset of OpenGL fixed function pipeline's matrix operations.
+ */
 public interface GLMatrixFunc {
 
-  public static final int GL_MATRIX_MODE = 0x0BA0;
-  public static final int GL_MODELVIEW = 0x1700;
-  public static final int GL_PROJECTION = 0x1701;
-  // public static final int GL_TEXTURE = 0x1702; // Use GL.GL_TEXTURE due to ambiguous GL usage
-  public static final int GL_MODELVIEW_MATRIX = 0x0BA6;
-  public static final int GL_PROJECTION_MATRIX = 0x0BA7;
-  public static final int GL_TEXTURE_MATRIX = 0x0BA8;
-
-  /**
-   * glGetFloatv
-   * @param pname GL_MODELVIEW_MATRIX, GL_PROJECTION_MATRIX or GL_TEXTURE_MATRIX
-   * @param params the FloatBuffer's position remains unchanged,
-   *        which is the same behavior than the native JOGL GL impl
-   */
-  public void glGetFloatv(int pname, java.nio.FloatBuffer params);
-  public void glGetFloatv(int pname, float[] params, int params_offset);
-  /**
-   * glGetIntegerv
-   * @param pname GL_MATRIX_MODE
-   * @param params the FloatBuffer's position remains unchanged
-   *        which is the same behavior than the native JOGL GL impl
-   */
-  public void glGetIntegerv(int pname, IntBuffer params);
-  public void glGetIntegerv(int pname, int[] params, int params_offset);
-
-  /**
-   * sets the current matrix
-   * @param pname GL_MODELVIEW, GL_PROJECTION or GL.GL_TEXTURE
-   */
-  public void glMatrixMode(int mode) ;
-
-  public void glPushMatrix();
-  public void glPopMatrix();
-
-  public void glLoadIdentity() ;
-
-  /**
-   * glLoadMatrixf
-   * @param params the FloatBuffer's position remains unchanged,
-   *        which is the same behavior than the native JOGL GL impl
-   */
-  public void glLoadMatrixf(java.nio.FloatBuffer m) ;
-  public void glLoadMatrixf(float[] m, int m_offset);
-
-  /**
-   * glMultMatrixf
-   * @param m the FloatBuffer's position remains unchanged,
-   *        which is the same behavior than the native JOGL GL impl
-   */
-  public void glMultMatrixf(java.nio.FloatBuffer m) ;
-  public void glMultMatrixf(float[] m, int m_offset);
-
-  public void glTranslatef(float x, float y, float z) ;
-
-  public void glRotatef(float angle, float x, float y, float z);
-
-  public void glScalef(float x, float y, float z) ;
-
-  public void glOrthof(float left, float right, float bottom, float top, float zNear, float zFar) ;
-
-  public void glFrustumf(float left, float right, float bottom, float top, float zNear, float zFar);
+    public static final int GL_MATRIX_MODE = 0x0BA0;
+    /** Matrix mode modelview */
+    public static final int GL_MODELVIEW = 0x1700;
+    /** Matrix mode projection */
+    public static final int GL_PROJECTION = 0x1701;
+    // public static final int GL_TEXTURE = 0x1702; // Use GL.GL_TEXTURE due to ambiguous GL usage
+    /** Matrix access name for modelview */
+    public static final int GL_MODELVIEW_MATRIX = 0x0BA6;
+    /** Matrix access name for projection */
+    public static final int GL_PROJECTION_MATRIX = 0x0BA7;
+    /** Matrix access name for texture */
+    public static final int GL_TEXTURE_MATRIX = 0x0BA8;
+
+    /**
+     * Copy the named matrix into the given storage.
+     * @param pname {@link #GL_MODELVIEW_MATRIX}, {@link #GL_PROJECTION_MATRIX} or {@link #GL_TEXTURE_MATRIX}
+     * @param params the FloatBuffer's position remains unchanged,
+     *        which is the same behavior than the native JOGL GL impl
+     */
+    public void glGetFloatv(int pname, java.nio.FloatBuffer params);
+    
+    /**
+     * Copy the named matrix to the given storage at offset.
+     * @param pname {@link #GL_MODELVIEW_MATRIX}, {@link #GL_PROJECTION_MATRIX} or {@link #GL_TEXTURE_MATRIX}
+     * @param params storage
+     * @param params_offset storage offset
+     */ 
+    public void glGetFloatv(int pname, float[] params, int params_offset);
+    
+    /**
+     * glGetIntegerv
+     * @param pname {@link #GL_MATRIX_MODE} to receive the current matrix mode 
+     * @param params the FloatBuffer's position remains unchanged
+     *        which is the same behavior than the native JOGL GL impl
+     */
+    public void glGetIntegerv(int pname, IntBuffer params);
+    public void glGetIntegerv(int pname, int[] params, int params_offset);
+
+    /**
+     * Sets the current matrix mode.
+     * @param mode {@link #GL_MODELVIEW}, {@link #GL_PROJECTION} or {@link GL#GL_TEXTURE GL_TEXTURE}.
+     */
+    public void glMatrixMode(int mode) ;
+
+    /**
+     * Push the current matrix to it's stack, while preserving it's values.
+     * <p>
+     * There exist one stack per matrix mode, i.e. {@link #GL_MODELVIEW}, {@link #GL_PROJECTION} and {@link GL#GL_TEXTURE GL_TEXTURE}.
+     * </p>
+     */
+    public void glPushMatrix();
+    
+    /**
+     * Pop the current matrix from it's stack.
+     * @see #glPushMatrix()
+     */
+    public void glPopMatrix();
+
+    /**
+     * Load the current matrix with the identity matrix 
+     */
+    public void glLoadIdentity() ;
+
+    /**
+     * Load the current matrix w/ the provided one. 
+     * @param params the FloatBuffer's position remains unchanged,
+     *        which is the same behavior than the native JOGL GL impl
+     */
+    public void glLoadMatrixf(java.nio.FloatBuffer m) ;    
+    /**
+     * Load the current matrix w/ the provided one.
+     */ 
+    public void glLoadMatrixf(float[] m, int m_offset);
+
+    /**
+     * Multiply the current matrix
+     * @param m the FloatBuffer's position remains unchanged,
+     *        which is the same behavior than the native JOGL GL impl
+     */
+    public void glMultMatrixf(java.nio.FloatBuffer m) ;
+    /**
+     * Multiply the current matrix
+     */
+    public void glMultMatrixf(float[] m, int m_offset);
+
+    /**
+     * Translate the current matrix.
+     */
+    public void glTranslatef(float x, float y, float z) ;
+
+    /**
+     * Rotate the current matrix.
+     */
+    public void glRotatef(float angle, float x, float y, float z);
+
+    /**
+     * Scale the current matrix.
+     */
+    public void glScalef(float x, float y, float z) ;
+
+    /**
+     * {@link #glMultMatrixf(FloatBuffer) Multiply} the current matrix with the orthogonal matrix.
+     */
+    public void glOrthof(float left, float right, float bottom, float top, float zNear, float zFar) ;
+
+    /**
+     * {@link #glMultMatrixf(FloatBuffer) Multiply} the current matrix with the frustum matrix.
+     */
+    public void glFrustumf(float left, float right, float bottom, float top, float zNear, float zFar);
 
 }