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

4 files changed, 49 insertions, 40 deletions

diff --git a/src/nativewindow/classes/jogamp/nativewindow/SurfaceUpdatedHelper.java b/src/nativewindow/classes/jogamp/nativewindow/SurfaceUpdatedHelper.java
index 4877d5c4f..4f68c6945 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/SurfaceUpdatedHelper.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/SurfaceUpdatedHelper.java
@@ -34,8 +34,8 @@ import javax.media.nativewindow.NativeSurface;
 import javax.media.nativewindow.SurfaceUpdatedListener;
 
 public class SurfaceUpdatedHelper implements SurfaceUpdatedListener {
-    private Object surfaceUpdatedListenersLock = new Object();
-    private ArrayList<SurfaceUpdatedListener> surfaceUpdatedListeners = new ArrayList<SurfaceUpdatedListener>();
+    private final Object surfaceUpdatedListenersLock = new Object();
+    private final ArrayList<SurfaceUpdatedListener> surfaceUpdatedListeners = new ArrayList<SurfaceUpdatedListener>();
 
     //
     // Management Utils
diff --git a/src/nativewindow/classes/jogamp/nativewindow/jawt/macosx/MacOSXJAWTWindow.java b/src/nativewindow/classes/jogamp/nativewindow/jawt/macosx/MacOSXJAWTWindow.java
index 42fd08df1..e81d61e0f 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/jawt/macosx/MacOSXJAWTWindow.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/jawt/macosx/MacOSXJAWTWindow.java
@@ -48,7 +48,7 @@ import javax.media.nativewindow.AbstractGraphicsConfiguration;
 import javax.media.nativewindow.Capabilities;
 import javax.media.nativewindow.NativeWindow;
 import javax.media.nativewindow.NativeWindowException;
-import javax.media.nativewindow.SurfaceChangeable;
+import javax.media.nativewindow.MutableSurface;
 import javax.media.nativewindow.util.Point;
 
 import com.jogamp.nativewindow.MutableGraphicsConfiguration;
@@ -62,7 +62,7 @@ import jogamp.nativewindow.jawt.JAWT_DrawingSurfaceInfo;
 import jogamp.nativewindow.jawt.macosx.JAWT_MacOSXDrawingSurfaceInfo;
 import jogamp.nativewindow.macosx.OSXUtil;
 
-public class MacOSXJAWTWindow extends JAWTWindow implements SurfaceChangeable {
+public class MacOSXJAWTWindow extends JAWTWindow implements MutableSurface {
   public MacOSXJAWTWindow(Object comp, AbstractGraphicsConfiguration config) {
     super(comp, config);
     if(DEBUG) {
@@ -103,24 +103,9 @@ public class MacOSXJAWTWindow extends JAWTWindow implements SurfaceChangeable {
       if(DEBUG) {
         System.err.println("MacOSXJAWTWindow.setSurfaceHandle(): 0x"+Long.toHexString(surfaceHandle));
       }
-      sscSet &= 0 != surfaceHandle; // reset ssc flag if NULL surfaceHandle, ie. back to JAWT
       this.surfaceHandle = surfaceHandle;
   }
 
-  public void surfaceSizeChanged(int width, int height) {
-      sscSet = true;
-      sscWidth = width;
-      sscHeight = height;
-  }
-
-  public int getWidth() {
-    return sscSet ? sscWidth : super.getWidth();
-  }
-
-  public int getHeight() {
-    return sscSet ? sscHeight: super.getHeight();
-  }
-
   protected JAWT fetchJAWTImpl() throws NativeWindowException {
        // use offscreen if supported and [ applet or requested ]
       return JAWTUtil.getJAWT(getShallUseOffscreenLayer() || isApplet());
@@ -280,8 +265,6 @@ public class MacOSXJAWTWindow extends JAWTWindow implements SurfaceChangeable {
   private long rootSurfaceLayerHandle = 0; // attached to the JAWT_SurfaceLayer
   
   private long surfaceHandle = 0;
-  private int sscWidth, sscHeight;
-  private boolean sscSet = false;
    
   // Workaround for instance of 4796548
   private boolean firstLock = true;
diff --git a/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java b/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java
index 4d472b01a..99fc9244e 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/macosx/OSXUtil.java
@@ -63,19 +63,15 @@ public class OSXUtil {
       return (Point) GetLocationOnScreen0(windowOrView, src_x, src_y);
     }
     
-    public static long CreateNSView(int x, int y, int width, int height) {
-      return CreateNSView0(x, y, width, height);
-    }
-    public static void DestroyNSView(long nsView) {
-        DestroyNSView0(nsView);
-    }
-
     public static long CreateNSWindow(int x, int y, int width, int height) {
       return CreateNSWindow0(x, y, width, height);
     }
     public static void DestroyNSWindow(long nsWindow) {
         DestroyNSWindow0(nsWindow);
     }
+    public static long GetNSView(long nsWindow) {
+      return GetNSView0(nsWindow);
+    }
     
     public static long CreateCALayer(int x, int y, int width, int height) {
         return CreateCALayer0(x, y, width, height);
@@ -134,10 +130,9 @@ public class OSXUtil {
     
     private static native boolean initIDs0();
     private static native Object GetLocationOnScreen0(long windowOrView, int src_x, int src_y);
-    private static native long CreateNSView0(int x, int y, int width, int height);
-    private static native void DestroyNSView0(long nsView);
     private static native long CreateNSWindow0(int x, int y, int width, int height);
     private static native void DestroyNSWindow0(long nsWindow);
+    private static native long GetNSView0(long nsWindow);
     private static native long CreateCALayer0(int x, int y, int width, int height);
     private static native void AddCASublayer0(long rootCALayer, long subCALayer);
     private static native void RemoveCASublayer0(long rootCALayer, long subCALayer);
diff --git a/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java b/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java
index c24f64b32..e368aa6a1 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/windows/GDISurface.java
@@ -31,6 +31,7 @@ package jogamp.nativewindow.windows;
 import javax.media.nativewindow.AbstractGraphicsConfiguration;
 import javax.media.nativewindow.NativeWindowException;
 import javax.media.nativewindow.ProxySurface;
+import javax.media.nativewindow.ProxySurface.UpstreamSurfaceHook;
 
 
 /**
@@ -43,22 +44,49 @@ public class GDISurface extends ProxySurface {
   protected long windowHandle;
   protected long surfaceHandle;
 
-  public GDISurface(AbstractGraphicsConfiguration cfg, long windowHandle) {
-    super(cfg);
-    if(0 == windowHandle) {
-        throw new NativeWindowException("Error hwnd 0, werr: "+GDI.GetLastError());
-    }
+  public GDISurface(AbstractGraphicsConfiguration cfg, long windowHandle, int initialWidth, int initialHeight, UpstreamSurfaceHook upstream) {
+    super(cfg, initialWidth, initialHeight, upstream);
     this.windowHandle=windowHandle;
+    this.surfaceHandle=0;
   }
 
   @Override
-  protected final void invalidateImpl() {
-    windowHandle=0;
-    surfaceHandle=0;
+  protected void invalidateImpl() {    
+    if(0 != surfaceHandle) {
+        throw new NativeWindowException("didn't release surface Handle: "+this);
+    }
+    windowHandle = 0;
+    // surfaceHandle = 0;
+  }
+  
+  /**
+   * {@inheritDoc}
+   * <p>
+   * Actually the window handle (HWND), since the surfaceHandle (HDC) is derived 
+   * from it at {@link #lockSurface()}.
+   * </p> 
+   */
+  @Override
+  public final void setSurfaceHandle(long surfaceHandle) {
+      this.windowHandle = surfaceHandle;
+  }
+
+  /**
+   * Sets the window handle (HWND). 
+   */
+  public final void setWindowHandle(long windowHandle) {
+      this.windowHandle = windowHandle;
+  }
+
+  public final long getWindowHandle() {
+      return windowHandle;
   }
 
   @Override
   final protected int lockSurfaceImpl() {
+    if (0 == windowHandle) {
+        throw new NativeWindowException("null window handle: "+this);
+    }
     if (0 != surfaceHandle) {
         throw new InternalError("surface not released");
     }
@@ -89,12 +117,15 @@ public class GDISurface extends ProxySurface {
 
   @Override
   final public String toString() {
-    return "GDISurface[config "+getPrivateGraphicsConfiguration()+
+    final UpstreamSurfaceHook ush = getUpstreamSurfaceHook();
+    final String ush_s = null != ush ? ( ush.getClass().getName() + ": " + ush ) : "nil";       
+    return getClass().getSimpleName()+"[config "+getPrivateGraphicsConfiguration()+
                 ", displayHandle 0x"+Long.toHexString(getDisplayHandle())+
                 ", windowHandle 0x"+Long.toHexString(windowHandle)+
                 ", surfaceHandle 0x"+Long.toHexString(getSurfaceHandle())+
                 ", size "+getWidth()+"x"+getHeight()+
-                ", surfaceLock "+surfaceLock+"]";
+                ", surfaceLock "+surfaceLock+
+                ", upstreamSurfaceHook "+ush_s+"]";
   }
 
 }