Bug 741 HiDPI: Refine Monitor/Screen [virtual] Viewport Definition / Add NEWT Support / Fix JAWT getPixelScale deadlock

- NativeWindow/Surface/NEWT API DOC: Define Coordinate System of Window and Screen

- OSXUtil: Add getPixelScale(..) via Screen index and 'windowOrView'

- JAWTWindow/JAWTUtil.getPixelScale(..): Use pre-fetched AWT GraphicsConfiguration to solve AWT-TreeLock (deadlock)

- [Virtual] Viewport of MonitorDevice and Screen:
  - Properly calculate and expose [virtual] viewport in window and pixel units
    - OSX Monitor viewports in pixel units are 'reconstructed'
  - Window/Viewport to Monitor selection shall be perfomed via window units (unique)

- OSX NEWT Window create/init (native): Use given size and coordinates even in fullscreen mode
  Don't override by quering NSScreen coordinates, trust given values.

- Fix test cases, i.e. usage of pixel- and window-units

5 files changed, 74 insertions, 27 deletions

diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java b/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java
index 24bc8fa51..d4f058201 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java
@@ -271,7 +271,7 @@ public abstract class JAWTWindow implements NativeWindow, OffscreenLayerSurface,
     final Rectangle jb = new Rectangle(jawtBounds.getX(), jawtBounds.getY(), jawtBounds.getWidth(), jawtBounds.getHeight());
     final int newPixelScale;
     {
-        final int s = JAWTUtil.getPixelScale(component);
+        final int s = JAWTUtil.getPixelScale(config.getAWTGraphicsConfiguration());
         newPixelScale = 0 < s ? s : 1;
     }
     final boolean changedBounds = !bounds.equals(jb);
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
index f8596bc74..8131ee283 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
@@ -32,8 +32,8 @@ package javax.media.nativewindow;
  * Provides low-level information required for
  * hardware-accelerated rendering using a surface in a platform-independent manner.
  * <p>
