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

- Using comment tag 'FIXME HiDPI' to locate remaining issues

- Fix remaining 'getPixel*(..)' -> 'getSurface*(..)'
  - UpstreamSurfaceHook

- Fix usage (one by one) of
  - NativeWindow: getWindowWidth() / getWindowHeight()
  - NativeSurface/GLDrawable: getSurfaceWidth() / getSurfaceHeight()

- mention window- or pixel units in API doc where required

- use 'setSurfaceSize(..)' where appropriate to match 'getSurface*()'
  - GLFBODrawable
  - GLOffscreenAutoDrawable
  - UpstreamSurfaceHook.MutableSize

- NativeWindow's Point: Add API doc and 'Point scaleInv(..)'

- NativeSurface
  Simplify new conversion methods and use single in-place storage
  - 'int[] getWindowUnitXY(int[], int[])' -> 'int[] convertToWindowUnits(int[], int[])'
  - 'int[] getPixelUnitXY(int[], int[])' -> 'int[] convertToPixelUnits(int[], int[])'

- NEWT Screen/Monitor
  - Assume screen/window units
  - TODO: Refine semantics - Monitor resolution probably is in pixel units ?!
    - Including the Rectangle/Monitor association etc etc

- NEWT Window
  - Add setSurfaceSize(..) for convenience
  - Add 'Point convertToWindowUnits(final Point pixelUnitsAndResult)', etc ..
  - All window ops are using window units (size, pos, ..),
    but methods operating on the surface/drawable: windowRepaint(..) ..

- TODO: Consider changing method names 'window*(..)' to 'surface*(..)'
  actually operating on surface/drawable
  - Window.windowRepaint(..)
  - GLAutoDrawableDelegate.windowResizedOp(..) (maybe all similar methods in here)

- NEWT Mouse/Pointer Events
  - Using pixel units

8 files changed, 87 insertions, 27 deletions

diff --git a/src/newt/classes/com/jogamp/newt/MonitorDevice.java b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
index 2d1d912c7..1198f7681 100644
--- a/src/newt/classes/com/jogamp/newt/MonitorDevice.java
+++ b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
@@ -168,12 +168,19 @@ public abstract class MonitorDevice {
         return supportedModes.getData();
     }
 
-    /** Returns the {@link RectangleImmutable rectangular} portion of the rotated virtual {@link Screen} size represented by this monitor. */
+    /**
+     * Returns the {@link RectangleImmutable rectangular} portion
+     * of the rotated virtual {@link Screen} size in screen/window units
+     * represented by this monitor.
+     */
     public final RectangleImmutable getViewport() {
         return viewport;
     }
 
