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, 191 insertions, 0 deletions

diff --git a/src/jogl/classes/com/jogamp/gluegen/runtime/opengl/GLNameResolver.java b/src/jogl/classes/com/jogamp/gluegen/runtime/opengl/GLNameResolver.java
new file mode 100644
index 000000000..92554776a
--- /dev/null
+++ b/src/jogl/classes/com/jogamp/gluegen/runtime/opengl/GLNameResolver.java
@@ -0,0 +1,191 @@
+/*
+ * Copyright (c) 2003-2005 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright (c) 2010 JogAmp Community. All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ * 
+ * - Redistribution of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * 
+ * - Redistribution in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * 
+ * Neither the name of Sun Microsystems, Inc. or the names of
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ * 
+ * This software is provided "AS IS," without a warranty of any kind. ALL
+ * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
+ * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
+ * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
+ * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
+ * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
+ * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
+ * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
+ * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
+ * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
+ * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
+ * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+ * 
+ * You acknowledge that this software is not designed or intended for use
+ * in the design, construction, operation or maintenance of any nuclear
+ * facility.
+ * 
+ */
+package com.jogamp.gluegen.runtime.opengl;
+
+/** Runtime utility identify and resolve extension names, which may be subsumed to core. */
+public class GLNameResolver {
+    //GL_XYZ : GL_XYZ, GL_XYZ_GL2, GL_XYZ_ARB, GL_XYZ_OES, GL_XYZ_OML
+    //GL_XYZ : GL_XYZ, GL_GL2_XYZ, GL_ARB_XYZ, GL_OES_XYZ, GL_OML_XYZ
+    //
+    // Pass-1 Unify ARB extensions with the same value
+    // Pass-2 Unify vendor extensions, 
+    //        if exist as an ARB extension with the same value.
+    // Pass-3 Emit
+
+    public static final String[] extensionsARB = { "ARB", "GL2", "OES", "KHR", "OML" };
+    public static final String[] extensionsVEN = { "3DFX", 
+                                                   "AMD",
+                                                   "ANGLE",
+                                                   "ARM",
+                                                   "APPLE",
+                                                   "ATI",
+                                                   "EXT",
+                                                   "HI",
+                                                   "HP",
+                                                   "IBM",
+                                                   "IMG",
+                                                   "MESA",
+                                                   "MESAX",
+                                                   "NV",
+                                                   "QCOM",
+                                                   "SGI",
+                                                   "SGIS",
+                                                   "SGIX",
+                                                   "SUN",
+                                                   "VIV",
+                                                   "WIN"
+                                                   };
+
+
+    public static final boolean isGLFunction(String str) {
+        return str.startsWith("gl")  || /* str.startsWith("glu") || str.startsWith("glX") || */
+               str.startsWith("egl") || str.startsWith("wgl") || str.startsWith("agl") ||
+               str.startsWith("cgl") ;
+    }
+
+    public static final boolean isGLEnumeration(String str) {
+        return str.startsWith("GL_")  || str.startsWith("GLU_") || str.startsWith("GLX_") ||
+               str.startsWith("EGL_") || str.startsWith("WGL_") || str.startsWith("AGL_") ||
+               str.startsWith("CGL_") ;
+    }
+
+    public static final int getExtensionIdx(String[] extensions, String str, boolean isGLFunc) {
+        if(isGLFunc) {
+            for(int i = extensions.length - 1 ; i>=0 ; i--) {
+                if( str.endsWith(extensions[i]) ) {
+                    return i;
+                }
+            }
+        } else {
+            for(int i = extensions.length - 1 ; i>=0 ; i--) {
+                if( str.endsWith("_"+extensions[i]) ) {
+                    return i;
+                }
+            }
+        }
+        return -1;
+    }
+
+    public static final boolean isExtension(String[] extensions, String str, boolean isGLFunc) {
+        return getExtensionIdx(extensions, str, isGLFunc)>=0;
+    }
+
+    public static final String getExtensionSuffix(String str, boolean isGLFunc) {
+        int idx = getExtensionIdx(extensionsARB, str, isGLFunc);
+        if(idx>=0) {
+            return extensionsARB[idx];
+        }
+        idx = getExtensionIdx(extensionsVEN, str, isGLFunc);
+        if(idx>=0) {
+            return extensionsVEN[idx];
+        }
+        return null;
+    }
+
+    public static final String normalize(String[] extensions, String str, boolean isGLFunc) {
+        boolean touched = false;
+        for(int i = extensions.length - 1 ; !touched && i>=0 ; i--) {
+            if(isGLFunc) {
+                if(str.endsWith(extensions[i])) {
+                    // functions
+                    str = str.substring(0, str.length()-extensions[i].length());
+                    touched=true;
+                }
+            } else {
+                if(str.endsWith("_"+extensions[i])) {
+                    // enums
+                    str = str.substring(0, str.length()-1-extensions[i].length());
+                    touched=true;
+                }
+            }
+        }
+        return str;
+    }
+    public static final String normalizeARB(String str, boolean isGLFunc) {
+        return normalize(extensionsARB, str, isGLFunc);
+    }
+    public static final boolean isExtensionARB(String str, boolean isGLFunc) {
+        return isExtension(extensionsARB, str, isGLFunc);
+    }
+    public static final String normalizeVEN(String str, boolean isGLFunc) {
+        return normalize(extensionsVEN, str, isGLFunc);
+    }
+    public static final boolean isExtensionVEN(String str, boolean isGLFunc) {
+        return isExtension(extensionsVEN, str, isGLFunc);
+    }
+    public static final String normalize(String str, boolean isGLFunc) {
+        if (isExtensionARB(str, isGLFunc)) {
+            return normalizeARB(str, isGLFunc);
+        }
+        if (isExtensionVEN(str, isGLFunc)) {
+            return normalizeVEN(str, isGLFunc);
+        }
+        return str;
+    }
+    public static final boolean isExtension(String str, boolean isGLFunc) {
+        return isExtension(extensionsARB, str, isGLFunc) || 
+               isExtension(extensionsVEN, str, isGLFunc);
+    }
+
+    public static final int getFuncNamePermutationNumber(String name) {
+        if(isExtensionARB(name, true) || isExtensionVEN(name, true)) {
+            // no name permutation, if it's already a known extension
+            return 1;
+        }
+        return 1 + extensionsARB.length + extensionsVEN.length;
+    }
+
+    public static final String getFuncNamePermutation(String name, int i) {
+        // identity
+        if(i==0) {
+            return name;
+        }
+        if(0>i || i>=(1+extensionsARB.length + extensionsVEN.length)) {
+            throw new RuntimeException("Index out of range [0.."+(1+extensionsARB.length+extensionsVEN.length-1)+"]: "+i);
+        }
+        // ARB
+        i-=1;
+        if(i<extensionsARB.length) {
+            return name+extensionsARB[i];
+        }
+        // VEN
+        i-=extensionsARB.length;
+        return name+extensionsVEN[i];
+    }
+}
+