Bug 742 HiDPI: [Core API Change] Distinguish window-units and pixel-units; Add HiDPI for AWT GLCanvas w/ OSX CALayer

Core API Change:

To support HiDPI thoroughly in JOGL (NativeWindow, JOGL, NEWT)
we need to separate window- and pixel units.

NativeWindow and NativeSurface now have distinguished
access methods for window units and pixel units.

  NativeWindow: Using window units
      - getWindowWidth()    * NEW Method *
      - getWindowHeight()   * NEW Method *
      - getX(), getY(), ...

  NativeSurface: Using pixel units
      - getWidth()  -> getSurfaceWidth()   * RENAMED *
      - getHeight() -> getSurfaceHeight()  * RENAMED *

  GLDrawable:  Using pixel units
      - getWidth()  -> getSurfaceWidth()   * RENAMED, aligned w/ NativeSurface *
      - getHeight() -> getSurfaceHeight()  * RENAMED, aligned w/ NativeSurface *

Above changes also removes API collision w/ other windowing TK,
e.g. AWT's getWidth()/getHeight() in GLCanvas
and the same method names in GLDrawable before this change.

+++

Now preliminary 'working':
  - AWT GLCanvas
  - AWT GLJPanel

Tested manually on OSX w/ and w/o HiDPI Retina:
  java com.jogamp.opengl.test.junit.jogl.demos.es2.awt.TestGearsES2AWT -manual -noanim -time 1000000
  java com.jogamp.opengl.test.junit.jogl.demos.es2.awt.TestGearsES2GLJPanelAWT -manual -noanim -time 1000000

+++

TODO:
  - NEWT
    - Change Window.setSize(..) to use pixel units ?
    - OSX HiDPI support

  - Testing ..

  - API refinement

6 files changed, 125 insertions, 46 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
index a755b1812..d5cc048a1 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
@@ -28,14 +28,20 @@
 
 package javax.media.nativewindow;
 
