NativeWindow/JOGL: Cleanup Caps doc and implicit related values.

Capabilities
  setBackgroundOpaque -> setAlphaBits

GLCapabilities
  setOnscreen <-> setPBuffer
  setSampleBuffers -> setAlphaBits

2 files changed, 57 insertions, 46 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLCapabilities.java b/src/jogl/classes/javax/media/opengl/GLCapabilities.java
index b63124e33..4d9d08827 100644
--- a/src/jogl/classes/javax/media/opengl/GLCapabilities.java
+++ b/src/jogl/classes/javax/media/opengl/GLCapabilities.java
@@ -211,19 +211,19 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
 
   /** 
    * Enables or disables pbuffer usage.<br>
-   * If enabled, onscreen := false.
+   * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}<br>
    * Defaults to false.
    */
-  public void setPBuffer(boolean onOrOff) {
-    if(onOrOff) {
+  public void setPBuffer(boolean enable) {
+    if(enable) {
       setOnscreen(false);
     }
-    pbuffer = onOrOff;
+    pbuffer = enable;
   }
 
   /**
    * Sets whether the drawable surface supports onscreen.<br>
-   * If enabled, pbuffer := false.<br>
+   * If enabled this method also invokes {@link #setPBuffer(int) setPBuffer(false)}<br>
    * Defaults to true.
   */
   public void setOnscreen(boolean onscreen) {
@@ -239,8 +239,8 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   }
 
   /** Enables or disables double buffering. */
-  public void setDoubleBuffered(boolean onOrOff) {
-    doubleBuffered = onOrOff;
+  public void setDoubleBuffered(boolean enable) {
+    doubleBuffered = enable;
   }
 
   /** Indicates whether stereo is enabled. */
@@ -249,8 +249,8 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   }
   
   /** Enables or disables stereo viewing. */
-  public void setStereo(boolean onOrOff) {
-    stereo = onOrOff;
+  public void setStereo(boolean enable) {
+    stereo = enable;
   }
 
   /** Indicates whether hardware acceleration is enabled. */
@@ -259,8 +259,8 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   }
   
   /** Enables or disables hardware acceleration. */
-  public void setHardwareAccelerated(boolean onOrOff) {
-    hardwareAccelerated = onOrOff;
+  public void setHardwareAccelerated(boolean enable) {
+    hardwareAccelerated = enable;
   }
 
   /** Returns the number of bits requested for the depth buffer. */
@@ -347,11 +347,19 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
     this.accumAlphaBits = accumAlphaBits;
   }
 
-  /** Indicates whether sample buffers for full-scene antialiasing
-      (FSAA) should be allocated for this drawable. Defaults to
-      false. */
-  public void setSampleBuffers(boolean onOrOff) {
-    sampleBuffers = onOrOff;
+  /**
+   * Defaults to false.<br>
+   * Indicates whether sample buffers for full-scene antialiasing
+   * (FSAA) should be allocated for this drawable.<br>
+   * Mind that this requires the alpha component.<br>
+   * If enabled this method also invokes {@link #setAlphaBits(int) setAlphaBits(1)}
+   * if {@link #getAlphaBits()} == 0.<br>
+   */
+  public void setSampleBuffers(boolean enable) {
+    sampleBuffers = enable;
+    if(sampleBuffers && getAlphaBits()==0) {
+        setAlphaBits(1);
+    }        
   }
 
   /** Returns whether sample buffers for full-scene antialiasing
@@ -375,8 +383,8 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
 
   /** For pbuffers only, indicates whether floating-point buffers
       should be used if available. Defaults to false. */
-  public void setPbufferFloatingPointBuffers(boolean onOrOff) {
-    pbufferFloatingPointBuffers = onOrOff;
+  public void setPbufferFloatingPointBuffers(boolean enable) {
+    pbufferFloatingPointBuffers = enable;
   }
 
   /** For pbuffers only, returns whether floating-point buffers should
@@ -387,8 +395,8 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
 
   /** For pbuffers only, indicates whether the render-to-texture
       extension should be used if available.  Defaults to false. */
-  public void setPbufferRenderToTexture(boolean onOrOff) {
-    pbufferRenderToTexture = onOrOff;
+  public void setPbufferRenderToTexture(boolean enable) {
+    pbufferRenderToTexture = enable;
   }
 
   /** For pbuffers only, returns whether the render-to-texture
@@ -400,8 +408,8 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   /** For pbuffers only, indicates whether the
       render-to-texture-rectangle extension should be used if
       available. Defaults to false. */
-  public void setPbufferRenderToTextureRectangle(boolean onOrOff) {
-    pbufferRenderToTextureRectangle = onOrOff;
+  public void setPbufferRenderToTextureRectangle(boolean enable) {
+    pbufferRenderToTextureRectangle = enable;
   }
 
   /** For pbuffers only, returns whether the render-to-texture
diff --git a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
index b162392da..d02efb04f 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
@@ -194,32 +194,35 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable, Comparabl
     this.alphaBits = alphaBits;
   }
 
-  /** For on-screen OpenGL contexts on some platforms, sets whether
-      the background of the context should be considered opaque. On
-      supported platforms, setting this to false, in conjunction with
-      the transparency values, may allow
-      hardware-accelerated OpenGL content inside of windows of
-      arbitrary shape. To achieve this effect it is necessary to use
-      an OpenGL clear color with an alpha less than 1.0. The default
-      value for this flag is <code>true</code>; setting it to false
-      may incur a certain performance penalty, so it is not
-      recommended to arbitrarily set it to false.<br>
-      If not set already, the transparency values for red, green, blue and alpha
-      are set to their default value, which is half of the value range
-      of the framebuffer's corresponding component,
-      ie <code> redValue = ( 1 << ( redBits - 1 ) ) -1 </code>.
-    */
+    /**
+     * Defaults to true, ie. opaque surface.
+     * <p>
+     * On supported platforms, setting opaque to false may result in a translucent surface. </p>
+     * 
+     * <p>
+     * Platform implementations may need an alpha component in the surface (eg. Windows), 
+     * or expect pre-multiplied alpha values (eg. X11/XRender).<br>
+     * To unify the experience, this method also invokes {@link #setAlphaBits(int) setAlphaBits(1)}
+     * if {@link #getAlphaBits()} == 0.<br>
+     * 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>
+     * </p>
+     */
   public void setBackgroundOpaque(boolean opaque) {
     backgroundOpaque = opaque;
-    if(!opaque) {
-        if(transparentValueRed<0)
-            transparentValueRed = ( 1 << ( getRedBits() - 1 ) )  - 1 ;
-        if(transparentValueGreen<0)
-            transparentValueGreen = ( 1 << ( getGreenBits() - 1 ) )  - 1 ;
-        if(transparentValueBlue<0)
-            transparentValueBlue = ( 1 << ( getBlueBits() - 1 ) )  - 1 ;
-        if(transparentValueAlpha<0)
-            transparentValueAlpha = ( 1 << ( getAlphaBits() - 1 ) )  - 1 ;
+    if(!opaque && getAlphaBits()==0) {
+        setAlphaBits(1);
     }
   }