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

13 files changed, 86 insertions, 59 deletions

diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java b/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java
index db4a979d1..9a462105f 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java
@@ -10,7 +10,7 @@ public class DelegatedUpstreamSurfaceHookWithSurfaceSize implements UpstreamSurf
 
     /**
      * @param upstream optional upstream UpstreamSurfaceHook used for {@link #create(ProxySurface)} and {@link #destroy(ProxySurface)}.
-     * @param surface mandatory {@link NativeSurface} used for {@link #getPixelWidth(ProxySurface)} and {@link #getPixelHeight(ProxySurface)}
+     * @param surface mandatory {@link NativeSurface} used for {@link #getSurfaceWidth(ProxySurface)} and {@link #getSurfaceHeight(ProxySurface)}
      */
     public DelegatedUpstreamSurfaceHookWithSurfaceSize(UpstreamSurfaceHook upstream, NativeSurface surface) {
         this.upstream = upstream;
@@ -35,12 +35,12 @@ public class DelegatedUpstreamSurfaceHookWithSurfaceSize implements UpstreamSurf
     }
 
     @Override
-    public final int getPixelWidth(ProxySurface s) {
+    public final int getSurfaceWidth(ProxySurface s) {
         return surface.getSurfaceWidth();
     }
 
     @Override
-    public final int getPixelHeight(ProxySurface s) {
+    public final int getSurfaceHeight(ProxySurface s) {
         return surface.getSurfaceHeight();
     }
 
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java b/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java
index 5910f5fea..25e2bbd49 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java
@@ -16,18 +16,18 @@ public class UpstreamSurfaceHookMutableSize implements UpstreamSurfaceHook.Mutab
     }
 
     @Override
-    public final void setPixelSize(int width, int height) {
+    public final void setSurfaceSize(int width, int height) {
         this.pixWidth = width;
         this.pixHeight = height;
     }
 
     @Override
-    public final int getPixelWidth(ProxySurface s) {
+    public final int getSurfaceWidth(ProxySurface s) {
         return pixWidth;
     }
 
     @Override
-    public final int getPixelHeight(ProxySurface s) {
+    public final int getSurfaceHeight(ProxySurface s) {
         return pixHeight;
     }
     @Override
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamWindowHookMutableSizePos.java b/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamWindowHookMutableSizePos.java
index f761b522a..2e9a33801 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamWindowHookMutableSizePos.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamWindowHookMutableSizePos.java
@@ -28,6 +28,9 @@ public class UpstreamWindowHookMutableSizePos extends UpstreamSurfaceHookMutable
     public final void setWinSize(int winWidth, int winHeight) {
         this.winWidth= winWidth;
         this.winHeight= winHeight;
+        // FIXME HiDPI: Use pixelScale ?!
+        // FIXME HiDPI: Consider setting winWidth/winHeight by setSurfaceSize(..) (back-propagation)
+        this.setSurfaceSize(winWidth, winHeight);
     }
 
     public final int getX() {
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java b/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java
index e35716c49..24bc8fa51 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/awt/JAWTWindow.java
@@ -648,19 +648,19 @@ public abstract class JAWTWindow implements NativeWindow, OffscreenLayerSurface,
   }
 
   @Override
-  public final int[] getWindowUnitXY(int[] result, final int[] pixelUnitXY) {
+  public final int[] convertToWindowUnits(final int[] pixelUnitsAndResult) {
       final int scale = getPixelScale();
-      result[0] = pixelUnitXY[0] / scale;
-      result[1] = pixelUnitXY[1] / scale;
-      return result;
+      pixelUnitsAndResult[0] /= scale;
+      pixelUnitsAndResult[1] /= scale;
+      return pixelUnitsAndResult;
   }
 
   @Override
-  public final int[] getPixelUnitXY(int[] result, final int[] windowUnitXY) {
+  public final int[] convertToPixelUnits(final int[] windowUnitsAndResult) {
       final int scale = getPixelScale();
-      result[0] = windowUnitXY[0] * scale;
-      result[1] = windowUnitXY[1] * scale;
-      return result;
+      windowUnitsAndResult[0] *= scale;
+      windowUnitsAndResult[1] *= scale;
+      return windowUnitsAndResult;
   }
 
   @Override
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
index d5cc048a1..f8596bc74 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
@@ -181,7 +181,7 @@ public interface NativeSurface extends SurfaceUpdatedListener {
    * Returns the width of the client area excluding insets (window decorations) in pixel units.
    * @return width of the client area in pixel units
    * @see NativeWindow#getWindowWidth()
-   * @see #getWindowUnitXY(int[], int[])
+   * @see #convertToWindowUnits(int[])
    */
   public int getSurfaceWidth();
 
@@ -189,25 +189,25 @@ public interface NativeSurface extends SurfaceUpdatedListener {
    * Returns the height of the client area excluding insets (window decorations) in pixel units.
    * @return height of the client area in pixel units
    * @see NativeWindow#getWindowHeight()
-   * @see #getWindowUnitXY(int[], int[])
+   * @see #convertToWindowUnits(int[])
    */
   public int getSurfaceHeight();
 
   /**
-   * Converts the given pixel units into window units.
-   * @param result int[2] storage for the result, may be equal to pixelUnitXY (in-place)
-   * @param pixelUnitXY int[2] x- and y-coord values in pixel units
-   * @return result int[2] storage for chaining holding the converted values
+   * Converts the given pixel units into window units <i>in place</i>.
+   * @param pixelUnitsAndResult int[2] storage holding the pixel units for the x- and y-coord to convert
+   *                             and the resulting values.
+   * @return result int[2] storage pixelUnitsAndResult for chaining holding the converted values
    */
-  public int[] getWindowUnitXY(int[] result, final int[] pixelUnitXY);
+  public int[] convertToWindowUnits(final int[] pixelUnitsAndResult);
 
   /**
-   * Converts the given window units into pixel units.
-   * @param result int[2] storage for the result, may be equal to windowUnitXY (in-place)
-   * @param windowUnitXY int[2] x- and y-coord values in window units
-   * @return result int[2] storage for chaining holding the converted values
+   * Converts the given window units into pixel units <i>in place</i>.
+   * @param windowUnitsAndResult int[2] storage holding the window units for the x- and y-coord to convert
+   *                             and the resulting values.
+   * @return result int[2] storage windowUnitsAndResult for chaining holding the converted values
    */
-  public int[] getPixelUnitXY(int[] result, final int[] windowUnitXY);
+  public int[] convertToPixelUnits(final int[] windowUnitsAndResult);
 
   /**
    * Returns the graphics configuration corresponding to this window.
diff --git a/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
index 39e316856..1a13b050a 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
@@ -39,14 +39,19 @@ public interface UpstreamSurfaceHook {
     public void destroy(ProxySurface s);
 
     /** Returns the width of the upstream surface in pixels, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */
-    public int getPixelWidth(ProxySurface s);
+    public int getSurfaceWidth(ProxySurface s);
     /** Returns the height of the upstream surface in pixels, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */
-    public int getPixelHeight(ProxySurface s);
+    public int getSurfaceHeight(ProxySurface s);
 
     /**
      * {@link UpstreamSurfaceHook} w/ mutable size, allowing it's {@link ProxySurface} user to resize.
      */
     public interface MutableSize extends UpstreamSurfaceHook {
-        public void setPixelSize(int width, int height);
+        /**
+         * Resizes the upstream surface.
+         * @param width new width in pixel units
+         * @param height new height in pixel units
+         */
+        public void setSurfaceSize(int width, int height);
     }
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/Point.java b/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
index 331c1388e..e544118d0 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
@@ -106,22 +106,54 @@ public class Point implements Cloneable, PointImmutable {
     public final void setX(int x) { this.x = x; }
     public final void setY(int y) { this.y = y; }
 
+    /**
+     * Translate this instance's x- and y-components,
+     * i.e. add the values of the given delta point to them.
+     * @param pd delta point
+     * @return this instance for scaling
+     */
     public final Point translate(Point pd) {
         x += pd.x ;
         y += pd.y ;
         return this;
     }
 
+    /**
+     * Translate this instance's x- and y-components,
+     * i.e. add the given deltas to them.
+     * @param dx delta for x
+     * @param dy delta for y
+     * @return this instance for scaling
+     */
     public final Point translate(int dx, int dy) {
         x += dx ;
         y += dy ;
         return this;
     }
 
+    /**
+     * Scale this instance's x- and y-components,
+     * i.e. multiply them by the given scale factors.
+     * @param sx scale factor for x
+     * @param sy scale factor for y
+     * @return this instance for scaling
+     */
     public final Point scale(int sx, int sy) {
         x *= sx ;
         y *= sy ;
         return this;
     }
 
+    /**
+     * Inverse scale this instance's x- and y-components,
+     * i.e. divide them by the given scale factors.
+     * @param sx inverse scale factor for x
+     * @param sy inverse scale factor for y
+     * @return this instance for scaling
+     */
+    public final Point scaleInv(int sx, int sy) {
+        x /= sx ;
+        y /= sy ;
+        return this;
+    }
 }
diff --git a/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java b/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
index dd1b6f185..969e012a6 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
@@ -150,12 +150,12 @@ public abstract class ProxySurfaceImpl implements ProxySurface {
 
     @Override
     public final int getSurfaceWidth() {
-        return upstream.getPixelWidth(this);
+        return upstream.getSurfaceWidth(this);
     }
 
     @Override
     public final int getSurfaceHeight() {
-        return upstream.getPixelHeight(this);
+        return upstream.getSurfaceHeight(this);
     }
 
     @Override
diff --git a/src/nativewindow/classes/jogamp/nativewindow/WrappedSurface.java b/src/nativewindow/classes/jogamp/nativewindow/WrappedSurface.java
index 5601dac02..902223c80 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/WrappedSurface.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/WrappedSurface.java
@@ -98,20 +98,13 @@ public class WrappedSurface extends ProxySurfaceImpl {
   }
 
   @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'
   }
 
-
-}
+}
\ No newline at end of file
diff --git a/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXDummyUpstreamSurfaceHook.java b/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXDummyUpstreamSurfaceHook.java
index 5a51aca3e..98ea68f4f 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXDummyUpstreamSurfaceHook.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXDummyUpstreamSurfaceHook.java
@@ -11,10 +11,10 @@ public class OSXDummyUpstreamSurfaceHook extends UpstreamSurfaceHookMutableSize
     long nsWindow;
 
     /**
-     * @param width the initial width as returned by {@link NativeSurface#getSurfaceWidth()} via {@link UpstreamSurfaceHook#getPixelWidth(ProxySurface)},
+     * @param width the initial width as returned by {@link NativeSurface#getSurfaceWidth()} via {@link UpstreamSurfaceHook#getSurfaceWidth(ProxySurface)},
      *        not the actual dummy surface width.
      *        The latter is platform specific and small
-     * @param height the initial height as returned by {@link NativeSurface#getSurfaceHeight()} via {@link UpstreamSurfaceHook#getPixelHeight(ProxySurface)},
+     * @param height the initial height as returned by {@link NativeSurface#getSurfaceHeight()} via {@link UpstreamSurfaceHook#getSurfaceHeight(ProxySurface)},
      *        not the actual dummy surface height,
      *        The latter is platform specific and small
      */
diff --git a/src/nativewindow/classes/jogamp/nativewindow/windows/GDIDummyUpstreamSurfaceHook.java b/src/nativewindow/classes/jogamp/nativewindow/windows/GDIDummyUpstreamSurfaceHook.java
index 9c74950e0..bf59a6639 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/windows/GDIDummyUpstreamSurfaceHook.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/windows/GDIDummyUpstreamSurfaceHook.java
@@ -9,10 +9,10 @@ import com.jogamp.nativewindow.UpstreamSurfaceHookMutableSize;
 
 public class GDIDummyUpstreamSurfaceHook extends UpstreamSurfaceHookMutableSize {
     /**
-     * @param width the initial width as returned by {@link NativeSurface#getSurfaceWidth()} via {@link UpstreamSurfaceHook#getPixelWidth(ProxySurface)},
+     * @param width the initial width as returned by {@link NativeSurface#getSurfaceWidth()} via {@link UpstreamSurfaceHook#getSurfaceWidth(ProxySurface)},
      *        not the actual dummy surface width.
      *        The latter is platform specific and small
-     * @param height the initial height as returned by {@link NativeSurface#getSurfaceHeight()} via {@link UpstreamSurfaceHook#getPixelHeight(ProxySurface)},
+     * @param height the initial height as returned by {@link NativeSurface#getSurfaceHeight()} via {@link UpstreamSurfaceHook#getSurfaceHeight(ProxySurface)},
      *        not the actual dummy surface height,
      *        The latter is platform specific and small
      */
diff --git a/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java b/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java
index c4ec0f653..c9e48e94e 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java
@@ -130,19 +130,13 @@ public class GDISurface extends ProxySurfaceImpl {
   }
 
   @Override
-  public final int[] getWindowUnitXY(int[] result, final int[] pixelUnitXY) {
-      if( pixelUnitXY != result ) { // no scale factor, window units == pixel units
-          System.arraycopy(pixelUnitXY, 0, result, 0, 2);
-      }
-      return result;
+  public final int[] convertToWindowUnits(final int[] pixelUnitsAndResult) {
+      return pixelUnitsAndResult; // no pixelScale factor
   }
 
   @Override
-  public final int[] getPixelUnitXY(int[] result, final int[] windowUnitXY) {
-      if( windowUnitXY != result ) { // no scale factor, window units == pixel units
-          System.arraycopy(windowUnitXY, 0, result, 0, 2);
-      }
-      return result;
+  public final int[] convertToPixelUnits(final int[] windowUnitsAndResult) {
+      return windowUnitsAndResult; // no pixelScale factor
   }
 
 }
diff --git a/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java b/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java
index 31d168fea..53b303071 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java
@@ -14,10 +14,10 @@ import com.jogamp.nativewindow.x11.X11GraphicsScreen;
 
 public class X11DummyUpstreamSurfaceHook extends UpstreamSurfaceHookMutableSize {
     /**
-     * @param width the initial width as returned by {@link NativeSurface#getSurfaceWidth()} via {@link UpstreamSurfaceHook#getPixelWidth(ProxySurface)},
+     * @param width the initial width as returned by {@link NativeSurface#getSurfaceWidth()} via {@link UpstreamSurfaceHook#getSurfaceWidth(ProxySurface)},
      *        not the actual dummy surface width.
      *        The latter is platform specific and small
-     * @param height the initial height as returned by {@link NativeSurface#getSurfaceHeight()} via {@link UpstreamSurfaceHook#getPixelHeight(ProxySurface)},
+     * @param height the initial height as returned by {@link NativeSurface#getSurfaceHeight()} via {@link UpstreamSurfaceHook#getSurfaceHeight(ProxySurface)},
      *        not the actual dummy surface height,
      *        The latter is platform specific and small
      */