Bug 1068, 1096: Unify EGL surface related code in EGLSurface; Add notion of 'Surfaceless Upstream Surface'

Preparation for Bug 1068: GLContext creation and makeCurrent without default framebuffer

- Unify EGL surface related code in EGLSurface
  - EGLWrappedSurface -> EGLSurface,
    which utilizes a more straight forward
    foreign upstream surface (X11, GDI, ..) to EGL mapping.
  This also addresses Bug 1096, i.e. EGL Cleanup.

- Add notion of 'Surfaceless Upstream Surface'
  - Add surfaceless 'fake' upstream surface hooks:
    - EGLUpstreamSurfacelessHook
    - X11UpstreamSurfacelessHook
    Utilizing the ProxySurface option bit 'OPT_UPSTREAM_SURFACELESS'
    signaling usage of 'no surface'.

  - Add GLDrawableFactoryImpl.createSurfacelessImpl(..)

5 files changed, 161 insertions, 6 deletions

diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java b/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
index d21994ea5..a38a48b85 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
@@ -34,11 +34,14 @@ package com.jogamp.nativewindow.egl;
 
 import javax.media.nativewindow.*;
 
+import com.jogamp.common.util.VersionNumber;
+
 /** Encapsulates a graphics device on EGL platforms.
  */
 public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneable {
-    final long[] nativeDisplayID = new long[1];
-    /* final */ EGLDisplayLifecycleCallback eglLifecycleCallback;
+    private final long[] nativeDisplayID = new long[1];
+    private /* final */ EGLDisplayLifecycleCallback eglLifecycleCallback;
+    private VersionNumber eglVersion = VersionNumber.zeroVersion;
 
     /**
      * Hack to allow inject a EGL termination call.
@@ -52,9 +55,11 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
          * Implementation should issue an <code>EGL.eglGetDisplay(nativeDisplayID)</code>
          * inclusive <code>EGL.eglInitialize(eglDisplayHandle, ..)</code> call.
          * @param nativeDisplayID in/out array of size 1, passing the requested nativeVisualID, may return a different revised nativeVisualID handle
+         * @param major out array for EGL major version
+         * @param minor out array for EGL minor version
          * @return the initialized EGL display ID, or <code>0</code> if not successful
          */
-        public long eglGetAndInitDisplay(long[] nativeDisplayID);
+        public long eglGetAndInitDisplay(final long[] nativeDisplayID, final int[] major, final int[] minor);
 
         /**
          * Implementation should issue an <code>EGL.eglTerminate(eglDisplayHandle)</code> call.
@@ -79,6 +84,9 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
         this.eglLifecycleCallback = eglLifecycleCallback;
     }
 
+    /** EGL server version as returned by {@code eglInitialize(..)}. Only valid after {@link #open()}. */
+    public VersionNumber getEGLVersion() { return eglVersion; }
+
     public long getNativeDisplayID() { return nativeDisplayID[0]; }
 
     @Override
@@ -98,11 +106,16 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
             if(DEBUG) {
                 System.err.println(Thread.currentThread().getName() + " - EGLGraphicsDevice.open(): "+this);
             }
-            handle = eglLifecycleCallback.eglGetAndInitDisplay(nativeDisplayID);
+            final int[] major = { 0 };
+            final int[] minor = { 0 };
+            handle = eglLifecycleCallback.eglGetAndInitDisplay(nativeDisplayID, major, minor);
             if(0 == handle) {
+                eglVersion = VersionNumber.zeroVersion;
                 throw new NativeWindowException("EGLGraphicsDevice.open() failed: "+this);
+            } else {
+                eglVersion = new VersionNumber(major[0], minor[0], 0);
+                return true;
             }
-            return true;
         }
         return false;
     }
@@ -142,5 +155,10 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
         eglLifecycleCallback = (EGLDisplayLifecycleCallback) newOwnership;
         return oldOwnership;
     }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName()+"[type "+getType()+", v"+eglVersion+", connection "+getConnection()+", unitID "+getUnitID()+", handle 0x"+Long.toHexString(getHandle())+", owner "+isHandleOwner()+", "+toolkitLock+"]";
