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

1 files changed, 125 insertions, 15 deletions

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) );
     }