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

diff --git a/src/jogl/classes/com/jogamp/opengl/GLExtensions.java b/src/jogl/classes/com/jogamp/opengl/GLExtensions.java
new file mode 100644
index 000000000..f7e25fa01
--- /dev/null
+++ b/src/jogl/classes/com/jogamp/opengl/GLExtensions.java
@@ -0,0 +1,81 @@
+/**
+ * Copyright 2012 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:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions 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.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.opengl;
+
+/**
+ * Class holding OpenGL extension strings, commonly used by JOGL's implementation. 
+ */
+public class GLExtensions {
+  public static final String VERSION_1_2                     = "GL_VERSION_1_2";
+  public static final String VERSION_1_4                     = "GL_VERSION_1_4";
+  public static final String VERSION_1_5                     = "GL_VERSION_1_5";
+  public static final String VERSION_2_0                     = "GL_VERSION_2_0";
+  
+  public static final String ARB_debug_output                = "GL_ARB_debug_output";
+  public static final String AMD_debug_output                = "GL_AMD_debug_output";
+    
+  public static final String ARB_framebuffer_object          = "GL_ARB_framebuffer_object";
+  public static final String OES_framebuffer_object          = "GL_OES_framebuffer_object";
+  public static final String EXT_framebuffer_object          = "GL_EXT_framebuffer_object";
+  public static final String EXT_framebuffer_blit            = "GL_EXT_framebuffer_blit";
+  public static final String EXT_framebuffer_multisample     = "GL_EXT_framebuffer_multisample";
+  public static final String EXT_packed_depth_stencil        = "GL_EXT_packed_depth_stencil";
+  public static final String OES_depth24                     = "GL_OES_depth24";
+  public static final String OES_depth32                     = "GL_OES_depth32";
+  public static final String OES_packed_depth_stencil        = "GL_OES_packed_depth_stencil";
+  public static final String NV_fbo_color_attachments        = "GL_NV_fbo_color_attachments";
+  
+  public static final String ARB_ES2_compatibility           = "GL_ARB_ES2_compatibility";
+  
+  public static final String EXT_abgr                        = "GL_EXT_abgr";
+  public static final String OES_rgb8_rgba8                  = "GL_OES_rgb8_rgba8";
+  public static final String OES_stencil1                    = "GL_OES_stencil1";
+  public static final String OES_stencil4                    = "GL_OES_stencil4";
+  public static final String OES_stencil8                    = "GL_OES_stencil8";
+  public static final String APPLE_float_pixels              = "GL_APPLE_float_pixels";
+  
+  public static final String ARB_texture_non_power_of_two    = "GL_ARB_texture_non_power_of_two";
+  public static final String ARB_texture_rectangle           = "GL_ARB_texture_rectangle";
+  public static final String EXT_texture_rectangle           = "GL_EXT_texture_rectangle";
+  public static final String NV_texture_rectangle            = "GL_NV_texture_rectangle";
+  public static final String EXT_texture_format_BGRA8888     = "GL_EXT_texture_format_BGRA8888";
+  public static final String IMG_texture_format_BGRA8888     = "GL_IMG_texture_format_BGRA8888";
+  public static final String EXT_texture_compression_s3tc    = "GL_EXT_texture_compression_s3tc";
+  public static final String NV_texture_compression_vtc      = "GL_NV_texture_compression_vtc";
+  public static final String SGIS_generate_mipmap            = "GL_SGIS_generate_mipmap";
+  public static final String OES_read_format                 = "GL_OES_read_format";
+  
+  public static final String OES_EGL_image_external          = "GL_OES_EGL_image_external";
+  
+  //
+  // Aliased GLX/WGL/.. extensions
+  //
+  
+  public static final String ARB_pixel_format                = "GL_ARB_pixel_format"; 
+  public static final String ARB_pbuffer                     = "GL_ARB_pbuffer";
+}