FloatUtil.makeFrustum(..): Add throws GLException API doc / Add GLException if zNear == zFar

throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0,
or if left == right, or bottom == top, or zNear == zFar

Add note on callers:
  - FloatUtil.makePerspective(..)
  - Matrix4.*
  - PMVMatrix.*
  - ProjectFloat.*

4 files changed, 42 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 1a8924c8f..4a08d2e1f 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
@@ -491,16 +491,18 @@ public final class FloatUtil {
    * @param zNear
    * @param zFar
    * @return given matrix for chaining
+   * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0,
+   *         or if left == right, or bottom == top, or zNear == zFar.
    */
   public static float[] makeFrustum(final float[] m, final int m_offset, final boolean initM,
                                     final float left, final float right,
                                     final float bottom, final float top,
-                                    final float zNear, final float zFar) {
-      if(zNear<=0.0f||zFar<0.0f) {
+                                    final float zNear, final float zFar) throws GLException {
+      if( zNear <= 0.0f || zFar < 0.0f ) {
           throw new GLException("GL_INVALID_VALUE: zNear and zFar must be positive, and zNear>0");
       }
-      if(left==right || top==bottom) {
-          throw new GLException("GL_INVALID_VALUE: top,bottom and left,right must not be equal");
+      if( left == right || top == bottom || zNear == zFar ) {
+          throw new GLException("GL_INVALID_VALUE: top,bottom and left,right and zNear,zFar must not be equal");
       }
       if( initM ) {
           // m[m_offset+0+4*0] = 1f;
@@ -563,9 +565,10 @@ public final class FloatUtil {
    * @param zNear
    * @param zFar
    * @return given matrix for chaining
+   * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0, or if zNear == zFar.
    */
   public static float[] makePerspective(final float[] m, final int m_off, final boolean initM,
-                                        final float fovy_rad, final float aspect, final float zNear, final float zFar) {
+                                        final float fovy_rad, final float aspect, final float zNear, final float zFar) throws GLException {
       final float top    =  tan(fovy_rad/2f) * zNear; // use tangent of half-fov !
       final float bottom =  -1.0f * top;
       final float left   = aspect * bottom;
@@ -588,9 +591,10 @@ public final class FloatUtil {
    * @param zNear
    * @param zFar
    * @return given matrix for chaining
+   * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0, or if zNear == zFar.
    */
   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 fovhv, final float zNear, final float zFar) throws GLException {
       final FovHVHalves fovhvTan = fovhv.toTangents();  // use tangent of half-fov !
       final float top    =         fovhvTan.top    * zNear;
       final float bottom = -1.0f * fovhvTan.bottom * zNear;
diff --git a/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java b/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
index 830f1a882..b86a26dd5 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
@@ -28,6 +28,7 @@
 
 package com.jogamp.opengl.math;
 
+import javax.media.opengl.GLException;
 import javax.media.opengl.fixedfunc.GLMatrixFunc;
 
 import com.jogamp.opengl.util.PMVMatrix;
@@ -139,11 +140,28 @@ public class Matrix4 {
         multMatrix( FloatUtil.makeOrtho(mat4Tmp1, 0, true, left, right, bottom, top, zNear, zFar) );
     }
 
-    public final void makeFrustum(final float left, final float right, final float bottom, final float top, final float zNear, final float zFar) {
+    /**
+     * @param left
+     * @param right
+     * @param bottom
+     * @param top
+     * @param zNear
+     * @param zFar
+     * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0,
+     *         or if left == right, or bottom == top, or zNear == zFar.
+     */
+    public final void makeFrustum(final float left, final float right, final float bottom, final float top, final float zNear, final float zFar) throws GLException {
         multMatrix( FloatUtil.makeFrustum(mat4Tmp1, 0, true, left, right, bottom, top, zNear, zFar) );
     }
 
-    public final void makePerspective(final float fovy_rad, final float aspect, final float zNear, final float zFar) {
+    /**
+     * @param fovy_rad
+     * @param aspect
+     * @param zNear
+     * @param zFar
+     * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0, or if zNear == zFar.
+     */
+    public final void makePerspective(final float fovy_rad, final float aspect, final float zNear, final float zFar) throws GLException {
         multMatrix( FloatUtil.makePerspective(mat4Tmp1, 0, true, fovy_rad, aspect, zNear, zFar) );
     }
 
diff --git a/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java b/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
index 11acb0c58..6dd8ae032 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
@@ -660,8 +660,14 @@ public final class PMVMatrix implements GLMatrixFunc {
         glMultMatrixf( FloatUtil.makeOrtho(mat4Tmp1, 0, true, left, right, bottom, top, zNear, zFar), 0 );
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0,
+     *         or if left == right, or bottom == top, or zNear == zFar.
+     */
     @Override
-    public final void glFrustumf(final float left, final float right, final float bottom, final float top, final float zNear, final float zFar) {
+    public final void glFrustumf(final float left, final float right, final float bottom, final float top, final float zNear, final float zFar) throws GLException {
         glMultMatrixf( FloatUtil.makeFrustum(mat4Tmp1, 0, true, left, right, bottom, top, zNear, zFar), 0 );
     }
 
@@ -676,8 +682,9 @@ public final class PMVMatrix implements GLMatrixFunc {
      * @param aspect aspect ratio width / height
      * @param zNear
      * @param zFar
+     * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0, or if zNear == zFar.
      */
-    public final void gluPerspective(final float fovy_deg, final float aspect, final float zNear, final float zFar) {
+    public final void gluPerspective(final float fovy_deg, final float aspect, final float zNear, final float zFar) throws GLException {
       glMultMatrixf( FloatUtil.makePerspective(mat4Tmp1, 0, true, fovy_deg * FloatUtil.PI / 180.0f, aspect, zNear, zFar), 0 );
     }
 
diff --git a/src/jogl/classes/jogamp/opengl/ProjectFloat.java b/src/jogl/classes/jogamp/opengl/ProjectFloat.java
index 5921eb9a9..235d3eb60 100644
--- a/src/jogl/classes/jogamp/opengl/ProjectFloat.java
+++ b/src/jogl/classes/jogamp/opengl/ProjectFloat.java
@@ -118,6 +118,7 @@ package jogamp.opengl;
 import java.nio.FloatBuffer;
 import java.nio.IntBuffer;
 
+import javax.media.opengl.GLException;
 import javax.media.opengl.fixedfunc.GLMatrixFunc;
 
 import com.jogamp.opengl.math.FloatUtil;
@@ -169,8 +170,9 @@ public class ProjectFloat {
    * @param aspect
    * @param zNear
    * @param zFar
+   * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0, or if zNear == zFar.
    */
-  public void gluPerspective(final GLMatrixFunc gl, final float fovy_deg, final float aspect, final float zNear, final float zFar) {
+  public void gluPerspective(final GLMatrixFunc gl, final float fovy_deg, final float aspect, final float zNear, final float zFar) throws GLException {
     gl.glMultMatrixf(FloatUtil.makePerspective(mat4Tmp1, 0, true, fovy_deg * FloatUtil.PI / 180.0f, aspect, zNear, zFar), 0);
   }