+    }
 }
 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
index 7a69b9a40..377dd55cd 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
@@ -65,6 +65,14 @@ public interface ProxySurface extends MutableSurface {
      */
     public static final int OPT_UPSTREAM_WINDOW_INVISIBLE = 1 << 8;
 
+    /**
+     * Implementation specific bitvalue stating the upstream's {@link NativeSurface}'s zero handle is valid.
+     * @see #addUpstreamOptionBits(int)
+     * @see #clearUpstreamOptionBits(int)
+     * @see #getUpstreamOptionBits()
+     */
+    public static final int OPT_UPSTREAM_SURFACELESS = 1 << 9;
+
     /** Allow redefining the AbstractGraphicsConfiguration */
     public void setGraphicsConfiguration(AbstractGraphicsConfiguration cfg);
 
diff --git a/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java b/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
index deb685b51..10d957186 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
@@ -28,6 +28,8 @@
 
 package jogamp.nativewindow;
 
+import java.io.PrintStream;
+
 import javax.media.nativewindow.AbstractGraphicsConfiguration;
 import javax.media.nativewindow.AbstractGraphicsDevice;
 import javax.media.nativewindow.NativeSurface;
@@ -279,6 +281,13 @@ public abstract class ProxySurfaceImpl implements ProxySurface {
             sink.append("WINDOW_INVISIBLE");
             needsOr = true;
         }
+        if( 0 != ( implBitfield & OPT_UPSTREAM_SURFACELESS ) ) {
+            if(needsOr) {
+                sink.append(" | ");
+            }
+            sink.append("SURFACELESS");
+            needsOr = true;
+        }
         sink.append(" ]");
         return sink;
     }
