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, 74 insertions, 38 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
index 6b1bb0e5e..e9fe80a91 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
@@ -36,6 +36,7 @@ import javax.media.opengl.GLAutoDrawable;
 import javax.media.opengl.GLContext;
 import javax.media.opengl.GLDrawable;
 import javax.media.opengl.GLDrawableFactory;
+import javax.media.opengl.GLEventListener;
 import javax.media.opengl.GLException;
 
 import com.jogamp.common.util.locks.LockFactory;
@@ -101,7 +102,22 @@ public class GLAutoDrawableDelegate extends GLAutoDrawableBase implements GLAuto
         super.defaultWindowRepaintOp();
     }
 
-    /** Implementation to handle resize events from the windowing system. All required locks are being claimed. */
+    /**
+     * Handling resize events from the windowing system.
+     * <p>
+     * Implementation:
+     * <ul>
+     *   <li>resizes {@link #getDelegatedDrawable() the GLDrawable}, if offscreen,</li>
+     *   <li>triggers a pending {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape events}, and</li>
+     *   <li>issues a {@link #display()} call, if no animator is present.</li>
+     * </ul>
+     * </p>
+     * <p>
+     * All required locks are being claimed.
+     * </p>
+     * @param newWidth new width in pixel units
+     * @param newWidth new height in pixel units
+     */
     public final void windowResizedOp(int newWidth, int newHeight) {
         super.defaultWindowResizedOp(newWidth, newHeight);
     }
diff --git a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
index 1c6dced6a..ec0935c18 100644
--- a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
+++ b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
@@ -455,12 +455,12 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
        public final void destroy(ProxySurface s) { /* nop */ }
 
        @Override
