NativeSurface.lockSurface(): Update API doc (+ emphasize LOCK_SURFACE_CHANGED); ProxySurface.lockSurface() +LOCK_SURFACE_CHANGED

2 files changed, 39 insertions, 13 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
index e255dc051..b7829cb6d 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
@@ -50,23 +50,35 @@ public interface NativeSurface extends SurfaceUpdatedListener {
   public static final int LOCK_SUCCESS = 3;
 
   /**
-   * Lock the surface of this native window<P>
-   *
-   * The surface handle, see {@link #lockSurface()}, <br>
-   * shall be valid after a successfull call,
-   * ie return a value other than {@link #LOCK_SURFACE_NOT_READY}.<P>
-   *
+   * Lock the surface of this native window.
+   * <p>
+   * The surface handle shall be valid after a successfull call,
+   * ie return a value other than {@link #LOCK_SURFACE_UNLOCKED} and {@link #LOCK_SURFACE_NOT_READY},
+   * which is 
+   * <pre> 
+   *    boolean ok = lockSurface() > LOCK_SURFACE_NOT_READY; 
+   * </pre> 
+   * </p>
+   * <p>
+   * The caller may need to take care of the result {@link #LOCK_SURFACE_CHANGED},
+   * where the surface handle is valid but has changed.
+   * </p>
+   * <p>
    * This call is blocking until the surface has been locked
-   * or a timeout is reached. The latter will throw a runtime exception. <P>
-   *
-   * This call allows recursion from the same thread.<P>
-   *
+   * or a timeout is reached. The latter will throw a runtime exception.
+   * </p>
+   * <p>
+   * This call allows recursion from the same thread.
+   * </p>
+   * <p>
    * The implementation may want to aquire the 
    * application level {@link com.jogamp.common.util.locks.RecursiveLock}
-   * first before proceeding with a native surface lock. <P>
-   *
+   * first before proceeding with a native surface lock.
+   * </p>
+   * <p>
    * The implementation shall also invoke {@link AbstractGraphicsDevice#lock()}
-   * for the initial lock (recursive count zero).<P>
+   * for the initial lock (recursive count zero).
+   * </p>
    *
    * @return {@link #LOCK_SUCCESS}, {@link #LOCK_SURFACE_CHANGED} or {@link #LOCK_SURFACE_NOT_READY}.
    *
diff --git a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
index 9100beac2..6a36bb130 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
@@ -28,15 +28,20 @@
 
 package javax.media.nativewindow;
 
+
+import jogamp.nativewindow.Debug;
 import jogamp.nativewindow.SurfaceUpdatedHelper;
 
 import com.jogamp.common.util.locks.LockFactory;
 import com.jogamp.common.util.locks.RecursiveLock;
 
 public abstract class ProxySurface implements NativeSurface {
+    public static final boolean DEBUG = Debug.debug("ProxySurface");
+    
     private SurfaceUpdatedHelper surfaceUpdatedHelper = new SurfaceUpdatedHelper();
     private AbstractGraphicsConfiguration config; // control access due to delegation
     protected RecursiveLock surfaceLock = LockFactory.createRecursiveLock();
+    private long surfaceHandle_old;
     protected long displayHandle;
     protected int height;
     protected int scrnIndex;
@@ -46,6 +51,7 @@ public abstract class ProxySurface implements NativeSurface {
         invalidate();
         config = cfg;
         displayHandle=cfg.getNativeGraphicsConfiguration().getScreen().getDevice().getHandle();
+        surfaceHandle_old = 0;
     }
 
     void invalidate() {
@@ -115,6 +121,13 @@ public abstract class ProxySurface implements NativeSurface {
                 adevice.lock();
                 try {
                     res = lockSurfaceImpl();
+                    if(LOCK_SUCCESS == res && surfaceHandle_old != getSurfaceHandle()) {
+                        res = LOCK_SURFACE_CHANGED;
+                        if(DEBUG) {            
+                            System.err.println("ProxySurface: surface change 0x"+Long.toHexString(surfaceHandle_old)+" -> 0x"+Long.toHexString(getSurfaceHandle()));
+                            // Thread.dumpStack();
+                        }
+                    }                    
                 } finally {
                     if (LOCK_SURFACE_NOT_READY >= res) {
                         adevice.unlock();
@@ -131,6 +144,7 @@ public abstract class ProxySurface implements NativeSurface {
 
     public final void unlockSurface() {
         surfaceLock.validateLocked();
+        surfaceHandle_old = getSurfaceHandle();
 
         if (surfaceLock.getHoldCount() == 1) {
             final AbstractGraphicsDevice adevice = getGraphicsConfiguration().getScreen().getDevice();