@@ -297,6 +306,34 @@ public abstract class ProxySurfaceImpl implements ProxySurface {
     @Override
     public final void clearUpstreamOptionBits(final int v) { implBitfield &= ~v; }
 
+    public static void dumpHierarchy(final PrintStream out, final ProxySurface s) {
+        out.println("Surface Hierarchy of "+s.getClass().getName());
+        dumpHierarchy(out, s, "");
+        out.println();
+    }
+    private static void dumpHierarchy(final PrintStream out, final NativeSurface s, String indentation) {
+        indentation = indentation + "  ";
+        out.println(indentation+"Surface device "+s.getGraphicsConfiguration().getScreen().getDevice());
+        out.println(indentation+"Surface size "+s.getSurfaceWidth()+"x"+s.getSurfaceHeight()+", handle 0x"+Long.toHexString(s.getSurfaceHandle()));
+        if( s instanceof ProxySurfaceImpl ) {
+            final ProxySurface ps = (ProxySurface)s;
+            out.println(indentation+"Upstream options "+ps.getUpstreamOptionBits(null).toString());
+
+            final UpstreamSurfaceHook psUSH = ps.getUpstreamSurfaceHook();
+            if( null != psUSH ) {
+                out.println(indentation+"Upstream Hook "+psUSH.getClass().getName());
+                final NativeSurface upstreamSurface = psUSH.getUpstreamSurface();
+                indentation = indentation + "  ";
+                if( null != upstreamSurface ) {
+                    out.println(indentation+"Upstream Hook's Surface "+upstreamSurface.getClass().getName());
+                    dumpHierarchy(out, upstreamSurface, indentation);
+                } else {
+                    out.println(indentation+"Upstream Hook's Surface NULL");
+                }
+            }
+        }
+    }
+
     @Override
     public StringBuilder toString(StringBuilder sink) {
         if(null == sink) {
diff --git a/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java b/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java
index 7e61ba6d0..1b3b207f6 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/x11/X11DummyUpstreamSurfaceHook.java
@@ -44,7 +44,7 @@ public class X11DummyUpstreamSurfaceHook extends UpstreamSurfaceHookMutableSize
                 s.setSurfaceHandle(windowHandle);
                 s.addUpstreamOptionBits( ProxySurface.OPT_PROXY_OWNS_UPSTREAM_SURFACE );
             }
-            s.addUpstreamOptionBits(ProxySurface.OPT_UPSTREAM_WINDOW_INVISIBLE);
+            s.addUpstreamOptionBits( ProxySurface.OPT_UPSTREAM_WINDOW_INVISIBLE );
         } finally {
             device.unlock();
         }
diff --git a/src/nativewindow/classes/jogamp/nativewindow/x11/X11UpstreamSurfacelessHook.java b/src/nativewindow/classes/jogamp/nativewindow/x11/X11UpstreamSurfacelessHook.java
new file mode 100644
index 000000000..4461f7691
--- /dev/null
+++ b/src/nativewindow/classes/jogamp/nativewindow/x11/X11UpstreamSurfacelessHook.java
@@ -0,0 +1,92 @@
+/**
+ * Copyright 2014 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 jogamp.nativewindow.x11;
+
+import javax.media.nativewindow.NativeSurface;
+import javax.media.nativewindow.ProxySurface;
+import javax.media.nativewindow.UpstreamSurfaceHook;
+
+import com.jogamp.nativewindow.UpstreamSurfaceHookMutableSize;
+import com.jogamp.nativewindow.x11.X11GraphicsConfiguration;
+import com.jogamp.nativewindow.x11.X11GraphicsDevice;
+import com.jogamp.nativewindow.x11.X11GraphicsScreen;
+
+public class X11UpstreamSurfacelessHook extends UpstreamSurfaceHookMutableSize {
+    /**
+     * @param width the initial width as returned by {@link NativeSurface#getSurfaceWidth()} via {@link UpstreamSurfaceHook#getSurfaceWidth(ProxySurface)},
+     *        not the actual dummy surface width.
+     *        The latter is platform specific and small
+     * @param height the initial height as returned by {@link NativeSurface#getSurfaceHeight()} via {@link UpstreamSurfaceHook#getSurfaceHeight(ProxySurface)},
+     *        not the actual dummy surface height,
+     *        The latter is platform specific and small
+     */
+    public X11UpstreamSurfacelessHook(final int width, final int height) {
+        super(width, height);
+    }
+
+    @Override
+    public final void create(final ProxySurface s) {
+        final X11GraphicsConfiguration cfg = (X11GraphicsConfiguration) s.getGraphicsConfiguration();
+        final X11GraphicsScreen screen = (X11GraphicsScreen) cfg.getScreen();
+        final X11GraphicsDevice device = (X11GraphicsDevice) screen.getDevice();
+        device.lock();
+        try {
+            if(0 == device.getHandle()) {
+                device.open();
+                s.addUpstreamOptionBits( ProxySurface.OPT_PROXY_OWNS_UPSTREAM_DEVICE );
+            }
+            if( 0 != s.getSurfaceHandle() ) {
+                throw new InternalError("Upstream surface not null: "+s);
+            }
+            s.addUpstreamOptionBits( ProxySurface.OPT_UPSTREAM_SURFACELESS |
+                                     ProxySurface.OPT_PROXY_OWNS_UPSTREAM_SURFACE |
+                                     ProxySurface.OPT_UPSTREAM_WINDOW_INVISIBLE );
+        } finally {
+            device.unlock();
+        }
+    }
+
+    @Override
+    public final void destroy(final ProxySurface s) {
+        if( s.containsUpstreamOptionBits( ProxySurface.OPT_PROXY_OWNS_UPSTREAM_SURFACE ) ) {
+            final X11GraphicsDevice device = (X11GraphicsDevice) s.getGraphicsConfiguration().getScreen().getDevice();
+            if( !s.containsUpstreamOptionBits( ProxySurface.OPT_UPSTREAM_SURFACELESS ) ) {
+                throw new InternalError("Owns upstream surface, but not a valid zero surface: "+s);
+            }
+            if( 0 != s.getSurfaceHandle() ) {
+                throw new InternalError("Owns upstream valid zero surface, but non zero surface: "+s);
+            }
+            device.lock();
+            try {
+                s.clearUpstreamOptionBits( ProxySurface.OPT_UPSTREAM_SURFACELESS | ProxySurface.OPT_PROXY_OWNS_UPSTREAM_SURFACE );
+            } finally {
+                device.unlock();
+            }
+        }
+    }
+}