-       public final int getPixelWidth(ProxySurface s) {
+       public final int getSurfaceWidth(ProxySurface s) {
            return clientArea.width;
        }
 
        @Override
-       public final int getPixelHeight(ProxySurface s) {
+       public final int getSurfaceHeight(ProxySurface s) {
            return clientArea.height;
        }
 
diff --git a/src/jogl/classes/javax/media/opengl/GLEventListener.java b/src/jogl/classes/javax/media/opengl/GLEventListener.java
index c8c3440b5..995ca2620 100644
--- a/src/jogl/classes/javax/media/opengl/GLEventListener.java
+++ b/src/jogl/classes/javax/media/opengl/GLEventListener.java
@@ -80,13 +80,23 @@ public interface GLEventListener extends EventListener {
       enabled. */
   public void display(GLAutoDrawable drawable);
 
-  /** Called by the drawable during the first repaint after the
-      component has been resized. The client can update the viewport
-      and view volume of the window appropriately, for example by a
-      call to {@link javax.media.opengl.GL#glViewport}; note that for
-      convenience the component has already called <code>glViewport(x,
-      y, width, height)</code> when this method is called, so the
-      client may not have to do anything in this method.
-  */
+  /**
+   * Called by the drawable during the first repaint after the
+   * component has been resized.
+   * <p>
+   * The client can update it's viewport associated data
+   * and view volume of the window appropriately.
+   * </p>
+   * <p>
+   * For efficiency the GL viewport has already been updated
+   * via <code>glViewport(x, y, width, height)</code> when this method is called.
+   * </p>
+   *
+   * @param drawable the triggering {@link GLAutoDrawable}
+   * @param x viewport x-coord in pixel units
+   * @param y viewport y-coord in pixel units
+   * @param width viewport width in pixel units
+   * @param height viewport height in pixel units
+   */
   public void reshape(GLAutoDrawable drawable, int x, int y, int width, int height);
 }
diff --git a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
index 052b08a4b..a34fca0fa 100644
--- a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
@@ -179,17 +179,17 @@ public interface GLFBODrawable extends GLDrawable {
     /** Resizeable {@link GLFBODrawable} specialization */
     public interface Resizeable extends GLFBODrawable {
         /**
-         * Resize this drawable.
+         * Resize this {@link GLFBODrawable}'s surface.
          * <p>
          * This drawable is being locked during operation.
          * </p>
          * @param context the {@link GLContext} bound to this drawable, will be made current during operation
          *                A prev. current context will be make current after operation.
-         * @param newWidth
-         * @param newHeight
+         * @param newWidth new width in pixel units
+         * @param newHeight new width in pixel units
          * @throws NativeWindowException in case the surface could no be locked
          * @throws GLException in case an error during the resize operation occurred
          */
-        void setSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException;
+        void setSurfaceSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException;
     }
 }
diff --git a/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java
index d34edaf2e..a69480242 100644
--- a/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java
@@ -37,19 +37,19 @@ import com.jogamp.opengl.FBObject;
  * exposing offscreen functionality.
  * <p>
  * This class distinguishes itself from {@link GLAutoDrawable}
- * with it's {@link #setSize(int, int)} functionality.
+ * with it's {@link #setSurfaceSize(int, int)} functionality.
  * </p>
  */
 public interface GLOffscreenAutoDrawable extends GLAutoDrawable, GLSharedContextSetter {
 
     /**
-     * Resize this auto drawable.
-     * @param newWidth
-     * @param newHeight
+     * Resize this {@link GLAutoDrawable}'s surface
+     * @param newWidth new width in pixel units
+     * @param newHeight new height in pixel units
      * @throws NativeWindowException in case the surface could no be locked
      * @throws GLException in case of an error during the resize operation
      */
-    void setSize(int newWidth, int newHeight) throws NativeWindowException, GLException;
+    void setSurfaceSize(int newWidth, int newHeight) throws NativeWindowException, GLException;
 
     /**
      * Set the upstream UI toolkit object.
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
index c5ce32827..d06b61624 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
@@ -101,7 +101,6 @@ import com.jogamp.opengl.JoglVersion;
 import com.jogamp.opengl.util.GLDrawableUtil;
 import com.jogamp.opengl.util.TileRenderer;
 
-import jogamp.nativewindow.jawt.JAWTUtil;
 import jogamp.opengl.Debug;
 import jogamp.opengl.GLContextImpl;
 import jogamp.opengl.GLDrawableHelper;
diff --git a/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java b/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java
index de7653570..493926f25 100644
--- a/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java
+++ b/src/jogl/classes/jogamp/opengl/GLAutoDrawableBase.java
@@ -216,8 +216,23 @@ public abstract class GLAutoDrawableBase implements GLAutoDrawable, GLStateKeepe
         }
     }
 
-    /** Default implementation to handle resize events from the windowing system. All required locks are being claimed. */
-    protected final void defaultWindowResizedOp(int newWidth, int newHeight) throws NativeWindowException, GLException {
+    /**
+     * Handling resize events from the windowing system.
+     * <p>
+     * Implementation:
+     * <ul>
+     *   <li>resizes {@link #getDelegatedDrawable() the GLDrawable}, if offscreen,</li>
+     *   <li>triggers a pending {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape events}, and</li>
+     *   <li>issues a {@link #display()} call, if no animator is present.</li>
+     * </ul>
+     * </p>
+     * <p>
+     * All required locks are being claimed.
+     * </p>
+     * @param newWidth new width in pixel units
+     * @param newWidth new height in pixel units
+     */
+    protected final void defaultWindowResizedOp(final int newWidth, final int newHeight) throws NativeWindowException, GLException {
         GLDrawableImpl _drawable = drawable;
         if( null!=_drawable ) {
             if(DEBUG) {
diff --git a/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java b/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java
index 6116a2886..c0603383a 100644
--- a/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java
+++ b/src/jogl/classes/jogamp/opengl/GLDrawableHelper.java
@@ -362,7 +362,7 @@ public class GLDrawableHelper {
               final ProxySurface ps = (ProxySurface) ns;
               final UpstreamSurfaceHook ush = ps.getUpstreamSurfaceHook();
               if(ush instanceof UpstreamSurfaceHook.MutableSize) {
-                  ((UpstreamSurfaceHook.MutableSize)ush).setPixelSize(newWidth, newHeight);
+                  ((UpstreamSurfaceHook.MutableSize)ush).setSurfaceSize(newWidth, newHeight);
               } else if(DEBUG) { // we have to assume UpstreamSurfaceHook contains the new size already, hence size check @ bottom
                   System.err.println("GLDrawableHelper.resizeOffscreenDrawable: Drawable's offscreen ProxySurface n.a. UpstreamSurfaceHook.MutableSize, but "+ush.getClass().getName()+": "+ush);
               }
diff --git a/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java b/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
index 0e9d3c1bb..bf6a56afe 100644
--- a/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
@@ -565,7 +565,7 @@ public class GLFBODrawableImpl extends GLDrawableImpl implements GLFBODrawable {
         }
 
         @Override
-        public final void setSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException {
+        public final void setSurfaceSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException {
             if(DEBUG) {
                 System.err.println("GLFBODrawableImpl.ResizeableImpl setSize: ("+getThreadName()+"): "+newWidth+"x"+newHeight+" - surfaceHandle 0x"+Long.toHexString(getNativeSurface().getSurfaceHandle()));
             }
@@ -578,7 +578,7 @@ public class GLFBODrawableImpl extends GLDrawableImpl implements GLFBODrawable {
                 final ProxySurface ps = (ProxySurface) getNativeSurface();
                 final UpstreamSurfaceHook ush = ps.getUpstreamSurfaceHook();
                 if(ush instanceof UpstreamSurfaceHook.MutableSize) {
-                    ((UpstreamSurfaceHook.MutableSize)ush).setPixelSize(newWidth, newHeight);
+                    ((UpstreamSurfaceHook.MutableSize)ush).setSurfaceSize(newWidth, newHeight);
                 } else {
                     throw new InternalError("GLFBODrawableImpl.ResizableImpl's ProxySurface doesn't hold a UpstreamSurfaceHookMutableSize but "+ush.getClass().getName()+", "+ps+", ush");
                 }
diff --git a/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java b/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java
index 345f08e4c..edfebdcfe 100644
--- a/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java
@@ -57,7 +57,7 @@ public class GLOffscreenAutoDrawableImpl extends GLAutoDrawableDelegate implemen
     }
 
     @Override
-    public void setSize(int newWidth, int newHeight) throws NativeWindowException, GLException {
+    public void setSurfaceSize(int newWidth, int newHeight) throws NativeWindowException, GLException {
         this.defaultWindowResizedOp(newWidth, newHeight);
     }
 
diff --git a/src/jogl/classes/jogamp/opengl/egl/EGLDummyUpstreamSurfaceHook.java b/src/jogl/classes/jogamp/opengl/egl/EGLDummyUpstreamSurfaceHook.java
index 6deaa26c7..205a94951 100644
--- a/src/jogl/classes/jogamp/opengl/egl/EGLDummyUpstreamSurfaceHook.java
+++ b/src/jogl/classes/jogamp/opengl/egl/EGLDummyUpstreamSurfaceHook.java
@@ -10,10 +10,10 @@ import com.jogamp.nativewindow.egl.EGLGraphicsDevice;
 /** Uses a PBuffer offscreen surface */
 public class EGLDummyUpstreamSurfaceHook 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/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java b/src/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java
index 8cc4580a7..d0dc79437 100644
--- a/src/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java
+++ b/src/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java
@@ -45,9 +45,9 @@ public class EGLUpstreamSurfaceHook implements UpstreamSurfaceHook.MutableSize {
     static String getThreadName() { return Thread.currentThread().getName(); }
 
     @Override
-    public final void setPixelSize(int width, int height) {
+    public final void setSurfaceSize(int width, int height) {
         if(null != upstreamSurfaceHookMutableSize) {
-            upstreamSurfaceHookMutableSize.setPixelSize(width, height);
+            upstreamSurfaceHookMutableSize.setSurfaceSize(width, height);
         }
     }
 
@@ -199,12 +199,12 @@ public class EGLUpstreamSurfaceHook implements UpstreamSurfaceHook.MutableSize {
     }
 
     @Override
-    public final int getPixelWidth(ProxySurface s) {
+    public final int getSurfaceWidth(ProxySurface s) {
         return upstreamSurface.getSurfaceWidth();
     }
 
     @Override
-    public final int getPixelHeight(ProxySurface s) {
+    public final int getSurfaceHeight(ProxySurface s) {
         return upstreamSurface.getSurfaceHeight();
     }
 
diff --git a/src/jogl/classes/jogamp/opengl/macosx/cgl/MacOSXCGLContext.java b/src/jogl/classes/jogamp/opengl/macosx/cgl/MacOSXCGLContext.java
index d3cfffdea..485fbd0a0 100644
--- a/src/jogl/classes/jogamp/opengl/macosx/cgl/MacOSXCGLContext.java
+++ b/src/jogl/classes/jogamp/opengl/macosx/cgl/MacOSXCGLContext.java
@@ -859,11 +859,7 @@ public class MacOSXCGLContext extends GLContextImpl
                   }
 
                   // All CALayer lifecycle ops are deferred on main-thread
-                  final int[] winSize;
-                  {
-                      final int[] pixelSize = { lastWidth, lastHeight };
-                      winSize = drawable.getNativeSurface().getWindowUnitXY(pixelSize, pixelSize);
-                  }
+                  final int[] winSize = drawable.getNativeSurface().convertToWindowUnits(new int[]{ lastWidth, lastHeight });
                   attachGLLayerCmd = new AttachGLLayerCmd(
                           backingLayerHost, ctx, gl3ShaderProgramName, pixelFormat, pbufferHandle, texID,
                           chosenCaps.isBackgroundOpaque(), lastWidth, lastHeight, winSize[0], winSize[1] );