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, 31 insertions, 25 deletions

diff --git a/make/config/jogl/gl-impl-CustomJavaCode-gl4bc.java b/make/config/jogl/gl-impl-CustomJavaCode-gl4bc.java
index 95aa7cc2c..e079a1a24 100644
--- a/make/config/jogl/gl-impl-CustomJavaCode-gl4bc.java
+++ b/make/config/jogl/gl-impl-CustomJavaCode-gl4bc.java
@@ -33,7 +33,7 @@ public GL4bcImpl(GLProfile glp, GLContextImpl context) {
  * Provides platform-independent access to the wglAllocateMemoryNV /
  * glXAllocateMemoryNV extension.
  */
-public java.nio.ByteBuffer glAllocateMemoryNV(int arg0, float arg1, float arg2, float arg3) {
+public final java.nio.ByteBuffer glAllocateMemoryNV(int arg0, float arg1, float arg2, float arg3) {
   return _context.glAllocateMemoryNV(arg0, arg1, arg2, arg3);
 }
 
@@ -52,7 +52,7 @@ private boolean haveGL15;
 private boolean haveGL21;
 private boolean haveARBVertexBufferObject;
 
-private void initBufferObjectExtensionChecks() {
+private final void initBufferObjectExtensionChecks() {
   if (bufferObjectExtensionsInitialized)
     return;
   bufferObjectExtensionsInitialized = true;
@@ -63,12 +63,12 @@ private void initBufferObjectExtensionChecks() {
   haveARBVertexBufferObject = isExtensionAvailable("GL_ARB_vertex_buffer_object");
 }
 
-private boolean checkBufferObject(boolean extension1,
-                                  boolean extension2,
-                                  boolean extension3,
-                                  boolean enabled,
-                                  int state,
-                                  String kind, boolean throwException) {
+private final boolean checkBufferObject(boolean extension1,
+                                        boolean extension2,
+                                        boolean extension3,
+                                        boolean enabled,
+                                        int state,
+                                        String kind, boolean throwException) {
   if (inBeginEndPair) {
     throw new GLException("May not call this between glBegin and glEnd");
   }
@@ -100,7 +100,7 @@ private boolean checkBufferObject(boolean extension1,
   return true;
 }  
 
-private boolean checkArrayVBODisabled(boolean throwException) { 
+private final boolean checkArrayVBODisabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveGL15,
                     haveARBVertexBufferObject,
@@ -110,7 +110,7 @@ private boolean checkArrayVBODisabled(boolean throwException) {
                     "array vertex_buffer_object", throwException);
 }
 
-private boolean checkArrayVBOEnabled(boolean throwException) { 
+private final boolean checkArrayVBOEnabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveGL15,
                     haveARBVertexBufferObject,
@@ -120,7 +120,7 @@ private boolean checkArrayVBOEnabled(boolean throwException) {
                     "array vertex_buffer_object", throwException);
 }
 
-private boolean checkElementVBODisabled(boolean throwException) { 
+private final boolean checkElementVBODisabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveGL15,
                     haveARBVertexBufferObject,
@@ -130,7 +130,7 @@ private boolean checkElementVBODisabled(boolean throwException) {
                     "element vertex_buffer_object", throwException);
 }
 
-private boolean checkElementVBOEnabled(boolean throwException) { 
+private final boolean checkElementVBOEnabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveGL15,
                     haveARBVertexBufferObject,
@@ -140,7 +140,7 @@ private boolean checkElementVBOEnabled(boolean throwException) {
                     "element vertex_buffer_object", throwException);
 }
 
-private boolean checkUnpackPBODisabled(boolean throwException) { 
+private final boolean checkUnpackPBODisabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveARBPixelBufferObject,
                     haveEXTPixelBufferObject,
@@ -150,7 +150,7 @@ private boolean checkUnpackPBODisabled(boolean throwException) {
                     "unpack pixel_buffer_object", throwException);
 }
 
-private boolean checkUnpackPBOEnabled(boolean throwException) { 
+private final boolean checkUnpackPBOEnabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveARBPixelBufferObject,
                     haveEXTPixelBufferObject,
@@ -160,7 +160,7 @@ private boolean checkUnpackPBOEnabled(boolean throwException) {
                     "unpack pixel_buffer_object", throwException);
 }
 
-private boolean checkPackPBODisabled(boolean throwException) { 
+private final boolean checkPackPBODisabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveARBPixelBufferObject,
                     haveEXTPixelBufferObject,
@@ -170,7 +170,7 @@ private boolean checkPackPBODisabled(boolean throwException) {
                     "pack pixel_buffer_object", throwException);
 }
 
-private boolean checkPackPBOEnabled(boolean throwException) { 
+private final boolean checkPackPBOEnabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(haveARBPixelBufferObject,
                     haveEXTPixelBufferObject,
@@ -180,18 +180,20 @@ private boolean checkPackPBOEnabled(boolean throwException) {
                     "pack pixel_buffer_object", throwException);
 }
 
-public boolean glIsPBOPackEnabled() {
+@Override
+public final boolean glIsPBOPackEnabled() {
     return checkPackPBOEnabled(false);
 }
 
-public boolean glIsPBOUnpackEnabled() {
+@Override
+public final boolean glIsPBOUnpackEnabled() {
     return checkUnpackPBOEnabled(false);
 }
 
-private HashMap<MemoryObject, MemoryObject> arbMemCache = new HashMap<MemoryObject, MemoryObject>();
+private final HashMap<MemoryObject, MemoryObject> arbMemCache = new HashMap<MemoryObject, MemoryObject>();
 
 /** Entry point to C language function: <br> <code> LPVOID glMapBuffer(GLenum target, GLenum access); </code>    */
-public java.nio.ByteBuffer glMapBuffer(int target, int access) {
+public final java.nio.ByteBuffer glMapBuffer(int target, int access) {
   final long __addr_ = ((GL4bcProcAddressTable)_context.getGLProcAddressTable())._addressof_glMapBuffer;
   if (__addr_ == 0) {
     throw new GLException("Method \"glMapBuffer\" not available");
@@ -230,7 +232,7 @@ public java.nio.ByteBuffer glMapBuffer(int target, int access) {
 native private long dispatch_glMapBuffer(int target, int access, long glProcAddress);
 
 /** Entry point to C language function: <code> GLvoid *  {@native glMapNamedBufferEXT}(GLuint buffer, GLenum access); </code> <br>Part of <code>GL_EXT_direct_state_access</code>   */
-public java.nio.ByteBuffer glMapNamedBufferEXT(int bufferName, int access)  {
+public final java.nio.ByteBuffer glMapNamedBufferEXT(int bufferName, int access)  {
   final long __addr_ = ((GL4bcProcAddressTable)_context.getGLProcAddressTable())._addressof_glMapNamedBufferEXT;
   if (__addr_ == 0) {
     throw new GLException("Method \"glMapNamedBufferEXT\" not available");
@@ -269,7 +271,8 @@ private native long dispatch_glMapNamedBufferEXT(int buffer, int access, long pr
 
 native private ByteBuffer newDirectByteBuffer(long addr, long capacity);
 
-    public void glVertexPointer(GLArrayData array) {
+    @Override
+    public final void glVertexPointer(GLArrayData array) {
       if(array.getComponentCount()==0) return;
       if(array.isVBO()) {
           glVertexPointer(array.getComponentCount(), array.getComponentType(), array.getStride(), array.getVBOOffset());
@@ -277,7 +280,8 @@ native private ByteBuffer newDirectByteBuffer(long addr, long capacity);
           glVertexPointer(array.getComponentCount(), array.getComponentType(), array.getStride(), array.getBuffer());
       }
     }
-    public void glColorPointer(GLArrayData array) {
+    @Override
+    public final void glColorPointer(GLArrayData array) {
       if(array.getComponentCount()==0) return;
       if(array.isVBO()) {
           glColorPointer(array.getComponentCount(), array.getComponentType(), array.getStride(), array.getVBOOffset());
@@ -286,7 +290,8 @@ native private ByteBuffer newDirectByteBuffer(long addr, long capacity);
       }
 
     }
-    public void glNormalPointer(GLArrayData array) {
+    @Override
+    public final void glNormalPointer(GLArrayData array) {
       if(array.getComponentCount()==0) return;
       if(array.getComponentCount()!=3) {
         throw new GLException("Only 3 components per normal allowed");
@@ -297,7 +302,8 @@ native private ByteBuffer newDirectByteBuffer(long addr, long capacity);
           glNormalPointer(array.getComponentType(), array.getStride(), array.getBuffer());
       }
     }
-    public void glTexCoordPointer(GLArrayData array) {
+    @Override
+    public final void glTexCoordPointer(GLArrayData array) {
       if(array.getComponentCount()==0) return;
       if(array.isVBO()) {
           glTexCoordPointer(array.getComponentCount(), array.getComponentType(), array.getStride(), array.getVBOOffset());