Seamless Integration of an FBObject based GLFBODrawable as GLOffscreenAutoDrawable.FBO and as an OffscreenLayerSurface's drawable (OSX) - Fix Bugs 569 and 599

Summary:
=========
The new FBObject based GLFBODrawable implementation allows the seamless utilization of
FBO offscreen rendering in single buffer, double buffer and MSAA mode.

The GLFBODrawable uses a parent drawable based on a
dummy surface to allow a GLOffscreenAutoDrawable.FBO creation
or a mutable surface supporting an existing offscreen layer surface (OSX CALayer).

Offscreen GLDrawable's and GLOffscreenAutoDrawable's can be selected via the
GLCapabilities. If simply !onscreen is selected in the caps instance w/o enabling FBO, PBuffer or Bitmap,
the factory will automatically choose regarding availability:
   FBO > PBuffer > Bitmap

Double buffering is supported in MSAA more (intrinsic) and explicit in non MSAA.
It is preferred when delivering resources (texture id's or framebuffer names)
to a shared GLContext.
This is demonstrated in (emulates our OSX CALayer implementation):
  TestFBOOffThreadSharedContextMix2DemosES2NEWT,
  TestFBOOnThreadSharedContext1DemoES2NEWT
and with the OSX JAWT OffscreenLayerSurface itself. FBO is the preferred choice.

+++

Offscreen drawables can be resized while maintaining a bound GLContext (e.g. w/ GLAutoDrawable).
Previously both, drawable and context, needed to be destroyed and recreated at offscreen resize.
Common implementation in GLDrawableHelper is used in the implementations
(NEWT's GLWindow, AWT GLCanvas, SWT GLCanvas).

+++

Tested:
=======

Manually run all unit tests on:
  - Linux x86_64 NVidia/AMD/Mesa3d(ES)
  - OSX x86_64 NVidia
  - Windows x86_64 NVidia
  - Android arm Mali-400/Tegra-2

No regressions.

Disclaimer:
===========
This feature is committed almost in one patch.

Both previous commits were introducing / fixing the capabilities behavior:
 90d45928186f2be99999461cfe45f76a783cc961
 9036376b7806a5fc61590bf49404eb71830de92f

I have to appologize for the huge size and impact (files and platforms) of this commit
however, I could not find a better way to inject this feature in one sane piece.

NativeWindow Details:
=====================

Complete decoupling of platform impl. detail of surfaces
implementing ProxySurface. Used to generalize dummy surfaces and EGL surfaces
on top of a native platform surface.
  - ProxySurface.UpstreamSurfaceHook -> UpstreamSurfaceHook
  - abstract class ProxySurface -> interface ProxySurface + ProxySurfaceImpl
  - Misc. implementations

JOGL Details:
=====================

FBOObject: API Change / Simplification & Usability
  - Removed reference counter to remove complexity, allow user to choose.
  - Add 'dispose' flag for detachColorbuffer(..), allowing to keep attachment alive
  - Fix equals operation of Attachment
  - Check pre-exising GL errors
  - Interface Colobuffer gets lifecycle methods
  - Add static factory methods to create Attachments w/o FBObject instance
  - Reset:
    - Clip min size to 1
    - Keep alive samplingSink, i.e. don't issue resetMSAATexture2DSink(..).
      It gets called at syncFramebuffer()/use(..) later on before actual usage.
      This allows the consumer to utilize the GL_FRONT buffer until (e.g.) swap.
  - misc bugfixes

GLOffscreenAutoDrawable: API Change
  - Reloc and interfacing
  - class com.jogamp.opengl.OffscreenAutoDrawable -> javax.media.opengl.*
    interfaces GLOffscreenAutoDrawable extends GLAutoDrawable
               GLOffscreenAutoDrawable.FBO extends GLOffscreenAutoDrawable, GLFBODrawable
  - Added general implementation and FBO specialization
  - Replacing GLPBuffer (deprecated) .. usable for any offscreen GLDrawable via factory

GLAutoDrawable:
  - Add 'GLDrawable getDelegatedDrawable()'
  - Refine documentation of setContext(..), remove disclaimer and fixme tags

GLDrawableFactory:
  - Refine API doc and it's selection mechanism for offscreen.
  - Add createOffscreenDrawable(..)
  - Add createOffscreenAutoDrawable(..)
  - Add canCreateFBO(..)
  - Mark createGLPbuffer(..) deprectated

Mark GLPBuffer deprecated

New: GLFBODrawable extends GLDrawable

GLCanvas (AWT and SWT): Add offscreen resize support w/o GLContext recreation

GLAutoDrawableBase .. GLWindow:
  - Add offscreen resize support w/o GLContext recreation
  - Remove double swapBuffer call
  -

GLBase/GLContext:
  - Add:
    - boolean hasBasicFBOSupport()
    - boolean hasFullFBOSupport()
    - int getMaxRenderbufferSamples()
    - boolean isTextureFormatBGRA8888Available()

GLContext: Fix version detection and hasGLSL()
  - Version detection in setGLFunctionAvailability(..)
    - Query GL_VERSION ASAP and parse it and compare w/ given major/minor
    - Use parsed version if valid and lower than given _or_ given is invalid.
    - Use validated version for caching (procaddr, ..), version number, etc.

  - Fix hasGLSL()
    Since 'isGL2ES2()' is true if 'isGL2()'
    and the latter simply alows GL 1.*, we confine the result to a GL >= 2.0
    on desktops. FIXME: May consider GL 1.5 w/ extensions.
    -  return isGL2ES2();
    +      return isGLES2() ||
    +             isGL3() ||
    +             isGL2() && ctxMajorVersion>1 ;

GLDrawableImpl:
  - Add 'associateContext(GLContext, boolean)' allowing impl.
    to have a (weak) reference list of bound context.
    This is was pulled up from the OSX specific drawable impl.
  - swapBuffersImpl() -> swapBuffersImpl(boolean doubleBuffered)
    and call it regardless of single buffering.
    This is required to propagate this event to impl. properly,
    i.e. FBODrawable requires a swap notification.
  - Clarify 'contextMadeCurrent(..)' protocol

GLDrawableHelper:
  - Add resize and recreate offscreen drawable util method
  - Simplify required init/reshape calls for GLEventListener
  -

GLGraphicsConfigurationUtil:
  - fixWinAttribBitsAndHwAccel: Reflect sharede context hw-accel bits
  - OSX has no offscreen bitmap, use pbuffer
  - use proper offscreen auto selection if offscreen and no modes are set

EGL Context/Drawable/DrawableFactory: Abstract native platform code out of base classes
  - Use EGLWrappedSurface w/ UpstreamSurfaceHook to handle upstream (X11, WGL, ..)
    lifecycle - in case the EGL resource is hooked up on it.

Invisible dummy surfaces: All platforms
  - size is now reduced to 64x64 and decoupled of actual generic mutable size
  - fix device  lifecycle, no more leaks

+++

OSX
====

Enable support for GLFBODrawableImpl in offscreen CALayer mode
  - NSOpenGLImpl: hooks to calayer native code
  - calayer code:
    - allows pbuffer and texures (FBO)
    - decouple size and draw calls avoiding flickering
    - enable auto resize of calayer tree

MacOSXCGLContext:
  - NSOpenGLImpl:
  - Fix false pbuffer 'usage', validate the pointer
  - If !pbuffer, copy other window mode bits of caps
  -

MacOSXCGLGraphicsConfiguration:
  - Only assume pbuffer if !onscreen
  - Remove reference of native pixelformat pointer

Native code:
  - use 'respondsToSelector:' query before calling 'new' methods
    avoiding an error message where unsuported (prev. OSX versions)
  - if monitor refresh-rate is queried 0, set to default 60hz
  - add missing NSAutoreleasePool decoration

+++

Android / NEWT:
===============

Issue setVisible(..) w/o wait, i.e. queue on EDT,
@Android surfaceChanged() callback. Otherwise we could deadlock:
   setVisible(..) -> EDT -> setVisibleImpl(..) -> 'GL-display'.
the latter may may cause havoc while Android-EDT is blocked [until it's return].

1 files changed, 117 insertions, 58 deletions

diff --git a/src/jogl/classes/jogamp/opengl/GLContextImpl.java b/src/jogl/classes/jogamp/opengl/GLContextImpl.java
index e82756022..050c619fd 100644
--- a/src/jogl/classes/jogamp/opengl/GLContextImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLContextImpl.java
@@ -47,6 +47,7 @@ import java.util.Map;
 
 import com.jogamp.common.os.DynamicLookupHelper;
 import com.jogamp.common.util.ReflectionUtil;
+import com.jogamp.common.util.VersionNumber;
 import com.jogamp.gluegen.runtime.FunctionAddressResolver;
 import com.jogamp.gluegen.runtime.ProcAddressTable;
 import com.jogamp.gluegen.runtime.opengl.GLNameResolver;
@@ -85,6 +86,7 @@ public abstract class GLContextImpl extends GLContext {
 
   private String glRenderer;
   private String glRendererLowerCase;
+  private String glVersion;
 
   // Tracks creation and initialization of buffer objects to avoid
   // repeated glGet calls upon glMapBuffer operations
@@ -126,6 +128,9 @@ public abstract class GLContextImpl extends GLContext {
     GLContextShareSet.synchronizeBufferObjectSharing(shareWith, this);
 
     this.drawable = drawable;
+    if(null != drawable) {
+        drawable.associateContext(this, true);
+    }
     this.drawableRead = drawable;
 
     this.glDebugHandler = new GLDebugMessageHandler(this);
@@ -205,8 +210,10 @@ public abstract class GLContextImpl extends GLContext {
     if(!setWriteOnly || drawableRead==drawable) { // if !setWriteOnly || !explicitReadDrawable
         drawableRead = (GLDrawableImpl) readWrite;
     }
-    final GLDrawable old = drawable;
+    final GLDrawableImpl old = drawable;
+    old.associateContext(this, false);
     drawable = (GLDrawableImpl) readWrite ;
+    drawable.associateContext(this, true);
     if(lockHeld) {
         makeCurrent();
     }
@@ -272,7 +279,7 @@ public abstract class GLContextImpl extends GLContext {
         if( actualRelease ) {
             if( !inDestruction ) {
                 try {
-                    drawable.contextMadeCurrent(this, false);
+                    contextMadeCurrent(false);
                 } catch (Throwable t) {
                     drawableContextMadeCurrentException = t;
                 }
@@ -331,7 +338,8 @@ public abstract class GLContextImpl extends GLContext {
                       makeCurrent();
                   }
                   try {
-                      drawable.contextRealized(this, false);
+                      contextRealized(false);
+                      drawable.associateContext(this, false);
                   } catch (Throwable t) {
                       drawableContextRealizedException = t;
                   }
@@ -514,19 +522,17 @@ public abstract class GLContextImpl extends GLContext {
             gl = gl.getContext().setGL( GLPipelineFactory.create("javax.media.opengl.Trace", null, gl, new Object[] { System.err } ) );
         }
         
-        drawable.contextRealized(this, true);
+        contextRealized(true);
         
         if(DEBUG || TRACE_SWITCH) {
             System.err.println(getThreadName() +": GLContext.ContextSwitch: obj " + toHexString(hashCode()) + ", ctx "+toHexString(contextHandle)+" - switch - CONTEXT_CURRENT_NEW - "+lock);
         }
-      } else {
-        drawable.contextMadeCurrent(this, true);
-        
-        if(TRACE_SWITCH) {
-            System.err.println(getThreadName() +": GLContext.ContextSwitch: obj " + toHexString(hashCode()) + ", ctx "+toHexString(contextHandle)+" - switch - CONTEXT_CURRENT - "+lock);
-        }
+      } else if(TRACE_SWITCH) {
+         System.err.println(getThreadName() +": GLContext.ContextSwitch: obj " + toHexString(hashCode()) + ", ctx "+toHexString(contextHandle)+" - switch - CONTEXT_CURRENT - "+lock);
       }
 
+      contextMadeCurrent(true);
+      
       /* FIXME: refactor dependence on Java 2D / JOGL bridge
 
       // Try cleaning up any stale server-side OpenGL objects
@@ -609,6 +615,20 @@ public abstract class GLContextImpl extends GLContext {
   protected abstract void makeCurrentImpl() throws GLException;
 
   /**
+   * @see GLDrawableImpl#contextRealized(GLContext, boolean) 
+   */ 
+  protected void contextRealized(boolean realized) {
+      drawable.contextRealized(this, realized);
+  }
+  
+  /**
+   * @see GLDrawableImpl#contextMadeCurrent(GLContext, boolean) 
+   */ 
+  protected void contextMadeCurrent(boolean current) {
+      drawable.contextMadeCurrent(this, current);      
+  }
+
+  /**
    * Platform dependent entry point for context creation.<br>
    *
    * This method is called from {@link #makeCurrentWithinLock()} .. {@link #makeCurrent()} .<br>
@@ -934,52 +954,43 @@ public abstract class GLContextImpl extends GLContext {
 
   /**
    * If major > 0 || minor > 0 : Use passed values, determined at creation time
-   * If major==0 && minor == 0 : Use GL_VERSION
    * Otherwise .. don't touch ..
    */
   private final void setContextVersion(int major, int minor, int ctp, boolean setVersionString) {
-      if (0==ctp) {
+      if ( 0 == ctp ) {
         throw new GLException("Invalid GL Version "+major+"."+minor+", ctp "+toHexString(ctp));
       }
-      if(major>0 || minor>0) {
-          if (!GLContext.isValidGLVersion(major, minor)) {
-            GLException e = new GLException("Invalid GL Version "+major+"."+minor+", ctp "+toHexString(ctp));
-            throw e;
-          }
-          ctxMajorVersion = major;
-          ctxMinorVersion = minor;
-          ctxOptions = ctp;
-          if(setVersionString) {
-              ctxVersionString = getGLVersion(ctxMajorVersion, ctxMinorVersion, ctxOptions, getGL().glGetString(GL.GL_VERSION));
-          }
-          return;
+      
+      if (!GLContext.isValidGLVersion(major, minor)) {
+        throw new GLException("Invalid GL Version "+major+"."+minor+", ctp "+toHexString(ctp));
       }
-
-      if(major==0 && minor==0) {
-          String versionStr = getGL().glGetString(GL.GL_VERSION);
-          if(null==versionStr) {
-            throw new GLException("GL_VERSION is NULL: "+this);
-          }
-          ctxOptions = ctp;
-
-          // Set version
-          GLVersionNumber version = new GLVersionNumber(versionStr);
+      ctxMajorVersion = major;
+      ctxMinorVersion = minor;
+      ctxOptions = ctp;
+      if(setVersionString) {
+          ctxVersionString = getGLVersion(ctxMajorVersion, ctxMinorVersion, ctxOptions, getGL().glGetString(GL.GL_VERSION));
+      }
+  }
+  
+  private static final VersionNumber getGLVersionNumber(int ctp, String glVersionStr) {
+      if( null != glVersionStr ) {
+          final GLVersionNumber version = new GLVersionNumber(glVersionStr);
           if (version.isValid()) {
-            ctxMajorVersion = version.getMajor();
-            ctxMinorVersion = version.getMinor();
-            // We cannot promote a non ARB context to >= 3.1,
-            // reduce it to 3.0 then.
-            if ( ( ctxMajorVersion>3 || ctxMajorVersion==3 && ctxMinorVersion>=1 )
-                 && 0 == (ctxOptions & CTX_IS_ARB_CREATED) ) {
-                ctxMajorVersion = 3;
-                ctxMinorVersion = 0;
-            }
-            if(setVersionString) {
-                ctxVersionString = getGLVersion(ctxMajorVersion, ctxMinorVersion, ctxOptions, versionStr);
-            }
-            return;
+              int major = version.getMajor();
+              int minor = version.getMinor();
+              // We cannot promote a non ARB context to >= 3.1,
+              // reduce it to 3.0 then.
+              if ( 0 == (ctp & CTX_IS_ARB_CREATED) && 
+                   ( major > 3 || major == 3 && minor >= 1 ) ) {
+                  major = 3;
+                  minor = 0;
+              }
+              if ( GLContext.isValidGLVersion(major, minor) ) {
+                  return new VersionNumber(major, minor, 0);
+              }
           }
       }
+      return null;      
   }
 
   //----------------------------------------------------------------------
@@ -1019,14 +1030,18 @@ public abstract class GLContextImpl extends GLContext {
   /**
    * Pbuffer support; given that this is a GLContext associated with a
    * pbuffer, binds this pbuffer to its texture target.
+   * @throws GLException if not implemented (default)
+   * @deprecated use FBO/GLOffscreenAutoDrawable instead of pbuffer
    */
-  public abstract void bindPbufferToTexture();
+  public void bindPbufferToTexture() { throw new GLException("not implemented"); }
 
   /**
    * Pbuffer support; given that this is a GLContext associated with a
    * pbuffer, releases this pbuffer from its texture target.
+   * @throws GLException if not implemented (default)
+   * @deprecated use FBO/GLOffscreenAutoDrawable instead of pbuffer
    */
-  public abstract void releasePbufferFromTexture();
+  public void releasePbufferFromTexture() { throw new GLException("not implemented"); }
 
   public abstract ByteBuffer glAllocateMemoryNV(int arg0, float arg1, float arg2, float arg3);
 
@@ -1064,7 +1079,7 @@ public abstract class GLContextImpl extends GLContext {
     table.reset(getDrawableImpl().getGLDynamicLookupHelper() );
   }
 
-  private final boolean initGLRendererStrings()  {
+  private final boolean initGLRendererAndGLVersionStrings()  {
     final GLDynamicLookupHelper glDynLookupHelper = getDrawableImpl().getGLDynamicLookupHelper();
     final long _glGetString = glDynLookupHelper.dynamicLookupFunction("glGetString");
     if(0 == _glGetString) {
@@ -1083,14 +1098,27 @@ public abstract class GLContextImpl extends GLContext {
                 Thread.dumpStack();
             }
             return false;
-        } else {
-            glRenderer = _glRenderer;
-            glRendererLowerCase = glRenderer.toLowerCase();
-            return true;
         }
+        glRenderer = _glRenderer;
+        glRendererLowerCase = glRenderer.toLowerCase();
+        
+        final String _glVersion = glGetStringInt(GL.GL_VERSION, _glGetString);
+        if(null == _glVersion) {
+            // FIXME
+            if(DEBUG) {
+                System.err.println("Warning: GL_VERSION is NULL.");
+                Thread.dumpStack();
+            }
+            return false;
+        }
+        glVersion = _glVersion;
+        return true;
     }
   }
 
+  protected final String getGLVersionString() {
+      return glVersion;
+  }
   protected final String getGLRendererString(boolean lowerCase) {
       return lowerCase ? glRendererLowerCase : glRenderer;
   }
@@ -1128,17 +1156,44 @@ public abstract class GLContextImpl extends GLContext {
     final AbstractGraphicsConfiguration aconfig = drawable.getNativeSurface().getGraphicsConfiguration();
     final AbstractGraphicsDevice adevice = aconfig.getScreen().getDevice();
     
-    if( !initGLRendererStrings() && DEBUG) {
-        System.err.println("Warning: intialization of GL renderer strings failed. "+adevice+" - "+GLContext.getGLVersion(major, minor, ctxProfileBits, null));
+    {
+        final boolean initGLRendererAndGLVersionStringsOK = initGLRendererAndGLVersionStrings();
+        if(DEBUG) {
+            if( !initGLRendererAndGLVersionStringsOK ) {
+                System.err.println("Warning: setGLFunctionAvailability: intialization of GL renderer strings failed. "+adevice+" - "+GLContext.getGLVersion(major, minor, ctxProfileBits, null));
+            } else {
+                System.err.println(getThreadName() + ": GLContext.setGLFuncAvail: Given "+adevice+" - "+GLContext.getGLVersion(major, minor, ctxProfileBits, glVersion));
+            }
+        }
     }
 
     if(!isCurrentContextHardwareRasterizer()) {
         ctxProfileBits |= GLContext.CTX_IMPL_ACCEL_SOFT;
     }
-
+    
+    // Pick the version from the GL-version string, 
+    // if smaller _or_ given major == 0.
+    final VersionNumber glVersionNumber;
+    {
+        final VersionNumber setGLVersionNumber = new VersionNumber(major, minor, 0);
+        final VersionNumber strGLVersionNumber = getGLVersionNumber(ctxProfileBits, glVersion);
+        if( null != strGLVersionNumber && ( strGLVersionNumber.compareTo(setGLVersionNumber) <= 0 || 0 == major ) ) {
+            glVersionNumber = strGLVersionNumber;
+            major = glVersionNumber.getMajor();
+            minor = glVersionNumber.getMinor();
+        } else {
+            glVersionNumber = setGLVersionNumber;
+        }
+    }
+    if ( !GLContext.isValidGLVersion(major, minor) ) {
+        throw new GLException("Invalid GL Version "+major+"."+minor+", ctp "+toHexString(ctxProfileBits)+", "+glVersion+", "+glVersionNumber);
+    }
+    if( 2 > major ) { // there is no ES2-compat for a profile w/ major < 2
+        ctxProfileBits &= ~GLContext.CTX_IMPL_ES2_COMPAT;
+    }
     contextFQN = getContextFQN(adevice, major, minor, ctxProfileBits);
     if (DEBUG) {
-      System.err.println(getThreadName() + ": GLContext.setGLFuncAvail.0 FQN: "+contextFQN+" - "+GLContext.getGLVersion(major, minor, ctxProfileBits, null));
+        System.err.println(getThreadName() + ": GLContext.setGLFuncAvail.0 validated FQN: "+contextFQN+" - "+GLContext.getGLVersion(major, minor, ctxProfileBits, glVersion) + ", "+glVersionNumber);
     }
 
     //
@@ -1201,6 +1256,10 @@ public abstract class GLContextImpl extends GLContext {
         ctxProfileBits |= CTX_IMPL_FBO;
     }
     
+    if(FORCE_NO_FBO_SUPPORT) {
+        ctxProfileBits &= ~CTX_IMPL_FBO ;
+    }      
+    
     //
     // Set GL Version (complete w/ version string)
     //