Add Comparable<?>: Point*, Dimension*, Rectangle*, SurfaceSize* and MonitorMode* ; Sort List<MonitorMode> in descending order to be well determined.

Add Comparable<?>: Point*, Dimension*, Rectangle*, SurfaceSize* and MonitorMode*:
  - Compare square values
  - See API doc for order of special semantics (flags, rotation, ..)

Sort List<MonitorMode> in descending order to be well determined:
  - Removes order by native mode id, give user a reliable natural order.

13 files changed, 268 insertions, 18 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/Dimension.java b/src/nativewindow/classes/javax/media/nativewindow/util/Dimension.java
index 4fae98f08..b52414146 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/Dimension.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/Dimension.java
@@ -85,6 +85,19 @@ public class Dimension implements Cloneable, DimensionImmutable {
     }
 
     @Override
+    public int compareTo(final DimensionImmutable d) {
+        final int tsq = width*height;
+        final int xsq = d.getWidth()*d.getHeight();
+        
+        if(tsq > xsq) {
+            return 1;
+        } else if(tsq < xsq) {
+            return -1;
+        }
+        return 0;
+    }
+    
+    @Override
     public boolean equals(Object obj) {
         if(this == obj)  { return true; }
         if (obj instanceof Dimension) {
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/DimensionImmutable.java b/src/nativewindow/classes/javax/media/nativewindow/util/DimensionImmutable.java
index d14e94c10..22bd3f48b 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/DimensionImmutable.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/DimensionImmutable.java
@@ -37,13 +37,22 @@ import com.jogamp.common.type.WriteCloneable;
  *  <li><code>height</code></li>
  * </ul>
  */
-public interface DimensionImmutable extends WriteCloneable {
+public interface DimensionImmutable extends WriteCloneable, Comparable<DimensionImmutable> {
 
     int getHeight();
 
     int getWidth();
 
     /**
+     * <p>
+     * Compares square of size.
+     * </p> 
+     * {@inheritDoc}
+     */
+    @Override
+    public int compareTo(final DimensionImmutable d);
+    
+    /**
      * Checks whether two dimensions objects are equal. Two instances
      * of <code>DimensionReadOnly</code> are equal if two components
      * <code>height</code> and <code>width</code> are equal.
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/Point.java b/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
index 8e6caf72b..a30d3030e 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/Point.java
@@ -55,6 +55,19 @@ public class Point implements Cloneable, PointImmutable {
     }
 
     @Override
+    public int compareTo(final PointImmutable d) {
+        final int sq = x*y;
+        final int xsq = d.getX()*d.getY();
+        
+        if(sq > xsq) {
+            return 1;
+        } else if(sq < xsq) {
+            return -1;
+        }
+        return 0;
+    }
+    
+    @Override
     public boolean equals(Object obj) {
         if(this == obj)  { return true; }
         if (obj instanceof Point) {
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/PointImmutable.java b/src/nativewindow/classes/javax/media/nativewindow/util/PointImmutable.java
index d7eb0e7b4..b00329bb5 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/PointImmutable.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/PointImmutable.java
@@ -32,13 +32,22 @@ package javax.media.nativewindow.util;
 import com.jogamp.common.type.WriteCloneable;
 
 /** Immutable Point interface */
-public interface PointImmutable extends WriteCloneable {
+public interface PointImmutable extends WriteCloneable, Comparable<PointImmutable> {
 
     int getX();
 
     int getY();
 
     /**
+     * <p>
+     * Compares the square of the position.
+     * </p> 
+     * {@inheritDoc}
+     */
+    @Override
+    public int compareTo(final PointImmutable d);
+    
+    /**
      * Checks whether two points objects are equal. Two instances
      * of <code>PointReadOnly</code> are equal if the two components
      * <code>y</code> and <code>x</code> are equal.
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/Rectangle.java b/src/nativewindow/classes/javax/media/nativewindow/util/Rectangle.java
index 8e6fc8e36..7576f4ec7 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/Rectangle.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/Rectangle.java
@@ -143,6 +143,31 @@ public class Rectangle implements Cloneable, RectangleImmutable {
     }
     
     @Override
+    public int compareTo(final RectangleImmutable d) {
+        {
+            final int sq = width*height;
+            final int xsq = d.getWidth()*d.getHeight();
+            
+            if(sq > xsq) {
+                return 1;
+            } else if(sq < xsq) {
+                return -1;
+            }
+        }
+        {
+            final int sq = x*y;
+            final int xsq = d.getX()*d.getY();
+            
+            if(sq > xsq) {
+                return 1;
+            } else if(sq < xsq) {
+                return -1;
+            }
+        }
+        return 0;
+    }
+    
+    @Override
     public boolean equals(Object obj) {
         if(this == obj)  { return true; }
         if (obj instanceof Rectangle) {
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/RectangleImmutable.java b/src/nativewindow/classes/javax/media/nativewindow/util/RectangleImmutable.java
index 7531989de..440d9e000 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/RectangleImmutable.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/RectangleImmutable.java
@@ -31,7 +31,7 @@ package javax.media.nativewindow.util;
 import com.jogamp.common.type.WriteCloneable;
 
 /** Immutable Rectangle interface */
-public interface RectangleImmutable extends WriteCloneable {
+public interface RectangleImmutable extends WriteCloneable, Comparable<RectangleImmutable> {
 
     int getHeight();
 
@@ -62,6 +62,15 @@ public interface RectangleImmutable extends WriteCloneable {
     float coverage(RectangleImmutable r);
     
     /**
+     * <p>
+     * Compares square of size 1st, if equal the square of position.
+     * </p> 
+     * {@inheritDoc}
+     */
+    @Override
+    public int compareTo(final RectangleImmutable d);
+    
+    /**
      * Checks whether two rect objects are equal. Two instances
      * of <code>Rectangle</code> are equal if the four integer values
      * of the fields <code>y</code>, <code>x</code>,
diff --git a/src/nativewindow/classes/javax/media/nativewindow/util/SurfaceSize.java b/src/nativewindow/classes/javax/media/nativewindow/util/SurfaceSize.java
index d7e451af8..3084816a5 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/util/SurfaceSize.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/util/SurfaceSize.java
@@ -29,13 +29,14 @@
  
 package javax.media.nativewindow.util;
 
-/** Immutable SurfaceSize Class, consisting of it's read only components:<br>
+/** 
+ * Immutable SurfaceSize Class, consisting of it's read only components:<br>
  * <ul>
  *  <li>{@link javax.media.nativewindow.util.DimensionImmutable} size in pixels</li>
  *  <li><code>bits per pixel</code></li>
  * </ul>
  */
-public class SurfaceSize {
+public class SurfaceSize implements Comparable<SurfaceSize> {
     final DimensionImmutable resolution;
     final int bitsPerPixel;
 
@@ -60,6 +61,27 @@ public class SurfaceSize {
     }
 
     /**
+     * <p>
+     * Compares {@link DimensionImmutable#compareTo(DimensionImmutable) resolution} 1st, if equal the bitsPerPixel.
+     * </p> 
+     * {@inheritDoc}
+     */
+    @Override
+    public int compareTo(final SurfaceSize ssz) {
+        final int rres = resolution.compareTo(ssz.getResolution());
+        if( 0 != rres ) {
+            return rres;
+        }
+        final int xbpp = ssz.getBitsPerPixel(); 
+        if(bitsPerPixel > xbpp) {
+            return 1;
+        } else if(bitsPerPixel < xbpp) {
+            return -1;
+        }
+        return 0;
+    }
+    
+    /**
      * Checks whether two size objects are equal. Two instances
      * of <code>SurfaceSize</code> are equal if the two components
      * <code>resolution</code> and <code>bitsPerPixel</code>
diff --git a/src/newt/classes/com/jogamp/newt/MonitorDevice.java b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
index 4b0a760a4..8bc7f40e3 100644
--- a/src/newt/classes/com/jogamp/newt/MonitorDevice.java
+++ b/src/newt/classes/com/jogamp/newt/MonitorDevice.java
@@ -129,6 +129,10 @@ public abstract class MonitorDevice {
     /**
      * Returns a list of immutable {@link MonitorMode}s supported by this monitor.
      * <p>
+     * The list is ordered in descending order,
+     * see {@link MonitorMode#compareTo(MonitorMode)}.
+     * </p>
+     * <p>
      * Use w/ care, it's not a copy!
      * </p>
      */
diff --git a/src/newt/classes/com/jogamp/newt/MonitorMode.java b/src/newt/classes/com/jogamp/newt/MonitorMode.java
index 914aa880f..dc7ae2c03 100644
--- a/src/newt/classes/com/jogamp/newt/MonitorMode.java
+++ b/src/newt/classes/com/jogamp/newt/MonitorMode.java
@@ -28,6 +28,8 @@
 
 package com.jogamp.newt;
 
+import java.util.Comparator;
+
 import javax.media.nativewindow.util.DimensionImmutable;
 import javax.media.nativewindow.util.RectangleImmutable;
 import javax.media.nativewindow.util.SurfaceSize;
@@ -108,22 +110,36 @@ import com.jogamp.newt.util.MonitorModeUtil;
         monitor.setCurrentMode(mm);
  * </pre>
  */
-public class MonitorMode {
+public class MonitorMode implements Comparable<MonitorMode> {
+    
+    /** Comparator for 2 {@link MonitorMode}s, following comparison order as described in {@link MonitorMode#compareTo(MonitorMode)}, returning the ascending order. */
+    public static final Comparator<MonitorMode> monitorModeComparator = new Comparator<MonitorMode>() {
+        public int compare(MonitorMode mm1, MonitorMode mm2) {
+            return mm1.compareTo(mm2);
+        } };
+    
+    /** Comparator for 2 {@link MonitorMode}s, following comparison order as described in {@link MonitorMode#compareTo(MonitorMode)}, returning the descending order. */
+    public static final Comparator<MonitorMode> monitorModeComparatorInv = new Comparator<MonitorMode>() {
+        public int compare(MonitorMode mm1, MonitorMode mm2) {
+            return mm2.compareTo(mm1);
+        } };
+        
     /** 
-     * Immutable <i>surfaceSize and refreshRate</i> Class, consisting of it's read only components:<br>
+     * Immutable <i>surfaceSize, flags and refreshRate</i> Class, consisting of it's read only components:<br>
      * <ul>
      *  <li>nativeId</li>
      *  <li>{@link SurfaceSize} surface memory size</li>
+     *  <li><code>flags</code></li>
      *  <li><code>refresh rate</code></li>
      * </ul>
      */
-    public static class SizeAndRRate {
+    public static class SizeAndRRate implements Comparable<SizeAndRRate> {
         /** Non rotated surface size */
         public final SurfaceSize surfaceSize;
-        /** Vertical refresh rate */
-        public final float refreshRate;
         /** Mode bitfield flags, i.e. {@link #FLAG_DOUBLESCAN}, {@link #FLAG_INTERLACE}, .. */
         public final int flags;
+        /** Vertical refresh rate */
+        public final float refreshRate;
         public final int hashCode;
     
         public SizeAndRRate(SurfaceSize surfaceSize, float refreshRate, int flags) {
@@ -131,8 +147,8 @@ public class MonitorMode {
                 throw new IllegalArgumentException("surfaceSize must be set ("+surfaceSize+")");
             }
             this.surfaceSize=surfaceSize;
-            this.refreshRate=refreshRate;
             this.flags = flags;
+            this.refreshRate=refreshRate;
             this.hashCode = getHashCode();
         }
     
@@ -161,6 +177,49 @@ public class MonitorMode {
         }
     
         /**
+         * <p>
+         * Compares {@link SurfaceSize#compareTo(SurfaceSize) surfaceSize} 1st, then {@link #flags}, then {@link #refreshRate}.
+         * </p> 
+         * <p>
+         * Flags are compared as follows:
+         * <pre>
+         *   NONE > DOUBLESCAN > INTERLACE
+         * </pre>
+         * </p>
+         * <p>
+         * Refresh rate differences of &lt; 0.01 are considered equal (epsilon).
+         * </p>
+         * {@inheritDoc}
+         */
+        @Override
+        public int compareTo(final SizeAndRRate sszr) {
+            final int rssz = surfaceSize.compareTo(sszr.surfaceSize);
+            if( 0 != rssz ) {
+                return rssz;
+            }            
+            final int tflags = 0 == flags ? Integer.MAX_VALUE : flags; // normalize NONE
+            final int xflags = 0 == sszr.flags ? Integer.MAX_VALUE : sszr.flags; // normalize NONE
+            if( tflags == xflags ) {
+                final float refreshEpsilon = 0.01f; // reasonable sorting granularity of refresh rate
+                final float drate = refreshRate - sszr.refreshRate;
+                if( Math.abs(drate) < refreshEpsilon ) {
+                    return 0;
+                } else if( drate > refreshEpsilon ) {
+                    return 1;
+                } else {
+                    return -1;
+                }
+            } else {
+                if(tflags > xflags) {
+                    return 1;
+                } else if(tflags < xflags) {
+                    return -1;
+                }
+                return 0;
+            }
+        }
+        
+        /**
          * Tests equality of two {@link SizeAndRRate} objects 
          * by evaluating equality of it's components:<br/>
          * <ul>
@@ -174,8 +233,8 @@ public class MonitorMode {
             if (obj instanceof SizeAndRRate) {
                 final SizeAndRRate p = (SizeAndRRate)obj;
                 return surfaceSize.equals(p.surfaceSize) &&
-                       refreshRate == p.refreshRate &&
-                       flags == p.flags ;
+                       flags == p.flags &&
+                       refreshRate == p.refreshRate ;
             }
             return false;
         }
@@ -184,8 +243,8 @@ public class MonitorMode {
          * Returns a combined hash code of it's elements:<br/>
          * <ul>
          *  <li><code>surfaceSize</code></li>
-         *  <li><code>refreshRate</code></li>
          *  <li><code>flags</code></li>
+         *  <li><code>refreshRate</code></li>
          * </ul>
          */
         public final int hashCode() {
@@ -194,8 +253,8 @@ public class MonitorMode {
         private final int getHashCode() {
             // 31 * x == (x << 5) - x
             int hash = 31 + surfaceSize.hashCode();
-            hash = ((hash << 5) - hash) + (int)(refreshRate*100.0f);
             hash = ((hash << 5) - hash) + flags;
+            hash = ((hash << 5) - hash) + (int)(refreshRate*100.0f);
             return hash;
         }        
     }
@@ -306,6 +365,42 @@ public class MonitorMode {
     }
 
     /**
+     * <p>
+     * Compares {@link SizeAndRRate#compareTo(SizeAndRRate) sizeAndRRate} 1st, then {@link #rotation}.
+     * </p> 
+     * <p>
+     * Rotation is compared inverted, i.e. <code>360 - rotation</code>, 
+     * so the lowest rotation reflects a higher value.
+     * </p>
+     * <p>
+     * Order of comparing MonitorMode:
+     * <ul>
+     *   <li>resolution</li>
+     *   <li>bits per pixel</li>
+     *   <li>flags</li>
+     *   <li>refresh rate</li>
+     *   <li>rotation</li>
+     * </ul> 
+     * </p>
+     * {@inheritDoc}
+     */
+    @Override
+    public int compareTo(final MonitorMode mm) {
+        final int c = sizeAndRRate.compareTo(mm.sizeAndRRate);
+        if( 0 != c ) {
+            return c;
+        }
+        final int trot = 360 - rotation; // normalize rotation
+        final int xrot = 360 - mm.rotation; // normalize rotation
+        if(trot > xrot) {
+            return 1;
+        } else if(trot < xrot) {
+            return -1;
+        }
+        return 0;
+    }
+    
+    /**
      * Tests equality of two {@link MonitorMode} objects 
      * by evaluating equality of it's components:<br/>
      * <ul>
diff --git a/src/newt/classes/com/jogamp/newt/Screen.java b/src/newt/classes/com/jogamp/newt/Screen.java
index f56aff964..9b349b527 100644
--- a/src/newt/classes/com/jogamp/newt/Screen.java
+++ b/src/newt/classes/com/jogamp/newt/Screen.java
@@ -164,6 +164,10 @@ public abstract class Screen {
 
     /** 
      * Return a list of all {@link MonitorMode}s for all {@link MonitorDevice}s.
+     * <p>
+     * The list is ordered in descending order,
+     * see {@link MonitorMode#compareTo(MonitorMode)}.
+     * </p>
      */
     public abstract List<MonitorMode> getMonitorModes();
 
diff --git a/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java b/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java
index 16ffe754f..c30b427d6 100644
--- a/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java
+++ b/src/newt/classes/com/jogamp/newt/util/MonitorModeUtil.java
@@ -31,7 +31,9 @@ package com.jogamp.newt.util;
 import com.jogamp.newt.MonitorMode;
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
+
 import javax.media.nativewindow.util.DimensionImmutable;
 import javax.media.nativewindow.util.SurfaceSize;
 
@@ -68,6 +70,15 @@ public class MonitorModeUtil {
         return null;
     }
     
+    /** Sort the given {@link MonitorMode} collection w/ {@link MonitorMode#compareTo(MonitorMode)} function. */
+    public static void sort(List<MonitorMode> monitorModes, boolean ascendingOrder) {
+        if( ascendingOrder ) {
+            Collections.sort(monitorModes);
+        } else {
+            Collections.sort(monitorModes, MonitorMode.monitorModeComparatorInv);
+        }
+    }
+    
     /**
      * 
      * @param monitorModes
diff --git a/src/newt/classes/jogamp/newt/ScreenImpl.java b/src/newt/classes/jogamp/newt/ScreenImpl.java
index f63d1499e..28f3e876c 100644
--- a/src/newt/classes/jogamp/newt/ScreenImpl.java
+++ b/src/newt/classes/jogamp/newt/ScreenImpl.java
@@ -52,6 +52,7 @@ import com.jogamp.newt.NewtFactory;
 import com.jogamp.newt.Screen;
 import com.jogamp.newt.event.MonitorEvent;
 import com.jogamp.newt.event.MonitorModeListener;
+import com.jogamp.newt.util.MonitorModeUtil;
 
 public abstract class ScreenImpl extends Screen implements MonitorModeListener {
     protected static final boolean DEBUG_TEST_SCREENMODE_DISABLED = Debug.isPropertyDefined("newt.test.Screen.disableScreenMode", true);
@@ -536,6 +537,11 @@ public abstract class ScreenImpl extends Screen implements MonitorModeListener {
                     final MonitorDevice monitor = getVirtualMonitorDevice(cache, 0, mode);
                     cache.monitorDevices.getOrAdd(monitor);
                 }
+                // Sort MonitorModes (all and per device) in descending order - default!
+                MonitorModeUtil.sort(cache.monitorModes.getData(), false /* ascendingOrder*/);
+                for(Iterator<MonitorDevice> iMonitor=cache.monitorDevices.iterator(); iMonitor.hasNext(); ) {
+                    MonitorModeUtil.sort(iMonitor.next().getSupportedModes(), false /* ascendingOrder*/);
+                }
                 if(DEBUG) {
                     int i=0;
                     for(Iterator<MonitorMode> iMode=cache.monitorModes.iterator(); iMode.hasNext(); i++) {
@@ -550,7 +556,7 @@ public abstract class ScreenImpl extends Screen implements MonitorModeListener {
                             System.err.println("["+i+"]["+j+"]: "+iMode.next());
                         }
                     }
-                }
+                }                
                 sms = new ScreenMonitorState(cache.monitorDevices, cache.monitorModes);
                 ScreenMonitorState.mapScreenMonitorState(this.getFQName(), sms);
             }
diff --git a/src/test/com/jogamp/opengl/test/junit/newt/mm/TestScreenMode00aNEWT.java b/src/test/com/jogamp/opengl/test/junit/newt/mm/TestScreenMode00aNEWT.java
index 123199427..7a15971d5 100644
--- a/src/test/com/jogamp/opengl/test/junit/newt/mm/TestScreenMode00aNEWT.java
+++ b/src/test/com/jogamp/opengl/test/junit/newt/mm/TestScreenMode00aNEWT.java
@@ -41,7 +41,9 @@ import com.jogamp.newt.MonitorDevice;
 import com.jogamp.newt.NewtFactory;
 import com.jogamp.newt.MonitorMode;
 import com.jogamp.newt.Screen;
+import com.jogamp.newt.util.MonitorModeUtil;
 import com.jogamp.opengl.test.junit.util.UITestCase;
+
 import java.util.Iterator;
 import java.util.List;
 import javax.media.nativewindow.util.Dimension;
@@ -56,6 +58,9 @@ import jogamp.newt.MonitorModeProps;
 /**
  * Validating consistency of MonitorMode data from Screen (all modes)
  * and from a particular MonitorDevice.
+ * <p>
+ * Also validates the descending order of the given MonitorMode lists.
+ * </p>
  */
 public class TestScreenMode00aNEWT extends UITestCase {
     static int screenIdx = 0;
@@ -130,8 +135,27 @@ public class TestScreenMode00aNEWT extends UITestCase {
         Assert.assertTrue(allMonitorModes.size()>0);
         {
             int i=0;
+            MonitorMode mmPre = null;
+            for(Iterator<MonitorMode> iMode=allMonitorModes.iterator(); iMode.hasNext(); i++) {
+                final MonitorMode mm = iMode.next();
+                System.err.println(String.format("All-0[%03d]: %s", i, mm));
+                if( null != mmPre ) {
+                    Assert.assertTrue("Wrong order", mmPre.compareTo(mm) >= 0);
+                }
+                mmPre = mm;
+            }
+        }
+        MonitorModeUtil.sort(allMonitorModes, true /* ascendingOrder*/);
+        {
+            int i=0;
+            MonitorMode mmPre = null;
             for(Iterator<MonitorMode> iMode=allMonitorModes.iterator(); iMode.hasNext(); i++) {
-                System.err.println("All["+i+"]: "+iMode.next());
+                final MonitorMode mm = iMode.next();
+                System.err.println(String.format("All-1[%03d]: %s", i, mm));
+                if( null != mmPre ) {
+                    Assert.assertTrue("Wrong order", mmPre.compareTo(mm) <= 0);
+                }
+                mmPre = mm;
             }
         }
         
@@ -144,8 +168,14 @@ public class TestScreenMode00aNEWT extends UITestCase {
             List<MonitorMode> modes = monitor.getSupportedModes();
             Assert.assertTrue(modes.size()>0);
             int i=0;
+            MonitorMode mmPre = null;
             for(Iterator<MonitorMode> iMode=modes.iterator(); iMode.hasNext(); i++) {
-                System.err.println("["+j+"]["+i+"]: "+iMode.next());
+                final MonitorMode mm = iMode.next();
+                System.err.println(String.format("[%02d][%03d]: %s", j, i, mm));
+                if( null != mmPre ) {
+                    Assert.assertTrue("Wrong order", mmPre.compareTo(mm) >= 0);
+                }
+                mmPre = mm;
             }
             Assert.assertTrue(allMonitorModes.containsAll(modes));