Bug 1120 - Refine HiDPI Support ( Part-2 ) (API CHANGE)

- Use float[2] for pixel-scale.
  Utilize simple integer rounding:
    int-pixel-units = (int) ( int-window-units * pixel-scale + 0.5f )

- Provide minimum and maximum allowed pixel-scale values
  to be set by platform, supporting generic pixel-scale validation.

- Remove 'OSXUtil.GetPixelScale(final RectangleImmutable r, final int[] screenIndexOut)',
  implementation for all platforms would cause huge redundancy of
  Screen and MonitorDevice code (duplication of NEWT).

- instead, add 'float[2] pixelScale' to NEWT's MonitorDevice

- Detect change of pixel-scale and propagate accordingly.
  This allows GLCanvas, GLJPanel and NewtCanvasAWT instances
  to be dragged between monitor devices w/ different pixel-scale.

- OSX: Handle native triggered reshape events off-thread to avoid EDT congestion
       due to locked window when consuming deferred events on EDT.

3 files changed, 64 insertions, 21 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
index 4d764dc4f..d5ac56178 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
@@ -198,6 +198,7 @@ public interface NativeSurface extends SurfaceUpdatedListener {
    * @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
+   * @see ScalableSurface
    */
   public int[] convertToWindowUnits(final int[] pixelUnitsAndResult);
 
@@ -206,6 +207,7 @@ public interface NativeSurface extends SurfaceUpdatedListener {
    * @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
+   * @see ScalableSurface
    */
   public int[] convertToPixelUnits(final int[] windowUnitsAndResult);
 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/ScalableSurface.java b/src/nativewindow/classes/javax/media/nativewindow/ScalableSurface.java
index ffd5c224c..0cd2c7961 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/ScalableSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/ScalableSurface.java
@@ -30,16 +30,17 @@ package javax.media.nativewindow;
 
 /**
  * Adding mutable surface pixel scale property to implementing class, usually to a {@link NativeSurface} implementation,
- * see {@link #setSurfaceScale(int[])}.
+ * see {@link #setSurfaceScale(float[])}.
  */
 public interface ScalableSurface {
   /** Setting surface-pixel-scale of {@value}, results in same pixel- and window-units. */
-  public static final int IDENTITY_PIXELSCALE = 1;
+  public static final float IDENTITY_PIXELSCALE = 1f;
   /** Setting surface-pixel-scale of {@value}, results in maximum platform dependent pixel-scale, i.e. pixel-units >> window-units where available. */
-  public static final int AUTOMAX_PIXELSCALE = 0;
+  public static final float AUTOMAX_PIXELSCALE = 0f;
 
   /**
-   * Request a pixel scale in x- and y-direction for the associated {@link NativeSurface}.
+   * Request a pixel scale in x- and y-direction for the associated {@link NativeSurface},
+   * where {@code size_in_pixel_units = pixel_scale * size_in_window_units}.
    * <p>
    * Default pixel scale request for both directions is {@link #AUTOMAX_PIXELSCALE}.
    * </p>
@@ -50,48 +51,57 @@ public interface ScalableSurface {
    * <p>
    * The <i>requested</i> pixel scale will be validated against platform limits before native scale-setup,
    * i.e. clipped to {@link #IDENTITY_PIXELSCALE} if not supported or clipped to the platform maximum.
-   * It can be queried via {@link #getRequestedSurfaceScale(int[])}.
+   * It can be queried via {@link #getRequestedSurfaceScale(float[])}.
    * </p>
    * <p>
    * The actual <i>realized</i> pixel scale values of the {@link NativeSurface}
-   * can be queried via {@link #getCurrentSurfaceScale(int[])} or
+   * can be queried via {@link #getCurrentSurfaceScale(float[])} or
    * computed via <code>surface.{@link NativeSurface#convertToPixelUnits(int[]) convertToPixelUnits}(new int[] { 1, 1 })</code>
    * </p>
- * @param pixelScale <i>requested</i> surface pixel scale int[2] values for x- and y-direction.
+   * @param pixelScale <i>requested</i> surface pixel scale float[2] values for x- and y-direction.
+   * @return {@code true} if the {@link #getCurrentSurfaceScale(float[]) current pixel scale} has changed, otherwise {@code false}.
+   * @see #getRequestedSurfaceScale(float[])
    */
-  public void setSurfaceScale(final int[] pixelScale);
+  public boolean setSurfaceScale(final float[] pixelScale);
 
   /**
-   * Returns the requested pixel scale of the associated {@link NativeSurface}.
+   * Returns the {@link #setSurfaceScale(float[]) requested} pixel scale of the associated {@link NativeSurface}.
    *
-   * @param result int[2] storage for the result
-   * @return the passed storage containing the requested pixelScale for chaining
+   * @param result float[2] storage for the result
+   * @return the passed storage containing the current pixelScale for chaining
+   * @see #setSurfaceScale(float[])
    */
-  int[] getRequestedSurfaceScale(final int[] result);
+  public float[] getRequestedSurfaceScale(final float[] result);
 
   /**
    * Returns the current pixel scale of the associated {@link NativeSurface}.
    *
-   * @param result int[2] storage for the result
+   * @param result float[2] storage for the result
    * @return the passed storage containing the current pixelScale for chaining
    */
-  public int[] getCurrentSurfaceScale(final int[] result);
+  public float[] getCurrentSurfaceScale(final float[] result);
+
+  /**
+   * Returns the minimum pixel scale of the associated {@link NativeSurface}.
+   * @param result float[2] storage for the result
+   * @return the passed storage containing the minimum pixelScale for chaining
+   */
+  public float[] getMinimumSurfaceScale(final float[] result);
 
   /**
-   * Returns the native pixel scale of the associated {@link NativeSurface}
-   * reflecting it's currently bound <i>monitor surface resolution in pixels</i>.
+   * Returns the maximum pixel scale of the associated {@link NativeSurface}.
    * <p>
-   * The native pixel scale maybe used to determine the proper <i>dpi</i>
-   * value of this {@link NativeSurface}:
+   * The maximum pixel scale maybe used to determine the proper <i>dpi</i>
+   * value of the monitor displaying this {@link NativeSurface}.
    * <pre>
    *    surfacePpMM = monitorPpMM * currentSurfaceScale / nativeSurfaceScale,
    *    with PpMM == pixel per millimeter
    * </pre>
    * </p>
    *
-   * @param result int[2] storage for the result
-   * @return the passed storage containing the native pixelScale for chaining
+   * @param result float[2] storage for the result
+   * @return the passed storage containing the maximum pixelScale for chaining
    */
-  public int[] getNativeSurfaceScale(final int[] result);
+  public float[] getMaximumSurfaceScale(final float[] result);
 }
 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/Point.java b/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
index 3576a7dd0..3d416d2f5 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
@@ -145,6 +145,22 @@ public class Point implements Cloneable, PointImmutable {
     }
 
     /**
+     * Scale this instance's x- and y-components,
+     * i.e. multiply them by the given scale factors.
+     * <p>
+     * The product is rounded back to integer.
+     * </p>
+     * @param sx scale factor for x
+     * @param sy scale factor for y
+     * @return this instance for scaling
+     */
+    public final Point scale(final float sx, final float sy) {
+        x = (int)(x * sx + 0.5f);
+        y = (int)(y * sy + 0.5f);
+        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
@@ -156,4 +172,19 @@ public class Point implements Cloneable, PointImmutable {
         y /= sy ;
         return this;
     }
+    /**
+     * Inverse scale this instance's x- and y-components,
+     * i.e. divide them by the given scale factors.
+     * <p>
+     * The product is rounded back to integer.
+     * </p>
+     * @param sx inverse scale factor for x
+     * @param sy inverse scale factor for y
+     * @return this instance for scaling
+     */
+    public final Point scaleInv(final float sx, final float sy) {
+        x = (int)(x / sx + 0.5f);
+        y = (int)(y / sy + 0.5f);
+        return this;
+    }
 }