From befd56510a781e65509256ae37e18888ff58181d Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Mon, 20 Jul 2015 02:55:00 +0200 Subject: Refine Frustum definition: Adding Frustum.FovDesc; Clarify makeFrustum argument constraints -> Exceptions --- .../classes/com/jogamp/opengl/math/FloatUtil.java | 26 ++++---- .../com/jogamp/opengl/math/FovHVHalves.java | 20 +++--- .../classes/com/jogamp/opengl/math/Matrix4.java | 8 ++- .../com/jogamp/opengl/math/geom/Frustum.java | 75 +++++++++++++++++++--- 4 files changed, 97 insertions(+), 32 deletions(-) (limited to 'src/jogl/classes/com/jogamp/opengl/math') diff --git a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java index a04055430..7f630f9d5 100644 --- a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java +++ b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java @@ -35,6 +35,7 @@ import jogamp.opengl.Debug; import com.jogamp.common.os.Platform; import com.jogamp.opengl.math.geom.AABBox; +import com.jogamp.opengl.math.geom.Frustum; /** * Basic Float math utility functions. @@ -491,18 +492,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. + * @throws GLException if {@code zNear <= 0} or {@code zFar <= zNear} + * or {@code left == right}, or {@code bottom == top}. */ 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) 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( zNear <= 0.0f || zFar <= zNear ) { + throw new GLException("Requirements zNear > 0 and zFar > zNear, but zNear "+zNear+", zFar "+zFar); } - 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( left == right || top == bottom) { + throw new GLException("GL_INVALID_VALUE: top,bottom and left,right must not be equal"); } if( initM ) { // m[m_offset+0+4*0] = 1f; @@ -565,14 +566,15 @@ 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. + * @throws GLException if {@code zNear <= 0} or {@code zFar <= zNear} + * @see #makeFrustum(float[], int, boolean, float, float, float, float, float, float) */ 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) 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; - final float right = aspect * top; + final float bottom = -1.0f * top; // -1f * fovhvTan.top * zNear + final float left = aspect * bottom; // aspect * -1f * fovhvTan.top * zNear + final float right = aspect * top; // aspect * fovhvTan.top * zNear return makeFrustum(m, m_off, initM, left, right, bottom, top, zNear, zFar); } @@ -591,7 +593,9 @@ 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. + * @throws GLException if {@code zNear <= 0} or {@code zFar <= zNear} + * @see #makeFrustum(float[], int, boolean, float, float, float, float, float, float) + * @see Frustum#updateByFovDesc(float[], int, boolean, Frustum.FovDesc) */ public static float[] makePerspective(final float[] m, final int m_offset, final boolean initM, final FovHVHalves fovhv, final float zNear, final float zFar) throws GLException { diff --git a/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java b/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java index 26ed57009..5d7907f2f 100644 --- a/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java +++ b/src/jogl/classes/com/jogamp/opengl/math/FovHVHalves.java @@ -35,13 +35,13 @@ package com.jogamp.opengl.math; *

*/ public final class FovHVHalves { - /** Half horizontal FOV from center to left. */ + /** Half horizontal FOV from center to left, either in {@link #inTangents} or radians. */ public final float left; - /** Half horizontal FOV from center to right. */ + /** Half horizontal FOV from center to right, either in {@link #inTangents} or radians. */ public final float right; - /** Half vertical FOV from center to top. */ + /** Half vertical FOV from center to top, either in {@link #inTangents} or radians. */ public final float top; - /** Half vertical FOV from center to bottom. */ + /** Half vertical FOV from center to bottom, either in {@link #inTangents} or radians. */ public final float bottom; /** If true, values are in tangent, otherwise radians.*/ public final boolean inTangents; @@ -67,7 +67,7 @@ public final class FovHVHalves { } /** - * Returns a symmetrical centered {@link FovHVHalves} instance in tangents, using: + * Returns a symmetrical centered {@link FovHVHalves} instance in {@link #inTangents}, using: * 
         halfHorizFovTan = tan( horizontalFov / 2f );
         halfVertFovTan  = tan( verticalFov / 2f );
@@ -82,7 +82,7 @@ public final class FovHVHalves {
     }
 
     /**
-     * Returns a symmetrical centered {@link FovHVHalves} instance in tangents, using:
+     * Returns a symmetrical centered {@link FovHVHalves} instance in {@link #inTangents}, using:
      * 
         top  = bottom = tan( verticalFov / 2f );
         left =  right = aspect * top;
@@ -99,7 +99,7 @@ public final class FovHVHalves {
     }
 
     /**
-     * Returns a custom symmetry {@link FovHVHalves} instance in tangents, using:
+     * Returns a custom symmetry {@link FovHVHalves} instance {@link #inTangents}, using:
      * 
         left   = tan( horizontalFov * horizCenterFromLeft )
         right  = tan( horizontalFov * ( 1f - horizCenterFromLeft ) )
@@ -121,7 +121,7 @@ public final class FovHVHalves {
     }
 
     /**
-     * Returns a custom symmetry {@link FovHVHalves} instance in tangents,
+     * Returns a custom symmetry {@link FovHVHalves} instance {@link #inTangents},
      * via computing the horizontalFov using:
      * 
         halfVertFovTan  = tan( verticalFov / 2f );
@@ -157,10 +157,10 @@ public final class FovHVHalves {
         }
     }
 
-    /** Returns the full horizontal FOV, i.e. {@link #left} + {@link #right}. */
+    /** Returns the full horizontal FOV, i.e. {@link #left} + {@link #right}, either in {@link #inTangents} or radians. */
     public final float horzFov() { return left+right; }
 
-    /** Returns the full vertical FOV, i.e. {@link #top} + {@link #bottom}. */
+    /** Returns the full vertical FOV, i.e. {@link #top} + {@link #bottom}, either in {@link #inTangents} or radians. */
     public final float vertFov() { return top+bottom; }
 
     public final String toString() {
diff --git a/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java b/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
index 421bb909f..a080d4442 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/Matrix4.java
@@ -147,8 +147,9 @@ public class Matrix4 {
      * @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.
+     * @throws GLException if {@code zNear <= 0} or {@code zFar <= zNear}
+     *                     or {@code left == right}, or {@code bottom == top}.
+     * @see FloatUtil#makeFrustum(float[], int, boolean, float, float, float, float, float, float)
      */
     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) );
@@ -159,7 +160,8 @@ public class Matrix4 {
      * @param aspect
      * @param zNear
      * @param zFar
-     * @throws GLException with GL_INVALID_VALUE if zNear is <= 0, or zFar < 0, or if zNear == zFar.
+     * @throws GLException if {@code zNear <= 0} or {@code zFar <= zNear}
+     * @see FloatUtil#makePerspective(float[], int, boolean, float, float, float, float)
      */
     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/math/geom/Frustum.java b/src/jogl/classes/com/jogamp/opengl/math/geom/Frustum.java
index b73bad613..8b0fa559e 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/geom/Frustum.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/geom/Frustum.java
@@ -30,6 +30,8 @@ package com.jogamp.opengl.math.geom;
 import jogamp.common.os.PlatformPropsImpl;
 
 import com.jogamp.common.os.Platform;
+import com.jogamp.opengl.math.FloatUtil;
+import com.jogamp.opengl.math.FovHVHalves;
 
 /**
  * Providing frustum {@link #getPlanes() planes} derived by different inputs
@@ -77,6 +79,35 @@ import com.jogamp.common.os.Platform;
  * 

  */
 public class Frustum {
+    /**
+     * {@link Frustum} description by {@link #fovhv} and {@link #zNear}, {@link #zFar}.
+     */
+    public static class FovDesc {
+        /** Field of view in both directions, may not be centered, either {@link FovHVHalves#inTangents} or radians. */
+        public final FovHVHalves fovhv;
+        /** Near Z */
+        public final float zNear;
+        /** Far Z */
+        public final float zFar;
+        /**
+         * @param fovhv field of view in both directions, may not be centered, either {@link FovHVHalves#inTangents} or radians
+         * @param zNear
+         * @param zFar
+         * @throws IllegalArgumentException if {@code zNear <= 0} or {@code zFar <= zNear}.
+         */
+        public FovDesc(final FovHVHalves fovhv, final float zNear, final float zFar) throws IllegalArgumentException {
+            if( zNear <= 0.0f || zFar <= zNear ) {
+                throw new IllegalArgumentException("Requirements zNear > 0 and zFar > zNear, but zNear "+zNear+", zFar "+zFar);
+            }
+            this.fovhv = fovhv;
+            this.zNear = zNear;
+            this.zFar = zFar;
+        }
+        public final String toString() {
+            return "FrustumFovDesc["+fovhv.toStringInDegrees()+", Z["+zNear+" - "+zFar+"]]";
+        }
+    }
+
     /** Normalized planes[l, r, b, t, n, f] */
 	protected final Plane[] planes = new Plane[6];
 
@@ -176,17 +207,45 @@ public class Frustum {
      */
     public final void updateByPlanes(final Plane[] src) {
         for (int i = 0; i < 6; ++i) {
-            final Plane p0 = planes[i];
-            final float[] p0_n = p0.n;
-            final Plane p1 = src[i];
-            final float[] p1_n = p1.n;
-            p0_n[0] = p1_n[0];
-            p0_n[1] = p1_n[1];
-            p0_n[2] = p1_n[2];
-            p0.d = p1.d;
+            final Plane pD = planes[i];
+            final Plane pS = src[i];
+            pD.d = pS.d;
+            System.arraycopy(pS.n, 0, pD.n, 0, 3);
         }
     }
 
+    /**
+     * Calculate the frustum planes in world coordinates
+     * using the passed {@link FovDesc}.
+     * 

+     * Operation Details:
+     * 
    
+     *   
  • The given {@link FovDesc} will be transformed
+     *       into the given float[16] as a perspective matrix (column major order) first,
+     *       see {@link FloatUtil#makePerspective(float[], int, boolean, FovHVHalves, float, float)}.
    • 
+     *   
  • Then the float[16] perspective matrix is used to {@link #updateByPMV(float[], int)} this instance.
    • 
+     * 

+     * 

+     * 

+     * Frustum plane's normals will point to the inside of the viewing frustum,
+     * as required by this class.
+     * 

+     *
+     * @param m 4x4 matrix in column-major order (also result)
+     * @param m_offset offset in given array m, i.e. start of the 4x4 matrix
+     * @param initM if true, given matrix will be initialized w/ identity matrix,
+     *              otherwise only the frustum fields are set.
+     * @param fovDesc {@link Frustum} {@link FovDesc}
+     * @return given matrix for chaining
+     * @see FloatUtil#makePerspective(float[], int, boolean, FovHVHalves, float, float)
+     */
+    public float[] updateByFovDesc(final float[] m, final int m_offset, final boolean initM,
+                                   final FovDesc fovDesc) {
+        FloatUtil.makePerspective(m, m_offset, initM, fovDesc.fovhv, fovDesc.zNear, fovDesc.zFar);
+        updateByPMV(m, 0);
+        return m;
+    }
+
     /**
      * Calculate the frustum planes in world coordinates
      * using the passed float[16] as premultiplied P*MV (column major order).
-- 
cgit v1.2.3