Fix Capabilities ambiguity and explosion of queried available-list; Add FBO availability detection for EGL, WGL and OSX.

Introducing Capabilities 'bitmap' boolean, complementing the offscreen modes FBO and PBuffer.
This allows:
  1 - deterministic setting of the offscreen mode

  2 - utilizing auto configuration of offscreen mode, if !onscreen !FBO !PBuffer and !Bitmap

  3 - adding 'availability' semantic of 'onscreen' boolean,
      i.e. if onscree:=1 for a queried instance, the offscreen modes still indicate offscreen
      availability - see [4]

  4 - avoiding explosion of the availability list due to [3],
      one Capability entry reflect on- and offscreen settings.

Add FBO availability detection for EGL, WGL and OSX.

Tested manually w/ 'TestGLCapabilities01NEWT' on X11 [NV, ATI], WGL[NV], OSX[NV].

3 files changed, 138 insertions, 76 deletions

diff --git a/src/jogl/classes/javax/media/opengl/DefaultGLCapabilitiesChooser.java b/src/jogl/classes/javax/media/opengl/DefaultGLCapabilitiesChooser.java
index 5fa8ce32d..b052769ca 100644
--- a/src/jogl/classes/javax/media/opengl/DefaultGLCapabilitiesChooser.java
+++ b/src/jogl/classes/javax/media/opengl/DefaultGLCapabilitiesChooser.java
@@ -87,20 +87,20 @@ import jogamp.opengl.Debug;
 public class DefaultGLCapabilitiesChooser implements GLCapabilitiesChooser {
   private static final boolean DEBUG = Debug.isPropertyDefined("jogl.debug.CapabilitiesChooser", true);
 
-  final static int NO_SCORE = -9999999;
-  final static int DOUBLE_BUFFER_MISMATCH_PENALTY = 1000;
-  final static int OPAQUE_MISMATCH_PENALTY = 750;
-  final static int STENCIL_MISMATCH_PENALTY = 500;
-  final static int MULTISAMPLE_MISMATCH_PENALTY = 500;
-  final static int MULTISAMPLE_EXTENSION_MISMATCH_PENALTY = 250; // just a little drop, no scale
+  private final static int NO_SCORE = -9999999;
+  private final static int DOUBLE_BUFFER_MISMATCH_PENALTY = 1000;
+  private final static int OPAQUE_MISMATCH_PENALTY = 750;
+  private final static int STENCIL_MISMATCH_PENALTY = 500;
+  private final static int MULTISAMPLE_MISMATCH_PENALTY = 500;
+  private final static int MULTISAMPLE_EXTENSION_MISMATCH_PENALTY = 250; // just a little drop, no scale
   // Pseudo attempt to keep equal rank penalties scale-equivalent
   // (e.g., stencil mismatch is 3 * accum because there are 3 accum
   // components)
-  final static int COLOR_MISMATCH_PENALTY_SCALE     = 36;
-  final static int DEPTH_MISMATCH_PENALTY_SCALE     = 6;
-  final static int ACCUM_MISMATCH_PENALTY_SCALE     = 1;
-  final static int STENCIL_MISMATCH_PENALTY_SCALE   = 3;
-  final static int MULTISAMPLE_MISMATCH_PENALTY_SCALE   = 3;
+  private final static int COLOR_MISMATCH_PENALTY_SCALE     = 36;
+  private final static int DEPTH_MISMATCH_PENALTY_SCALE     = 6;
+  private final static int ACCUM_MISMATCH_PENALTY_SCALE     = 1;
+  private final static int STENCIL_MISMATCH_PENALTY_SCALE   = 3;
+  private final static int MULTISAMPLE_MISMATCH_PENALTY_SCALE   = 3;
   
   @Override
   public int chooseCapabilities(final CapabilitiesImmutable desired,
@@ -150,11 +150,20 @@ public class DefaultGLCapabilitiesChooser implements GLCapabilitiesChooser {
       if (cur == null) {
         continue;
       }
-      if (gldes.isOnscreen() != cur.isOnscreen()) {
-        continue;
+      if (gldes.isOnscreen() && !cur.isOnscreen()) {
+        continue; // requested onscreen, but n/a
       }
-      if (!gldes.isOnscreen() && gldes.isPBuffer() && !cur.isPBuffer()) {
-        continue; // only skip if requested Offscreen && PBuffer, but no PBuffer available
+      if (!gldes.isOnscreen()) {
+          /** FBO is generic ..
+          if (gldes.isFBO() && !cur.isFBO()) {
+            continue; // requested FBO, but n/a
+          }  */
+          if (gldes.isPBuffer() && !cur.isPBuffer()) {
+            continue; // requested pBuffer, but n/a
+          }          
+          if (gldes.isBitmap() && !cur.isBitmap()) {
+            continue; // requested pBuffer, but n/a
+          }          
       }
       if (gldes.getStereo() != cur.getStereo()) {
         continue;
diff --git a/src/jogl/classes/javax/media/opengl/GLCapabilities.java b/src/jogl/classes/javax/media/opengl/GLCapabilities.java
index 8845ec665..30a6215e7 100644
--- a/src/jogl/classes/javax/media/opengl/GLCapabilities.java
+++ b/src/jogl/classes/javax/media/opengl/GLCapabilities.java
@@ -105,20 +105,21 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   @Override
   public int hashCode() {
     // 31 * x == (x << 5) - x
-    int hash = 31 + this.glProfile.hashCode() ;
+    int hash = super.hashCode(); 
+    hash = ((hash << 5) - hash) + this.glProfile.hashCode() ;
+    hash = ((hash << 5) - hash) + ( this.hardwareAccelerated ? 1 : 0 );
+    hash = ((hash << 5) - hash) + ( this.stereo ? 1 : 0 );
     hash = ((hash << 5) - hash) + ( this.isFBO ? 1 : 0 );
     hash = ((hash << 5) - hash) + ( this.isPBuffer ? 1 : 0 );
-    hash = ((hash << 5) - hash) + ( this.stereo ? 1 : 0 );
-    hash = ((hash << 5) - hash) + ( this.hardwareAccelerated ? 1 : 0 );
+    hash = ((hash << 5) - hash) + ( this.sampleBuffers ? 1 : 0 );
+    hash = ((hash << 5) - hash) + this.getNumSamples();
+    hash = ((hash << 5) - hash) + this.sampleExtension.hashCode();
     hash = ((hash << 5) - hash) + this.depthBits;
     hash = ((hash << 5) - hash) + this.stencilBits;
     hash = ((hash << 5) - hash) + this.accumRedBits;
     hash = ((hash << 5) - hash) + this.accumGreenBits;
     hash = ((hash << 5) - hash) + this.accumBlueBits;
     hash = ((hash << 5) - hash) + this.accumAlphaBits;
-    hash = ((hash << 5) - hash) + ( this.sampleBuffers ? 1 : 0 );
-    hash = ((hash << 5) - hash) + this.numSamples;
-    hash = ((hash << 5) - hash) + this.sampleExtension.hashCode();
     hash = ((hash << 5) - hash) + ( this.pbufferFloatingPointBuffers ? 1 : 0 );
     hash = ((hash << 5) - hash) + ( this.pbufferRenderToTexture ? 1 : 0 );
     hash = ((hash << 5) - hash) + ( this.pbufferRenderToTextureRectangle ? 1 : 0 );
@@ -148,9 +149,8 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
                   other.getPbufferFloatingPointBuffers()==pbufferFloatingPointBuffers &&
                   other.getPbufferRenderToTexture()==pbufferRenderToTexture &&
                   other.getPbufferRenderToTextureRectangle()==pbufferRenderToTextureRectangle;
-    if(sampleBuffers) {
-        res = res &&
-              other.getNumSamples()==numSamples &&
+    if(res && sampleBuffers) {
+        res = other.getNumSamples()==getNumSamples() &&
               other.getSampleExtension().equals(sampleExtension) ;
     }
     return res;
@@ -222,19 +222,24 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   public void setGLProfile(GLProfile profile) {
     glProfile=profile;
   }
-
+  
   @Override
   public final boolean isPBuffer() {
     return isPBuffer;
   }
 
   /**
-   * Enables or disables pbuffer usage.
+   * Requesting offscreen pbuffer mode.
    * <p>
    * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}.
    * </p>
+   * <p>
    * Defaults to false.
-   */
+   * </p>
+   * <p>
+   * Requesting offscreen pbuffer mode disables the offscreen auto selection.
+   * </p>
+   */  
   public void setPBuffer(boolean enable) {
     if(enable) {
       setOnscreen(false);
@@ -248,11 +253,16 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   }
   
   /**
-   * Enables or disables FBO usage.
+   * Requesting offscreen FBO mode.
    * <p>
    * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}.
    * </p>
+   * <p>
    * Defaults to false.
+   * </p>
+   * <p>
+   * Requesting offscreen FBO mode disables the offscreen auto selection.
+   * </p>
    */
   public void setFBO(boolean enable) {
     if(enable) {
@@ -261,21 +271,6 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
     isFBO = enable;
   }
 
-  /**
-   * Sets whether the drawable surface supports onscreen.<br>
-   * If enabled this method also invokes {@link #setPBuffer(int) setPBuffer(false)}
-   * and {@link #setFBO(int) setFBO(false)}<br>
-   * Defaults to true.
-  */
-  @Override
-  public void setOnscreen(boolean onscreen) {
-    if(onscreen) {
-        setPBuffer(false);
-        setFBO(false);
-    }
-    super.setOnscreen(onscreen);
-  }
-
   @Override
   public final boolean getDoubleBuffered() {
     return doubleBuffered;
@@ -465,9 +460,9 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
         sink = new StringBuilder();
     }
 
-    int samples = sampleBuffers ? numSamples : 0 ;
+    final int samples = sampleBuffers ? numSamples : 0 ;
 
-    super.toString(sink);
+    super.toString(sink, false);
 
     sink.append(", accum-rgba ").append(accumRedBits).append("/").append(accumGreenBits).append("/").append(accumBlueBits).append("/").append(accumAlphaBits);
     sink.append(", dp/st/ms: ").append(depthBits).append("/").append(stencilBits).append("/").append(samples);
@@ -490,20 +485,37 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
         sink.append(", sw, ");
     }
     sink.append(glProfile);
-    if(!isOnscreen()) {
-        if(isFBO) {
-            sink.append(", fbo");
-        } 
-        if(isPBuffer) {
-            sink.append(", pbuffer [r2t ").append(pbufferRenderToTexture?1:0)
-                .append(", r2tr ").append(pbufferRenderToTextureRectangle?1:0)
-                .append(", float ").append(pbufferFloatingPointBuffers?1:0)
-                .append("]");
-        } 
-        if(!isFBO && !isPBuffer) {
-            sink.append(", pixmap");
+    if(isOnscreen()) {
+        sink.append(", on-scr[");
+    } else {
+        sink.append(", offscr[");
+    }
+    boolean ns=false;
+    if(isFBO()) {
+        sink.append("fbo");
+        ns = true;
+    }
+    if(isPBuffer()) {
+        if(ns) { sink.append(", "); }
+        sink.append("pbuffer [r2t ").append(pbufferRenderToTexture?1:0)
+            .append(", r2tr ").append(pbufferRenderToTextureRectangle?1:0)
+            .append(", float ").append(pbufferFloatingPointBuffers?1:0)
+            .append("]");                
+        ns = true;
+    }
+    if(isBitmap()) {
+        if(ns) { sink.append(", "); }
+        sink.append("bitmap");
+        ns = true;
+    }
+    if(!ns) { // !FBO !PBuffer !Bitmap
+        if(isOnscreen()) {
+            sink.append(".");        // no additional off-screen modes besides on-screen
+        } else {
+            sink.append("auto-cfg"); // auto-config off-screen mode            
         }
     }
+    sink.append("]");
 
     return sink;
   }
diff --git a/src/jogl/classes/javax/media/opengl/GLCapabilitiesImmutable.java b/src/jogl/classes/javax/media/opengl/GLCapabilitiesImmutable.java
index 7e0459b2d..ee261ca01 100644
--- a/src/jogl/classes/javax/media/opengl/GLCapabilitiesImmutable.java
+++ b/src/jogl/classes/javax/media/opengl/GLCapabilitiesImmutable.java
@@ -50,7 +50,7 @@ public interface GLCapabilitiesImmutable extends CapabilitiesImmutable {
     GLProfile getGLProfile();
 
     /**
-     * Returns the number of bits requested for the accumulation
+     * Returns the number of bits for the accumulation
      * buffer's alpha component. On some systems only the accumulation
      * buffer depth, which is the sum of the red, green, and blue bits,
      * is considered.
@@ -58,7 +58,7 @@ public interface GLCapabilitiesImmutable extends CapabilitiesImmutable {
     int getAccumAlphaBits();
 
     /**
-     * Returns the number of bits requested for the accumulation
+     * Returns the number of bits for the accumulation
      * buffer's blue component. On some systems only the accumulation
      * buffer depth, which is the sum of the red, green, and blue bits,
      * is considered.
@@ -66,7 +66,7 @@ public interface GLCapabilitiesImmutable extends CapabilitiesImmutable {
     int getAccumBlueBits();
 
     /**
-     * Returns the number of bits requested for the accumulation
+     * Returns the number of bits for the accumulation
      * buffer's green component. On some systems only the accumulation
      * buffer depth, which is the sum of the red, green, and blue bits,
      * is considered.
@@ -74,7 +74,7 @@ public interface GLCapabilitiesImmutable extends CapabilitiesImmutable {
     int getAccumGreenBits();
 
     /**
-     * Returns the number of bits requested for the accumulation
+     * Returns the number of bits for the accumulation
      * buffer's red component. On some systems only the accumulation
      * buffer depth, which is the sum of the red, green, and blue bits,
      * is considered.
@@ -82,74 +82,115 @@ public interface GLCapabilitiesImmutable extends CapabilitiesImmutable {
     int getAccumRedBits();
 
     /**
-     * Returns the number of bits requested for the depth buffer.
+     * Returns the number of depth buffer bits.
      */
     int getDepthBits();
 
     /**
-     * Indicates whether double-buffering is enabled.
+     * Returns whether double-buffering is requested, available or chosen.
+     * <p>
+     * Default is true.
+     * </p>
      */
     boolean getDoubleBuffered();
 
     /**
-     * Indicates whether hardware acceleration is enabled.
+     * Returns whether hardware acceleration is requested, available or chosen.
+     * <p>
+     * Default is true.
+     * </p>
      */
     boolean getHardwareAccelerated();
 
     /**
-     * Returns the used extension for full-scene antialiasing
-     * (FSAA), default is {@link #DEFAULT_SAMPLE_EXTENSION}.
+     * Returns the extension for full-scene antialiasing
+     * (FSAA).
+     * <p>
+     * Default is {@link #DEFAULT_SAMPLE_EXTENSION}.
+     * </p>
      */
     String getSampleExtension();
     
     /**
      * Returns whether sample buffers for full-scene antialiasing
-     * (FSAA) should be allocated for this drawable. Defaults to
-     * false.
+     * (FSAA) should be allocated for this drawable. 
+     * <p>
+     * Default is false.
+     * </p>
      */
     boolean getSampleBuffers();
 
     /**
      * Returns the number of sample buffers to be allocated if sample
-     * buffers are enabled, otherwise returns 0. Defaults to 2.
+     * buffers are enabled, otherwise returns 0.
+     * <p>
+     * Default is 0 due to disable sample buffers per default.
+     * </p>
      */
     int getNumSamples();
 
     /**
      * For pbuffers only, returns whether floating-point buffers should
-     * be used if available. Defaults to false.
+     * be used if available. 
+     * <p>
+     * Default is false.
+     * </p>
      */
     boolean getPbufferFloatingPointBuffers();
 
     /**
      * For pbuffers only, returns whether the render-to-texture
-     * extension should be used if available.  Defaults to false.
+     * extension should be used if available.  
+     * <p>
+     * Default is false.
+     * </p>
      */
     boolean getPbufferRenderToTexture();
 
     /**
      * For pbuffers only, returns whether the render-to-texture
-     * extension should be used. Defaults to false.
+     * extension should be used. 
+     * <p>
+     * Default is false.
+     * </p>
      */
     boolean getPbufferRenderToTextureRectangle();
 
     /**
-     * Returns the number of bits requested for the stencil buffer.
+     * Returns the number of stencil buffer bits.
+     * <p>
+     * Default is 0.
+     * </p>
      */
     int getStencilBits();
 
     /**
-     * Indicates whether stereo is enabled.
+     * Returns whether stereo is requested, available or chosen.
+     * <p>
+     * Default is false.
+     * </p>
      */
     boolean getStereo();
 
     /**
-     * Indicates whether pbuffer offscreen is used/requested.
+     * Returns whether pbuffer offscreen mode is requested, available or chosen.
+     * <p>
+     * Default is false.
+     * </p>
+     * <p>
+     * For chosen capabilities, only the selected offscreen surface is set to <code>true</code>.
+     * </p>
      */
     boolean isPBuffer();
 
     /**
-     * Indicates whether FBO offscreen is used/requested.
+     * Returns whether FBO offscreen mode is requested, available or chosen.
+     * <p>
+     * Default is false.
+     * </p>
+     * <p>
+     * For chosen capabilities, only the selected offscreen surface is set to <code>true</code>.
+     * </p>
      */
     boolean isFBO();