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, 124 insertions, 80 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
index cb33aec5e..50e6ed46c 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
@@ -61,6 +61,9 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
 
   // Switch for on- or offscreen
   private boolean onscreen  = true;
+  
+  // offscreen bitmap mode
+  private boolean isBitmap  = false;
 
   /** Creates a Capabilities object. All attributes are in a default
       state.
@@ -85,6 +88,8 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
   public int hashCode() {
     // 31 * x == (x << 5) - x
     int hash = 31 + this.redBits;
+    hash = ((hash << 5) - hash) + ( this.onscreen ? 1 : 0 );
+    hash = ((hash << 5) - hash) + ( this.isBitmap ? 1 : 0 );
     hash = ((hash << 5) - hash) + this.greenBits;
     hash = ((hash << 5) - hash) + this.blueBits;
     hash = ((hash << 5) - hash) + this.alphaBits;
@@ -93,7 +98,6 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
     hash = ((hash << 5) - hash) + this.transparentValueGreen;
     hash = ((hash << 5) - hash) + this.transparentValueBlue;
     hash = ((hash << 5) - hash) + this.transparentValueAlpha;
-    hash = ((hash << 5) - hash) + ( this.onscreen ? 1 : 0 );
     return hash;
   }
 
@@ -109,12 +113,13 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
                   other.getBlueBits()==blueBits &&
                   other.getAlphaBits()==alphaBits &&
                   other.isBackgroundOpaque()==backgroundOpaque &&
-                  other.isOnscreen()==onscreen;
-    if(!backgroundOpaque) {
-     res = res && other.getTransparentRedValue()==transparentValueRed &&
-                  other.getTransparentGreenValue()==transparentValueGreen &&
-                  other.getTransparentBlueValue()==transparentValueBlue &&
-                  other.getTransparentAlphaValue()==transparentValueAlpha;
+                  other.isOnscreen()==onscreen &&
+                  other.isBitmap()==isBitmap;
+    if(res && !backgroundOpaque) {
+     res = other.getTransparentRedValue()==transparentValueRed &&
+           other.getTransparentGreenValue()==transparentValueGreen &&
+           other.getTransparentBlueValue()==transparentValueBlue &&
+           other.getTransparentAlphaValue()==transparentValueAlpha;
     }
 
     return res;
@@ -158,9 +163,6 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
       }
   }
 
-  /** 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. */
   @Override
   public final int getRedBits() {
     return redBits;
@@ -173,9 +175,6 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
     this.redBits = redBits;
   }
 
-  /** Returns the number of bits requested for the color buffer's
-      green component. On some systems only the color depth, which is
-      the sum of the red, green, and blue bits, is considered. */
   @Override
   public final int getGreenBits() {
     return greenBits;
@@ -188,9 +187,6 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
     this.greenBits = greenBits;
   }
 
-  /** Returns the number of bits requested for the color buffer's blue
-      component. On some systems only the color depth, which is the
-      sum of the red, green, and blue bits, is considered. */
   @Override
   public final int getBlueBits() {
     return blueBits;
@@ -203,9 +199,6 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
     this.blueBits = blueBits;
   }
 
-  /** Returns the number of bits requested for the color buffer's
-      alpha component. On some systems only the color depth, which is
-      the sum of the red, green, and blue bits, is considered. */
   @Override
   public final int getAlphaBits() {
     return alphaBits;
@@ -228,10 +221,7 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
   }
 
   /**
-   * Defaults to true, ie. opaque surface.
-   * <p>
-   * On supported platforms, setting opaque to false may result in a translucent surface. </p>
-   *
+   * Sets whether the surface shall be opaque or translucent.
    * <p>
    * Platform implementations may need an alpha component in the surface (eg. Windows),
    * or expect pre-multiplied alpha values (eg. X11/XRender).<br>
@@ -240,16 +230,9 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
    * Please note that in case alpha is required on the platform the
    * clear color shall have an alpha lower than 1.0 to allow anything shining through.
    * </p>
-   *
    * <p>
    * Mind that translucency may cause a performance penalty
-   * due to the composite work required by the window manager.</p>
-   *
-   * <p>
-   * The platform implementation may utilize the transparency RGBA values.<br>
-   * This is true for the original GLX transparency specification, which is no more used today.<br>
-   * Actually these values are currently not used by any implementation,
-   * so we may mark them deprecated soon, if this doesn't change.<br>
+   * due to the composite work required by the window manager.
    * </p>
    */
   public void setBackgroundOpaque(boolean opaque) {
@@ -259,56 +242,65 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
       }
   }
 