-/** Provides low-level information required for
-    hardware-accelerated rendering using a surface in a platform-independent manner.<P>
-
-    A NativeSurface created for a particular on- or offscreen component is
-    expected to have the same lifetime as that component. As long as
-    the component is alive and realized/visible, NativeSurface must be able
-    provide information such as the surface handle while it is locked.<P>
-*/
+/**
+ * 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}.
+ * </p>
+ * <p>
+ * A NativeSurface created for a particular on- or offscreen component is
+ * expected to have the same lifetime as that component. As long as
+ * the component is alive and realized/visible, NativeSurface must be able
+ * provide information such as the surface handle while it is locked.
+ * </p>
+ */
 public interface NativeSurface extends SurfaceUpdatedListener {
   /** Unlocked state */
   public static final int LOCK_SURFACE_UNLOCKED = 0;
@@ -172,16 +178,36 @@ public interface NativeSurface extends SurfaceUpdatedListener {
   public long getSurfaceHandle();
 
   /**
-   * Returns the width of the client area excluding insets (window decorations).
-   * @return width of the client area
+   * 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[])
+   */
+  public int getSurfaceWidth();
+
+  /**
+   * 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[])
+   */
+  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
    */
-  public int getWidth();
+  public int[] getWindowUnitXY(int[] result, final int[] pixelUnitXY);
 
   /**
-   * Returns the height of the client area excluding insets (window decorations).
-   * @return height of the client area
+   * 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
    */
-  public int getHeight();
+  public int[] getPixelUnitXY(int[] result, final int[] windowUnitXY);
 
   /**
    * Returns the graphics configuration corresponding to this window.
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
index a740ebbe0..242f25d43 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
@@ -43,14 +43,21 @@ package javax.media.nativewindow;
 import javax.media.nativewindow.util.InsetsImmutable;
 import javax.media.nativewindow.util.Point;
 
-/** Extend the {@link NativeSurface} interface with windowing
-    information such as window handle and position.<P>
-
-    A window toolkit such as the AWT may either implement this interface
-    directly with one of its components, or provide and register an
-    implementation of {@link NativeWindowFactory NativeWindowFactory}
-    which can create NativeWindow objects for its components. <P>
-*/
+/**
+ * Extend the {@link NativeSurface} interface with windowing
+ * 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}.
+ * </p>
+ * <p>
+ * A window toolkit such as the AWT may either implement this interface
+ * directly with one of its components, or provide and register an
+ * implementation of {@link NativeWindowFactory NativeWindowFactory}
+ * which can create NativeWindow objects for its components.
+ * </p>
+ */
 public interface NativeWindow extends NativeSurface {
 
   /**
@@ -76,8 +83,10 @@ public interface NativeWindow extends NativeSurface {
 
   /**
    * Returns the insets defined as the width and height of the window decoration
-   * on the left, right, top and bottom.<br>
+   * on the left, right, top and bottom in window units.
+   * <p>
    * Insets are zero if the window is undecorated, including child windows.
+   * </p>
    *
    * <p>
    * Insets are available only after the native window has been created,
@@ -85,14 +94,14 @@ public interface NativeWindow extends NativeSurface {
    *
    * The top-level window area's top-left corner is located at
    * <pre>
-   *   getX() - getInsets().{@link InsetsImmutable#getLeftWidth() getLeftWidth()}
-   *   getY() - getInsets().{@link InsetsImmutable#getTopHeight() getTopHeight()}
+   *   {@link #getX()} - getInsets().{@link InsetsImmutable#getLeftWidth() getLeftWidth()}
+   *   {@link #getY()} - getInsets().{@link InsetsImmutable#getTopHeight() getTopHeight()}
    * </pre>
    *
    * The top-level window size is
    * <pre>
-   *   getWidth()  + getInsets().{@link InsetsImmutable#getTotalWidth() getTotalWidth()}
-   *   getHeight() + getInsets().{@link InsetsImmutable#getTotalHeight() getTotalHeight()}
+   *   {@link #getWindowWidth()}  + getInsets().{@link InsetsImmutable#getTotalWidth() getTotalWidth()}
+   *   {@link #getWindowHeight()} + getInsets().{@link InsetsImmutable#getTotalHeight() getTotalHeight()}
    * </pre>
    *
    * @return insets
@@ -103,7 +112,7 @@ public interface NativeWindow extends NativeSurface {
 
   /**
    * @return the current x position of the top-left corner
-   *         of the client area relative to it's parent.
+   *         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.
    * @see #getInsets()
    */
@@ -111,15 +120,29 @@ public interface NativeWindow extends NativeSurface {
 
   /**
    * @return the current y position of the top-left corner
-   *         of the client area relative to it's parent.
+   *         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.
    * @see #getInsets()
    */
   public int getY();
 
   /**
+   * Returns the width of the client area excluding insets (window decorations) in window units.
+   * @return width of the client area in window units
+   * @see NativeSurface#getSurfaceWidth()
+   */
+  public int getWindowWidth();
+
+  /**
+   * Returns the height of the client area excluding insets (window decorations) in window units.
+   * @return height of the client area in window units
+   * @see NativeSurface#getSurfaceHeight()
+   */
+  public int getWindowHeight();
+
+  /**
    * Returns the current position of the top-left corner
-   * of the client area in screen coordinates.
+   * of the client area in window units.
    * <p>
    * Since the position reflects the client area, it does not include the insets.
    * </p>
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java
index 034bf2456..1546bd909 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java
@@ -56,7 +56,7 @@ import jogamp.nativewindow.x11.X11Lib;
 
 import com.jogamp.common.os.Platform;
 import com.jogamp.common.util.ReflectionUtil;
-import com.jogamp.nativewindow.UpstreamSurfaceHookMutableSizePos;
+import com.jogamp.nativewindow.UpstreamWindowHookMutableSizePos;
 import com.jogamp.nativewindow.awt.AWTGraphicsDevice;
 import com.jogamp.nativewindow.awt.AWTGraphicsScreen;
 import com.jogamp.nativewindow.macosx.MacOSXGraphicsDevice;
@@ -669,7 +669,7 @@ public abstract class NativeWindowFactory {
     /**
      * Creates a wrapped {@link NativeWindow} with given native handles and {@link AbstractGraphicsScreen}.
      * <p>
-     * The given {@link UpstreamSurfaceHookMutableSizePos} maybe used to reflect resizes and repositioning of the native window.
+     * The given {@link UpstreamWindowHookMutableSizePos} maybe used to reflect resizes and repositioning of the native window.
      * </p>
      * <p>
      * The {@link AbstractGraphicsScreen} may be created via {@link #createScreen(AbstractGraphicsDevice, int)}.
@@ -680,7 +680,7 @@ public abstract class NativeWindowFactory {
      * </p>
      */
     public static NativeWindow createWrappedWindow(AbstractGraphicsScreen aScreen, long surfaceHandle, long windowHandle,
-                                                   UpstreamSurfaceHookMutableSizePos hook) {
+                                                   UpstreamWindowHookMutableSizePos hook) {
         final CapabilitiesImmutable caps = new Capabilities();
         final AbstractGraphicsConfiguration config = new DefaultGraphicsConfiguration(aScreen, caps, caps);
         return new WrappedWindow(config, surfaceHandle, hook, true, windowHandle);
diff --git a/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
index f08a6c938..39e316856 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
@@ -38,15 +38,15 @@ public interface UpstreamSurfaceHook {
     /** called within {@link ProxySurface#destroyNotify()} within lock, before clearing fields. */
     public void destroy(ProxySurface s);
 
-    /** Returns the width of the upstream surface, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */
-    public int getWidth(ProxySurface s);
-    /** Returns the height of the upstream surface, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */
-    public int getHeight(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);
+    /** Returns the height of the upstream surface in pixels, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */
+    public int getPixelHeight(ProxySurface s);
 
     /**
      * {@link UpstreamSurfaceHook} w/ mutable size, allowing it's {@link ProxySurface} user to resize.
      */
     public interface MutableSize extends UpstreamSurfaceHook {
-        public void setSize(int width, int height);
+        public void setPixelSize(int width, int height);
     }
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/Insets.java b/src/nativewindow/classes/javax/media/nativewindow/util/Insets.java
index 3644916fe..dfe78b06f 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/Insets.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/Insets.java
@@ -28,11 +28,15 @@
 
 package javax.media.nativewindow.util;
 
+/**
+ * Mutable insets representing rectangular window decoration insets on all four edges
+ * in window units.
+ */
 public class Insets implements Cloneable, InsetsImmutable {
     static final InsetsImmutable zeroInsets = new Insets();
     public static final InsetsImmutable getZero() { return zeroInsets; }
 
-    int l, r, t, b;
+    private int l, r, t, b;
 
     public Insets() {
         this(0, 0, 0, 0);
@@ -72,12 +76,35 @@ public class Insets implements Cloneable, InsetsImmutable {
     @Override
     public final int getTotalHeight() { return t + b; }
 
+    /**
+     * Set the inset values of this instance in window units.
+     * @param left left inset width in window units.
+     * @param right right inset width in window units.
+     * @param top top inset width in window units.
+     * @param bottom bottom inset width in window units.
+     */
     public final void set(int left, int right, int top, int bottom) {
         l = left; r = right; t = top; b = bottom;
     }
+    /**
+     * Set the left inset value of this instance in window units.
+     * @param left left inset width in window units.
+     */
     public final void setLeftWidth(int left) { l = left; }
+    /**
+     * Set the right inset value of this instance in window units.
+     * @param right right inset width in window units.
+     */
     public final void setRightWidth(int right) { r = right; }
+    /**
+     * Set the top inset value of this instance in window units.
+     * @param top top inset width in window units.
+     */
     public final void setTopHeight(int top) { t = top; }
+    /**
+     * Set the bottom inset value of this instance in window units.
+     * @param bottom bottom inset width in window units.
+     */
     public final void setBottomHeight(int bottom) { b = bottom; }
 
     @Override
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/InsetsImmutable.java b/src/nativewindow/classes/javax/media/nativewindow/util/InsetsImmutable.java
index 8256068cd..0f8ba0158 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/InsetsImmutable.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/InsetsImmutable.java
@@ -30,25 +30,28 @@ package javax.media.nativewindow.util;
 
 import com.jogamp.common.type.WriteCloneable;
 
-/** Immutable Rectangle interface */
+/**
+ * Immutable insets representing rectangular window decoration insets on all four edges
+ * in window units.
+ */
 public interface InsetsImmutable extends WriteCloneable {
 
-    /** @return left inset width */
+    /** @return left inset width in window units. */
     int getLeftWidth();
 
-    /** @return right inset width */
+    /** @return right inset width in window units. */
     int getRightWidth();
 
-    /** @return total width, ie. <code>left_width + right_width</code> */
+    /** @return total width in window units, ie. <code>left_width + right_width</code> */
     int getTotalWidth();
 
-    /** @return top inset height */
+    /** @return top inset height in window units. */
     int getTopHeight();
 
-    /** @return bottom inset height */
+    /** @return bottom inset height in window units. */
     int getBottomHeight();
 
-    /** @return total height, ie. <code>top_height + bottom_height</code> */
+    /** @return total height in window units, ie. <code>top_height + bottom_height</code> */
     int getTotalHeight();
 
     /**