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, 104 insertions, 24 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
index 9fd895c1f..b6e7b0576 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
@@ -48,13 +48,16 @@ import java.util.List;
 import com.jogamp.common.JogampRuntimeException;
 
 import com.jogamp.common.util.ReflectionUtil;
+import com.jogamp.opengl.GLAutoDrawableDelegate;
 
 import javax.media.nativewindow.AbstractGraphicsDevice;
 import javax.media.nativewindow.AbstractGraphicsScreen;
+import javax.media.nativewindow.AbstractGraphicsConfiguration;
+import javax.media.nativewindow.CapabilitiesImmutable;
 import javax.media.nativewindow.NativeSurface;
 import javax.media.nativewindow.NativeWindowFactory;
 import javax.media.nativewindow.ProxySurface;
-import javax.media.nativewindow.ProxySurface.UpstreamSurfaceHook;
+import javax.media.nativewindow.UpstreamSurfaceHook;
 
 import jogamp.opengl.Debug;
 
@@ -373,44 +376,63 @@ public abstract class GLDrawableFactory {
   // Methods to create high-level objects
 
   /**
-   * Returns a GLDrawable according to it's chosen Capabilities,<br>
+   * Returns a GLDrawable according to it's chosen {@link GLCapabilitiesImmutable},<br>
    * which determines pixel format, on- and offscreen incl. PBuffer type.
    * <p>
-   * The native platform's chosen Capabilties are referenced within the target
-   * NativeSurface's AbstractGraphicsConfiguration.<p>
-   *
-   * In case target's {@link javax.media.nativewindow.Capabilities#isOnscreen()} is true,<br>
-   * an onscreen GLDrawable will be realized.
+   * The chosen {@link GLCapabilitiesImmutable} are referenced within the target
+   * {@link NativeSurface}'s {@link AbstractGraphicsConfiguration}.<p>
+   * </p>
    * <p>
-   * In case target's {@link javax.media.nativewindow.Capabilities#isOnscreen()} is false,<br>
-   * either a Pbuffer drawable is created if target's {@link javax.media.opengl.GLCapabilities#isPBuffer()} is true,<br>
-   * or a simple pixmap/bitmap drawable is created. The latter is unlikely to be hardware accelerated.<br>
+   * An onscreen GLDrawable is created if {@link CapabilitiesImmutable#isOnscreen() caps.isOnscreen()} is true.
+   * </p>
    * <p>
-   *
+   * A FBO drawable is created if both {@link GLCapabilitiesImmutable#isFBO() caps.isFBO()}
+   * and {@link GLContext#isFBOAvailable(AbstractGraphicsDevice, GLProfile) canCreateFBO(device, caps.getGLProfile())} is true.
+   * </p>
+   * <p>
+   * A Pbuffer drawable is created if both {@link GLCapabilitiesImmutable#isPBuffer() caps.isPBuffer()}
+   * and {@link #canCreateGLPbuffer(AbstractGraphicsDevice) canCreateGLPbuffer(device)} is true.
+   * </p>
+   * <p>
+   * If not onscreen and neither FBO nor Pbuffer is available, 
+   * a simple pixmap/bitmap drawable/surface is created, which is unlikely to be hardware accelerated.
+   * </p>
+   * 
    * @throws IllegalArgumentException if the passed target is null
    * @throws GLException if any window system-specific errors caused
    *         the creation of the GLDrawable to fail.
    *
+   * @see #canCreateGLPbuffer(AbstractGraphicsDevice)
+   * @see GLContext#isFBOAvailable(AbstractGraphicsDevice, GLProfile)
+   * @see javax.media.opengl.GLCapabilities#isOnscreen()
+   * @see javax.media.opengl.GLCapabilities#isFBO()
+   * @see javax.media.opengl.GLCapabilities#isPBuffer()
    * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
    */
   public abstract GLDrawable createGLDrawable(NativeSurface target)
     throws IllegalArgumentException, GLException;
-
+  
   /**
-   * Creates a Offscreen GLDrawable incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions.
+   * Creates an {@link GLOffscreenAutoDrawable} incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions.
    * <p>
-   * It's {@link AbstractGraphicsConfiguration} is properly set according to the given {@link GLCapabilitiesImmutable}, see below.
+   * The {@link GLOffscreenAutoDrawable}'s {@link GLDrawable} is realized and it's {@link GLContext} assigned but not yet made current.
    * </p>
    * <p>
-   * A FBO drawable is created if both {@link javax.media.opengl.GLCapabilities#isFBO() caps.isFBO()}
+   * In case the passed {@link GLCapabilitiesImmutable} contains default values, i.e.
+   * {@link GLCapabilitiesImmutable#isOnscreen() caps.isOnscreen()} <code> == true</code>,
+   * it is auto-configured. The latter will set offscreen and also FBO <i>or</i> Pbuffer, whichever is available in that order.
+   * </p>
+   * <p>
+   * A FBO based auto drawable, {@link GLOffscreenAutoDrawable.FBO}, is created if both {@link GLCapabilitiesImmutable#isFBO() caps.isFBO()}
    * and {@link GLContext#isFBOAvailable(AbstractGraphicsDevice, GLProfile) canCreateFBO(device, caps.getGLProfile())} is true.
    * </p>
    * <p>
-   * A Pbuffer drawable is created if both {@link javax.media.opengl.GLCapabilities#isPBuffer() caps.isPBuffer()}
-   * and {@link #canCreateGLPbuffer(javax.media.nativewindow.AbstractGraphicsDevice) canCreateGLPbuffer(device)} is true.
+   * A Pbuffer based auto drawable is created if both {@link GLCapabilitiesImmutable#isPBuffer() caps.isPBuffer()}
+   * and {@link #canCreateGLPbuffer(AbstractGraphicsDevice) canCreateGLPbuffer(device)} is true.
    * </p>
    * <p>
-   * If neither FBO nor Pbuffer is available, a simple pixmap/bitmap drawable/surface is created, which is unlikely to be hardware accelerated.
+   * If neither FBO nor Pbuffer is available, 
+   * a simple pixmap/bitmap auto drawable is created, which is unlikely to be hardware accelerated.
    * </p>
    *
    * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared device to be used, may be <code>null</code> for the platform's default device.
@@ -418,17 +440,55 @@ public abstract class GLDrawableFactory {
    * @param chooser the custom chooser, may be null for default
    * @param width the requested offscreen width
    * @param height the requested offscreen height
+   * @return the created and initialized offscreen {@link GLOffscreenAutoDrawable} instance
    *
-   * @return the created offscreen GLDrawable
+   * @throws GLException if any window system-specific errors caused
+   *         the creation of the Offscreen to fail.
+   *         
+   * @see #createOffscreenDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int)
+   */
+  public abstract GLOffscreenAutoDrawable createOffscreenAutoDrawable(AbstractGraphicsDevice device,
+                                                                      GLCapabilitiesImmutable caps,
+                                                                      GLCapabilitiesChooser chooser,
+                                                                      int width, int height,
+                                                                      GLContext shareWith) throws GLException;
+  /**
+   * Creates a offscreen {@link GLDrawable} incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions.
+   * <p>
+   * In case the passed {@link GLCapabilitiesImmutable} contains default values, i.e.
+   * {@link GLCapabilitiesImmutable#isOnscreen() caps.isOnscreen()} <code> == true</code>,
+   * it is auto-configured. The latter will set offscreen and also FBO <i>or</i> Pbuffer, whichever is available in that order.
+   * </p>
+   * <p>
+   * A resizeable FBO drawable, {@link GLFBODrawable.Resizeable}, is created if both {@link GLCapabilitiesImmutable#isFBO() caps.isFBO()}
+   * and {@link GLContext#isFBOAvailable(AbstractGraphicsDevice, GLProfile) canCreateFBO(device, caps.getGLProfile())} is true.
+   * </p>
+   * <p>
+   * A Pbuffer drawable is created if both {@link GLCapabilitiesImmutable#isPBuffer() caps.isPBuffer()}
+   * and {@link #canCreateGLPbuffer(AbstractGraphicsDevice) canCreateGLPbuffer(device)} is true.
+   * </p>
+   * <p>
+   * If neither FBO nor Pbuffer is available, 
+   * a simple pixmap/bitmap drawable is created, which is unlikely to be hardware accelerated.
+   * </p>
+   *
+   * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared device to be used, may be <code>null</code> for the platform's default device.
+   * @param caps the requested GLCapabilties
+   * @param chooser the custom chooser, may be null for default
+   * @param width the requested offscreen width
+   * @param height the requested offscreen height
+   *
+   * @return the created offscreen {@link GLDrawable}
    *
    * @throws GLException if any window system-specific errors caused
    *         the creation of the Offscreen to fail.
+   *         
+   * @see #createOffscreenAutoDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int, GLContext)
    */
   public abstract GLDrawable createOffscreenDrawable(AbstractGraphicsDevice device,
-                                                     GLCapabilitiesImmutable capabilities,
+                                                     GLCapabilitiesImmutable caps,
                                                      GLCapabilitiesChooser chooser,
-                                                     int width, int height)
-    throws GLException;
+                                                     int width, int height) throws GLException;
 
   /**
    * Creates a proxy {@link NativeSurface} w/ defined surface handle, i.e. a {@link WrappedSurface} or {@link GDISurface} instance. 
@@ -459,6 +519,21 @@ public abstract class GLDrawableFactory {
                                                   GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, UpstreamSurfaceHook upstream);
 
   /**
+   * Returns true if it is possible to create an <i>framebuffer object</i> (FBO).
+   * <p>
+   * FBO feature is implemented in OpenGL, hence it is {@link GLProfile} dependent.
+   * </p> 
+   * <p>
+   * FBO support is queried as described in {@link GLContext#hasBasicFBOSupport()}.
+   * </p>
+   *
+   * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> for the platform's default device.
+   * @param glp {@link GLProfile} to check for FBO capabilities
+   * @see GLContext#hasBasicFBOSupport()
+   */
+  public abstract boolean canCreateFBO(AbstractGraphicsDevice device, GLProfile glp);
+
+  /**
    * Returns true if it is possible to create a GLPbuffer. Some older
    * graphics cards do not have this capability.
    *
@@ -467,7 +542,10 @@ public abstract class GLDrawableFactory {
   public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device);
 
   /**
-   * Creates a GLPbuffer with the given capabilites and dimensions. <P>
+   * Creates a GLPbuffer {@link GLAutoDrawable} with the given capabilites and dimensions.
+   * <p>
+   * The GLPbuffer drawable is realized and initialized eagerly.
+   * </p>
    *
    * See the note in the overview documentation on
    * <a href="../../../overview-summary.html#SHARING">context sharing</a>.
@@ -479,10 +557,12 @@ public abstract class GLDrawableFactory {
    * @param initialHeight initial height of pbuffer
    * @param shareWith a shared GLContext this GLPbuffer shall use
    *
-   * @return the new {@link GLPbuffer} specific {@link GLAutoDrawable}
+   * @return the created and initialized {@link GLPbuffer} instance
    *
    * @throws GLException if any window system-specific errors caused
    *         the creation of the GLPbuffer to fail.
+   *         
+   * @deprecated {@link GLPbuffer} is deprecated, use {@link #createOffscreenAutoDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int, GLContext)}
    */
   public abstract GLPbuffer createGLPbuffer(AbstractGraphicsDevice device,
                                             GLCapabilitiesImmutable capabilities,