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

1 files changed, 102 insertions, 27 deletions

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