-    /** Returns <code>true</code> if given coordinates are contained by this {@link #getViewport() viewport}, otherwise <code>false</code>. */
+    /**
+     * Returns <code>true</code> if given screen coordinates in screen/window units
+     * are contained by this {@link #getViewport() viewport}, otherwise <code>false</code>.
+     */
     public final boolean contains(int x, int y) {
         return x >= viewport.getX() &&
                x <  viewport.getX() + viewport.getWidth() &&
diff --git a/src/newt/classes/com/jogamp/newt/NewtFactory.java b/src/newt/classes/com/jogamp/newt/NewtFactory.java
index 3b31861f0..4443c70c9 100644
--- a/src/newt/classes/com/jogamp/newt/NewtFactory.java
+++ b/src/newt/classes/com/jogamp/newt/NewtFactory.java
@@ -296,7 +296,7 @@ public class NewtFactory {
         }
         final Window win = WindowImpl.create(parentWindow, 0, screen, caps);
 
-        win.setSize(parentWindow.getSurfaceWidth(), parentWindow.getSurfaceHeight());
+        win.setSize(parentWindow.getWindowWidth(), parentWindow.getWindowHeight());
         if ( null != newtParentWindow ) {
             newtParentWindow.addChild(win);
             win.setVisible(newtParentWindow.isVisible());
diff --git a/src/newt/classes/com/jogamp/newt/Screen.java b/src/newt/classes/com/jogamp/newt/Screen.java
index ef62ec95d..2a713c538 100644
--- a/src/newt/classes/com/jogamp/newt/Screen.java
+++ b/src/newt/classes/com/jogamp/newt/Screen.java
@@ -131,27 +131,27 @@ public abstract class Screen {
     public abstract int getIndex();
 
     /**
-     * @return the x position of the virtual viewport's top-left origin.
+     * @return the x position of the virtual viewport's top-left origin in screen/window units.
      */
     public abstract int getX();
 
     /**
-     * @return the y position of the virtual viewport's top-left origin.
+     * @return the y position of the virtual viewport's top-left origin in screen/window units.
      */
     public abstract int getY();
 
     /**
-     * @return the <b>rotated</b> virtual viewport's width.
+     * @return the <b>rotated</b> virtual viewport's width in screen/window units.
      */
     public abstract int getWidth();
 
     /**
-     * @return the <b>rotated</b> virtual viewport's height.
+     * @return the <b>rotated</b> virtual viewport's height in screen/window units.
      */
     public abstract int getHeight();
 
     /**
-     * @return the <b>rotated</b> virtual viewport, i.e. origin and size.
+     * @return the <b>rotated</b> virtual viewport, i.e. origin and size in screen/window units.
      */
     public abstract RectangleImmutable getViewport();
 
@@ -186,6 +186,7 @@ public abstract class Screen {
      * <p>
      * If no coverage is detected the first {@link MonitorDevice} is returned.
      * </p>
+     * @param r arbitrary rectangle in screen/window units
      */
     public final MonitorDevice getMainMonitor(RectangleImmutable r) {
         MonitorDevice res = null;
@@ -206,7 +207,7 @@ public abstract class Screen {
     }
 
     /**
-     * Returns the union of all monitor's {@link MonitorDevice#getViewport() viewport}.
+     * Returns the union of all monitor's {@link MonitorDevice#getViewport() viewport} in screen/window 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.
@@ -257,7 +258,7 @@ public abstract class Screen {
         synchronized(screenList) {
             int i = fromIndex >= 0 ? fromIndex : screenList.size() - 1 ;
             while( ( incr > 0 ) ? i < screenList.size() : i >= 0 ) {
-                final Screen screen = (Screen) screenList.get(i).get();
+                final Screen screen = screenList.get(i).get();
                 if( null == screen ) {
                     // Clear GC'ed dead reference entry!
                     screenList.remove(i);
diff --git a/src/newt/classes/com/jogamp/newt/Window.java b/src/newt/classes/com/jogamp/newt/Window.java
index 9cf67c56f..b733406e8 100644
--- a/src/newt/classes/com/jogamp/newt/Window.java
+++ b/src/newt/classes/com/jogamp/newt/Window.java
@@ -46,6 +46,7 @@ import javax.media.nativewindow.CapabilitiesChooser;
 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.RectangleImmutable;
 
 /**
@@ -251,11 +252,38 @@ public interface Window extends NativeWindow, WindowClosingProtocol {
      * @param width of the window's client area in window units
      * @param height of the window's client area in window units
      *
+     * @see #setSurfaceSize(int, int)
+     * @see #setTopLevelSize(int, int)
      * @see #getInsets()
      */
     void setSize(int width, int height);
 
     /**
+     * Sets the size of the window's surface in pixel units which claims the window's client area excluding decorations.
+     *
+     * <p>
+     * Zero size semantics are respected, see {@link #setVisible(boolean)}:<br>
+     * <pre>
+     * if ( visible && 0 != windowHandle && ( 0 &ge; width || 0 &ge; height ) ) {
+     *   setVisible(false);
+     * } else if ( visible && 0 == windowHandle && 0 &lt; width && 0 &lt; height ) {
+     *   setVisible(true);
+     * } else {
+     *   // as expected ..
+     * }
+     * </pre></p>
+     * <p>
+     * This call is ignored if in fullscreen mode.<br></p>
+     *
+     * @param pixelWidth of the window's client area in pixel units
+     * @param pixelHeight of the window's client area in pixel units
+     *
+     * @see #setSize(int, int)
+     * @see #getInsets()
+     */
+    void setSurfaceSize(int pixelWidth, int pixelHeight);
+
+    /**
      * Sets the size of the top-level window including insets (window decorations) in window units.
      *
      * <p>
@@ -299,6 +327,22 @@ public interface Window extends NativeWindow, WindowClosingProtocol {
      */
     void setTopLevelPosition(int x, int y);
 
+    /**
+     * Converts the given pixel units into window units <i>in place</i>.
+     * @param pixelUnitsAndResult point storage holding the pixel units to convert
+     *                            and the resulting conversion.
+     * @return resulting point storage pixelUnitsAndResult for chaining holding the converted values
+     */
+    Point convertToWindowUnits(final Point pixelUnitsAndResult);
+
+    /**
+     * Converts the given window units into pixel units <i>in place</i>.
+     * @param windowUnitsAndResult point storage holding the window units to convert
+     *                            and the resulting conversion.
+     * @return resulting point storage windowUnitsAndResult for chaining holding the converted values
+     */
+    Point convertToPixelUnits(final Point windowUnitsAndResult);
+
     void setUndecorated(boolean value);
 
     boolean isUndecorated();
diff --git a/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java b/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java
index 891843cb7..0d70b5f8c 100644
--- a/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java
+++ b/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java
@@ -400,7 +400,7 @@ public class NewtCanvasAWT extends java.awt.Canvas implements WindowClosingProto
         final Window w = newtChild;
         if( null != w ) {
             // use NEWT child's size for min/pref size!
-            java.awt.Dimension minSize = new java.awt.Dimension(w.getSurfaceWidth(), w.getSurfaceHeight());
+            java.awt.Dimension minSize = new java.awt.Dimension(w.getWindowWidth(), w.getWindowHeight());
             setMinimumSize(minSize);
             setPreferredSize(minSize);
         }
diff --git a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
index c4a5fcab1..7ba4bddf0 100644
--- a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
+++ b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
@@ -363,13 +363,23 @@ public class GLWindow extends GLAutoDrawableBase implements GLAutoDrawable, Wind
     }
 
     @Override
-    public final int[] getWindowUnitXY(int[] result, final int[] pixelUnitXY) {
-        return window.getWindowUnitXY(result, pixelUnitXY);
+    public final int[] convertToWindowUnits(final int[] pixelUnitsAndResult) {
+        return window.convertToWindowUnits(pixelUnitsAndResult);
     }
 
     @Override
-    public final int[] getPixelUnitXY(int[] result, final int[] windowUnitXY) {
-        return window.getPixelUnitXY(result, windowUnitXY);
+    public final int[] convertToPixelUnits(final int[] windowUnitsAndResult) {
+        return window.convertToPixelUnits(windowUnitsAndResult);
+    }
+
+    @Override
+    public final Point convertToWindowUnits(final Point pixelUnitsAndResult) {
+        return window.convertToWindowUnits(pixelUnitsAndResult);
+    }
+
+    @Override
+    public final Point convertToPixelUnits(final Point windowUnitsAndResult) {
+        return window.convertToPixelUnits(windowUnitsAndResult);
     }
 
     @Override
@@ -471,6 +481,10 @@ public class GLWindow extends GLAutoDrawableBase implements GLAutoDrawable, Wind
         window.setSize(width, height);
     }
     @Override
+    public final void setSurfaceSize(int pixelWidth, int pixelHeight) {
+        window.setSurfaceSize(pixelWidth, pixelHeight);
+    }
+    @Override
     public void setTopLevelSize(int width, int height) {
         window.setTopLevelSize(width, height);
     }
diff --git a/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java b/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java
index ee01212cb..b627fa1ad 100644
--- a/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java
+++ b/src/newt/classes/com/jogamp/newt/swt/NewtCanvasSWT.java
@@ -470,19 +470,13 @@ public class NewtCanvasSWT extends Canvas implements WindowClosingProtocol {
         }
 
         @Override
-        public final int[] getWindowUnitXY(int[] result, final int[] pixelUnitXY) {
-            final int scale = 1; // FIXME: Use 'scale' ..
-            result[0] = pixelUnitXY[0] / scale;
-            result[1] = pixelUnitXY[1] / scale;
-            return result;
+        public final int[] convertToWindowUnits(final int[] pixelUnitsAndResult) {
+            return pixelUnitsAndResult; // FIXME HiDPI: use 'pixelScale'
         }
 
         @Override
-        public final int[] getPixelUnitXY(int[] result, final int[] windowUnitXY) {
-            final int scale = 1; // FIXME: Use 'scale' ..
-            result[0] = windowUnitXY[0] * scale;
-            result[1] = windowUnitXY[1] * scale;
-            return result;
+        public final int[] convertToPixelUnits(final int[] windowUnitsAndResult) {
+            return windowUnitsAndResult; // FIXME HiDPI: use 'pixelScale'
         }
 
         @Override
diff --git a/src/newt/classes/com/jogamp/newt/util/applet/JOGLNewtApplet3Run.java b/src/newt/classes/com/jogamp/newt/util/applet/JOGLNewtApplet3Run.java
index 8a3e5616d..7b6a1c8cd 100644
--- a/src/newt/classes/com/jogamp/newt/util/applet/JOGLNewtApplet3Run.java
+++ b/src/newt/classes/com/jogamp/newt/util/applet/JOGLNewtApplet3Run.java
@@ -172,7 +172,7 @@ public class JOGLNewtApplet3Run implements Applet3 {
         glWindow = GLWindow.create(w);
         glWindow.setUndecorated(glUndecorated);
         glWindow.setAlwaysOnTop(glAlwaysOnTop);
-        glWindow.setSize(browserWin.getSurfaceWidth(), browserWin.getSurfaceHeight());
+        glWindow.setSize(browserWin.getWindowWidth(), browserWin.getWindowHeight());
 
         return new NativeWindowDownstream() {
             @Override
@@ -184,7 +184,7 @@ public class JOGLNewtApplet3Run implements Applet3 {
 
             @Override
             public void setSize(int width, int height) {
-                upstreamSizePosHook.setPixelSize(width, height);
+                upstreamSizePosHook.setWinSize(width, height);
                 if( null != glWindow ) {
                     glWindow.setSize(width, height);
                 }