Bug 1021: Add OculusVR distortion renderer (single FBO and dual FBO); Add GLEventListener2 (WIP); Refine FloatUtil

- GLEventListener2 extends GLEventListener adds refined control:
  - display w/ flags, i.e. repeat, don't clear
  - setProjectionModelview(..)

- FloatUtil.* Add return value for chaining, where missing

+++

- jogamp.opengl.oculusvr.OVRDistortion
  - Handles all OVR related data and maps it to shader + GL buffers
  - display method

- com.jogamp.opengl.oculusvr.OVRSBSRendererSingleFBO implements GLEventListener
  - Simple OVRDistortion renderer using single FBO
  - Using upstream GLEventListener2 (the content)

- com.jogamp.opengl.oculusvr.OVRSBSRendererDualFBO implements GLEventListener
  - Simple OVRDistortion renderer using two FBOs
  - Using upstream GLEventListener2 (the content)

Manual Test: com.jogamp.opengl.test.junit.jogl.stereo.ovr.OVRDemo01

4 files changed, 154 insertions, 37 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
index 7e9d7cdd8..f5200443c 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
@@ -705,8 +705,8 @@ public final class FloatUtil {
    *
    * @param msrc 4x4 matrix in column-major order, the source
    * @param msrc_offset offset in given array <i>msrc</i>, i.e. start of the 4x4 matrix
-   * @param mres 4x4 matrix in column-major order, the result - may be <code>msrc</code> (in-place)
-   * @param mres_offset offset in given array <i>mres</i>, i.e. start of the 4x4 matrix - may be <code>msrc_offset</code> (in-place)
+   * @param mres 4x4 matrix in column-major order, the result
+   * @param mres_offset offset in given array <i>mres</i>, i.e. start of the 4x4 matrix
    * @return given result matrix <i>mres</i> for chaining
    */
   public static float[] transposeMatrix(final float[] msrc, final int msrc_offset, final float[] mres, final int mres_offset) {
@@ -737,16 +737,37 @@ public final class FloatUtil {
   }
 
   /**
-   * Transpose the given matrix in place.
+   * Transpose the given matrix.
    *
-   * @param m 4x4 matrix in column-major order, the source
-   * @param m_offset offset in given array <i>m</i>, i.e. start of the 4x4 matrix
-   * @param temp temporary 4*4 float storage
-   * @return given result matrix <i>m</i> for chaining
+   * @param msrc 4x4 matrix in column-major order, the source
+   * @param mres 4x4 matrix in column-major order, the result
+   * @return given result matrix <i>mres</i> for chaining
    */
-  public static float[] transposeMatrix(final float[] m, final int m_offset, final float[/*4*4*/] temp) {
-      System.arraycopy(m, m_offset, temp, 0, 16);
-      return transposeMatrix(temp, 0, m, m_offset);
+  public static float[] transposeMatrix(final float[] msrc, final float[] mres) {
+      mres[0] = msrc[0*4];
+      mres[1] = msrc[1*4];
+      mres[2] = msrc[2*4];
+      mres[3] = msrc[3*4];
+
+      final int i4_1 = 1*4;
+      mres[0+i4_1] = msrc[1+0*4];
+      mres[1+i4_1] = msrc[1+1*4];
+      mres[2+i4_1] = msrc[1+2*4];
+      mres[3+i4_1] = msrc[1+3*4];
+
+      final int i4_2 = 2*4;
+      mres[0+i4_2] = msrc[2+0*4];
+      mres[1+i4_2] = msrc[2+1*4];
+      mres[2+i4_2] = msrc[2+2*4];
+      mres[3+i4_2] = msrc[2+3*4];
+
+      final int i4_3 = 3*4;
+      mres[0+i4_3] = msrc[3+0*4];
+      mres[1+i4_3] = msrc[3+1*4];
+      mres[2+i4_3] = msrc[3+2*4];
+      mres[3+i4_3] = msrc[3+3*4];
+
+      return mres;
   }
 
   /**
@@ -1422,8 +1443,9 @@ public final class FloatUtil {
    * @param a 4x4 matrix in column-major order
    * @param b 4x4 matrix in column-major order
    * @param d result a*b in column-major order
+   * @return given result matrix <i>d</i> for chaining
    */
-  public static void multMatrix(final float[] a, final int a_off, final float[] b, final int b_off, float[] d, final int d_off) {
+  public static float[] multMatrix(final float[] a, final int a_off, final float[] b, final int b_off, float[] d, final int d_off) {
       final float b00 = b[b_off+0+0*4];
       final float b10 = b[b_off+1+0*4];
       final float b20 = b[b_off+2+0*4];
@@ -1476,6 +1498,8 @@ public final class FloatUtil {
       d[d_off+3+1*4] = ai0 * b01  +  ai1 * b11  +  ai2 * b21  +  ai3 * b31 ;
       d[d_off+3+2*4] = ai0 * b02  +  ai1 * b12  +  ai2 * b22  +  ai3 * b32 ;
       d[d_off+3+3*4] = ai0 * b03  +  ai1 * b13  +  ai2 * b23  +  ai3 * b33 ;
+
+      return d;
   }
 
   /**
@@ -1483,8 +1507,9 @@ public final class FloatUtil {
    * @param a 4x4 matrix in column-major order
    * @param b 4x4 matrix in column-major order
    * @param d result a*b in column-major order
+   * @return given result matrix <i>d</i> for chaining
    */
-  public static void multMatrix(final float[] a, final float[] b, float[] d) {
+  public static float[] multMatrix(final float[] a, final float[] b, float[] d) {
       final float b00 = b[0+0*4];
       final float b10 = b[1+0*4];
       final float b20 = b[2+0*4];
@@ -1537,14 +1562,17 @@ public final class FloatUtil {
       d[3+1*4] = ai0 * b01  +  ai1 * b11  +  ai2 * b21  +  ai3 * b31 ;
       d[3+2*4] = ai0 * b02  +  ai1 * b12  +  ai2 * b22  +  ai3 * b32 ;
       d[3+3*4] = ai0 * b03  +  ai1 * b13  +  ai2 * b23  +  ai3 * b33 ;
+
+      return d;
   }
 
   /**
    * Multiply matrix: [a] = [a] x [b]
    * @param a 4x4 matrix in column-major order (also result)
    * @param b 4x4 matrix in column-major order
+   * @return given result matrix <i>a</i> for chaining
    */
-  public static void multMatrix(final float[] a, final int a_off, final float[] b, final int b_off) {
+  public static float[] multMatrix(final float[] a, final int a_off, final float[] b, final int b_off) {
       final float b00 = b[b_off+0+0*4];
       final float b10 = b[b_off+1+0*4];
       final float b20 = b[b_off+2+0*4];
@@ -1597,14 +1625,17 @@ public final class FloatUtil {
       a[a_off+3+1*4] = ai0 * b01  +  ai1 * b11  +  ai2 * b21  +  ai3 * b31 ;
       a[a_off+3+2*4] = ai0 * b02  +  ai1 * b12  +  ai2 * b22  +  ai3 * b32 ;
       a[a_off+3+3*4] = ai0 * b03  +  ai1 * b13  +  ai2 * b23  +  ai3 * b33 ;
+
+      return a;
   }
 
   /**
    * Multiply matrix: [a] = [a] x [b]
    * @param a 4x4 matrix in column-major order (also result)
    * @param b 4x4 matrix in column-major order
+   * @return given result matrix <i>a</i> for chaining
    */
-  public static void multMatrix(final float[] a, final float[] b) {
+  public static float[] multMatrix(final float[] a, final float[] b) {
       final float b00 = b[0+0*4];
       final float b10 = b[1+0*4];
       final float b20 = b[2+0*4];
@@ -1657,6 +1688,8 @@ public final class FloatUtil {
       a[3+1*4] = ai0 * b01  +  ai1 * b11  +  ai2 * b21  +  ai3 * b31 ;
       a[3+2*4] = ai0 * b02  +  ai1 * b12  +  ai2 * b22  +  ai3 * b32 ;
       a[3+3*4] = ai0 * b03  +  ai1 * b13  +  ai2 * b23  +  ai3 * b33 ;
+
+      return a;
   }
 
   /**
@@ -1705,10 +1738,11 @@ public final class FloatUtil {
    * @param m_in_off
    * @param v_in 4-component column-vector
    * @param v_out m_in * v_in
+   * @return given result vector <i>v_out</i> for chaining
    */
-  public static void multMatrixVec(final float[] m_in, final int m_in_off,
-                                   final float[] v_in, final int v_in_off,
-                                   final float[] v_out, final int v_out_off) {
+  public static float[] multMatrixVec(final float[] m_in, final int m_in_off,
+                                      final float[] v_in, final int v_in_off,
+                                      final float[] v_out, final int v_out_off) {
       // (one matrix row in column-major order) X (column vector)
       v_out[0 + v_out_off] = v_in[0+v_in_off] * m_in[0*4+m_in_off  ]  +  v_in[1+v_in_off] * m_in[1*4+m_in_off  ] +
                              v_in[2+v_in_off] * m_in[2*4+m_in_off  ]  +  v_in[3+v_in_off] * m_in[3*4+m_in_off  ];
@@ -1724,6 +1758,8 @@ public final class FloatUtil {
       final int m_in_off_3 = 3+m_in_off;
       v_out[3 + v_out_off] = v_in[0+v_in_off] * m_in[0*4+m_in_off_3]  +  v_in[1+v_in_off] * m_in[1*4+m_in_off_3] +
                              v_in[2+v_in_off] * m_in[2*4+m_in_off_3]  +  v_in[3+v_in_off] * m_in[3*4+m_in_off_3];
+
+      return v_out;
   }
 
   /**
@@ -1731,8 +1767,9 @@ public final class FloatUtil {
    * @param m_in_off
    * @param v_in 4-component column-vector
    * @param v_out m_in * v_in
+   * @return given result vector <i>v_out</i> for chaining
    */
-  public static void multMatrixVec(final float[] m_in, final float[] v_in, final float[] v_out) {
+  public static float[] multMatrixVec(final float[] m_in, final float[] v_in, final float[] v_out) {
       // (one matrix row in column-major order) X (column vector)
       v_out[0] = v_in[0] * m_in[0*4  ]  +  v_in[1] * m_in[1*4  ] +
                  v_in[2] * m_in[2*4  ]  +  v_in[3] * m_in[3*4  ];
@@ -1745,6 +1782,8 @@ public final class FloatUtil {
 
       v_out[3] = v_in[0] * m_in[0*4+3]  +  v_in[1] * m_in[1*4+3] +
                  v_in[2] * m_in[2*4+3]  +  v_in[3] * m_in[3*4+3];
+
+      return v_out;
   }
 
   /**
@@ -1776,14 +1815,16 @@ public final class FloatUtil {
    * @param column named column to copy
    * @param v_out the column-vector storage, at least 3 components long
    * @param v_out_off offset to storage
+   * @return given result vector <i>v_out</i> for chaining
    */
-  public static void copyMatrixColumn(final float[] m_in, final int m_in_off, final int column, final float[] v_out, final int v_out_off) {
+  public static float[] copyMatrixColumn(final float[] m_in, final int m_in_off, final int column, final float[] v_out, final int v_out_off) {
       v_out[0+v_out_off]=m_in[0+column*4+m_in_off];
       v_out[1+v_out_off]=m_in[1+column*4+m_in_off];
       v_out[2+v_out_off]=m_in[2+column*4+m_in_off];
       if( v_out.length > 3+v_out_off ) {
           v_out[3+v_out_off]=m_in[3+column*4+m_in_off];
       }
+      return v_out;
   }
 
   /**
@@ -1796,14 +1837,16 @@ public final class FloatUtil {
    * @param row named row to copy
    * @param v_out the row-vector storage, at least 3 components long
    * @param v_out_off offset to storage
+   * @return given result vector <i>v_out</i> for chaining
    */
-  public static void copyMatrixRow(final float[] m_in, final int m_in_off, final int row, final float[] v_out, final int v_out_off) {
+  public static float[] copyMatrixRow(final float[] m_in, final int m_in_off, final int row, final float[] v_out, final int v_out_off) {
       v_out[0+v_out_off]=m_in[row+0*4+m_in_off];
       v_out[1+v_out_off]=m_in[row+1*4+m_in_off];
       v_out[2+v_out_off]=m_in[row+2*4+m_in_off];
       if( v_out.length > 3+v_out_off ) {
           v_out[3+v_out_off]=m_in[row+3*4+m_in_off];
       }
+      return v_out;
   }
 
   /**
diff --git a/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java b/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
index 069e6a0a9..830f1a882 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
@@ -123,7 +123,8 @@ public class Matrix4 {
     }
 
     public final void transpose() {
-        FloatUtil.transposeMatrix(matrix, 0, mat4Tmp1);
+        System.arraycopy(matrix, 0, mat4Tmp1, 0, 16);
+        FloatUtil.transposeMatrix(mat4Tmp1, matrix);
     }
 
     public final float determinant() {
diff --git a/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java b/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
index dabde83dd..a1735766e 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
@@ -45,7 +45,6 @@ import javax.media.opengl.GLCapabilitiesImmutable;
 import javax.media.opengl.GLDrawable;
 import javax.media.opengl.GLEventListener;
 import javax.media.opengl.GLException;
-import javax.media.opengl.GLFBODrawable;
 import jogamp.opengl.Debug;
 
 /**
@@ -228,14 +227,14 @@ public abstract class TileRendererBase {
     protected GLEventListener glEventListenerPre = null;
     protected GLEventListener glEventListenerPost = null;
 
-    private final String hashStr(Object o) {
+    private final String hashStr(final Object o) {
         final int h = null != o ? o.hashCode() : 0;
         return "0x"+Integer.toHexString(h);
     }
-    protected StringBuilder tileDetails(StringBuilder sb) {
+    protected StringBuilder tileDetails(final StringBuilder sb) {
         return sb.append("cur "+currentTileXPos+"/"+currentTileYPos+" "+currentTileWidth+"x"+currentTileHeight+", buffer "+hashStr(tileBuffer));
     }
-    public StringBuilder toString(StringBuilder sb) {
+    public StringBuilder toString(final StringBuilder sb) {
         final int gladListenerCount = null != listeners ? listeners.length : 0;
         sb.append("tile[");
         tileDetails(sb);
@@ -246,7 +245,7 @@ public abstract class TileRendererBase {
     }
     @Override
     public String toString() {
-        StringBuilder sb = new StringBuilder();
+        final StringBuilder sb = new StringBuilder();
         return getClass().getSimpleName()+
                 "["+toString(sb).toString()+"]";
     }
@@ -270,7 +269,7 @@ public abstract class TileRendererBase {
      *
      * @param buffer The buffer itself. Must be large enough to contain a random tile
      */
-    public final void setTileBuffer(GLPixelBuffer buffer) {
+    public final void setTileBuffer(final GLPixelBuffer buffer) {
         tileBuffer = buffer;
         if( DEBUG ) {
             System.err.println("TileRenderer: tile-buffer "+tileBuffer);
@@ -286,7 +285,7 @@ public abstract class TileRendererBase {
      * @param width The width of the final image
      * @param height The height of the final image
      */
-    public void setImageSize(int width, int height) {
+    public void setImageSize(final int width, final int height) {
         imageSize.set(width, height);
     }
 
@@ -298,7 +297,7 @@ public abstract class TileRendererBase {
      *
      * @param buffer the buffer itself, must be large enough to hold the final image
      */
-    public final void setImageBuffer(GLPixelBuffer buffer) {
+    public final void setImageBuffer(final GLPixelBuffer buffer) {
         imageBuffer = buffer;
         if( DEBUG ) {
             System.err.println("TileRenderer: image-buffer "+imageBuffer);
@@ -308,7 +307,7 @@ public abstract class TileRendererBase {
     /** @see #setImageBuffer(GLPixelBuffer) */
     public final GLPixelBuffer getImageBuffer() { return imageBuffer; }
 
-    /* pp */ final void validateGL(GL gl) throws GLException {
+    /* pp */ final void validateGL(final GL gl) throws GLException {
         if( imageBuffer != null && !gl.isGL2ES3()) {
             throw new GLException("Using image-buffer w/ inssufficient GL context: "+gl.getContext().getGLVersion()+", "+gl.getGLProfile());
         }
@@ -415,7 +414,7 @@ public abstract class TileRendererBase {
      * See {@link GLDrawableUtil#swapBuffersBeforeRead(GLCapabilitiesImmutable)}.
      * </p>
      */
-    public final boolean reqPreSwapBuffers(GLCapabilitiesImmutable chosenCaps) {
+    public final boolean reqPreSwapBuffers(final GLCapabilitiesImmutable chosenCaps) {
         return GLDrawableUtil.swapBuffersBeforeRead(chosenCaps);
     }
 
@@ -466,7 +465,7 @@ public abstract class TileRendererBase {
      * @see #getAttachedDrawable()
      * @see #detachAutoDrawable()
      */
-    public final void attachAutoDrawable(GLAutoDrawable glad) throws IllegalStateException {
+    public final void attachAutoDrawable(final GLAutoDrawable glad) throws IllegalStateException {
         if( null != this.glad ) {
             throw new IllegalStateException("GLAutoDrawable already attached");
         }
@@ -551,7 +550,7 @@ public abstract class TileRendererBase {
      * @param preTile the pre operations
      * @param postTile the post operations
      */
-    public final void setGLEventListener(GLEventListener preTile, GLEventListener postTile) {
+    public final void setGLEventListener(final GLEventListener preTile, final GLEventListener postTile) {
         glEventListenerPre = preTile;
         glEventListenerPost = postTile;
     }
@@ -573,7 +572,7 @@ public abstract class TileRendererBase {
         final TileRenderer tileRenderer = TileRendererBase.this instanceof TileRenderer ? (TileRenderer) TileRendererBase.this : null;
 
         @Override
-        public void init(GLAutoDrawable drawable) {
+        public void init(final GLAutoDrawable drawable) {
             if( null != glEventListenerPre ) {
                 glEventListenerPre.init(drawable);
             }
@@ -590,7 +589,7 @@ public abstract class TileRendererBase {
             }
         }
         @Override
-        public void dispose(GLAutoDrawable drawable) {
+        public void dispose(final GLAutoDrawable drawable) {
             if( null != glEventListenerPre ) {
                 glEventListenerPre.dispose(drawable);
             }
@@ -603,7 +602,7 @@ public abstract class TileRendererBase {
             }
         }
         @Override
-        public void display(GLAutoDrawable drawable) {
+        public void display(final GLAutoDrawable drawable) {
             if( null != glEventListenerPre ) {
                 glEventListenerPre.reshape(drawable, 0, 0, currentTileWidth, currentTileHeight);
                 glEventListenerPre.display(drawable);
@@ -660,6 +659,6 @@ public abstract class TileRendererBase {
             }
         }
         @Override
-        public void reshape(GLAutoDrawable drawable, int x, int y, int width, int height) { }
+        public void reshape(final GLAutoDrawable drawable, final int x, final int y, final int width, final int height) { }
     };
 }
\ No newline at end of file
diff --git a/src/jogl/classes/javax/media/opengl/GLEventListener2.java b/src/jogl/classes/javax/media/opengl/GLEventListener2.java
new file mode 100644
index 000000000..d4e8e84a4
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/GLEventListener2.java
@@ -0,0 +1,74 @@
+/**
+ * Copyright 2014 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package javax.media.opengl;
+
+/**
+ * Extended {@link GLEventListener} interface
+ * supporting more fine grained control over the implementation.
+ */
+public interface GLEventListener2 extends GLEventListener {
+    /**
+     * {@link #display(GLAutoDrawable, int) display flag}: Repeat last produced image.
+     * <p>
+     * While a repeated frame shall produce the same artifacts as the last <code>display</code> call,
+     * e.g. not change animated objects, it shall reflect the {@link #setProjectionModelview(GLAutoDrawable, float[], float[]) current matrix}.
+     * </p>
+     */
+    public static final int DISPLAY_REPEAT    = 1 << 0;
+
+    /**
+     * {@link #display(GLAutoDrawable, int) display flag}: Do not clear any target buffer, e.g. color-, depth- or stencil-buffers.
+     */
+    public static final int DISPLAY_DONTCLEAR = 1 << 1;
+
+    /**
+     * Extended {@link #display(GLAutoDrawable) display} method,
+     * allowing to pass a display flag, e.g. {@link #DISPLAY_REPEAT} or {@link #DISPLAY_DONTCLEAR}.
+     * <p>
+     * Method is usually called by a custom rendering loop,
+     * e.g. for manual stereo rendering or the like.
+     * </p>
+     * @param drawable
+     * @param flags
+     */
+    public void display(final GLAutoDrawable drawable, final int flags);
+
+    /**
+     * Might be called instead of {@link #reshape(GLAutoDrawable, int, int, int, int) reshape}
+     * to specify a custom projection and modelview matrix determined by the caller.
+     * <p>
+     * Method is usually called by a custom rendering loop,
+     * e.g. for manual stereo rendering or the like.
+     * </p>
+     *
+     * @param drawable the triggering {@link GLAutoDrawable}
+     * @param mat4Projection float[16] projection matrix
+     * @param mat4Modelview float[16] modelview matrix
+     */
+    public void setProjectionModelview(final GLAutoDrawable drawable, final float[] mat4Projection, final float[] mat4Modelview);
+}