GraphUI Enhance: API doc; Scene/Button Z-offset and -epsilon; Push temp AffineTransform to local method; Simplify BaseButton setCorner(0) -> setPerp(); Protected abstract ctor ..

9 files changed, 243 insertions, 54 deletions

diff --git a/src/graphui/classes/com/jogamp/graph/ui/GraphShape.java b/src/graphui/classes/com/jogamp/graph/ui/GraphShape.java
index 2c724fa52..c9799baff 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/GraphShape.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/GraphShape.java
@@ -60,11 +60,11 @@ public abstract class GraphShape extends Shape {
     private final List<GLRegion> dirtyRegions = new ArrayList<GLRegion>();
 
     /**
-     * Create a Graph based {@link GLRegion} UI {@link Shape}.
+     * Create a generic Graph based {@link GLRegion} UI {@link Shape}.
      *
      * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
      */
-    public GraphShape(final int renderModes) {
+    protected GraphShape(final int renderModes) {
         super();
         this.renderModes = renderModes;
     }
diff --git a/src/graphui/classes/com/jogamp/graph/ui/Scene.java b/src/graphui/classes/com/jogamp/graph/ui/Scene.java
index 1a55b39c7..ded7a9336 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/Scene.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/Scene.java
@@ -106,8 +106,10 @@ public final class Scene implements Container, GLEventListener {
     public static final float DEFAULT_ZNEAR = 0.1f;
     /** Default projection z-far value is {@value}. */
     public static final float DEFAULT_ZFAR = 7000.0f;
-    /** Default Z precision on 16-bit depth buffer using {@link #DEFAULT_SCENE_DIST} z-position and {@link #DEFAULT_ZNEAR}. Value is {@code 0.0000061033...}*/
+    /** Default Z precision on 16-bit depth buffer using {@link #DEFAULT_SCENE_DIST} z-position and {@link #DEFAULT_ZNEAR}. Value is {@code 6.1033297E-6}. */
     public static final float DEFAULT_Z16_EPSILON = FloatUtil.getZBufferEpsilon(16 /* zBits */, DEFAULT_SCENE_DIST, DEFAULT_ZNEAR);
+    /** Default Z precision on 16-bit depth buffer using {@code -1} z-position and {@link #DEFAULT_ZNEAR}. Value is {@code 1.5256461E-4}. */
+    // public static final float DIST1_Z16_EPSILON = FloatUtil.getZBufferEpsilon(16 /* zBits */, -1, DEFAULT_ZNEAR);
 
     /**
      * Return Z precision on using {@link PMVMatrixSetup#getSceneDist()} z-position and {@link PMVMatrixSetup#getZNear()}.
diff --git a/src/graphui/classes/com/jogamp/graph/ui/Shape.java b/src/graphui/classes/com/jogamp/graph/ui/Shape.java
index b1e4081db..43c95c92a 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/Shape.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/Shape.java
@@ -167,7 +167,10 @@ public abstract class Shape {
     private Listener onToggleListener = null;
     private Listener onClickedListener = null;
 
-    public Shape() {
+    /**
+     * Create a generic UI {@link Shape}
+     */
+    protected Shape() {
         this.box = new AABBox();
     }
 
diff --git a/src/graphui/classes/com/jogamp/graph/ui/shapes/BaseButton.java b/src/graphui/classes/com/jogamp/graph/ui/shapes/BaseButton.java
index 7c3b1119e..83835a913 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/shapes/BaseButton.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/shapes/BaseButton.java
@@ -28,19 +28,23 @@
 package com.jogamp.graph.ui.shapes;
 
 import com.jogamp.graph.curve.OutlineShape;
+import com.jogamp.graph.curve.Region;
+import com.jogamp.graph.curve.opengl.GLRegion;
 import com.jogamp.graph.ui.GraphShape;
+import com.jogamp.graph.ui.Shape;
 import com.jogamp.opengl.GL2ES2;
 import com.jogamp.opengl.GLProfile;
+import com.jogamp.opengl.util.texture.TextureSequence;
 
 /**
- * An abstract GraphUI base filled button {@link GraphShape},
+ * An abstract GraphUI filled base button {@link GraphShape},
  * usually used as a backdrop or base shape for more informative button types.
  * <p>
  * GraphUI is GPU based and resolution independent.
  * </p>
  * <p>
  * This button is rendered with a round oval shape {@link #ROUND_CORNER by default},
- * but can be set to {@link #PERP_CORNER rectangular shape}.
+ * but can be set to any roundness or {@link #PERP_CORNER rectangular shape} via {#link {@link #setCorner(float)} or {@link #setPerp()}.
  * </p>
  */
 public class BaseButton extends GraphShape {
@@ -54,6 +58,15 @@ public class BaseButton extends GraphShape {
     protected float height;
     protected float corner = ROUND_CORNER;
 
+    /**
+     * Create a base button Graph based {@link GLRegion} UI {@link Shape} with a {@link #ROUND_CORNER}.
+     * <p>
+     * Call {#link {@link #setCorner(float)} or {@link #setPerp()} to modify the corner shape.
+     * </p>
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param width
+     * @param height
+     */
     public BaseButton(final int renderModes, final float width, final float height) {
         super(renderModes);
         this.width = width;
@@ -70,26 +83,36 @@ public class BaseButton extends GraphShape {
      * Set corner size with range [0.01 .. 1.00] for round corners
      * or `zero` for perpendicular corners.
      * <p>
-     *  , default is {@link #ROUND_CORNER round corner},
+     * Default is {@link #ROUND_CORNER round corner},
      * alternative a {@link #PERP_CORNER perpendicular corner} for a rectangular shape is available.
      * </p>
+     * @param corner corner size with range [0.01 .. 1.00 ] for round corners or `zero` for perpendicular corners.
+     * @return this instance for chaining
      * @see #ROUND_CORNER
      * @see #PERP_CORNER
+     * @see #setPerp()
      */
     public BaseButton setCorner(final float corner) {
-        if( 0.01f <= corner && corner <= 1.0f ) {
-            this.corner = corner;
-        }
         if( corner > 1.0f ){
-            this.corner = 1.0f;
+            this.corner = ROUND_CORNER;
         } else if( corner < 0.01f ){
-            this.corner = 0.0f;
+            this.corner = PERP_CORNER;
         } else {
             this.corner = corner;
         }
         markShapeDirty();
         return this;
     }
+    /**
+     * Sets a {@link #PERP_CORNER perpendicular} {@link #setCorner(float) corner}.
+     * @return this instance for chaining
+     * @see #setCorner(float)
+     */
+    public BaseButton setPerp() {
+        this.corner = PERP_CORNER;
+        markShapeDirty();
+        return this;
+    }
 
     public BaseButton setSize(final float width, final float height) {
         this.width = width;
diff --git a/src/graphui/classes/com/jogamp/graph/ui/shapes/Button.java b/src/graphui/classes/com/jogamp/graph/ui/shapes/Button.java
index dfc17c2f7..72589937d 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/shapes/Button.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/shapes/Button.java
@@ -31,17 +31,21 @@ import com.jogamp.opengl.GL2ES2;
 import com.jogamp.opengl.GLProfile;
 import com.jogamp.graph.curve.OutlineShape;
 import com.jogamp.graph.curve.Region;
+import com.jogamp.graph.curve.opengl.GLRegion;
 import com.jogamp.graph.curve.opengl.RegionRenderer;
 import com.jogamp.graph.curve.opengl.TextRegionUtil;
 import com.jogamp.graph.font.Font;
 import com.jogamp.graph.geom.plane.AffineTransform;
 import com.jogamp.graph.ui.GraphShape;
 import com.jogamp.graph.ui.Scene;
+import com.jogamp.graph.ui.Shape;
+import com.jogamp.graph.ui.Scene.PMVMatrixSetup;
 import com.jogamp.opengl.math.FloatUtil;
 import com.jogamp.opengl.math.Vec2f;
 import com.jogamp.opengl.math.Vec3f;
 import com.jogamp.opengl.math.Vec4f;
 import com.jogamp.opengl.math.geom.AABBox;
+import com.jogamp.opengl.util.texture.TextureSequence;
 
 import jogamp.graph.ui.shapes.Label0;
 
@@ -61,43 +65,107 @@ public class Button extends BaseButton {
     /** {@value} */
     public static final float DEFAULT_SPACING_Y = 0.42f;
 
-    private static final float DEFAULT_LABEL_ZOFFSET = 0.00016f; // 16 zBits, -1 zDist, 0.1 zNear, i.e. FloatUtil.getZBufferEpsilon(16, -1f, 0.1f)
+    /**
+     * Default {@link #setLabelZOffset(float) Z-axis offset},
+     * using the smallest resolvable Z separation rounded value {@value} at 16-bits depth buffer, -1 z-distance and 0.1 z-near,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * <p>
+     * {@link FloatUtil#getZBufferEpsilon(int, float, float)}
+     * <pre>
+     * 1.5256461E-4 = 16 zBits, -0.2 zDist, 0.1 zNear
+     * 6.1033297E-6 = 16 zBits, -1.0 zDist, 0.1 zNear
+     * </pre>
+     * </p>
+     */
+    public static final float DEFAULT_LABEL_ZOFFSET = 0.000153f; // 0.00015256461 = 16 zBits, -1 zDist, 0.1 zNear, i.e. FloatUtil.getZBufferEpsilon(16, -1f, 0.1f)
     private float labelZOffset;
 
     private final Label0 label;
     private float spacingX = DEFAULT_SPACING_X;
     private float spacingY = DEFAULT_SPACING_Y;
 
-    private final AffineTransform tempT1 = new AffineTransform();
-    private final AffineTransform tempT2 = new AffineTransform();
-    private final AffineTransform tempT3 = new AffineTransform();
-
-    public Button(final int renderModes, final Font labelFont,
-                  final String labelText, final float width, final float height) {
+    /**
+     * Create a text labeled button Graph based {@link GLRegion} UI {@link Shape}.
+     * <p>
+     * Sets the {@link #setLabelZOffset(float) Z-axis offset} to
+     * a default smallest resolvable Z separation rounded value {@code 0.000153} at 16-bits depth buffer, -1 z-distance and 0.1 z-near,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * </p>
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param labelFont {@link Font} for the label
+     * @param labelText the label text
+     * @param width width of the button
+     * @param height height of the button
+     * @see #Button(int, Font, CharSequence, float, float, float)
+     */
+    public Button(final int renderModes, final Font labelFont, final CharSequence labelText,
+                  final float width, final float height) {
         this(renderModes, labelFont, labelText, width, height, DEFAULT_LABEL_ZOFFSET);
     }
 
-    public Button(final int renderModes, final Font labelFont,
-                  final String labelText, final float width, final float height,
-                  final int zBits, final Scene.PMVMatrixSetup setup) {
+    /**
+     * Create a text labeled button Graph based {@link GLRegion} UI {@link Shape}.
+     * <p>
+     * Sets the {@link #setLabelZOffset(float) Z-axis offset} to the smallest resolvable Z separation at the given range,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * </p>
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param labelFont {@link Font} for the label
+     * @param labelText the label text
+     * @param width width of the button
+     * @param height height of the button
+     * @param zBits depth buffer bit-depth, minimum 16-bit
+     * @param setup {@link PMVMatrixSetup} for scene-distance as z-position and zNear
+     * @see FloatUtil#getZBufferEpsilon(int, float, float)
+     * @see Scene#getZEpsilon(int, com.jogamp.graph.ui.Scene.PMVMatrixSetup)
+     */
+    public Button(final int renderModes, final Font labelFont, final CharSequence labelText,
+                  final float width, final float height, final int zBits, final Scene.PMVMatrixSetup setup) {
         this(renderModes, labelFont, labelText, width, height, Scene.getZEpsilon(zBits, setup));
     }
 
-    public Button(final int renderModes, final Font labelFont,
-                  final String labelText, final float width, final float height,
-                  final int zBits, final Scene scene) {
+    /**
+     * Create a text labeled button Graph based {@link GLRegion} UI {@link Shape}.
+     * <p>
+     * Sets the {@link #setLabelZOffset(float) Z-axis offset} to the smallest resolvable Z separation at the given range,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * </p>
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param labelFont {@link Font} for the label
+     * @param labelText the label text
+     * @param width width of the button
+     * @param height height of the button
+     * @param zBits depth buffer bit-depth, minimum 16-bit
+     * @param scene {@link Scene} to use {@link Scene#getZEpsilon(int)}
+     * @see FloatUtil#getZBufferEpsilon(int, float, float)
+     * @see Scene#getZEpsilon(int)
+     */
+    public Button(final int renderModes, final Font labelFont, final CharSequence labelText,
+                  final float width, final float height, final int zBits, final Scene scene) {
         this(renderModes, labelFont, labelText, width, height, scene.getZEpsilon(zBits));
     }
 
-    public Button(final int renderModes, final Font labelFont, final String labelText,
+    /**
+     * Create a text labeled button Graph based {@link GLRegion} UI {@link Shape}.
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param labelFont {@link Font} for the label
+     * @param labelText the label text
+     * @param width width of the button
+     * @param height height of the button
+     * @param zOffset the Z-axis offset, used to separate the {@link BaseButton} from the {@link Label}
+     * @see FloatUtil#getZBufferEpsilon(int, float, float)
+     */
+    public Button(final int renderModes, final Font labelFont, final CharSequence labelText,
                   final float width, final float height, final float zOffset) {
         super(renderModes | Region.COLORCHANNEL_RENDERING_BIT, width, height);
         this.labelZOffset = zOffset;
         this.label = new Label0(labelFont, labelText, new Vec4f( 1.66f, 1.66f, 1.66f, 1.0f )); // 0.60 * 1.66 ~= 1.0
     }
 
+    /** Returns the label {@link Font}. */
     public Font getFont() { return label.getFont(); }
-    public String getLaben() { return label.getText(); }
+    /** Returns the label text. */
+    public CharSequence getText() { return label.getText(); }
 
     @Override
     public void draw(final GL2ES2 gl, final RegionRenderer renderer, final int[] sampleCount) {
@@ -111,6 +179,10 @@ public class Button extends BaseButton {
 
     @Override
     protected void addShapeToRegion(final GLProfile glp, final GL2ES2 gl) {
+        final AffineTransform tempT1 = new AffineTransform();
+        final AffineTransform tempT2 = new AffineTransform();
+        final AffineTransform tempT3 = new AffineTransform();
+
         final OutlineShape shape = createBaseShape( FloatUtil.isZero(labelZOffset) ? 0f : -labelZOffset );
         box.resize(shape.getBounds());
         setRotationPivot( box.getCenter() );
@@ -158,17 +230,55 @@ public class Button extends BaseButton {
 
     public float getLabelZOffset() { return labelZOffset; }
 
+    /**
+     * Set the Z-axis offset to the given value,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * @param v the zoffset
+     * @return this instance for chaining
+     * @see FloatUtil#getZBufferEpsilon(int, float, float)
+     */
     public Button setLabelZOffset(final float v) {
         labelZOffset = v;
         markShapeDirty();
         return this;
     }
+
+    /**
+     * Set the Z-axis offset to the smallest resolvable Z separation at the given range,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * @param zBits number of bits of Z precision, i.e. z-buffer depth
+     * @param zDist distance from the eye to the object
+     * @param zNear distance from eye to near clip plane
+     * @return this instance for chaining
+     * @see FloatUtil#getZBufferEpsilon(int, float, float)
+     * @see Scene#getZEpsilon(int, com.jogamp.graph.ui.Scene.PMVMatrixSetup)
+     */
     public Button setLabelZOffset(final int zBits, final float zDist, final float zNear) {
         return setLabelZOffset( FloatUtil.getZBufferEpsilon(zBits, zDist, zNear) );
     }
+
+    /**
+     * Set the Z-axis offset to the smallest resolvable Z separation at the given range,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * @param zBits depth buffer bit-depth, minimum 16-bit
+     * @param setup {@link PMVMatrixSetup} for scene-distance as z-position and zNear
+     * @return this instance for chaining
+     * @see FloatUtil#getZBufferEpsilon(int, float, float)
+     * @see Scene#getZEpsilon(int, com.jogamp.graph.ui.Scene.PMVMatrixSetup)
+     */
     public Button setLabelZOffset(final int zBits, final Scene.PMVMatrixSetup setup) {
         return setLabelZOffset( Scene.getZEpsilon(zBits, setup) );
     }
+
+    /**
+     * Set the Z-axis offset to the smallest resolvable Z separation at the given range,
+     * used to separate the {@link BaseButton} from the {@link Label}.
+     * @param zBits depth buffer bit-depth, minimum 16-bit
+     * @param scene {@link Scene} to use {@link Scene#getZEpsilon(int)}
+     * @return this instance for chaining
+     * @see FloatUtil#getZBufferEpsilon(int, float, float)
+     * @see Scene#getZEpsilon(int)
+     */
     public Button setLabelZOffset(final int zBits, final Scene scene) {
         return setLabelZOffset( scene.getZEpsilon(zBits) );
     }
diff --git a/src/graphui/classes/com/jogamp/graph/ui/shapes/Label.java b/src/graphui/classes/com/jogamp/graph/ui/shapes/Label.java
index 4904f4d42..3192488c2 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/shapes/Label.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/shapes/Label.java
@@ -30,7 +30,10 @@ package com.jogamp.graph.ui.shapes;
 import com.jogamp.opengl.GL2ES2;
 import com.jogamp.opengl.GLProfile;
 import com.jogamp.opengl.math.geom.AABBox;
+import com.jogamp.opengl.util.texture.TextureSequence;
 import com.jogamp.graph.curve.OutlineShape;
+import com.jogamp.graph.curve.Region;
+import com.jogamp.graph.curve.opengl.GLRegion;
 import com.jogamp.graph.curve.opengl.RegionRenderer;
 import com.jogamp.graph.curve.opengl.TextRegionUtil;
 import com.jogamp.graph.font.Font;
@@ -47,20 +50,20 @@ import com.jogamp.graph.ui.GraphShape;
 public class Label extends GraphShape {
     private Font font;
     private float fontScale;
-    private String text;
-
-    private final AffineTransform tempT1 = new AffineTransform();
-    private final AffineTransform tempT2 = new AffineTransform();
-    private final AffineTransform tempT3 = new AffineTransform();
+    private CharSequence text;
 
     /**
-     * Label ctor using a separate {@code fontScale} to scale the em-sized type glyphs
-     * @param renderModes region renderModes
-     * @param font the font
+     * Label ctor using a separate {@code fontScale} to scale the em-sized type glyphs.
+     * <p>
+     * If possible, try using {@link Label#Label(int, Font, CharSequence)} and {@link #scale(float, float, float)}.
+     * </p>
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param font {@link Font} for this label
      * @param fontScale font-scale factor, by which the em-sized type glyphs shall be scaled
-     * @param text the text to render
+     * @param text the label text
+     * @see #Label(int, Font, CharSequence)
      */
-    public Label(final int renderModes, final Font font, final float fontScale, final String text) {
+    public Label(final int renderModes, final Font font, final float fontScale, final CharSequence text) {
         super(renderModes);
         this.font = font;
         this.fontScale = fontScale;
@@ -69,19 +72,17 @@ public class Label extends GraphShape {
 
     /**
      * Label ctor using em-size type glyphs
-     * @param renderModes region renderModes
-     * @param font the font
-     * @param text the text to render
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param font {@link Font} for this label
+     * @param text the label text
+     * @see #Label(int, Font, float, CharSequence)
      */
-    public Label(final int renderModes, final Font font, final String text) {
-        super(renderModes);
-        this.font = font;
-        this.fontScale = 1f;
-        this.text = text;
+    public Label(final int renderModes, final Font font, final CharSequence text) {
+        this(renderModes, font, 1f, text);
     }
 
-    /** Return the text to be rendered. */
-    public String getText() {
+    /** Returns the label text. */
+    public CharSequence getText() {
         return text;
     }
 
@@ -131,7 +132,7 @@ public class Label extends GraphShape {
     }
 
     /**
-     * Return the {@link Font} used to render the text
+     * Returns the {@link Font} used to render the text
      */
     public Font getFont() {
         return font;
@@ -153,7 +154,7 @@ public class Label extends GraphShape {
     }
 
     /**
-     * Gets the font-scale factor, by which the em-sized type glyphs shall be scaled.
+     * Returns the font-scale factor, by which the em-sized type glyphs shall be scaled.
      */
     public float getFontScale() {
         return fontScale;
@@ -203,6 +204,10 @@ public class Label extends GraphShape {
 
     @Override
     protected void addShapeToRegion(final GLProfile glp, final GL2ES2 gl) {
+        final AffineTransform tempT1 = new AffineTransform();
+        final AffineTransform tempT2 = new AffineTransform();
+        final AffineTransform tempT3 = new AffineTransform();
+
         final int[] vertIndCount = TextRegionUtil.countStringRegion(font, text, new int[2]);
         resetGLRegion(glp, gl, null, vertIndCount[0], vertIndCount[1]);
 
@@ -217,6 +222,6 @@ public class Label extends GraphShape {
     @Override
     public String getSubString() {
         final int m = Math.min(text.length(), 8);
-        return super.getSubString()+", fscale " + fontScale + ", '" + text.substring(0, m)+"'";
+        return super.getSubString()+", fscale " + fontScale + ", '" + text.subSequence(0, m)+"'";
     }
 }
diff --git a/src/graphui/classes/com/jogamp/graph/ui/shapes/Rectangle.java b/src/graphui/classes/com/jogamp/graph/ui/shapes/Rectangle.java
index 2b9698e3a..7f9375fc6 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/shapes/Rectangle.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/shapes/Rectangle.java
@@ -28,10 +28,14 @@
 package com.jogamp.graph.ui.shapes;
 
 import com.jogamp.graph.curve.OutlineShape;
+import com.jogamp.graph.curve.Region;
+import com.jogamp.graph.curve.opengl.GLRegion;
 import com.jogamp.graph.ui.GraphShape;
+import com.jogamp.graph.ui.Shape;
 import com.jogamp.opengl.GL2ES2;
 import com.jogamp.opengl.GLProfile;
 import com.jogamp.opengl.math.geom.AABBox;
+import com.jogamp.opengl.util.texture.TextureSequence;
 
 /**
  * A GraphUI rectangle {@link GraphShape}
@@ -45,6 +49,17 @@ public class Rectangle extends GraphShape {
     private float height;
     private float lineWidth;
 
+    /**
+     * Create a rectangular Graph based {@link GLRegion} UI {@link Shape}.
+     *
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param minX
+     * @param minY
+     * @param width
+     * @param height
+     * @param lineWidth
+     * @param zPos
+     */
     public Rectangle(final int renderModes, final float minX, final float minY, final float width, final float height, final float lineWidth, final float zPos) {
         super(renderModes);
         this.minX = minX;
@@ -55,13 +70,39 @@ public class Rectangle extends GraphShape {
         this.lineWidth = lineWidth;
     }
 
+    /**
+     * Create a rectangular Graph based {@link GLRegion} UI {@link Shape}.
+     *
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param abox
+     * @param lineWidth
+     */
     public Rectangle(final int renderModes, final AABBox abox, final float lineWidth) {
         this( renderModes, abox.getMinX(), abox.getMinY(), abox.getWidth(), abox.getHeight(), lineWidth, abox.getCenter().z());
     }
 
+    /**
+     * Create a rectangular Graph based {@link GLRegion} UI {@link Shape}.
+     *
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param minX
+     * @param minY
+     * @param width
+     * @param height
+     * @param lineWidth
+     */
     public Rectangle(final int renderModes, final float minX, final float minY, final float width, final float height, final float lineWidth) {
         this( renderModes, minX, minY, width, height, lineWidth, 0);
     }
+
+    /**
+     * Create a rectangular Graph based {@link GLRegion} UI {@link Shape}.
+     *
+     * @param renderModes Graph's {@link Region} render modes, see {@link GLRegion#create(GLProfile, int, TextureSequence) create(..)}.
+     * @param width
+     * @param height
+     * @param lineWidth
+     */
     public Rectangle(final int renderModes, final float width, final float height, final float lineWidth) {
         this( renderModes, 0, 0, width, height, lineWidth, 0);
     }
diff --git a/src/graphui/classes/jogamp/graph/ui/shapes/Label0.java b/src/graphui/classes/jogamp/graph/ui/shapes/Label0.java
index e5f7dd26c..74dcb8491 100644
--- a/src/graphui/classes/jogamp/graph/ui/shapes/Label0.java
+++ b/src/graphui/classes/jogamp/graph/ui/shapes/Label0.java
@@ -37,16 +37,16 @@ import com.jogamp.opengl.math.geom.AABBox;
 
 public class Label0 {
     protected Font font;
-    protected String text;
+    protected CharSequence text;
     protected final Vec4f rgbaColor;
 
-    public Label0(final Font font, final String text, final Vec4f rgbaColor) {
+    public Label0(final Font font, final CharSequence text, final Vec4f rgbaColor) {
         this.font = font;
         this.text = text;
         this.rgbaColor = rgbaColor;
     }
 
-    public final String getText() { return text; }
+    public final CharSequence getText() { return text; }
 
     public final Vec4f getColor() { return rgbaColor; }
 
@@ -79,6 +79,6 @@ public class Label0 {
     @Override
     public final String toString(){
         final int m = Math.min(text.length(), 8);
-        return "Label0 ['" + text.substring(0, m) + "']";
+        return "Label0 ['" + text.subSequence(0, m) + "']";
     }
 }
diff --git a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
index 34a581681..901ed7181 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/FloatUtil.java
@@ -1576,6 +1576,11 @@ public final class FloatUtil {
    * <pre>
    *  return z * z / ( zNear * (1&lt;&lt;zBits) - z )
    * </pre>
+   * Examples:
+   * <pre>
+   * 1.5256461E-4 = 16 zBits, -0.2 zDist, 0.1 zNear
+   * 6.1033297E-6 = 16 zBits, -1.0 zDist, 0.1 zNear
+   * </pre>
    * @param zBits number of bits of Z precision, i.e. z-buffer depth
    * @param z distance from the eye to the object
    * @param zNear distance from eye to near clip plane