From d5b17eddf7e7f1c33b269a3a2ed8eca959c6d639 Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Mon, 4 Sep 2023 05:16:33 +0200
Subject: GraphUI Enhance: API doc; Scene/Button Z-offset and -epsilon; Push
temp AffineTransform to local method; Simplify BaseButton setCorner(0) ->
setPerp(); Protected abstract ctor ..
---
.../classes/com/jogamp/graph/ui/shapes/Button.java | 140 ++++++++++++++++++---
1 file changed, 125 insertions(+), 15 deletions(-)
(limited to 'src/graphui/classes/com/jogamp/graph/ui/shapes/Button.java')
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) );
}
--
cgit v1.2.3