Bug 1021: Add GenericStereoDevice* Supporting custom configurations; Hook-in oculusvr-sdk java distortion-mesh calculation if available

StereoDeviceFactory support new GenericStereoDeviceFactory, with it's GenericStereoDevice and GenericStereoDeviceRenderer.

GenericStereoDevice maintains different configurations, triggered either by passing a GenericStereoDevice.Config
instance directly or by the device-index parameter:

  - 0: monoscopi device: No post-processing

  - 1: stereoscopic device SBS: No post-processing

  - 2: stereoscopic device SBS + Lenses: Distortion post-processing
       (only available w/ oculusvr-sdk sub-module)

Producing a 'GenericStereoDevice.Config' instance is self containing
and may extend if supporting more device types like top-bottom, interlaced etc.

StereoDemo01 handles all use-cases and may be used as a test-bed
to add and experiment with stereoscopy, devices and settings.

3 files changed, 128 insertions, 11 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
index d2e535eaf..3a3568697 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
@@ -559,7 +559,7 @@ public final class FloatUtil {
    * @param initM if true, given matrix will be initialized w/ identity matrix,
    *              otherwise only the frustum fields are set.
    * @param fovy_rad angle in radians
-   * @param aspect
+   * @param aspect aspect ratio width / height
    * @param zNear
    * @param zFar
    * @return given matrix for chaining
@@ -591,7 +591,7 @@ public final class FloatUtil {
    */
   public static float[] makePerspective(final float[] m, final int m_offset, final boolean initM,
                                         final FovHVHalves fovhv, final float zNear, final float zFar) {
-      final FovHVHalves fovhvTan = fovhv.getInTangents();  // use tangent of half-fov !
+      final FovHVHalves fovhvTan = fovhv.toTangents();  // use tangent of half-fov !
       final float top    =         fovhvTan.top    * zNear;
       final float bottom = -1.0f * fovhvTan.bottom * zNear;
       final float left   = -1.0f * fovhvTan.left   * zNear;
diff --git a/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java b/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java
index 786d146e6..26ed57009 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java
@@ -69,26 +69,87 @@ public final class FovHVHalves {
     /**
      * Returns a symmetrical centered {@link FovHVHalves} instance in tangents, using:
      * <pre>
-        final float halfHorizFovTan = (float)Math.tan(horizontalFov/2f);
-        final float halfVertFovTan = (float)Math.tan(verticalFov/2f);
+        halfHorizFovTan = tan( horizontalFov / 2f );
+        halfVertFovTan  = tan( verticalFov / 2f );
      * </pre>
      * @param horizontalFov whole horizontal FOV in radians
      * @param verticalFov whole vertical FOV in radians
      */
-    public static FovHVHalves createByRadians(final float horizontalFov, final float verticalFov) {
+    public static FovHVHalves byRadians(final float horizontalFov, final float verticalFov) {
         final float halfHorizFovTan = FloatUtil.tan(horizontalFov/2f);
         final float halfVertFovTan = FloatUtil.tan(verticalFov/2f);
         return new FovHVHalves(halfHorizFovTan, halfHorizFovTan, halfVertFovTan, halfVertFovTan, true);
     }
 
     /**
-     * Returns this instance values <i>in tangent</i> values.
+     * Returns a symmetrical centered {@link FovHVHalves} instance in tangents, using:
+     * <pre>
+        top  = bottom = tan( verticalFov / 2f );
+        left =  right = aspect * top;
+     * </pre>
+     *
+     * @param verticalFov vertical FOV in radians
+     * @param aspect aspect ration width / height
+     */
+    public static FovHVHalves byFovyRadianAndAspect(final float verticalFov, final float aspect) {
+        final float halfVertFovTan = FloatUtil.tan(verticalFov/2f);
+        final float halfHorizFovTan = aspect * halfVertFovTan;
+        return new FovHVHalves(halfHorizFovTan, halfHorizFovTan,
+                               halfVertFovTan, halfVertFovTan, true);
+    }
+
+    /**
+     * Returns a custom symmetry {@link FovHVHalves} instance in tangents, using:
+     * <pre>
+        left   = tan( horizontalFov * horizCenterFromLeft )
+        right  = tan( horizontalFov * ( 1f - horizCenterFromLeft ) )
+        top    = tan( verticalFov   * vertCenterFromTop )
+        bottom = tan( verticalFov   * (1f - vertCenterFromTop ) )
+     * </pre>
+     * @param horizontalFov whole horizontal FOV in radians
+     * @param horizCenterFromLeft horizontal center from left in [0..1]
+     * @param verticalFov whole vertical FOV in radians
+     * @param vertCenterFromTop vertical center from top in [0..1]
+     */
+    public static FovHVHalves byRadians(final float horizontalFov, final float horizCenterFromLeft,
+                                        final float verticalFov, final float vertCenterFromTop) {
+        return new FovHVHalves(FloatUtil.tan(horizontalFov * horizCenterFromLeft),
+                               FloatUtil.tan(horizontalFov * ( 1f - horizCenterFromLeft )),
+                               FloatUtil.tan(verticalFov   * vertCenterFromTop),
+                               FloatUtil.tan(verticalFov   * (1f - vertCenterFromTop )),
+                               true);
+    }
+
+    /**
+     * Returns a custom symmetry {@link FovHVHalves} instance in tangents,
+     * via computing the <code>horizontalFov</code> using:
+     * <pre>
+        halfVertFovTan  = tan( verticalFov / 2f );
+        halfHorizFovTan = aspect * halfVertFovTan;
+        horizontalFov   = atan( halfHorizFovTan ) * 2f;
+        return {@link #byRadians(float, float, float, float) byRadians}(horizontalFov, horizCenterFromLeft, verticalFov, vertCenterFromTop)
+     * </pre>
+     * @param verticalFov whole vertical FOV in radians
+     * @param vertCenterFromTop vertical center from top in [0..1]
+     * @param aspect aspect ration width / height
+     * @param horizCenterFromLeft horizontal center from left in [0..1]
+     */
+    public static FovHVHalves byFovyRadianAndAspect(final float verticalFov, final float vertCenterFromTop,
+                                                    final float aspect, final float horizCenterFromLeft) {
+        final float halfVertFovTan = FloatUtil.tan(verticalFov/2f);
+        final float halfHorizFovTan = aspect * halfVertFovTan;
+        final float horizontalFov = FloatUtil.atan(halfHorizFovTan) * 2f;
+        return byRadians(horizontalFov, horizCenterFromLeft, verticalFov, vertCenterFromTop);
+    }
+
+    /**
+     * Returns this instance <i>in tangent</i> values.
      * <p>
      * If this instance is {@link #inTangents} already, method returns this instance,
      * otherwise a newly created instance w/ converted values to tangent.
      * </p>
      */
-    public final FovHVHalves getInTangents() {
+    public final FovHVHalves toTangents() {
         if( inTangents ) {
             return this;
         } else {
diff --git a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
index c11c2bd2b..36222cf4a 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
@@ -393,7 +393,7 @@ public final class VectorUtil {
     }
 
     /**
-     * Scales a vector by param using given result float[]
+     * Scales a vector by param using given result float[], result = vector * scale
      * @param result vector for the result, may be vector (in-place)
      * @param vector input vector
      * @param scale single scale constant for all vector components
@@ -406,7 +406,7 @@ public final class VectorUtil {
     }
 
     /**
-     * Scales a vector by param using given result float[]
+     * Scales a vector by param using given result float[], result = vector * scale
      * @param result vector for the result, may be vector (in-place)
      * @param vector input vector
      * @param scale single scale constant for all vector components
@@ -420,7 +420,7 @@ public final class VectorUtil {
     }
 
     /**
-     * Scales a vector by param using given result float[]
+     * Scales a vector by param using given result float[], result = vector * scale
      * @param result vector for the result, may be vector (in-place)
      * @param vector input vector
      * @param scale 3 component scale constant for each vector component
@@ -435,7 +435,7 @@ public final class VectorUtil {
     }
 
     /**
-     * Scales a vector by param using given result float[]
+     * Scales a vector by param using given result float[], result = vector * scale
      * @param result vector for the result, may be vector (in-place)
      * @param vector input vector
      * @param scale 2 component scale constant for each vector component
@@ -449,6 +449,62 @@ public final class VectorUtil {
     }
 
     /**
+     * Divides a vector by param using given result float[], result = vector / scale
+     * @param result vector for the result, may be vector (in-place)
+     * @param vector input vector
+     * @param scale single scale constant for all vector components
+     * @return result vector for chaining
+     */
+    public static float[] divVec2(final float[] result, final float[] vector, final float scale) {
+        result[0] = vector[0] / scale;
+        result[1] = vector[1] / scale;
+        return result;
+    }
+
+    /**
+     * Divides a vector by param using given result float[], result = vector / scale
+     * @param result vector for the result, may be vector (in-place)
+     * @param vector input vector
+     * @param scale single scale constant for all vector components
+     * @return result vector for chaining
+     */
+    public static float[] divVec3(final float[] result, final float[] vector, final float scale) {
+        result[0] = vector[0] / scale;
+        result[1] = vector[1] / scale;
+        result[2] = vector[2] / scale;
+        return result;
+    }
+
+    /**
+     * Divides a vector by param using given result float[], result = vector / scale
+     * @param result vector for the result, may be vector (in-place)
+     * @param vector input vector
+     * @param scale 3 component scale constant for each vector component
+     * @return result vector for chaining
+     */
+    public static float[] divVec3(final float[] result, final float[] vector, final float[] scale)
+    {
+        result[0] = vector[0] / scale[0];
+        result[1] = vector[1] / scale[1];
+        result[2] = vector[2] / scale[2];
+        return result;
+    }
+
+    /**
+     * Divides a vector by param using given result float[], result = vector / scale
+     * @param result vector for the result, may be vector (in-place)
+     * @param vector input vector
+     * @param scale 2 component scale constant for each vector component
+     * @return result vector for chaining
+     */
+    public static float[] divVec2(final float[] result, final float[] vector, final float[] scale)
+    {
+        result[0] = vector[0] / scale[0];
+        result[1] = vector[1] / scale[1];
+        return result;
+    }
+
+    /**
      * Adds two vectors, result = v1 + v2
      * @param result float[2] result vector, may be either v1 or v2 (in-place)
      * @param v1 vector 1