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

diff --git a/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java b/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
new file mode 100644
index 000000000..b7ea4f826
--- /dev/null
+++ b/src/jogl/classes/jogamp/opengl/GLFBODrawableImpl.java
@@ -0,0 +1,138 @@
+package jogamp.opengl;
+
+import javax.media.nativewindow.NativeSurface;
+import javax.media.opengl.GL;
+import javax.media.opengl.GL2GL3;
+import javax.media.opengl.GLCapabilitiesImmutable;
+import javax.media.opengl.GLContext;
+import javax.media.opengl.GLException;
+
+import com.jogamp.nativewindow.MutableGraphicsConfiguration;
+import com.jogamp.opengl.FBObject;
+import com.jogamp.opengl.FBObject.Attachment;
+import com.jogamp.opengl.FBObject.TextureAttachment;
+
+/**
+ * Offscreen GLDrawable implementation using framebuffer object (FBO)
+ * as it's offscreen rendering mechanism.
+ * 
+ * @see GLDrawableImpl#contextRealized(GLContext, boolean)
+ * @see GLDrawableImpl#contextMadeCurrent(GLContext, boolean)
+ * @see GLDrawableImpl#getDefaultDrawFramebuffer()
+ * @see GLDrawableImpl#getDefaultReadFramebuffer()
+ */
+public class GLFBODrawableImpl extends GLDrawableImpl {
+    final GLDrawableImpl parent;
+    final FBObject fbo;
+    int texUnit;
+    int samplesTexUnit = 0;
+    int width=0, height=0, samples=0;
+    
+    protected GLFBODrawableImpl(GLDrawableFactoryImpl factory, GLDrawableImpl parent, 
+                                NativeSurface surface, int initialWidth, int initialHeight, int textureUnit) {
+        super(factory, surface, false);
+        this.parent = parent;
+        this.texUnit = textureUnit;
+        final GLCapabilitiesImmutable caps = (GLCapabilitiesImmutable) surface.getGraphicsConfiguration().getChosenCapabilities();
+        this.width = initialWidth;
+        this.height = initialHeight;
+        this.samples = caps.getNumSamples();
+        this.fbo = new FBObject();
+    }
+    
+    @Override
+    protected void contextRealized(GLContext glc, boolean realized) {
+        final GLCapabilitiesImmutable caps = (GLCapabilitiesImmutable) surface.getGraphicsConfiguration().getChosenCapabilities();
+        final GL gl = glc.getGL();
+        if(realized) {                   
+            fbo.reset(gl, width, height, samples);
+            samples = fbo.getNumSamples(); // update, maybe capped
+            if(samples > 0) {
+                fbo.attachColorbuffer(gl, 0, caps.getAlphaBits()>0);
+            } else {
+                fbo.attachTexture2D(gl, 0, caps.getAlphaBits()>0);
+            }
+            if( caps.getStencilBits() > 0 ) {
+                fbo.attachRenderbuffer(gl, Attachment.Type.DEPTH_STENCIL, 24);
+            } else {
+                fbo.attachRenderbuffer(gl, Attachment.Type.DEPTH, 24);
+            }
+        } else if(null != fbo) {
+            fbo.destroy(gl);
+        }
+    }
+    
+    @Override
+    protected void contextMadeCurrent(GLContext glc, boolean current) {
+        final GL gl = glc.getGL();
+        if(current) {
+            fbo.bind(gl);
+        } else {
+            fbo.unbind(gl);
+            gl.glActiveTexture(GL.GL_TEXTURE0 + texUnit);
+            fbo.use(gl, samples > 0 ? fbo.getSamplingSink() : (TextureAttachment) fbo.getColorbuffer(0) );
+            if( samples > 0) {
+                gl.glBindFramebuffer(GL2GL3.GL_READ_FRAMEBUFFER, fbo.getReadFramebuffer());
+            }
+        }
+    }
+    
+    @Override
+    protected int getDefaultDrawFramebuffer() { return fbo.getWriteFramebuffer(); }
+    
+    @Override
+    protected int getDefaultReadFramebuffer() { return fbo.getReadFramebuffer(); }
+    
+    public FBObject getFBObject() { return fbo; }
+    
+    public void setSize(GL gl, int newWidth, int newHeight) throws GLException {
+        width = newWidth;
+        height = newHeight;        
+        fbo.reset(gl, width, height, samples);
+        samples = fbo.getNumSamples(); // update, maybe capped
+    }
+    
+    public void setSamples(GL gl, int newSamples) throws GLException {
+        samples = newSamples;
+        fbo.reset(gl, width, height, samples);
+        samples = fbo.getNumSamples(); // update, maybe capped
+    }
+    
+    
+    @Override
+    public GLContext createContext(GLContext shareWith) {
+        final GLContext ctx = parent.createContext(shareWith);
+        ctx.setGLDrawable(this, false);
+        return ctx;
+    }
+
+    @Override
+    public GLDynamicLookupHelper getGLDynamicLookupHelper() {
+        return parent.getGLDynamicLookupHelper();
+    }
+
+    @Override
+    protected void swapBuffersImpl() {
+    }
+
+    @Override
+    protected void setRealizedImpl() {
+        parent.setRealized(realized);
+        if(realized) {    
+            final MutableGraphicsConfiguration msConfig = (MutableGraphicsConfiguration) surface.getGraphicsConfiguration();
+            final GLCapabilitiesImmutable chosenCaps = (GLCapabilitiesImmutable) msConfig.getChosenCapabilities();
+            final GLCapabilitiesImmutable chosenFBOCaps = GLGraphicsConfigurationUtil.fixOffscreenGLCapabilities(chosenCaps, true /*FBO*/, false /*PBO*/);    
+            msConfig.setChosenCapabilities(chosenFBOCaps);
+        }
+    }
+
+    @Override
+    public int getWidth() {
+        return width;
+    }
+
+    @Override
+    public int getHeight() {
+        return height;
+    }    
+}