-  /** Indicates whether the background of this OpenGL context should
-      be considered opaque. Defaults to true.
-
-      @see #setBackgroundOpaque
-  */
   @Override
   public final boolean isBackgroundOpaque() {
     return backgroundOpaque;
   }
 
-  /** Sets whether the drawable surface supports onscreen.
-      Defaults to true.
-  */
+  /**
+   * Sets whether the surface shall be on- or offscreen.
+   * <p>
+   * Defaults to true.
+   * </p>
+   * <p>
+   * If requesting an offscreen surface without further selection of it's mode, 
+   * e.g. FBO, Pbuffer or {@link #setBitmap(boolean) bitmap},
+   * the implementation will choose the best available offscreen mode.
+   * </p>
+   * @param onscreen
+   */
   public void setOnscreen(boolean onscreen) {
     this.onscreen=onscreen;
   }
 
-  /** Indicates whether the drawable surface is onscreen.
-      Defaults to true.
-  */
   @Override
   public final boolean isOnscreen() {
     return onscreen;
   }
 
-  /** Gets the transparent red value for the frame buffer configuration.
-    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
-    * @see #setTransparentRedValue
-    */
+  /**
+   * Requesting offscreen bitmap mode.
+   * <p>
+   * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}.
+   * </p>
+   * <p>
+   * Defaults to false.
+   * </p>
+   * <p>
+   * Requesting offscreen bitmap mode disables the offscreen auto selection.
+   * </p>
+   */
+  public void setBitmap(boolean enable) {
+    if(enable) {
+      setOnscreen(false);
+    }
+    isBitmap = enable;
+  }
+  
+  @Override
+  public boolean isBitmap() {
+    return isBitmap;      
+  }
+  
   @Override
   public final int getTransparentRedValue() { return transparentValueRed; }
 
-  /** Gets the transparent green value for the frame buffer configuration.
-    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
-    * @see #setTransparentGreenValue
-    */
   @Override
   public final int getTransparentGreenValue() { return transparentValueGreen; }
 
-  /** Gets the transparent blue value for the frame buffer configuration.
-    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
-    * @see #setTransparentBlueValue
-    */
   @Override
   public final int getTransparentBlueValue() { return transparentValueBlue; }
 
-  /** Gets the transparent alpha value for the frame buffer configuration.
-    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
-    * @see #setTransparentAlphaValue
-    */
   @Override
   public final int getTransparentAlphaValue() { return transparentValueAlpha; }
 
@@ -342,32 +334,58 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
 
   @Override
   public StringBuilder toString(StringBuilder sink) {
+      return toString(sink, true);
+  }
+  
+  /** Returns a textual representation of this Capabilities
+      object. */
+  @Override
+  public String toString() {
+    StringBuilder msg = new StringBuilder();
+    msg.append("Caps[");
+    toString(msg);
+    msg.append("]");
+    return msg.toString();
+  }
+  
+  /** Return a textual representation of this object's on/off screen state. Use the given StringBuffer [optional]. */
+  protected StringBuilder onoffScreenToString(StringBuilder sink) {
     if(null == sink) {
         sink = new StringBuilder();
     }
     if(onscreen) {
         sink.append("on-scr");
     } else {
-        sink.append("offscr");
+        sink.append("offscr[");
+    }
+    if(isBitmap) {
+        sink.append("bitmap");
+    } else if(onscreen) {
+        sink.append(".");        // no additional off-screen modes besides on-screen
+    } else {
+        sink.append("auto-cfg"); // auto-config off-screen mode            
+    }
+    sink.append("]");    
+    
+    return sink;
+  }
+  
+  protected StringBuilder toString(StringBuilder sink, boolean withOnOffScreen) {  
+    if(null == sink) {
+        sink = new StringBuilder();
     }
-    sink.append(", rgba 0x").append(toHexString(redBits)).append("/").append(toHexString(greenBits)).append("/").append(toHexString(blueBits)).append("/").append(toHexString(alphaBits));
+    sink.append("rgba 0x").append(toHexString(redBits)).append("/").append(toHexString(greenBits)).append("/").append(toHexString(blueBits)).append("/").append(toHexString(alphaBits));
     if(backgroundOpaque) {
         sink.append(", opaque");
     } else {
         sink.append(", trans-rgba 0x").append(toHexString(transparentValueRed)).append("/").append(toHexString(transparentValueGreen)).append("/").append(toHexString(transparentValueBlue)).append("/").append(toHexString(transparentValueAlpha));
     }
+    if(withOnOffScreen) {
+        sink.append(", ");
+        onoffScreenToString(sink);
+    }
     return sink;
   }
