GLDrawable: Refine API doc; GLDrawableImpl: Balance createHandle()/destroyHandle(); Handle LOCK_SURFACE_CHANGED in lockSurface() ; GLContextImpl.makeCurrent(): Fix drawable handle validation.

GLDrawable: Refine API doc (realized/handle)
  - Lifecycle of the drawable handle was not clear
  - Ephasizing handle's dependency on NativeSurface's lock state and drawable's realization

GLDrawableImpl: Balance createHandle()/destroyHandle()
  - updateHandle() -> createHandle()
  - ensure both are balance, see below

GLDrawableImpl: Handle LOCK_SURFACE_CHANGED in GLDrawableImpl's lockSurface()
  - call destroyHandle() and createHandle()

GLContextImpl.makeCurrent(): Validate drawable handle if realized only.
  - it is valid to have an invalid drawable handle if not realized (see above)

5 files changed, 107 insertions, 55 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java
index 95c314a48..65c8b2ea5 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java
@@ -65,29 +65,31 @@ public interface GLDrawable {
   public GLContext createContext(GLContext shareWith);
 
   /**
-   * Indicates to on-screen GLDrawable implementations whether the
-   * underlying window has been created and can be drawn into. End
-   * users do not need to call this method; it is not necessary to
-   * call <code>setRealized</code> on a GLCanvas, a GLJPanel, or a
-   * GLPbuffer, as these perform the appropriate calls on their
-   * underlying GLDrawables internally.
-   *
-   * <P>
-   *
+   * Indicates to GLDrawable implementations whether the
+   * underlying {@link NativeSurface surface} has been created and can be drawn into.
+   * <p>
+   * If realized, the {@link #getHandle() drawable handle} may become
+   * valid while it's {@link NativeSurface surface} is being {@link NativeSurface#lockSurface() locked}.
+   * </p>
+   * <p>
+   * End users do not need to call this method; it is not necessary to
+   * call <code>setRealized</code> on a {@link GLAutoDrawable} 
+   * as these perform the appropriate calls on their underlying GLDrawables internally.
+   * </p>
+   * <p>
    * Developers implementing new OpenGL components for various window
    * toolkits need to call this method against GLDrawables obtained
-   * from the GLDrawableFactory via the {@link
-   * GLDrawableFactory#getGLDrawable
-   * GLDrawableFactory.getGLDrawable()} method. It must typically be
+   * from the GLDrawableFactory via the 
+   * {@link GLDrawableFactory#createGLDrawable(NativeSurface)} method.
+   * It must typically be
    * called with an argument of <code>true</code> when the component
    * associated with the GLDrawable is realized and with an argument
    * of <code>false</code> just before the component is unrealized.
    * For the AWT, this means calling <code>setRealized(true)</code> in
    * the <code>addNotify</code> method and with an argument of
    * <code>false</code> in the <code>removeNotify</code> method.
-   *
-   * <P>
-   *
+   * </p>
+   * <p>   
    * <code>GLDrawable</code> implementations should handle multiple
    * cycles of <code>setRealized(true)</code> /
    * <code>setRealized(false)</code> calls. Most, if not all, Java
@@ -101,12 +103,11 @@ public interface GLDrawable {
    * <code>GLDrawable</code> to re-initialize and destroy any
    * associated resources as the component becomes realized and
    * unrealized, respectively.
-   *
-   * <P>
-   *
+   * </p>
+   * <p>   
    * With an argument of <code>true</code>,
    * the minimum implementation shall call
-   * {@link NativeSurface#lockSurface() NativeSurface's lockSurface()} and if successfull:
+   * {@link NativeSurface#lockSurface() NativeSurface's lockSurface()} and if successful:
    * <ul>
    *    <li> Update the {@link GLCapabilities}, which are associated with
    *         the attached {@link NativeSurface}'s {@link AbstractGraphicsConfiguration}.</li>
@@ -115,14 +116,17 @@ public interface GLDrawable {
    * This is important since {@link NativeSurface#lockSurface() NativeSurface's lockSurface()}
    * ensures resolving the window/surface handles, and the drawable's {@link GLCapabilities}
    * might have changed.
-   *
-   * <P>
-   *
+   * </p>
+   * <p>   
    * Calling this method has no other effects. For example, if
    * <code>removeNotify</code> is called on a Canvas implementation
    * for which a GLDrawable has been created, it is also necessary to
    * destroy all OpenGL contexts associated with that GLDrawable. This
    * is not done automatically by the implementation.
+   * </p>
+   * @see #isRealized()
+   * @see #getHandle()
+   * @see NativeSurface#lockSurface()
    */
   public void setRealized(boolean realized);
 
@@ -131,6 +135,7 @@ public interface GLDrawable {
    * <p>
    * A drawable can be realized and unrealized via {@link #setRealized(boolean)}.
    * </p>
+   * @see #setRealized(boolean)
    */
   public boolean isRealized();
 
@@ -172,11 +177,22 @@ public interface GLDrawable {
   public NativeSurface getNativeSurface();
 
   /**
-   * This is the GL/Windowing drawable handle.<br>
-   * It is usually the {@link javax.media.nativewindow.NativeSurface#getSurfaceHandle()},
-   * ie the native surface handle of the underlying windowing toolkit.<br>
-   * However, on X11/GLX this reflects a GLXDrawable, which represents a GLXWindow, GLXPixmap, or GLXPbuffer.<br>
-   * On EGL, this represents the EGLSurface.<br>
+   * Returns the GL drawable handle, 
+   * guaranteed to be valid after {@link #setRealized(boolean) realization}
+   * <i>and</i> while it's {@link NativeSurface surface} is being {@link NativeSurface#lockSurface() locked}.
+   * <p>
+   * It is usually identical to the underlying windowing toolkit {@link NativeSurface surface}'s 
+   * {@link javax.media.nativewindow.NativeSurface#getSurfaceHandle() handle}
+   * or an intermediate layer to suite GL, e.g. an EGL surface.
+   * </p>
+   * <p>
+   * On EGL it is represented by the EGLSurface.<br>
+   * On X11/GLX it is represented by either the Window XID, GLXPixmap, or GLXPbuffer.<br>
+   * On Windows it is represented by the HDC, which may change with each {@link #lockSurface()}.<br>
+   * </p>
+   * @see #setRealized(boolean)
+   * @see NativeSurface#lockSurface()
+   * @see NativeSurface#unlockSurface()
    */
   public long getHandle();
 
diff --git a/src/jogl/classes/jogamp/opengl/GLContextImpl.java b/src/jogl/classes/jogamp/opengl/GLContextImpl.java
index 64ade3eff..90f5a9907 100644
--- a/src/jogl/classes/jogamp/opengl/GLContextImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLContextImpl.java
@@ -258,7 +258,7 @@ public abstract class GLContextImpl extends GLContext {
     if(DEBUG) {
         String sgl1 = (null!=this.gl)?this.gl.getClass().getSimpleName()+", "+this.gl.toString():"<null>";
         String sgl2 = (null!=gl)?gl.getClass().getSimpleName()+", "+gl.toString():"<null>";
-        Exception e = new Exception("Info: setGL (OpenGL "+getGLVersion()+"): "+Thread.currentThread().getName()+", "+sgl1+" -> "+sgl2);
+        Exception e = new Exception("Info: setGL (OpenGL "+getGLVersion()+"): "+getThreadName()+", "+sgl1+" -> "+sgl2);
         e.printStackTrace();
     }
     this.gl = gl;
@@ -495,14 +495,10 @@ public abstract class GLContextImpl extends GLContext {
     boolean unlockContextAndSurface = true; // Must be cleared if successful, otherwise finally block will release context and surface!
     int res = CONTEXT_NOT_CURRENT;
     try {
-        if (0 == drawable.getHandle()) {
-            throw new GLException("drawable has invalid handle: "+drawable);
-        }
-        if (NativeSurface.LOCK_SURFACE_CHANGED == lockRes) {
-            drawable.updateHandle();
-        }
-
         if ( drawable.isRealized() ) {
+            if ( 0 == drawable.getHandle() ) {
+                throw new GLException("drawable has invalid handle: "+drawable);
+            }
             lock.lock();
             try {
                 // One context can only be current by one thread,
diff --git a/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java b/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java
index d0c1461a9..a2b99c7da 100644
--- a/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java
@@ -79,14 +79,11 @@ public abstract class GLDrawableImpl implements GLDrawable {
     if( !realized ) { // volatile OK (locked below)
         return; // destroyed already
     }
-    int lockRes = lockSurface(); // it's recursive, so it's ok within [makeCurrent .. release]
+    final int lockRes = lockSurface(); // it's recursive, so it's ok within [makeCurrent .. release]
     if (NativeSurface.LOCK_SURFACE_NOT_READY == lockRes) {
         return;
     }
     try {
-        if (NativeSurface.LOCK_SURFACE_CHANGED == lockRes) {
-            updateHandle();
-        }
         if( realized ) { // volatile OK
             final GLCapabilitiesImmutable caps = (GLCapabilitiesImmutable)surface.getGraphicsConfiguration().getChosenCapabilities();
             if ( caps.getDoubleBuffered() ) {
@@ -145,11 +142,21 @@ public abstract class GLDrawableImpl implements GLDrawable {
     return surface;
   }
 
-  /** called with locked surface @ setRealized(false) */
+  /** 
+   * called with locked surface @ setRealized(false) or @ lockSurface(..) when surface changed
+   * <p>
+   * Must be paired w/ {@link #createHandle()}.
+   * </p> 
+   */
   protected void destroyHandle() {}
 
-  /** called with locked surface @ setRealized(true) or @ lockSurface(..) when surface changed */
-  protected void updateHandle() {}
+  /** 
+   * called with locked surface @ setRealized(true) or @ lockSurface(..) when surface changed
+   * <p>
+   * Must be paired w/ {@link #destroyHandle()}.
+   * </p> 
+   */
+  protected void createHandle() {}
 
   @Override
   public long getHandle() {
@@ -174,7 +181,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
             if(isProxySurface) {
                 ((ProxySurface)surface).createNotify();
             }
-            if(NativeSurface.LOCK_SURFACE_NOT_READY >= lockSurface()) {
+            if(NativeSurface.LOCK_SURFACE_NOT_READY >= surface.lockSurface()) {
                 throw new GLException("GLDrawableImpl.setRealized(true): Surface not ready (lockSurface)");
             }
         } else {
@@ -185,7 +192,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
                 realized = realizedArg;
                 if(realizedArg) {
                     setRealizedImpl();
-                    updateHandle();
+                    createHandle();
                 } else {
                     destroyHandle();
                     setRealizedImpl();
@@ -193,7 +200,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
             }
         } finally {
             if(realizedArg) {
-                unlockSurface();
+                surface.unlockSurface();
             } else {
                 aDevice.unlock();
                 if(isProxySurface) {
@@ -276,12 +283,47 @@ public abstract class GLDrawableImpl implements GLDrawable {
     return surface.getHeight();
   }
 
-  /** @see NativeSurface#lockSurface() */
+  /** 
+   * {@link NativeSurface#lockSurface() Locks} the underlying windowing toolkit's {@link NativeSurface surface}.
+   * <p>
+   * <i>If</i> drawable is {@link #setRealized(boolean) realized},
+   * the {@link #getHandle() drawable handle} is valid after successfully {@link NativeSurface#lockSurface() locking} 
+   * it's {@link NativeSurface surface} until being {@link #unlockSurface() unlocked}.
+   * </p>
+   * <p>
+   * In case the {@link NativeSurface surface} has changed as indicated by it's 
+   * {@link NativeSurface#lockSurface() lock} result {@link NativeSurface#LOCK_SURFACE_CHANGED},
+   * the implementation is required to update this information as needed within it's implementation. 
+   * </p>
+   * 
+   * @see NativeSurface#lockSurface()
+   * @see #getHandle()
+   */
   public final int lockSurface() throws GLException {
-    return surface.lockSurface();
+    final int lockRes = surface.lockSurface();
+    if ( NativeSurface.LOCK_SURFACE_CHANGED == lockRes && realized ) {
+        // Update the drawable handle, in case the surface handle has changed.
+        final long _handle1 = getHandle();
+        destroyHandle();
+        createHandle();
+        final long _handle2 = getHandle();        
+        if(DEBUG) {
+            if( _handle1 != _handle2) {
+                System.err.println(getThreadName() + ": Drawable handle changed: "+toHexString(_handle1)+" -> "+toHexString(_handle2));
+            }
+        }
+    }
+    return lockRes;
+    
   }
 
-  /** @see NativeSurface#unlockSurface() */
+  /** 
+   * {@link NativeSurface#unlockSurface() Unlocks} the underlying windowing toolkit {@link NativeSurface surface},
+   * which may render the {@link #getHandle() drawable handle} invalid.
+   * 
+   * @see NativeSurface#unlockSurface() 
+   * @see #getHandle()
+   */
   public final void unlockSurface() {
     surface.unlockSurface();
   }
@@ -294,9 +336,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
                 ",\n\tSurface   "+getNativeSurface()+"]";
   }
 
-  protected static String getThreadName() {
-    return Thread.currentThread().getName();
-  }
+  protected static String getThreadName() { return Thread.currentThread().getName(); }
 
   protected GLDrawableFactory factory;
   protected NativeSurface surface;
diff --git a/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java b/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java
index 167eebf3a..2edf26145 100644
--- a/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java
+++ b/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java
@@ -100,10 +100,10 @@ public abstract class EGLDrawable extends GLDrawableImpl {
     }
 
     @Override
-    protected final void updateHandle() {
+    protected final void createHandle() {
         final EGLWrappedSurface eglws = (EGLWrappedSurface) surface;
         if(DEBUG) {
-            System.err.println(getThreadName() + ": updateHandle of "+eglws);
+            System.err.println(getThreadName() + ": createHandle of "+eglws);
         }        
         if( eglws.containsUpstreamOptionBits( ProxySurface.OPT_PROXY_OWNS_UPSTREAM_SURFACE ) ) {
             if( EGL.EGL_NO_SURFACE != eglws.getSurfaceHandle() ) {
diff --git a/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java b/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java
index c15065cfa..6b239a43d 100644
--- a/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java
+++ b/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java
@@ -56,7 +56,7 @@ public class X11OnscreenGLXDrawable extends X11GLXDrawable {
     glXWindow=0;
     useGLXWindow=false;
     if(realized) {
-        updateHandle();
+        createHandle();
     }
   }
 
@@ -82,7 +82,7 @@ public class X11OnscreenGLXDrawable extends X11GLXDrawable {
   }
 
   @Override
-  protected final void updateHandle() {
+  protected final void createHandle() {
     if(USE_GLXWINDOW) {
         X11GLXGraphicsConfiguration config = (X11GLXGraphicsConfiguration)getNativeSurface().getGraphicsConfiguration();
         if(config.getFBConfig()>=0) {