Bug 599 - FBObject / Offscreen Support - Part 1

- New FBObject implementation handling FBO and it's attachments  *** API CHANGE: Util -> Core ***
  while it's size and sample-count can be reconfigured on the fly.
    - com.jogamp.opengl.util.FBObject -> com.jogamp.opengl.FBObject
    - agnostic to texture unit
    - separate attachments using OO hierarchy reflecting FBO
    - handling MSAA and blitting
    - no FBO destruction for reconfig (attach/detach)

- New GLFBODrawableImpl impl. an FBObject based GLDrawable
   - Instantiated by a dummy native surface (onscreen and invisible)
     hooked up to a dummy GLDrawable, which is the delegation for context creation.

   - Utilizies ProxySurface.UpstreamSurfaceHook for dummy surface
     avoiding specialization for native platforms.

   - TODO: Allow to utilize common surface interface as a
     dummy-surface to supporting API seperation of
     windowing/GL. The latter allows impl. of createGLDrawable(NativeSurface)
     with FBO.

- New OffscreenAutoDrawable (extends GLAutoDrawableDelegate)
  for all offscreen drawables. Shall replace GLPbuffer.

- New GLCapabilities*.isFBO() / setFBO(boolean) to request FBO offscreen,
  similar to isPBuffer(). Rule: if both are requested, FBO shall be favored.

- GLContext adds raw FBO availability query (min. FBO avail),
  FBObject contains fine grained queries (TODO: Move parts to GLContext for efficiency).

- Add framebuffer tracking, allowing fast querying:
  - GLBase/GLContext:
      public int getBoundFramebuffer(int target);
      public int getDefaultDrawFramebuffer();
      public int getDefaultReadFramebuffer();

  - GLContextImpl
      public final void setBoundFramebuffer(int target, int framebufferName)
      .. called by GL impl bind framebuffer

- GL: getDefaultDrawFramebuffer(), getDefaultReadFramebuffer()
  Adding default framebuffer queries being issued by
  GL.glBindFramebuffer(target, 0) w/ a default framebuffer, o.e. zero.
  This allows a transparent use of a custom FBO even in case the applications
  attempts to reset FBO to zero.
    Value flow: GL <- GLContext <- GLDrawable,

- GLCapabilities handle fbo/pbuffer seperate, don't disable the other

- GLContext/GL track read/write framebuffer to be queried by FBObject
  to determine whether to bind/unbind  a framebuffer

- Test cases for multiple FBO w/ and w/o MSAA

Other Features:

- New interface ProxySurface.UpstreamSurfaceHook,
  allowing to hook an upstream surface of unknown type
  providing lifecycle and information (size, ..) callbacks.
  Used for all new dummy NativeSurface impl and SWT GLCanvas.

  - GLContext -> GLDrawable propagation context/drawable lifecycle
    via ProxySurface.UpstreamSurfaceHook allowing dynamic resources
    to react (create, init, ..)
    - contextRealized()
    - contextMadeCurrent()

- SurfaceChangeable -> MutableSurface
  currently only contains setting the surface handle.

  TODO: May need to move ProxySurface.UpstreamSurfaceHook -> MutableSurface.UpstreamSurfaceHook,
        allowing other impl. classes (NEWT OffscreenWindow) to utilize the new
        upstream hookup mechanism - will allow FBO/Dummy window to work.

- SWT GLCanvas using ProxySurface.UpstreamSurfaceHook for proper size
  propagation.

- New GLAutoDrawable::getUpstreamWidget(), allowing GLEventListener
  to fetch the owning Java side UI element (NEWT, SWT, AWT, ..).

- GLDrawableFactory: Removed createOffscreenSurface() - unused and not GL related

- EGLDrawableFactory handles device/profile avail. mapping
  while actually creating context/drawable.
  This allows us to learn whether the ES context is software/hardware as well as FBO avail.

- EGLDrawable: Removed secret buckets of EGL configs :)
  Employ native surface (X11, WGL, ..) to EGL 'mapping' in
  EGLDrawableFactory utilizing new EGLUpstreamSurfaceHook (implements ProxySurface.UpstreamSurfaceHook).

Other Bugs:

- Add CTX_OPTION_DEBUG to ctx/extension cache key since only a debug ctx
  may expose the ARB debug capability.
  This bug caused lack of ARB/AMD debug functionality.

