NativeWindow public* reorg 3/3 ; NativeVisualID -> VisualIDHolder incl. proper utilization.

- VisualIDHolder: Update documentation (Exception case, etc)

- NativeVisualID -> VisualIDHolder (public)
  - incl. generic Comparator
  - better doc and enum values
  - VID_UNDEFINED == 0
  - methods shall not throw exception, but return UNDEFINED

- CapabilitiesImmutable extends VisualIDHolder

- All Capabilties impl.
  - use VID_UNDEFINED for undef. value
  - use final private (immutable) fields

- AbstractGraphicsConfiguration extends VisualIDHolder

- X11 CreateDummyWindow takes (int) visualID

7 files changed, 117 insertions, 44 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java b/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java
index 1930bdda3..ebdaf2fbb 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java
@@ -43,7 +43,7 @@ package javax.media.nativewindow;
 /** A marker interface describing a graphics configuration, visual, or
     pixel format in a toolkit-independent manner. */
 
-public interface AbstractGraphicsConfiguration extends Cloneable {
+public interface AbstractGraphicsConfiguration extends VisualIDHolder, Cloneable {
     /**
      * Return the screen this graphics configuration is valid for
      */
diff --git a/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsDevice.java b/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsDevice.java
index fa25c214f..1dd01a274 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsDevice.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsDevice.java
@@ -114,8 +114,8 @@ public interface AbstractGraphicsDevice extends Cloneable {
      * <p>
      * The default implementation is a <code>NOP</code>, just setting the handle to <code>null</code>.
      * </p>
-     * The specific implementing, ie {@link javax.media.nativewindow.x11.X11GraphicsDevice},
-     * shall have a enable/disable like {@link javax.media.nativewindow.x11.X11GraphicsDevice#setCloseDisplay(boolean, boolean)},<br>
+     * The specific implementing, ie {@link com.jogamp.nativewindow.x11.X11GraphicsDevice},
+     * shall have a enable/disable like {@link com.jogamp.nativewindow.x11.X11GraphicsDevice#setCloseDisplay(boolean, boolean)},<br>
      * which shall be invoked at creation time to determine ownership/role of freeing the resource.<br>
      *
      * @return true if the handle was not <code>null</code>, otherwise false.
diff --git a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
index 89cd3d60f..7a58e688f 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
@@ -40,6 +40,8 @@
 
 package javax.media.nativewindow;
 
+import javax.media.nativewindow.VisualIDHolder.VIDType;
+
 /** Specifies a set of capabilities that a window's rendering context
     must support, such as color depth per channel. It currently
     contains the minimal number of routines which allow configuration
@@ -140,6 +142,17 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable, Comparabl
     return 0; // they are equal: RGBA
   }
 
+  @Override
+  public int getVisualID(VIDType type) throws NativeWindowException {
+      switch(type) {
+          case INTRINSIC:
+          case NATIVE:
+              return VisualIDHolder.VID_UNDEFINED;
+          default:
+              throw new NativeWindowException("Invalid type <"+type+">");
+      }      
+  }
+    
   /** Returns the number of bits requested for the color buffer's red
       component. On some systems only the color depth, which is the
       sum of the red, green, and blue bits, is considered. */
@@ -331,4 +344,5 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable, Comparabl
     msg.append("]");
     return msg.toString();
   }
+
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesImmutable.java b/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesImmutable.java
index eccdf7797..848ec74e1 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesImmutable.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesImmutable.java
@@ -36,7 +36,7 @@ import com.jogamp.common.type.WriteCloneable;
  * 
  * @see javax.media.nativewindow.Capabilities
  */
-public interface CapabilitiesImmutable extends WriteCloneable {
+public interface CapabilitiesImmutable extends VisualIDHolder, WriteCloneable {
 
     /**
      * Returns the number of bits requested for the color buffer's red
diff --git a/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java b/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java
index 15c9e6a36..a33c3792a 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java
@@ -44,13 +44,16 @@ public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphics
     public DefaultGraphicsConfiguration(AbstractGraphicsScreen screen, 
                                         CapabilitiesImmutable capsChosen, CapabilitiesImmutable capsRequested) {
         if(null == screen) {
-            throw new NativeWindowException("Null screen");
+            throw new IllegalArgumentException("Null screen");
         }
         if(null == capsChosen) {
-            throw new NativeWindowException("Null chosen caps");
+            throw new IllegalArgumentException("Null chosen caps");
         }
         if(null == capsRequested) {
-            throw new NativeWindowException("Null requested caps");
+            throw new IllegalArgumentException("Null requested caps");
+        }
+        if( ! ( capsChosen instanceof VisualIDHolder ) ) {
+            throw new IllegalArgumentException("Chosen caps is not implementing NativeVisualID");
         }
         this.screen = screen;
         this.capabilitiesChosen = capsChosen;
@@ -66,15 +69,15 @@ public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphics
         }
     }
 
-    public AbstractGraphicsScreen getScreen() {
+    final public AbstractGraphicsScreen getScreen() {
         return screen;
     }
 
-    public CapabilitiesImmutable getChosenCapabilities() {
+    final public CapabilitiesImmutable getChosenCapabilities() {
         return capabilitiesChosen;
     }
 
-    public CapabilitiesImmutable getRequestedCapabilities() {
+    final public CapabilitiesImmutable getRequestedCapabilities() {
         return capabilitiesRequested;
     }
 
@@ -82,6 +85,11 @@ public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphics
         return this;
     }
 
+    @Override
+    final public int getVisualID(VIDType type) throws NativeWindowException {
+        return capabilitiesChosen.getVisualID(type);
+    }
+            
     /**
      * Set the capabilities to a new value.
      *
@@ -102,7 +110,7 @@ public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphics
      *
      * A copy of the passed object is being used.
      */
-    protected void setScreen(DefaultGraphicsScreen screen) {
+    final protected void setScreen(DefaultGraphicsScreen screen) {
         this.screen = (AbstractGraphicsScreen) screen.clone();
     }
 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java b/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java
index fb8bf2764..e5f230b4c 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java
@@ -223,12 +223,12 @@ public abstract class GraphicsConfigurationFactory {
      * returned graphics configuration must be specified in the
      * documentation binding this particular API to the underlying
      * window toolkit. The Reference Implementation accepts {@link
-     * javax.media.nativewindow.awt.AWTGraphicsDevice AWTGraphicsDevice} objects and returns {@link
-     * javax.media.nativewindow.awt.AWTGraphicsConfiguration AWTGraphicsConfiguration} objects. On
+     * com.jogamp.nativewindow.awt.AWTGraphicsDevice AWTGraphicsDevice} objects and returns {@link
+     * com.jogamp.nativewindow.awt.AWTGraphicsConfiguration AWTGraphicsConfiguration} objects. On
      * X11 platforms where the AWT is not in use, it also accepts
-     * {@link javax.media.nativewindow.x11.X11GraphicsDevice
+     * {@link com.jogamp.nativewindow.x11.X11GraphicsDevice
      * X11GraphicsDevice} objects and returns {@link
-     * javax.media.nativewindow.x11.X11GraphicsConfiguration
+     * com.jogamp.nativewindow.x11.X11GraphicsConfiguration
      * X11GraphicsConfiguration} objects.</P>
      *
      * @param capsChosen     the intermediate chosen capabilities to be refined by this implementation, may be equal to capsRequested
diff --git a/src/nativewindow/classes/javax/media/nativewindow/VisualIDHolder.java b/src/nativewindow/classes/javax/media/nativewindow/VisualIDHolder.java
index 20d3ad6dc..4f3d3ff00 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/VisualIDHolder.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/VisualIDHolder.java
@@ -26,59 +26,110 @@
  * or implied, of JogAmp Community.
  */
 
-package jogamp.nativewindow;
+package javax.media.nativewindow;
+
+import java.util.Comparator;
 
 /**
- * Specifies query to the native capabilities identification.
- * Semantics may differ depending on the native windowing system,
+ * Visual ID holder interface.
+ * <p>
+ * Allows queries of different types of native visual IDs,
  * see {@link #getVisualID(int)}.
+ * </p>
  */
-public interface NativeVisualID {
+public interface VisualIDHolder {
     
-    public enum NVIDType {
-        GEN_ID(0), NATIVE_ID(1), 
-        EGL_ConfigID(2), EGL_NativeVisualID(3), X11_XVisualID(4), X11_FBConfigID(5), WIN32_PFDID(6); 
+    public enum VIDType {
+        // Generic Values
+        INTRINSIC(0), NATIVE(1),
+        // EGL Values
+        EGL_CONFIG(10),
+        // X11 Values
+        X11_XVISUAL(20), X11_FBCONFIG(21),
+        // Windows Values
+        WIN32_PFD(30); 
         
         public final int id;
 
-        NVIDType(int id){
+        VIDType(int id){
             this.id = id;
         }
     }    
     
     /**
-     * Returns the native identification of the given <code>type</code>.
+     * Returns the native visual ID of the given <code>type</code>
+     * if supported, or {@link #VID_UNDEFINED} if not supported.
      * <p> 
-     * Depending on the native windowing system, this might be
+     * Depending on the native windowing system, <code>type</code> is handled as follows:
      * <ul>
-     *   <li>X11
+     *   <li>X11 throws NativeWindowException on <code>EGL_CONFIG</code>, <code>WIN32_PFD</code>
      *     <ul>
-     *       <li>GEN_ID: X11_XVisualID</li>
-     *       <li>NATIVE_ID: X11_XVisualID</li>
-     *       <li>X11_XVisualID</li>
+     *       <li><code>INTRINSIC</code>: <i>X11 XVisual ID</i></li>
+     *       <li><code>NATIVE</code>: <i>X11 XVisual ID</i></li>
+     *       <li><code>X11_XVISUAL</code>: <i>X11 XVisual ID</i></li>
+     *       <li><code>X11_FBCONFIG</code>: <code>VID_UNDEFINED</code></li>
      *     </ul></li>
-     *   <li>X11/GL
+     *   <li>X11/GL throws NativeWindowException on <code>EGL_CONFIG</code>, <code>WIN32_PFD</code>
      *     <ul>
-     *       <li>GEN_ID: X11_XVisualID</li>
-     *       <li>NATIVE_ID: X11_XVisualID</li>
-     *       <li>X11_XVisualID</li>
-     *       <li>X11FBConfigID</li>
+     *       <li><code>INTRINSIC</code>: <i>X11 XVisual ID</i></li>
+     *       <li><code>NATIVE</code>: <i>X11 XVisual ID</i></li>
+     *       <li><code>X11_XVISUAL</code>: <i>X11 XVisual ID</i></li>
+     *       <li><code>X11_FBCONFIG</code>: <i>X11 FBConfig ID</i> or <code>VID_UNDEFINED</code></li>
      *     </ul></li>
-     *   <li>Windows/GL
+     *   <li>Windows/GL throws NativeWindowException on <code>EGL_CONFIG</code>, <code>X11_XVISUAL</code>, <code>X11_FBCONFIG</code> 
      *     <ul>
-     *       <li>GEN_ID: WIN32_PFDID</li>
-     *       <li>NATIVE_ID: WIN32_PFDID</li>
-     *       <li>WIN32_PFDID</li>
+     *       <li><code>INTRINSIC</code>: <i>Win32 PIXELFORMATDESCRIPTOR ID</i></li>
+     *       <li><code>NATIVE</code>: <i>Win32 PIXELFORMATDESCRIPTOR ID</i></li>
+     *       <li><code>WIN32_PFD</code>: <i>Win32 PIXELFORMATDESCRIPTOR ID</i></li>
      *     </ul></li>
-     *   <li>EGL/GL
+     *   <li>EGL/GL throws NativeWindowException on <code>X11_XVISUAL</code>, <code>X11_FBCONFIG</code>, <code>WIN32_PFD</code>
      *     <ul>
-     *       <li>GEN_ID: EGL_ConfigID</li>
-     *       <li>NATIVE_ID: EGL_NativeVisualID (X11_XVisualID, WIN32_PFDID, ..)</li>
-     *       <li>EGL_ConfigID</li>
-     *       <li>EGL_NativeVisualID</li>
+     *       <li><code>INTRINSIC</code>: <i>EGL Config ID</i></li>
+     *       <li><code>NATIVE</code>: <i>EGL NativeVisual ID</i> (<i>X11 XVisual ID</i>, <i>Win32 PIXELFORMATDESCRIPTOR ID</i>, ...)</li>
+     *       <li><code>EGL_CONFIG</code>: <i>EGL Config ID</i></li>
      *     </ul></li>
      * </ul>
      * </p>
+     * Note: <code>INTRINSIC</code> and <code>NATIVE</code> are always handled,
+     *       but may result in {@link #VID_UNDEFINED}. The latter is true if 
+     *       the native value are actually undefined or the corresponding object is not 
+     *       mapped to a native visual object.
+     *       
+     * @throws NativeWindowException if <code>type</code> is neither
+     *         <code>INTRINSIC</code> nor <code>NATIVE</code>
+     *         and does not match the native implementation. 
+     */
+    int getVisualID(VIDType type) throws NativeWindowException ;
+    
+    /** 
+     * {@link #getVisualID(VIDType)} result indicating an undefined value,
+     * which could be cause by an unsupported query.
+     * <p>
+     * We assume the const value <code>0</code> doesn't reflect a valid native visual ID
+     * and is interpreted as <i>no value</i> on all platforms.
+     * This is currently true for Android, X11 and Windows.
+     * </p> 
      */
-    int getVisualID(NVIDType type);
+    static final int VID_UNDEFINED = 0;
+    
+    /** Comparing {@link VIDType#NATIVE} */
+    public static class VIDComparator implements Comparator<VisualIDHolder> {
+        private VIDType type;
+        
+        public VIDComparator(VIDType type) {
+            this.type = type;
+        }
+        
+        public int compare(VisualIDHolder vid1, VisualIDHolder vid2) {
+            final int id1 = vid1.getVisualID(type);
+            final int id2 = vid2.getVisualID(type);
+
+            if(id1 > id2) {
+                return 1;
+            } else if(id1 < id2) {
+                return -1;
+            }
+            return 0;
+        }
+    }    
 }