- * All values of this interface are represented in pixel units,
- * see {@link NativeWindow}.
+ * All values of this interface are represented in pixel units, if not stated otherwise.
+ * See {@link NativeWindow}.
  * </p>
  * <p>
  * A NativeSurface created for a particular on- or offscreen component is
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
index 242f25d43..63a643f3c 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
@@ -48,8 +48,18 @@ import javax.media.nativewindow.util.Point;
  * information such as {@link #getWindowHandle() window-handle},
  * {@link #getWindowWidth() window-size} and {@link #getX() window-position}.
  * <p>
- * All values of this interface are represented in window units.
- * see {@link NativeSurface}.
+ * All values of this interface are represented in window units, if not stated otherwise.
+ * See {@link NativeSurface}.
+ * </p>
+ *
+ * <a name="coordinateSystem"><h5>Coordinate System</h5></a>
+ * <p>
+ *  <ul>
+ *      <li>Abstract screen space has it's origin in the top-left corner, and may not be at 0/0.</li>
+ *      <li>Window origin is in it's top-left corner, see {@link #getX()} and {@link #getY()}. </li>
+ *      <li>Window client-area excludes {@link #getInsets() insets}, i.e. window decoration.</li>
+ *      <li>Window origin is relative to it's parent window if exist, or the screen position (top-level).</li>
+ *  </ul>
  * </p>
  * <p>
  * A window toolkit such as the AWT may either implement this interface
@@ -111,18 +121,36 @@ public interface NativeWindow extends NativeSurface {
   /** Returns the current x position of this window, relative to it's parent. */
 
   /**
-   * @return the current x position of the top-left corner
-   *         of the client area relative to it's parent in window units.
-   *         Since the position reflects the client area, it does not include the insets.
+   * Returns the x position of the top-left corner
+   * of the client area relative to it's parent in window units.
+   * <p>
+   * If no parent exist (top-level window), this coordinate equals the screen coordinate.
+   * </p>
+   * <p>
+   * Since the position reflects the client area, it does not include the insets.
+   * </p>
+   * <p>
+   * See <a href="#coordinateSystem"> Coordinate System</a>.
+   * </p>
    * @see #getInsets()
+   * @see #getLocationOnScreen(Point)
    */
   public int getX();
 
   /**
-   * @return the current y position of the top-left corner
-   *         of the client area relative to it's parent in window units.
-   *         Since the position reflects the client area, it does not include the insets.
+   * Returns the current y position of the top-left corner
+   * of the client area relative to it's parent in window units.
+   * <p>
+   * If no parent exist (top-level window), this coordinate equals the screen coordinate.
+   * </p>
+   * <p>
+   * Since the position reflects the client area, it does not include the insets.
+   * </p>
+   * <p>
+   * See <a href="#coordinateSystem"> Coordinate System</a>.
+   * </p>
    * @see #getInsets()
+   * @see #getLocationOnScreen(Point)
    */
   public int getY();
 
@@ -141,16 +169,23 @@ public interface NativeWindow extends NativeSurface {
   public int getWindowHeight();
 
   /**
-   * Returns the current position of the top-left corner
-   * of the client area in window units.
+   * Returns the window's top-left client-area position in the screen.
+   * <p>
+   * If {@link Point} is not <code>null</code>, it is translated about the resulting screen position
+   * and returned.
+   * </p>
+   * <p>
+   * See <a href="#coordinateSystem"> Coordinate System</a>.
+   * </p>
    * <p>
    * Since the position reflects the client area, it does not include the insets.
    * </p>
-   * @param point if not null,
-   *        {@link javax.media.nativewindow.util.Point#translate(javax.media.nativewindow.util.Point)}
-   *        the passed {@link javax.media.nativewindow.util.Point} by this location on the screen and return it.
-   * @return either the passed non null translated point by the screen location of this NativeWindow,
-   *         or a new instance with the screen location of this NativeWindow.
+   * @param point Optional {@link Point} storage.
+   *              If not null, <code>null</code>, it is translated about the resulting screen position
+   *              and returned.
+   * @see #getX()
+   * @see #getY()
+   * @see #getInsets()
    */
   public Point getLocationOnScreen(Point point);
 
diff --git a/src/nativewindow/classes/jogamp/nativewindow/jawt/JAWTUtil.java b/src/nativewindow/classes/jogamp/nativewindow/jawt/JAWTUtil.java
index 387f40f89..92ec27b69 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/jawt/JAWTUtil.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/jawt/JAWTUtil.java
@@ -37,7 +37,6 @@
 
 package jogamp.nativewindow.jawt;
 
-import java.awt.Component;
 import java.awt.EventQueue;
 import java.awt.GraphicsConfiguration;
 import java.awt.GraphicsDevice;
@@ -560,10 +559,9 @@ public class JAWTUtil {
   }
 
   /**
-   * Returns the pixel scale factor of the given {@link Component}'s {@link GraphicsDevice}, if supported.
+   * Returns the pixel scale factor of the given {@link GraphicsConfiguration}'s {@link GraphicsDevice}, if supported.
    * <p>
-   * If the component is not yet {@link Component#isDisplayable() displayable},
-   * <code>zero</code> is returned.
+   * If the {@link GraphicsDevice} is <code>null</code>, <code>zero</code> is returned.
    * </p>
    * <p>
    * If the component does not support pixel scaling the default
@@ -572,17 +570,21 @@ public class JAWTUtil {
    * <p>
    * Note: Currently only supported on OSX since 1.7.0_40 for HiDPI retina displays
    * </p>
-   * @param component the {@link Component} instance used to query the pixel scale
+   * @param gc the {@link GraphicsConfiguration} instance used to query the pixel scale
    * @return the pixel scale factor
    */
-  public static final int getPixelScale(final Component component) {
-      final GraphicsConfiguration gc = component.getGraphicsConfiguration();
+  public static final int getPixelScale(final GraphicsConfiguration gc) {
       final GraphicsDevice device = null != gc ? gc.getDevice() : null;
+      final int ps;
       if( null == device ) {
-          return 0;
+          ps = 0;
       } else {
-          return JAWTUtil.getPixelScale(device);
+          ps = JAWTUtil.getPixelScale(device);
       }
+      if( DEBUG ) {
+          System.err.println("JAWTWindow.updatePixelScale: Fetched "+ps);
+      }
+      return ps;
   }
 }
 
diff --git a/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java b/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java
index 88ba531d1..31b06d360 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java
@@ -122,6 +122,14 @@ public class OSXUtil implements ToolkitProperties {
       return (Insets) GetInsets0(windowOrView);
     }
 
+    public static double GetPixelScale(int screenIndex) {
+      return GetPixelScale0(screenIndex);
+    }
+
+    public static double GetPixelScale(long windowOrView) {
+      return GetPixelScale1(windowOrView);
+    }
+
     public static long CreateNSWindow(int x, int y, int width, int height) {
       return CreateNSWindow0(x, y, width, height);
     }
@@ -365,6 +373,8 @@ public class OSXUtil implements ToolkitProperties {
     private static native boolean isNSWindow0(long object);
     private static native Object GetLocationOnScreen0(long windowOrView, int src_x, int src_y);
     private static native Object GetInsets0(long windowOrView);
+    private static native double GetPixelScale0(int screenIndex);
+    private static native double GetPixelScale1(long windowOrView);
     private static native long CreateNSWindow0(int x, int y, int width, int height);
     private static native void DestroyNSWindow0(long nsWindow);
     private static native long GetNSView0(long nsWindow);