Graph FontScale: Simplify names, fix API doc and add unit test

11 files changed, 173 insertions, 36 deletions

diff --git a/src/demos/com/jogamp/opengl/demos/graph/GPURendererListenerBase01.java b/src/demos/com/jogamp/opengl/demos/graph/GPURendererListenerBase01.java
index 185699d55..5bceba5eb 100644
--- a/src/demos/com/jogamp/opengl/demos/graph/GPURendererListenerBase01.java
+++ b/src/demos/com/jogamp/opengl/demos/graph/GPURendererListenerBase01.java
@@ -125,7 +125,7 @@ public abstract class GPURendererListenerBase01 implements GLEventListener {
         if( upObj instanceof Window ) {
             final Window window = (Window) upObj;
             final float[] sPpMM = window.getPixelsPerMM(new float[2]);
-            final float[] sDPI = FontScale.perMMToPerInch( new float[] { sPpMM[0], sPpMM[1] } );
+            final float[] sDPI = FontScale.ppmmToPPI( new float[] { sPpMM[0], sPpMM[1] } );
             System.err.println("DPI "+sDPI[0]+" x "+sDPI[1]+", "+sPpMM[0]+" x "+sPpMM[1]+" pixel/mm");
 
             final float[] hasSurfacePixelScale1 = window.getCurrentSurfaceScale(new float[2]);
diff --git a/src/demos/com/jogamp/opengl/demos/graph/GPUTextNewtDemo.java b/src/demos/com/jogamp/opengl/demos/graph/GPUTextNewtDemo.java
index bbdf4bfbb..ad5434b09 100644
--- a/src/demos/com/jogamp/opengl/demos/graph/GPUTextNewtDemo.java
+++ b/src/demos/com/jogamp/opengl/demos/graph/GPUTextNewtDemo.java
@@ -149,7 +149,7 @@ public class GPUTextNewtDemo {
 
         {
             final Font font2 = textGLListener.getFont();
-            final float[] sDPI = FontScale.perMMToPerInch( window.getPixelsPerMM(new float[2]) );
+            final float[] sDPI = FontScale.ppmmToPPI( window.getPixelsPerMM(new float[2]) );
             final float font_ptpi = 12f;
             final float font_ppi = FontScale.toPixels(font_ptpi, sDPI[1]);
             final AABBox fontNameBox = font2.getMetricBounds(GPUTextRendererListenerBase01.textX1);
diff --git a/src/demos/com/jogamp/opengl/demos/graph/GPUTextRendererListenerBase01.java b/src/demos/com/jogamp/opengl/demos/graph/GPUTextRendererListenerBase01.java
index 0b506af72..dadbcd373 100644
--- a/src/demos/com/jogamp/opengl/demos/graph/GPUTextRendererListenerBase01.java
+++ b/src/demos/com/jogamp/opengl/demos/graph/GPUTextRendererListenerBase01.java
@@ -232,7 +232,7 @@ public abstract class GPUTextRendererListenerBase01 extends GPURendererListenerB
         if( upObj instanceof Window ) {
             upstream_window = (Window) upObj;
             final float[] sPpMM = upstream_window.getPixelsPerMM(new float[2]);
-            final float[] sDPI = FontScale.perMMToPerInch( new float[] { sPpMM[0], sPpMM[1] } );
+            final float[] sDPI = FontScale.ppmmToPPI( new float[] { sPpMM[0], sPpMM[1] } );
             dpiV = sDPI[1];
             ppmmV = sPpMM[1];
             System.err.println("Using vertical screen DPI of "+dpiV+", "+ppmmV+" pixel/mm");
diff --git a/src/demos/com/jogamp/opengl/demos/graph/TextRendererGLELBase.java b/src/demos/com/jogamp/opengl/demos/graph/TextRendererGLELBase.java
index c0093c6c8..22f2d096a 100644
--- a/src/demos/com/jogamp/opengl/demos/graph/TextRendererGLELBase.java
+++ b/src/demos/com/jogamp/opengl/demos/graph/TextRendererGLELBase.java
@@ -141,7 +141,7 @@ public abstract class TextRendererGLELBase implements GLEventListener {
 
         final Object upObj = drawable.getUpstreamWidget();
         if( upObj instanceof Window ) {
-            final float[] dpi = FontScale.perMMToPerInch( ((Window)upObj).getPixelsPerMM(new float[2]) );
+            final float[] dpi = FontScale.ppmmToPPI( ((Window)upObj).getPixelsPerMM(new float[2]) );
             dpiH = dpi[1];
         }
     }
diff --git a/src/jogl/classes/com/jogamp/graph/font/FontScale.java b/src/jogl/classes/com/jogamp/graph/font/FontScale.java
index a0f2ef4e0..da8df807f 100644
--- a/src/jogl/classes/com/jogamp/graph/font/FontScale.java
+++ b/src/jogl/classes/com/jogamp/graph/font/FontScale.java
@@ -1,48 +1,100 @@
+/**
+ * Copyright 2010-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:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
 package com.jogamp.graph.font;
 
 /**
- * Simple static font scale methods for unit conversion.
+ * Simple static font scale methods for unit conversions.
+ *
+ * PostScript - current DTP point system used e.g in CSS (Cascading Style Sheets).
+ * - 1 point = 1pt = 1/72in (cala) = 0.3528 mm
+ * - 1 pica = 1pc = 12pt= 1/6in (cala) = 4.233(3) mm
  */
 public class FontScale {
     /**
-     * Converts typical font size in points (per-inch) and screen resolution in dpi to font size in pixels (per-inch),
-     * which can be used for pixel-size font scaling operations.
-     * <p>
-     * Note that 1em == size of the selected font.<br/>
-     * In case the pixel per em size is required (advance etc),
-     * the resulting pixel-size (per-inch) of this method shall be used if rendering directly into the screen resolution!
-     * </p>
+     * Converts the the given points size to inch, dividing by {@code 72} points per inch.
+     * <pre>
+         1 points = 1/72 inch
+     *
+     * </pre>
+     */
+    public static float ptToInch(final float points) {
+        return points / 72f /* points per inch */;
+    }
+
+    /**
+     * Converts the the given points size to mm, dividing by {@code 72 * 25.4} points per inch.
      * <pre>
-        Font Scale Formula:
          1 inch = 25.4 mm
+         1 points = 1/72 inch
+         1 points = 1/72 * 25.4 mm
+     *
+     * </pre>
+     */
+    public static float ptToMM(final float points) {
+        return points / 72f /* points per inch */ * 25.4f /* mm_per_inch */;
+    }
 
-         1 inch = 72 points
-         pointSize: [point] = [1/72 inch]
+    /**
+     * Converts typical font size in points and screen resolution in dpi (pixels-per-inch) to font size in pixels,
+     * which can be used for pixel-size font scaling operations.
+     * <pre>
+        Font Scale Formula:
+         1 points = 1/72 inch
 
-         [1]      Scale := pointSize * resolution / ( 72 points per inch * units_per_em )
-         [2]  PixelSize := pointSize * resolution / ( 72 points per inch )
-         [3]      Scale := PixelSize / units_per_em
+         pixels = points / 72 * res_dpi
      * </pre>
-     * @param font_sz_pt in points (per-inch)
-     * @param res_dpi display resolution in dots-per-inch
-     * @return pixel-per-inch, pixelSize scale factor for font operations.
+     * @param points in points
+     * @param res_dpi display resolution in pixels-per-inch
+     * @return pixelSize scale factor for font operations.
      * @see #toPixels2(float, float)
      */
-    public static float toPixels(final float font_sz_pt /* points per inch */, final float res_dpi /* dots per inch */) {
-        return ( font_sz_pt / 72f /* points per inch */ ) * res_dpi;
+    public static float toPixels(final float points /* points */, final float res_dpi /* pixels per inch */) {
+        return ptToInch( points ) * res_dpi;
     }
 
     /**
-     * Converts typical font size in points-per-inch and screen resolution in points-per-mm to font size in pixels (per-inch),
+     * Converts typical font size in points and screen resolution in pixels (pixels-per-mm) to font size in pixels,
      * which can be used for pixel-size font scaling operations.
-     *
-     * @param font_sz_pt in points (per-inch)
-     * @param res_ppmm display resolution in dots-per-mm
-     * @return pixel-per-inch, pixelSize scale factor for font operations.
+     * <pre>
+        Font Scale Formula:
+         1 inch = 25.4 mm
+         1 points = 1/72 inch
+         1 points = 1/72 * 25.4 mm
+
+         pixels = points / 72 * 25.4 * res_ppmm
+     * </pre>
+     * @param points in points
+     * @param res_ppmm display resolution in pixels-per-mm
+     * @return pixelSize scale factor for font operations.
      * @see #toPixels(float, float)
      */
-    public static float toPixels2(final float font_sz_pt /* points per inch */, final float res_ppmm /* pixels per mm */) {
-        return ( font_sz_pt / 72f /* points per inch */ ) * ( res_ppmm * 25.4f /* mm per inch */ ) ;
+    public static float toPixels2(final float points /* points */, final float res_ppmm /* pixels per mm */) {
+        return ptToMM( points ) * res_ppmm;
     }
 
     /**
@@ -50,7 +102,7 @@ public class FontScale {
      * @param ppmm float[2] [1/mm] value
      * @return return [1/inch] value
      */
-    public static float[/*2*/] perMMToPerInch(final float[/*2*/] ppmm) {
+    public static float[/*2*/] ppmmToPPI(final float[/*2*/] ppmm) {
         ppmm[0] *= 25.4f;
         ppmm[1] *= 25.4f;
         return ppmm;
@@ -67,4 +119,27 @@ public class FontScale {
         res[1] = ppmm[1] * 25.4f;
         return res;
     }
+
+    /**
+     * Converts [1/inch] to [1/mm] in place
+     * @param ppi float[2] [1/inch] value
+     * @return return [1/mm] value
+     */
+    public static float[/*2*/] ppiToPPMM(final float[/*2*/] ppi) {
+        ppi[0] /= 25.4f;
+        ppi[1] /= 25.4f;
+        return ppi;
+    }
+
+    /**
+     * Converts [1/inch] to [1/mm] into res storage
+     * @param ppi float[2] [1/inch] value
+     * @param res the float[2] result storage
+     * @return return [1/mm] value, i.e. the given res storage
+     */
+    public static float[/*2*/] ppiToPPMM(final float[/*2*/] ppi, final float[/*2*/] res) {
+        res[0] = ppi[0] / 25.4f;
+        res[1] = ppi[1] / 25.4f;
+        return res;
+    }
 }
diff --git a/src/newt/classes/com/jogamp/newt/opengl/util/NEWTDemoListener.java b/src/newt/classes/com/jogamp/newt/opengl/util/NEWTDemoListener.java
index 563c09474..3960f6eb3 100644
--- a/src/newt/classes/com/jogamp/newt/opengl/util/NEWTDemoListener.java
+++ b/src/newt/classes/com/jogamp/newt/opengl/util/NEWTDemoListener.java
@@ -475,7 +475,7 @@ public class NEWTDemoListener extends WindowAdapter implements KeyListener, Mous
         final CapabilitiesImmutable reqCaps = win.getRequestedCapabilities();
         final CapabilitiesImmutable caps = null != chosenCaps ? chosenCaps : reqCaps;
         final String capsA = caps.isBackgroundOpaque() ? "opaque" : "transl";
-        final float[] sDPI = FontScale.perMMToPerInch( win.getPixelsPerMM(new float[2]) );
+        final float[] sDPI = FontScale.ppmmToPPI( win.getPixelsPerMM(new float[2]) );
         final float[] minSurfacePixelScale = win.getMinimumSurfaceScale(new float[2]);
         final float[] maxSurfacePixelScale = win.getMaximumSurfaceScale(new float[2]);
         final float[] reqSurfacePixelScale = win.getRequestedSurfaceScale(new float[2]);
diff --git a/src/test/com/jogamp/opengl/test/junit/graph/GPURendererListenerBase01.java b/src/test/com/jogamp/opengl/test/junit/graph/GPURendererListenerBase01.java
index b99d91070..50ceebdc5 100644
--- a/src/test/com/jogamp/opengl/test/junit/graph/GPURendererListenerBase01.java
+++ b/src/test/com/jogamp/opengl/test/junit/graph/GPURendererListenerBase01.java
@@ -125,7 +125,7 @@ public abstract class GPURendererListenerBase01 implements GLEventListener {
         if( upObj instanceof Window ) {
             final Window window = (Window) upObj;
             final float[] sPpMM = window.getPixelsPerMM(new float[2]);
-            final float[] sDPI = FontScale.perMMToPerInch( new float[] { sPpMM[0], sPpMM[1] } );
+            final float[] sDPI = FontScale.ppmmToPPI( new float[] { sPpMM[0], sPpMM[1] } );
             System.err.println("DPI "+sDPI[0]+" x "+sDPI[1]+", "+sPpMM[0]+" x "+sPpMM[1]+" pixel/mm");
 
             final float[] hasSurfacePixelScale1 = window.getCurrentSurfaceScale(new float[2]);
diff --git a/src/test/com/jogamp/opengl/test/junit/graph/GPUTextRendererListenerBase01.java b/src/test/com/jogamp/opengl/test/junit/graph/GPUTextRendererListenerBase01.java
index ccec9b982..90700e35a 100644
--- a/src/test/com/jogamp/opengl/test/junit/graph/GPUTextRendererListenerBase01.java
+++ b/src/test/com/jogamp/opengl/test/junit/graph/GPUTextRendererListenerBase01.java
@@ -232,7 +232,7 @@ public abstract class GPUTextRendererListenerBase01 extends GPURendererListenerB
         if( upObj instanceof Window ) {
             upstream_window = (Window) upObj;
             final float[] sPpMM = upstream_window.getPixelsPerMM(new float[2]);
-            final float[] sDPI = FontScale.perMMToPerInch( new float[] { sPpMM[0], sPpMM[1] } );
+            final float[] sDPI = FontScale.ppmmToPPI( new float[] { sPpMM[0], sPpMM[1] } );
             dpiV = sDPI[1];
             ppmmV = sPpMM[1];
             System.err.println("Using vertical screen DPI of "+dpiV+", "+ppmmV+" pixel/mm");
diff --git a/src/test/com/jogamp/opengl/test/junit/graph/TestFontScale01NOUI.java b/src/test/com/jogamp/opengl/test/junit/graph/TestFontScale01NOUI.java
new file mode 100644
index 000000000..ad6355d8a
--- /dev/null
+++ b/src/test/com/jogamp/opengl/test/junit/graph/TestFontScale01NOUI.java
@@ -0,0 +1,62 @@
+/**
+ * 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:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.opengl.test.junit.graph;
+
+import com.jogamp.graph.font.FontScale;
+import com.jogamp.junit.util.JunitTracer;
+
+import com.jogamp.opengl.math.FloatUtil;
+
+import org.junit.Assert;
+import org.junit.Test;
+import org.junit.FixMethodOrder;
+import org.junit.runners.MethodSorters;
+
+@FixMethodOrder(MethodSorters.NAME_ASCENDING)
+public class TestFontScale01NOUI extends JunitTracer {
+
+    @Test
+    public void test01() {
+        Assert.assertEquals(10f/72f, FontScale.ptToInch(10), FloatUtil.EPSILON); // pt -> inch
+        Assert.assertEquals(10f/72f * 25.4f, FontScale.ptToMM(10), FloatUtil.EPSILON); // pt -> mm
+        Assert.assertEquals(0.138888f, FontScale.ptToInch(10), 0.000001f); // pt -> inch
+        Assert.assertEquals(3.527778f, FontScale.ptToMM(10), 0.000001f); // pt -> mm
+
+        Assert.assertEquals(5f, FontScale.ppiToPPMM(new float[] { 127f, 127f })[0], FloatUtil.EPSILON); // dpi -> pixel/mm
+        Assert.assertEquals(127f, FontScale.ppmmToPPI(new float[] { 5f, 5f })[0], FloatUtil.EPSILON); // pixel/mm -> dpi
+
+        System.err.println("10pt @ 128 dpi -> pixels "+FontScale.toPixels(10 /* pt */, 127f /* dpi */));
+        System.err.println("10pt @  5 ppmm -> pixels "+FontScale.toPixels2(10 /* pt */,   5f /* ppmm */));
+        Assert.assertEquals(17.638889f, FontScale.toPixels(10 /* pt */, 127f /* dpi */), 0.000001f);
+        Assert.assertEquals(17.638889f, FontScale.toPixels2(10 /* pt */,   5f /* ppmm */), 0.000001f);
+    }
+
+    public static void main(final String args[]) {
+        org.junit.runner.JUnitCore.main(TestFontScale01NOUI.class.getName());
+    }
+}
diff --git a/src/test/com/jogamp/opengl/test/junit/graph/TextRendererGLELBase.java b/src/test/com/jogamp/opengl/test/junit/graph/TextRendererGLELBase.java
index 99cbb5118..f7a7e4c09 100644
--- a/src/test/com/jogamp/opengl/test/junit/graph/TextRendererGLELBase.java
+++ b/src/test/com/jogamp/opengl/test/junit/graph/TextRendererGLELBase.java
@@ -137,7 +137,7 @@ public abstract class TextRendererGLELBase implements GLEventListener {
 
         final Object upObj = drawable.getUpstreamWidget();
         if( upObj instanceof Window ) {
-            final float[] dpi = FontScale.perMMToPerInch( ((Window)upObj).getPixelsPerMM(new float[2]) );
+            final float[] dpi = FontScale.ppmmToPPI( ((Window)upObj).getPixelsPerMM(new float[2]) );
             dpiH = dpi[1];
         }
     }
diff --git a/src/test/com/jogamp/opengl/test/junit/newt/parenting/NewtReparentingKeyAdapter.java b/src/test/com/jogamp/opengl/test/junit/newt/parenting/NewtReparentingKeyAdapter.java
index 5d1ceba36..ae73f8853 100644
--- a/src/test/com/jogamp/opengl/test/junit/newt/parenting/NewtReparentingKeyAdapter.java
+++ b/src/test/com/jogamp/opengl/test/junit/newt/parenting/NewtReparentingKeyAdapter.java
@@ -105,7 +105,7 @@ public class NewtReparentingKeyAdapter extends NEWTDemoListener {
         final CapabilitiesImmutable reqCaps = win.getRequestedCapabilities();
         final CapabilitiesImmutable caps = null != chosenCaps ? chosenCaps : reqCaps;
         final String capsA = caps.isBackgroundOpaque() ? "opaque" : "transl";
-        final float[] sDPI = FontScale.perMMToPerInch( win.getPixelsPerMM(new float[2]) );
+        final float[] sDPI = FontScale.ppmmToPPI( win.getPixelsPerMM(new float[2]) );
         win.setTitle("GLWindow["+capsA+"], win: "+win.getBounds()+", pix: "+win.getSurfaceWidth()+"x"+win.getSurfaceHeight()+", sDPI "+sDPI[0]+" x "+sDPI[1]);
     }
 }