Bug 742 HiDPI: [Core API Change] Distinguish window-units and pixel-units: Refine commit fb57c652fee6be133990cd7afbbd2fdfc084afaa

- NEWT Screen, Monitor, MonitorMode, ..
  - All Units are in pixel units, not window units!

  - On OSX HiDPI, we report the current scaled monitor resolution,
    instead of the native pixel sized.
    Need to filter out those, i.e. report only native unscaled resolutions,
    since out MonitorMode analogy is per MonitorDevice and not per window!

- Fix usage (one by one) of
   - Screen and Monitor viewport usage

6 files changed, 79 insertions, 40 deletions

diff --git a/src/newt/classes/com/jogamp/newt/MonitorDevice.java b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
index 1198f7681..af0ce0146 100644
--- a/src/newt/classes/com/jogamp/newt/MonitorDevice.java
+++ b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
@@ -170,7 +170,7 @@ public abstract class MonitorDevice {
 
     /**
      * Returns the {@link RectangleImmutable rectangular} portion
-     * of the rotated virtual {@link Screen} size in screen/window units
+     * of the rotated virtual {@link Screen} size in pixel units
      * represented by this monitor.
      */
     public final RectangleImmutable getViewport() {
@@ -178,10 +178,12 @@ public abstract class MonitorDevice {
     }
 
     /**
-     * Returns <code>true</code> if given screen coordinates in screen/window units
+     * Returns <code>true</code> if given screen coordinates in pixel units
      * are contained by this {@link #getViewport() viewport}, otherwise <code>false</code>.
+     * @param x x-coord in pixel units
+     * @param y y-coord in pixel units
      */
-    public final boolean contains(int x, int y) {
+    public final boolean contains(final int x, final int y) {
         return x >= viewport.getX() &&
                x <  viewport.getX() + viewport.getWidth() &&
                y >= viewport.getY() &&
@@ -189,7 +191,8 @@ public abstract class MonitorDevice {
     }
 
     /**
-     * Returns the coverage of given rectangle w/ this this {@link #getViewport() viewport}, i.e. between <code>0.0</code> and <code>1.0</code>.
+     * Returns the coverage of given rectangle in pixel units
+     * w/ this {@link #getViewport() viewport}, i.e. between <code>0.0</code> and <code>1.0</code>.
      * <p>
      * Coverage is computed by:
      * <pre>
@@ -197,16 +200,17 @@ public abstract class MonitorDevice {
      *    coverage = area( isect ) / area( viewport ) ;
      * </pre>
      * </p>
+     * @param r {@link RectangleImmutable rectangle} in pixel units
      */
-    public final float coverage(RectangleImmutable r) {
+    public final float coverage(final RectangleImmutable r) {
         return viewport.coverage(r);
     }
 
     /**
-     * Returns the union of the given monitor's {@link #getViewport() viewport}.
+     * Returns the union of the given monitor's {@link #getViewport() viewport} in pixel units.
      * @param result storage for result, will be returned
      * @param monitors given list of monitors
-     * @return viewport representing the union of given monitor's viewport.
+     * @return viewport representing the union of given monitor's viewport in pixel units, i.e. result storage for chaining
      */
     public static Rectangle unionOfViewports(final Rectangle result, final List<MonitorDevice> monitors) {
         int x1=Integer.MAX_VALUE, y1=Integer.MAX_VALUE;
diff --git a/src/newt/classes/com/jogamp/newt/MonitorMode.java b/src/newt/classes/com/jogamp/newt/MonitorMode.java
index 9690f18db..ba21df22a 100644
--- a/src/newt/classes/com/jogamp/newt/MonitorMode.java
+++ b/src/newt/classes/com/jogamp/newt/MonitorMode.java
@@ -51,7 +51,7 @@ import com.jogamp.newt.util.MonitorModeUtil;
  *  <ul>
  *    <li>A List of all {@link MonitorDevice}s is accessible via {@link Screen#getMonitorDevices()}.</li>
  *    <li>The main monitor used by a windows is accessible via {@link Window#getMainMonitor()}.</li>
- *    <li>The main monitor covering an arbitrary rectnagle is accessible via {@link Screen#getMainMonitor(RectangleImmutable)}.</li>
+ *    <li>The main monitor covering an arbitrary rectangle is accessible via {@link Screen#getMainMonitor(RectangleImmutable)}.</li>
  *  </ul></li>
  *  <li>The current MonitorMode can be obtained via {@link MonitorDevice#getCurrentMode()}.</li>
  *  <li>The original MonitorMode can be obtained via {@link MonitorDevice#getOriginalMode()}.</li>
@@ -88,8 +88,8 @@ import com.jogamp.newt.util.MonitorModeUtil;
         MonitorMode mmCurrent = monitor.queryCurrentMode();
         MonitorMode mmOrig = monitor.getOriginalMode();
 
-        // Target resolution
-        Dimension res = new Dimension(800, 600);
+        // Target resolution in pixel units
+        DimensionImmutable res = new Dimension(800, 600);
 
         // Target refresh rate shall be similar to current one ..
         float freq = mmCurrent.getRefreshRate();
@@ -136,7 +136,7 @@ public class MonitorMode implements Comparable<MonitorMode> {
      * </ul>
      */
     public static class SizeAndRRate implements Comparable<SizeAndRRate> {
-        /** Non rotated surface size */
+        /** Non rotated surface size in pixel units */
         public final SurfaceSize surfaceSize;
         /** Mode bitfield flags, i.e. {@link #FLAG_DOUBLESCAN}, {@link #FLAG_INTERLACE}, .. */
         public final int flags;
@@ -349,7 +349,7 @@ public class MonitorMode implements Comparable<MonitorMode> {
         return rotation;
     }
 
-    /** Returns the rotated screen width,
+    /** Returns the rotated screen width in pixel units,
      *  derived from <code>getMonitorMode().getSurfaceSize().getResolution()</code>
      *  and <code>getRotation()</code>
      */
@@ -357,7 +357,7 @@ public class MonitorMode implements Comparable<MonitorMode> {
         return getRotatedWH(true);
     }
 
-    /** Returns the rotated screen height,
+    /** Returns the rotated screen height in pixel units,
      *  derived from <code>getMonitorMode().getSurfaceSize().getResolution()</code>
      *  and <code>getRotation()</code>
      */
diff --git a/src/newt/classes/com/jogamp/newt/Screen.java b/src/newt/classes/com/jogamp/newt/Screen.java
index 2a713c538..919b98b45 100644
--- a/src/newt/classes/com/jogamp/newt/Screen.java
+++ b/src/newt/classes/com/jogamp/newt/Screen.java
@@ -131,31 +131,42 @@ public abstract class Screen {
     public abstract int getIndex();
 
     /**
-     * @return the x position of the virtual viewport's top-left origin in screen/window units.
+     * @return the x position of the virtual viewport's top-left origin in pixel units.
      */
     public abstract int getX();
 
     /**
-     * @return the y position of the virtual viewport's top-left origin in screen/window units.
+     * @return the y position of the virtual viewport's top-left origin in pixel units.
      */
     public abstract int getY();
 
     /**
-     * @return the <b>rotated</b> virtual viewport's width in screen/window units.
+     * @return the <b>rotated</b> virtual viewport's width in pixel units.
      */
     public abstract int getWidth();
 
     /**
-     * @return the <b>rotated</b> virtual viewport's height in screen/window units.
+     * @return the <b>rotated</b> virtual viewport's height in pixel units.
      */
     public abstract int getHeight();
 
     /**
-     * @return the <b>rotated</b> virtual viewport, i.e. origin and size in screen/window units.
+     * @return the <b>rotated</b> virtual viewport, i.e. origin and size in pixel units.
+     * @see #getViewportInWindowUnits(Window)
      */
     public abstract RectangleImmutable getViewport();
 
     /**
+     * Returns a newly created {@link Rectangle} containing the <b>rotated</b> virtual viewport
+     * in window units of the given {@link Window} instance.
+     * @return rotated viewport values, i.e. origin and size, in pixel units.
+     * @see #getViewport()
+     */
+    public final Rectangle getViewportInWindowUnits(final Window win) {
+        return win.convertToWindowUnits( (Rectangle) getViewport().cloneMutable() );
+    }
+
+    /**
      * @return the associated Display
      */
     public abstract Display getDisplay();
@@ -181,14 +192,14 @@ public abstract class Screen {
     public abstract List<MonitorDevice> getMonitorDevices();
 
     /**
-     * Returns the {@link MonitorDevice} which {@link MonitorDevice#getViewport() viewport}
-     * {@link MonitorDevice#coverage(RectangleImmutable) covers} the given rectangle the most.
+     * Returns the {@link MonitorDevice} with the highest {@link MonitorDevice#getViewport() viewport}
+     * {@link MonitorDevice#coverage(RectangleImmutable) coverage} of the given rectangle in pixel units.
      * <p>
      * If no coverage is detected the first {@link MonitorDevice} is returned.
      * </p>
-     * @param r arbitrary rectangle in screen/window units
+     * @param r arbitrary rectangle in pixel units
      */
-    public final MonitorDevice getMainMonitor(RectangleImmutable r) {
+    public final MonitorDevice getMainMonitor(final RectangleImmutable r) {
         MonitorDevice res = null;
         float maxCoverage = Float.MIN_VALUE;
         final List<MonitorDevice> monitors = getMonitorDevices();
@@ -207,7 +218,7 @@ public abstract class Screen {
     }
 
     /**
-     * Returns the union of all monitor's {@link MonitorDevice#getViewport() viewport} in screen/window units.
+     * Returns the union of all monitor's {@link MonitorDevice#getViewport() viewport} in pixel units.
      * <p>
      * Should be equal to {@link #getX()}, {@link #getY()}, {@link #getWidth()} and {@link #getHeight()},
      * however, some native toolkits may choose a different virtual screen area.
diff --git a/src/newt/classes/com/jogamp/newt/Window.java b/src/newt/classes/com/jogamp/newt/Window.java
index b733406e8..872d67087 100644
--- a/src/newt/classes/com/jogamp/newt/Window.java
+++ b/src/newt/classes/com/jogamp/newt/Window.java
@@ -47,6 +47,7 @@ import javax.media.nativewindow.CapabilitiesImmutable;
 import javax.media.nativewindow.NativeWindow;
 import javax.media.nativewindow.WindowClosingProtocol;
 import javax.media.nativewindow.util.Point;
+import javax.media.nativewindow.util.Rectangle;
 import javax.media.nativewindow.util.RectangleImmutable;
 
 /**
@@ -233,6 +234,18 @@ public interface Window extends NativeWindow, WindowClosingProtocol {
     //
 
     /**
+     * Returns a newly created {@link Rectangle} containing window origin, {@link #getX()} & {@link #getY()},
+     * and size, {@link #getWidth()} & {@link #getHeight()}, in window units.
+     */
+    Rectangle getBounds();
+
+    /**
+     * Returns a newly created {@link Rectangle} containing the scaled window origin, {@link #getX()} & {@link #getY()},
+     * and size, {@link #getSurfaceWidth()} & {@link #getSurfaceHeight()}, in pixel units.
+     */
+    Rectangle getSurfaceBounds();
+
+    /**
      * Sets the size of the window's client area in window units, excluding decorations.
      *
      * <p>
@@ -329,19 +342,19 @@ public interface Window extends NativeWindow, WindowClosingProtocol {
 
     /**
      * Converts the given pixel units into window units <i>in place</i>.
-     * @param pixelUnitsAndResult point storage holding the pixel units to convert
+     * @param pixelUnitsAndResult rectangle storage holding the pixel units to convert
      *                            and the resulting conversion.
-     * @return resulting point storage pixelUnitsAndResult for chaining holding the converted values
+     * @return resulting rectangle storage pixelUnitsAndResult for chaining holding the converted values
      */
-    Point convertToWindowUnits(final Point pixelUnitsAndResult);
+    Rectangle convertToWindowUnits(final Rectangle pixelUnitsAndResult);
 
     /**
      * Converts the given window units into pixel units <i>in place</i>.
-     * @param windowUnitsAndResult point storage holding the window units to convert
+     * @param windowUnitsAndResult rectangle storage holding the window units to convert
      *                            and the resulting conversion.
-     * @return resulting point storage windowUnitsAndResult for chaining holding the converted values
+     * @return resulting rectangle storage windowUnitsAndResult for chaining holding the converted values
      */
-    Point convertToPixelUnits(final Point windowUnitsAndResult);
+    Rectangle convertToPixelUnits(final Rectangle windowUnitsAndResult);
 
     void setUndecorated(boolean value);
 
diff --git a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
index 7ba4bddf0..ecd50aa5f 100644
--- a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
+++ b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
@@ -47,6 +47,7 @@ import javax.media.nativewindow.NativeWindowException;
 import javax.media.nativewindow.SurfaceUpdatedListener;
 import javax.media.nativewindow.util.InsetsImmutable;
 import javax.media.nativewindow.util.Point;
+import javax.media.nativewindow.util.Rectangle;
 import javax.media.opengl.FPSCounter;
 import javax.media.opengl.GL;
 import javax.media.opengl.GL3;
@@ -363,33 +364,43 @@ public class GLWindow extends GLAutoDrawableBase implements GLAutoDrawable, Wind
     }
 
     @Override
-    public final int[] convertToWindowUnits(final int[] pixelUnitsAndResult) {
-        return window.convertToWindowUnits(pixelUnitsAndResult);
+    public final Rectangle getBounds() {
+        return window.getBounds();
     }
 
     @Override
-    public final int[] convertToPixelUnits(final int[] windowUnitsAndResult) {
-        return window.convertToPixelUnits(windowUnitsAndResult);
+    public final int getSurfaceWidth() {
+        return window.getSurfaceWidth();
+    }
+
+    @Override
+    public final int getSurfaceHeight() {
+        return window.getSurfaceHeight();
     }
 
     @Override
-    public final Point convertToWindowUnits(final Point pixelUnitsAndResult) {
+    public final Rectangle getSurfaceBounds() {
+        return window.getSurfaceBounds();
+    }
+
+    @Override
+    public final int[] convertToWindowUnits(final int[] pixelUnitsAndResult) {
         return window.convertToWindowUnits(pixelUnitsAndResult);
     }
 
     @Override
-    public final Point convertToPixelUnits(final Point windowUnitsAndResult) {
+    public final int[] convertToPixelUnits(final int[] windowUnitsAndResult) {
         return window.convertToPixelUnits(windowUnitsAndResult);
     }
 
     @Override
-    public final int getSurfaceWidth() {
-        return window.getSurfaceWidth();
+    public final Rectangle convertToWindowUnits(final Rectangle pixelUnitsAndResult) {
+        return window.convertToWindowUnits(pixelUnitsAndResult);
     }
 
     @Override
-    public final int getSurfaceHeight() {
-        return window.getSurfaceHeight();
+    public final Rectangle convertToPixelUnits(final Rectangle windowUnitsAndResult) {
+        return window.convertToPixelUnits(windowUnitsAndResult);
     }
 
     @Override
diff --git a/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java b/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java
index fdd7985fe..e019068f5 100644
--- a/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java
+++ b/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java
@@ -157,7 +157,7 @@ public class MonitorModeUtil {
 
     /**
      * @param monitorModes
-     * @param resolution
+     * @param resolution in pixel units
      * @return modes with nearest resolution, or matching ones. May return zero sized list for non.
      */
     public static List<MonitorMode> filterByResolution(List<MonitorMode> monitorModes, DimensionImmutable resolution) {