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)

4 files changed, 64 insertions, 28 deletions

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) {