- Fix GLProfile deadlock (debug mode, w/ EGL/ES, no X11),
  dump availability information _after_ lock.

- ImmModeSink draw(): Use GL's glDrawElements(..), don't cast for GL2ES1.
  Fixes use for GL2ES2.

- Fix KeyEvent.getKeyChar() comment (-> only stable for keyTyped(..))

Misc:

- Refined alot of API doc

- New GLExtensions holds commonly used GL extension strings,
  allows better referencing and usage lookup.

- Move GL (interface) decl. to GLBase

- GLBuffers: Cleanup API doc (format, types)

- TextureIO: Add PAM and PPM static suffix identifier

- GLCapabilities getNumSamples() returns 0 if sampleBuffers is disabled, this seems to be more natural.

- finalized a lot

1 files changed, 48 insertions, 18 deletions

diff --git a/src/jogl/classes/jogamp/opengl/GLGraphicsConfigurationUtil.java b/src/jogl/classes/jogamp/opengl/GLGraphicsConfigurationUtil.java
index b7c15bfda..900d6a2a0 100644
--- a/src/jogl/classes/jogamp/opengl/GLGraphicsConfigurationUtil.java
+++ b/src/jogl/classes/jogamp/opengl/GLGraphicsConfigurationUtil.java
@@ -38,7 +38,8 @@ public class GLGraphicsConfigurationUtil {
     public static final int WINDOW_BIT  = 1 << 0;
     public static final int BITMAP_BIT  = 1 << 1;
     public static final int PBUFFER_BIT = 1 << 2;
-    public static final int ALL_BITS    = WINDOW_BIT | BITMAP_BIT | PBUFFER_BIT ;
+    public static final int FBO_BIT     = 1 << 3;
+    public static final int ALL_BITS    = WINDOW_BIT | BITMAP_BIT | PBUFFER_BIT | FBO_BIT ;
 
     public static final StringBuilder winAttributeBits2String(StringBuilder sb, int winattrbits) {
         if(null==sb) {
@@ -61,30 +62,43 @@ public class GLGraphicsConfigurationUtil {
                 sb.append(", ");
             }
             sb.append("PBUFFER");
+            seperator=true;
+        }
+        if( 0 != ( FBO_BIT & winattrbits )  )  {
+            if(seperator) {
+                sb.append(", ");
+            }
+            sb.append("FBO");
         }
         return sb;
     }
 
     /**
+     * @param isFBO TODO
      * @return bitmask representing the input boolean in exclusive or logic, ie only one bit will be set
      */
-    public static final int getWinAttributeBits(boolean isOnscreen, boolean isPBuffer) {
+    public static final int getWinAttributeBits(boolean isOnscreen, boolean isPBuffer, boolean isFBO) {
         int winattrbits = 0;
         if(isOnscreen) {
             winattrbits |= WINDOW_BIT;
-        } else if (!isPBuffer) {
-            winattrbits |= BITMAP_BIT;
         } else {
-            winattrbits |= PBUFFER_BIT;
+            if(isFBO) {
+                winattrbits |= FBO_BIT;
+            }
+            if (!isPBuffer) {
+                winattrbits |= BITMAP_BIT;
+            } else {
+                winattrbits |= PBUFFER_BIT;
+            }
         }
         return winattrbits;
     }
 
     /**
-     * @see #getWinAttributeBits(boolean, boolean)
+     * @see #getWinAttributeBits(boolean, boolean, boolean)
      */
     public static final int getWinAttributeBits(GLCapabilitiesImmutable caps) {
-        return getWinAttributeBits(caps.isOnscreen(), caps.isPBuffer());
+        return getWinAttributeBits(caps.isOnscreen(), caps.isPBuffer(), false);
     }
 
     public static final boolean addGLCapabilitiesPermutations(List<GLCapabilitiesImmutable> capsBucket, GLCapabilitiesImmutable temp, int winattrbits) {
@@ -92,43 +106,58 @@ public class GLGraphicsConfigurationUtil {
         if( 0 != ( WINDOW_BIT & winattrbits )  )  {
             GLCapabilities cpy  = (GLCapabilities) temp.cloneMutable();
             cpy.setOnscreen(true);
+            cpy.setPBuffer(false);
+            cpy.setFBO(false);
             capsBucket.add(cpy);
         }
-        if( 0 != ( PBUFFER_BIT & winattrbits )  )  {
+        if( 0 != ( PBUFFER_BIT & winattrbits ) || 0 != ( FBO_BIT & winattrbits )  )  {
             GLCapabilities cpy  = (GLCapabilities) temp.cloneMutable();
-            cpy.setPBuffer(true);
+            cpy.setFBO(0 != ( FBO_BIT & winattrbits ));
+            cpy.setPBuffer(0 != ( PBUFFER_BIT & winattrbits ));
             capsBucket.add(cpy);
         }
         if( 0 != ( BITMAP_BIT & winattrbits )  )  {
             GLCapabilities cpy  = (GLCapabilities) temp.cloneMutable();
             cpy.setOnscreen(false);
             cpy.setPBuffer(false);
+            cpy.setFBO(false);
             capsBucket.add(cpy);
         }
         return capsBucket.size() > preSize;
     }
 
-    public static GLCapabilitiesImmutable fixGLCapabilities(GLCapabilitiesImmutable capsRequested, boolean pbufferAvailable)
+    public static GLCapabilitiesImmutable fixGLCapabilities(GLCapabilitiesImmutable capsRequested, boolean fboAvailable, boolean pbufferAvailable)
     {
         if( !capsRequested.isOnscreen() ) {
-            return fixOffScreenGLCapabilities(capsRequested, pbufferAvailable);
+            return fixOffscreenGLCapabilities(capsRequested, fboAvailable, pbufferAvailable);
         }
-        return capsRequested;
+        return fixOnscreenGLCapabilities(capsRequested);
     }
 
-    public static GLCapabilitiesImmutable fixOffScreenGLCapabilities(GLCapabilitiesImmutable capsRequested, boolean pbufferAvailable)
+    public static GLCapabilitiesImmutable fixOnscreenGLCapabilities(GLCapabilitiesImmutable capsRequested)
+    {
+        if( !capsRequested.isOnscreen() ) {
+            // fix caps ..
+            GLCapabilities caps2 = (GLCapabilities) capsRequested.cloneMutable();
+            caps2.setOnscreen(true);
+            return caps2;
+        }
+        return capsRequested;
+    }
+    
+    public static GLCapabilitiesImmutable fixOffscreenGLCapabilities(GLCapabilitiesImmutable capsRequested, boolean fboAvailable, boolean pbufferAvailable)
     {
         if( capsRequested.getDoubleBuffered() ||
             capsRequested.isOnscreen() ||
-            ( !pbufferAvailable && capsRequested.isPBuffer() ) )
+            ( fboAvailable != capsRequested.isFBO() ) || 
+            ( pbufferAvailable != capsRequested.isPBuffer() ) )
         {
             // fix caps ..
             GLCapabilities caps2 = (GLCapabilities) capsRequested.cloneMutable();
             caps2.setDoubleBuffered(false); // FIXME DBLBUFOFFSCRN
             caps2.setOnscreen(false);
-            if(caps2.isPBuffer() && !pbufferAvailable) {
-                caps2.setPBuffer(false);
-            }
+            caps2.setFBO( fboAvailable ); 
+            caps2.setPBuffer( pbufferAvailable );
             return caps2;
         }
         return capsRequested;
@@ -136,12 +165,13 @@ public class GLGraphicsConfigurationUtil {
 
     public static GLCapabilitiesImmutable fixGLPBufferGLCapabilities(GLCapabilitiesImmutable capsRequested)
     {
-        if( capsRequested.getDoubleBuffered() || capsRequested.isOnscreen() || !capsRequested.isPBuffer()) {
+        if( capsRequested.getDoubleBuffered() || capsRequested.isOnscreen() || !capsRequested.isPBuffer() || capsRequested.isFBO() ) {
             // fix caps ..
             GLCapabilities caps2 = (GLCapabilities) capsRequested.cloneMutable();
             caps2.setDoubleBuffered(false); // FIXME DBLBUFOFFSCRN - we don't need to be single buffered ..
             caps2.setOnscreen(false);
             caps2.setPBuffer(true);
+            caps2.setFBO(false);
             return caps2;
         }
         return capsRequested;