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

5 files changed, 81 insertions, 42 deletions

diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/WrappedSurface.java b/src/nativewindow/classes/com/jogamp/nativewindow/WrappedSurface.java
index 04f616daf..b7f6ba45d 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/WrappedSurface.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/WrappedSurface.java
@@ -30,51 +30,49 @@ package com.jogamp.nativewindow;
 
 import javax.media.nativewindow.AbstractGraphicsConfiguration;
 import javax.media.nativewindow.ProxySurface;
-import javax.media.nativewindow.SurfaceChangeable;
 
+public class WrappedSurface extends ProxySurface {
+  protected long surfaceHandle;  
 
-public class WrappedSurface extends ProxySurface implements SurfaceChangeable {
-  protected long surfaceHandle;
-
-  public WrappedSurface(AbstractGraphicsConfiguration cfg) {
-      this(cfg, 0);
-  }
-
-  public WrappedSurface(AbstractGraphicsConfiguration cfg, long handle) {
-    super(cfg);
+  public WrappedSurface(AbstractGraphicsConfiguration cfg, long handle, int initialWidth, int initialHeight, UpstreamSurfaceHook upstream) {
+    super(cfg, initialWidth, initialHeight, upstream);
     surfaceHandle=handle;
   }
 
   @Override
-  protected final void invalidateImpl() {
+  protected void invalidateImpl() {    
     surfaceHandle = 0;
   }
 
   @Override
-  final public long getSurfaceHandle() {
+  public final long getSurfaceHandle() {
     return surfaceHandle;
   }
 
   @Override
-  final public void setSurfaceHandle(long surfaceHandle) {
+  public final void setSurfaceHandle(long surfaceHandle) {
     this.surfaceHandle=surfaceHandle;
   }
-
+  
   @Override
-  final protected int lockSurfaceImpl() {
-      return LOCK_SUCCESS;
+  protected final int lockSurfaceImpl() {
+    return LOCK_SUCCESS;
   }
 
   @Override
-  final protected void unlockSurfaceImpl() {
+  protected final void unlockSurfaceImpl() {
   }
 
   @Override
   public String toString() {
+    final UpstreamSurfaceHook ush = getUpstreamSurfaceHook();
+    final String ush_s = null != ush ? ( ush.getClass().getName() + ": " + ush ) : "nil"; 
+    
     return "WrappedSurface[config " + getPrivateGraphicsConfiguration()+
            ", displayHandle 0x" + Long.toHexString(getDisplayHandle()) +
            ", surfaceHandle 0x" + Long.toHexString(getSurfaceHandle()) +
            ", size " + getWidth() + "x" + getHeight() +
-           ", surfaceLock "+surfaceLock+"]";
+           ", surfaceLock "+surfaceLock+
+           ", upstreamSurfaceHook "+ush_s+"]";
   }
 }
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java b/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
index d161f2f34..389949e90 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
@@ -38,7 +38,7 @@ import javax.media.nativewindow.*;
  */
 public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneable {
     final long nativeDisplayID;
-    final EGLTerminateCallback eglTerminateCallback;
+    final EGLDisplayLifecycleCallback eglLifecycleCallback;
 
     /**
      * Hack to allow inject a EGL termination call.
@@ -47,7 +47,14 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
      * since then it can be utilized directly.
      * </p> 
      */
-    public interface EGLTerminateCallback {
+    public interface EGLDisplayLifecycleCallback {
+        /**
+         * Implementation should issue an <code>EGL.eglGetDisplay(nativeDisplayID)</code>
+         * inclusive <code>EGL.eglInitialize(eglDisplayHandle, ..)</code> call.
+         * @param eglDisplayHandle
+         */
+        public long eglGetAndInitDisplay(long nativeDisplayID);
+        
         /**
          * Implementation should issue an <code>EGL.eglTerminate(eglDisplayHandle)</code> call.
          * @param eglDisplayHandle
@@ -61,28 +68,45 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
      */
     public EGLGraphicsDevice(String connection, int unitID) {
         super(NativeWindowFactory.TYPE_EGL, connection, unitID);
-        this.nativeDisplayID = 0;
-        this.eglTerminateCallback = null;
+        this.nativeDisplayID = 0 ; // EGL.EGL_DEFAULT_DISPLAY
+        this.eglLifecycleCallback = null;
     }
 
-    public EGLGraphicsDevice(long nativeDisplayID, long eglDisplay, String connection, int unitID, EGLTerminateCallback eglTerminateCallback) {
+    public EGLGraphicsDevice(long nativeDisplayID, long eglDisplay, String connection, int unitID, EGLDisplayLifecycleCallback eglLifecycleCallback) {
         super(NativeWindowFactory.TYPE_EGL, connection, unitID, eglDisplay);
         this.nativeDisplayID = nativeDisplayID;
-        this.eglTerminateCallback = eglTerminateCallback;
+        this.eglLifecycleCallback = eglLifecycleCallback;
     }
     
     public long getNativeDisplayID() { return nativeDisplayID; }
     
+    @Override
     public Object clone() {
       return super.clone();
     }
+
+    @Override
+    public boolean open() {
+        if(null != eglLifecycleCallback && 0 == handle) {
+            if(DEBUG) {
+                System.err.println(Thread.currentThread().getName() + " - EGLGraphicsDevice.open(): "+this);
+            }
+            handle = eglLifecycleCallback.eglGetAndInitDisplay(nativeDisplayID);
+            if(0 == handle) {
+                throw new NativeWindowException("EGLGraphicsDevice.open() failed: "+this);
+            }
+            return true;
+        }
+        return false;
+    }
     
+    @Override
     public boolean close() {
-        if(null != eglTerminateCallback) {
+        if(null != eglLifecycleCallback && 0 != handle) {
             if(DEBUG) {
-                System.err.println(Thread.currentThread().getName() + " - eglTerminate: "+this);
+                System.err.println(Thread.currentThread().getName() + " - EGLGraphicsDevice.close(): "+this);
             }
-            eglTerminateCallback.eglTerminate(handle);
+            eglLifecycleCallback.eglTerminate(handle);
         }
         return super.close();
     }
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/swt/SWTAccessor.java b/src/nativewindow/classes/com/jogamp/nativewindow/swt/SWTAccessor.java
index 735d85fb1..0494bb408 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/swt/SWTAccessor.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/swt/SWTAccessor.java
@@ -43,7 +43,6 @@ import com.jogamp.nativewindow.macosx.MacOSXGraphicsDevice;
 import com.jogamp.nativewindow.windows.WindowsGraphicsDevice;
 import com.jogamp.nativewindow.x11.X11GraphicsDevice;
 
-import jogamp.common.awt.AWTEDTExecutor;
 import jogamp.nativewindow.macosx.OSXUtil;
 
 public class SWTAccessor {
@@ -204,8 +203,6 @@ public class SWTAccessor {
         if( null != OS_gtk_class ) {
             long widgedHandle = callStaticMethodL2L(OS_GTK_WIDGET_WINDOW, handle);
             long displayHandle = callStaticMethodL2L(OS_gdk_x11_drawable_get_xdisplay, widgedHandle);
-            // FIXME: May think about creating a private non-shared X11 Display handle, like we use to for AWT
-            //        to avoid locking problems !
             return new X11GraphicsDevice(displayHandle, AbstractGraphicsDevice.DEFAULT_UNIT, false);
         }
         if( NativeWindowFactory.TYPE_WINDOWS == NativeWindowFactory.getNativeWindowType(false) ) {
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsDevice.java b/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsDevice.java
index a02332413..7a98e3c25 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsDevice.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsDevice.java
@@ -33,7 +33,6 @@
 
 package com.jogamp.nativewindow.x11;
 
-import jogamp.nativewindow.Debug;
 import jogamp.nativewindow.x11.X11Lib;
 import jogamp.nativewindow.x11.X11Util;
 
@@ -46,7 +45,7 @@ import javax.media.nativewindow.ToolkitLock;
  */
 
 public class X11GraphicsDevice extends DefaultGraphicsDevice implements Cloneable {
-    final boolean closeDisplay;
+    final boolean handleOwner;
 
     /** Constructs a new X11GraphicsDevice corresponding to the given connection and default
      *  {@link javax.media.nativewindow.ToolkitLock} via {@link NativeWindowFactory#getDefaultToolkitLock(String)}.<br>
@@ -56,7 +55,7 @@ public class X11GraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
      */
     public X11GraphicsDevice(String connection, int unitID) {
         super(NativeWindowFactory.TYPE_X11, connection, unitID);
-        closeDisplay = false;
+        handleOwner = false;
     }
 
     /** Constructs a new X11GraphicsDevice corresponding to the given native display handle and default
@@ -69,7 +68,7 @@ public class X11GraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
         if(0==display) {
             throw new NativeWindowException("null display");
         }
-        closeDisplay = owner;
+        handleOwner = owner;
     }
 
     /**
@@ -82,16 +81,39 @@ public class X11GraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
         if(0==display) {
             throw new NativeWindowException("null display");
         }
-        closeDisplay = owner;
+        handleOwner = owner;
     }
 
+    public int getDefaultVisualID() {
+        // It still could be an AWT hold handle ..
+        final long display = getHandle();
+        final int scrnIdx = X11Lib.DefaultScreen(display);
+        return (int) X11Lib.DefaultVisualID(display, scrnIdx);
+    }
+    
+    @Override
     public Object clone() {
       return super.clone();
     }
 
+    @Override
+    public boolean open() {
+        if(handleOwner && 0 == handle) {
+            if(DEBUG) {
+                System.err.println(Thread.currentThread().getName() + " - X11GraphicsDevice.open(): "+this);
+            }
+            handle = X11Util.openDisplay(connection);
+            if(0 == handle) {
+                throw new NativeWindowException("X11GraphicsDevice.open() failed: "+this);
+            }
+            return true;
+        }
+        return false;
+    }
+        
+    @Override
     public boolean close() {
-        // FIXME: shall we respect the unitID ?
-        if(closeDisplay && 0 != handle) {
+        if(handleOwner && 0 != handle) {
             if(DEBUG) {
                 System.err.println(Thread.currentThread().getName() + " - X11GraphicsDevice.close(): "+this);
             }
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsScreen.java b/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsScreen.java
index 94013ec38..014f4f688 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsScreen.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/x11/X11GraphicsScreen.java
@@ -56,13 +56,11 @@ public class X11GraphicsScreen extends DefaultGraphicsScreen implements Cloneabl
         return new X11GraphicsScreen(new X11GraphicsDevice(display, AbstractGraphicsDevice.DEFAULT_UNIT, owner), screenIdx);
     }
 
-    public long getDefaultVisualID() {
+    public int getVisualID() {
         // It still could be an AWT hold handle ..
-        long display = getDevice().getHandle();
-        int scrnIdx = X11Lib.DefaultScreen(display);
-        return X11Lib.DefaultVisualID(display, scrnIdx);
+        return (int) X11Lib.DefaultVisualID(getDevice().getHandle(), getIndex());
     }
-
+    
     private static int fetchScreen(X11GraphicsDevice device, int screen) {
         // It still could be an AWT hold handle ..
         if(X11Util.XineramaIsEnabled(device.getHandle())) {