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, 47 insertions, 19 deletions

diff --git a/make/config/jogl/gl-impl-CustomJavaCode-gles1.java b/make/config/jogl/gl-impl-CustomJavaCode-gles1.java
index dff33cf81..68eadc683 100644
--- a/make/config/jogl/gl-impl-CustomJavaCode-gles1.java
+++ b/make/config/jogl/gl-impl-CustomJavaCode-gles1.java
@@ -12,98 +12,122 @@ public GLES1Impl(GLProfile glp, GLContextImpl context) {
   this.glProfile = glp;
 }
 
+@Override
 public final boolean isGL4bc() {
     return false;
 }
 
+@Override
 public final boolean isGL4() {
     return false;
 }
 
+@Override
 public final boolean isGL3bc() {
     return false;
 }
 
+@Override
 public final boolean isGL3() {
     return false;
 }
 
+@Override
 public final boolean isGL2() {
     return false;
 }
 
+@Override
 public final boolean isGLES1() {
     return true;
 }
 
+@Override
 public final boolean isGLES2() {
     return false;
 }
 
+@Override
 public final boolean isGLES() {
     return true;
 }
 
+@Override
 public final boolean isGL2ES1() {
     return true;
 }
 
+@Override
 public final boolean isGL2ES2() {
     return false;
 }
 
+@Override
 public final boolean isGLES2Compatible() {
     return false;
 }
 
+@Override
 public final boolean isGL2GL3() {
     return false;
 }
 
+@Override
 public final boolean hasGLSL() {
     return false;
 }
 
+@Override
 public boolean isNPOTTextureAvailable() {
   return false;
 }
 
+@Override
 public final GL4bc getGL4bc() throws GLException {
     throw new GLException("Not a GL4bc implementation");
 }
 
+@Override
 public final GL4 getGL4() throws GLException {
     throw new GLException("Not a GL4 implementation");
 }
 
+@Override
 public final GL3bc getGL3bc() throws GLException {
     throw new GLException("Not a GL3bc implementation");
 }
 
+@Override
 public final GL3 getGL3() throws GLException {
     throw new GLException("Not a GL3 implementation");
 }
 
+@Override
 public final GL2 getGL2() throws GLException {
     throw new GLException("Not a GL2 implementation");
 }
 
+@Override
 public final GLES1 getGLES1() throws GLException {
     return this;
 }
 
+@Override
 public final GLES2 getGLES2() throws GLException {
     throw new GLException("Not a GLES2 implementation");
 }
 
+@Override
 public final GL2ES1 getGL2ES1() throws GLException {
     return this;
 }
 
+@Override
 public final GL2ES2 getGL2ES2() throws GLException {
     throw new GLException("Not a GL2ES2 implementation");
 }
 
+@Override
 public final GL2GL3 getGL2GL3() throws GLException {
     throw new GLException("Not a GL2GL3 implementation");
 }
@@ -119,17 +143,17 @@ private final GLStateTracker       glStateTracker;
 private boolean bufferObjectExtensionsInitialized = false;
 private boolean haveOESFramebufferObject;
 
-private void initBufferObjectExtensionChecks() {
+private final void initBufferObjectExtensionChecks() {
   if (bufferObjectExtensionsInitialized)
     return;
   bufferObjectExtensionsInitialized = true;
   haveOESFramebufferObject  = isExtensionAvailable("GL_OES_framebuffer_object");
 }
 
-private boolean checkBufferObject(boolean avail,
-                                  boolean enabled,
-                                  int state,
-                                  String kind, boolean throwException) {
+private final boolean checkBufferObject(boolean avail,
+                                        boolean enabled,
+                                        int state,
+                                        String kind, boolean throwException) {
   if (!avail) {
     if (!enabled)
       return true;
@@ -157,7 +181,7 @@ private boolean checkBufferObject(boolean avail,
   return true;
 }  
 
-private boolean checkArrayVBODisabled(boolean throwException) { 
+private final boolean checkArrayVBODisabled(boolean throwException) { 
   initBufferObjectExtensionChecks();
   return checkBufferObject(true,
                     false,
@@ -165,7 +189,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(true,
                     true,
@@ -173,7 +197,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(true,
                     false,
@@ -181,7 +205,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(true,
                     true,
@@ -189,30 +213,30 @@ private boolean checkElementVBOEnabled(boolean throwException) {
                     "element vertex_buffer_object", throwException);
 }
 
-private boolean checkUnpackPBODisabled(boolean throwException) { 
+private final boolean checkUnpackPBODisabled(boolean throwException) { 
     // PBO n/a for ES 1.1 or ES 2.0
     return true;
 }
 
-private boolean checkUnpackPBOEnabled(boolean throwException) { 
+private final boolean checkUnpackPBOEnabled(boolean throwException) { 
     // PBO n/a for ES 1.1 or ES 2.0
     return false;
 }
 
-private boolean checkPackPBODisabled(boolean throwException) { 
+private final boolean checkPackPBODisabled(boolean throwException) { 
     // PBO n/a for ES 1.1 or ES 2.0
     return true;
 }
 
-private boolean checkPackPBOEnabled(boolean throwException) { 
+private final boolean checkPackPBOEnabled(boolean throwException) { 
     // PBO n/a for ES 1.1 or ES 2.0
     return 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_ = ((GLES1ProcAddressTable)_context.getGLProcAddressTable())._addressof_glMapBuffer;
   if (__addr_ == 0) {
     throw new GLException("Method \"glMapBuffer\" not available");
@@ -252,7 +276,8 @@ native private long dispatch_glMapBuffer(int target, int access, long glProcAddr
 
 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());
@@ -260,7 +285,8 @@ public void glVertexPointer(GLArrayData array) {
       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());
@@ -269,7 +295,8 @@ public void glColorPointer(GLArrayData array) {
   }
 
 }
-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");
@@ -280,7 +307,8 @@ public void glNormalPointer(GLArrayData array) {
       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());