+  
   protected final String toHexString(int val) { return Integer.toHexString(val); }
-
-  /** Returns a textual representation of this Capabilities
-      object. */
-  @Override
-  public String toString() {
-    StringBuilder msg = new StringBuilder();
-    msg.append("Caps[");
-    toString(msg);
-    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 b984a4626..b801ab457 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesImmutable.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesImmutable.java
@@ -39,45 +39,66 @@ import com.jogamp.common.type.WriteCloneable;
 public interface CapabilitiesImmutable extends VisualIDHolder, WriteCloneable, Comparable<CapabilitiesImmutable> {
 
     /**
-     * Returns the number of bits requested for the color buffer's red
+     * Returns the number of bits 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.
      */
     int getRedBits();
 
     /**
-     * Returns the number of bits requested for the color buffer's green
+     * Returns the number of bits for the color buffer's green
      * component. On some systems only the color depth, which is the sum of the
      * red, green, and blue bits, is considered.
      */
     int getGreenBits();
 
     /**
-     * Returns the number of bits requested for the color buffer's blue
+     * Returns the number of bits for the color buffer's blue
      * component. On some systems only the color depth, which is the sum of the
      * red, green, and blue bits, is considered.
      */
     int getBlueBits();
 
     /**
-     * Returns the number of bits requested for the color buffer's alpha
+     * Returns the number of bits for the color buffer's alpha
      * component. On some systems only the color depth, which is the sum of the
      * red, green, and blue bits, is considered.
      */
     int getAlphaBits();
 
     /**
-     * Indicates whether the background of this OpenGL context should be
-     * considered opaque. Defaults to true.
+     * Returns whether an opaque or translucent surface is requested, supported or chosen.
+     * <p>
+     * Default is true, i.e. opaque.
+     * </p> 
      */
     boolean isBackgroundOpaque();
 
     /**
-     * Indicates whether the drawable surface is onscreen. Defaults to true.
+     * Returns whether an on- or offscreen surface is requested, available or chosen. 
+     * <p>
+     * Default is true, i.e. onscreen.
+     * </p>
+     * <p>
+     * Mind that an capabilities intance w/ <i>available</i> semantics
+     * may show onscreen, but also the offscreen modes FBO, Pbuffer or {@link #setBitmap(boolean) bitmap}.
+     * This is valid, since one native configuration maybe used for either functionality.
+     * </p> 
      */
     boolean isOnscreen();
 
     /**
+     * Returns whether bitmap 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 isBitmap();
+    
+    /**
      * Gets the transparent red value for the frame buffer configuration. This
      * value is undefined if; equals true.
      */
diff --git a/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java b/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java
index 9d4b112b1..744c7e6d5 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java
@@ -68,6 +68,9 @@ import jogamp.nativewindow.Debug;
 public class DefaultCapabilitiesChooser implements CapabilitiesChooser {
   private static final boolean DEBUG = Debug.isPropertyDefined("nativewindow.debug.CapabilitiesChooser", true); 
 
+  private final static int NO_SCORE = -9999999;
+  private final static int COLOR_MISMATCH_PENALTY_SCALE     = 36;
+  
   public int chooseCapabilities(final CapabilitiesImmutable desired,
                                 final List<? extends CapabilitiesImmutable> available,
                                 final int windowSystemRecommendedChoice) {
@@ -92,8 +95,6 @@ public class DefaultCapabilitiesChooser implements CapabilitiesChooser {
 
     // Create score array
     int[] scores = new int[availnum];
-    int NO_SCORE = -9999999;
-    int COLOR_MISMATCH_PENALTY_SCALE     = 36;
     for (int i = 0; i < availnum; i++) {
       scores[i] = NO_SCORE;
     }
@@ -103,6 +104,10 @@ public class DefaultCapabilitiesChooser implements CapabilitiesChooser {
       if (cur == null) {
         continue;
       }
+      if (desired.isOnscreen() && !cur.isOnscreen()) {
+        continue; // requested onscreen, but n/a
+      }
+      
       int score = 0;
       // Compute difference in color depth
       score += (COLOR_MISMATCH_PENALTY_SCALE *