API doc cleanup, add + refine math tests

API doc

8 files changed, 36 insertions, 18 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawable.java b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawable.java
index 385acf082..b9ed73650 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawable.java
@@ -175,7 +175,7 @@ public interface GLAutoDrawable extends GLDrawable {
    *   <li>If the old context was current on this thread, it is being released after disassociating this auto-drawable.</li>
    *   <li>If the new context was current on this thread, it is being released before associating this auto-drawable
    *       and made current afterwards.</li>
-   *   <li>Implementation may issue {@link #makeCurrent()} and {@link #release()} while drawable reassociation.</li>
+   *   <li>Implementation may issue {@link GLContext#makeCurrent()} and {@link GLContext#release()} while drawable reassociation.</li>
    *   <li>The user shall take extra care of thread synchronization,
    *       i.e. lock the involved {@link GLAutoDrawable auto-drawable's}
    *       {@link GLAutoDrawable#getUpstreamLock() upstream-locks} and {@link GLAutoDrawable#getNativeSurface() surfaces}
diff --git a/src/jogl/classes/com/jogamp/opengl/GLEventListener.java b/src/jogl/classes/com/jogamp/opengl/GLEventListener.java
index 8c5dfd3b3..6b3786b0d 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLEventListener.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLEventListener.java
@@ -93,10 +93,10 @@ public interface GLEventListener extends EventListener {
    * </p>
    *
    * @param drawable the triggering {@link GLAutoDrawable}
-   * @param x viewport x-coord in pixel units
-   * @param y viewport y-coord in pixel units
-   * @param width viewport width in pixel units
-   * @param height viewport height in pixel units
+   * @param x lower left corner of the viewport rectangle in pixel units
+   * @param y lower left corner of the viewport rectangle in pixel units
+   * @param width width of the viewport rectangle in pixel units
+   * @param height height of the viewport rectangle in pixel units
    */
   public void reshape(GLAutoDrawable drawable, int x, int y, int width, int height);
 }
diff --git a/src/jogl/classes/com/jogamp/opengl/GLRunnable.java b/src/jogl/classes/com/jogamp/opengl/GLRunnable.java
index 97a72d6cd..f8bd56fdc 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLRunnable.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLRunnable.java
@@ -41,6 +41,13 @@ package com.jogamp.opengl;
  * The OpenGL context is current while executing the GLRunnable.
  * </p>
  * <p>
+ * {@link GLRunnable#run(GLAutoDrawable)} shall return true to indicate
+ * that the GL [back] framebuffer remains intact by this runnable. <br/>
+ * If returning false {@link GLAutoDrawable} will call
+ * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)}
+ * of all registered {@link GLEventListener}s once more to reinstate the framebuffer.
+ * </p>
+ * <p>
  * This might be useful to inject OpenGL commands from an I/O event listener.
  * </p>
  */
diff --git a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
index 73244cb13..af1db0c1e 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
@@ -1908,11 +1908,11 @@ public final class FloatUtil {
       final int a0 = aOffset + a.position();
       if(rowMajorOrder) {
           for(int c=0; c<columns; c++) {
-              sb.append( String.format((Locale)null, f+" ", a.get( a0 + row*columns + c ) ) );
+              sb.append( String.format((Locale)null, f+", ", a.get( a0 + row*columns + c ) ) );
           }
       } else {
           for(int r=0; r<columns; r++) {
-              sb.append( String.format((Locale)null, f+" ", a.get( a0 + row + r*rows ) ) );
+              sb.append( String.format((Locale)null, f+", ", a.get( a0 + row + r*rows ) ) );
           }
       }
       return sb;
@@ -1936,11 +1936,11 @@ public final class FloatUtil {
       }
       if(rowMajorOrder) {
           for(int c=0; c<columns; c++) {
-              sb.append( String.format((Locale)null, f+" ", a[ aOffset + row*columns + c ] ) );
+              sb.append( String.format((Locale)null, f+", ", a[ aOffset + row*columns + c ] ) );
           }
       } else {
           for(int r=0; r<columns; r++) {
-              sb.append( String.format((Locale)null, f+" ", a[ aOffset + row + r*rows ] ) );
+              sb.append( String.format((Locale)null, f+", ", a[ aOffset + row + r*rows ] ) );
           }
       }
       return sb;
@@ -1963,11 +1963,15 @@ public final class FloatUtil {
           sb = new StringBuilder();
       }
       final String prefix = ( null == rowPrefix ) ? "" : rowPrefix;
+      sb.append(prefix).append("{ ");
       for(int i=0; i<rows; i++) {
-          sb.append(prefix).append("[ ");
+          if( 0 < i ) {
+              sb.append(prefix).append("  ");
+          }
           matrixRowToString(sb, f, a, aOffset, rows, columns, rowMajorOrder, i);
-          sb.append("]").append(Platform.getNewline());
+          sb.append(Platform.getNewline());
       }
+      sb.append(prefix).append("}").append(Platform.getNewline());
       return sb;
   }
 
@@ -1988,11 +1992,15 @@ public final class FloatUtil {
           sb = new StringBuilder();
       }
       final String prefix = ( null == rowPrefix ) ? "" : rowPrefix;
+      sb.append(prefix).append("{ ");
       for(int i=0; i<rows; i++) {
-          sb.append(prefix).append("[ ");
+          if( 0 < i ) {
+              sb.append(prefix).append("  ");
+          }
           matrixRowToString(sb, f, a, aOffset, rows, columns, rowMajorOrder, i);
-          sb.append("]").append(Platform.getNewline());
+          sb.append(Platform.getNewline());
       }
+      sb.append(prefix).append("}").append(Platform.getNewline());
       return sb;
   }
 
@@ -2314,10 +2322,10 @@ public final class FloatUtil {
 
   /**
    * Returns orthogonal distance
-   * (1f/zNear-1f/orthoDist)/(1f/zNear-1f/zFar);
+   * (1f/zNear-1f/orthoZ) / (1f/zNear-1f/zFar);
    */
   public static float getOrthoWinZ(final float orthoZ, final float zNear, final float zFar) {
-      return (1f/zNear-1f/orthoZ)/(1f/zNear-1f/zFar);
+      return (1f/zNear-1f/orthoZ) / (1f/zNear-1f/zFar);
   }
 
 }
\ No newline at end of file
diff --git a/src/jogl/classes/com/jogamp/opengl/math/Ray.java b/src/jogl/classes/com/jogamp/opengl/math/Ray.java
index 4d651d1c3..a528f0763 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/Ray.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/Ray.java
@@ -1,5 +1,5 @@
 /**
- * Copyright 2014 JogAmp Community. All rights reserved.
+ * Copyright 2014-2023 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:
@@ -53,6 +53,7 @@ public class Ray {
     /** Normalized direction vector of ray, float[3]. */
     public final float[] dir = new float[3];
 
+    @Override
     public String toString() {
         return "Ray[orig["+orig[0]+", "+orig[1]+", "+orig[2]+"], dir["+dir[0]+", "+dir[1]+", "+dir[2]+"]]";
     }
diff --git a/src/jogl/classes/com/jogamp/opengl/math/geom/AABBox.java b/src/jogl/classes/com/jogamp/opengl/math/geom/AABBox.java
index 5a14406b0..f858b1c0d 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/geom/AABBox.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/geom/AABBox.java
@@ -596,6 +596,7 @@ public class AABBox {
      * @param size a constant float value
      * @param tmpV3 caller provided temporary 3-component vector
      * @return this AABBox for chaining
+     * @see #scale2(float, float[])
      */
     public final AABBox scale(final float size, final float[] tmpV3) {
         tmpV3[0] = high[0] - center[0];
@@ -622,6 +623,7 @@ public class AABBox {
      * @param size a constant float value
      * @param tmpV3 caller provided temporary 3-component vector
      * @return this AABBox for chaining
+     * @see #scale(float, float[])
      */
     public final AABBox scale2(final float size, final float[] tmpV3) {
         VectorUtil.scaleVec3(high, high, size); // in-place scale
diff --git a/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java b/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
index 5383f91be..f8f1d3930 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
@@ -373,7 +373,7 @@ public final class PMVMatrix implements GLMatrixFunc {
         return frustum;
     }
 
-    /*
+    /**
      * @return the matrix of the current matrix-mode
      */
     public final FloatBuffer glGetMatrixf() {
diff --git a/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java b/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java
index e4b5eae5c..2228d6977 100644
--- a/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java
+++ b/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java
@@ -225,7 +225,7 @@ public class GLDrawableHelper {
    *   <li>If the old context was current on this thread, it is being released after disassociating the drawable.</li>
    *   <li>If the new context was current on this thread, it is being released before associating the drawable
    *       and made current afterwards.</li>
-   *   <li>Implementation may issue {@link #makeCurrent()} and {@link #release()} while drawable reassociation.</li>
+   *   <li>Implementation may issue {@link GLContext#makeCurrent()} and {@link GLContext#release()} while drawable reassociation.</li>
    *   <li>The user shall take extra care of thread synchronization,
    *       i.e. lock the involved {@link GLDrawable#getNativeSurface() drawable's} {@link NativeSurface}s
    *       to avoid a race condition. In case {@link GLAutoDrawable auto-drawable's} are used,