UpstreamSurfaceHook: Add 'NativeSurface getUpstreamSurface()' (from EGLUpstreamSurfaceHook) to generalize ProxySurfaceImpl.getUpstreamSurface()

8 files changed, 61 insertions, 14 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
index ec0935c18..fbe5fedc4 100644
--- a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
+++ b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
@@ -468,6 +468,17 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
        public String toString() {
            return "SWTCanvasUpstreamSurfaceHook[upstream: "+GLCanvas.this.toString()+", "+clientArea.width+"x"+clientArea.height+"]";
        }
+
+       /**
+        * {@inheritDoc}
+        * <p>
+        * Returns <code>null</code>.
+        * </p>
+        */
+       @Override
+       public final NativeSurface getUpstreamSurface() {
+           return null;
+       }
    };
 
    protected final void updateSizeCheck() {
diff --git a/src/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java b/src/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java
index d0dc79437..052872122 100644
--- a/src/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java
+++ b/src/jogl/classes/jogamp/opengl/egl/EGLUpstreamSurfaceHook.java
@@ -17,7 +17,7 @@ import com.jogamp.nativewindow.egl.EGLGraphicsDevice;
  * <pre>
  * EGLWrappedSurface [ is_a -> WrappedSurface -> ProxySurfaceImpl -> ProxySurface -> MutableSurface -> NativeSurface] has_a
  *     EGLUpstreamSurfaceHook [ is_a -> UpstreamSurfaceHook.MutableSize -> UpstreamSurfaceHook ] has_a
- *        NativeSurface (i.e. native X11 surface)
+ *        NativeSurface (e.g. native X11 surface)
  * </pre>
  */
 public class EGLUpstreamSurfaceHook implements UpstreamSurfaceHook.MutableSize {
@@ -40,10 +40,17 @@ public class EGLUpstreamSurfaceHook implements UpstreamSurfaceHook.MutableSize {
         }
     }
 
-    public final NativeSurface getUpstreamSurface() { return upstreamSurface; }
-
     static String getThreadName() { return Thread.currentThread().getName(); }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns the actual upstream {@link NativeSurface}, e.g. native X11 surface.
+     * </p>
+     */
+    @Override
+    public final NativeSurface getUpstreamSurface() { return upstreamSurface; }
+
     @Override
     public final void setSurfaceSize(int width, int height) {
         if(null != upstreamSurfaceHookMutableSize) {
diff --git a/src/jogl/classes/jogamp/opengl/egl/EGLWrappedSurface.java b/src/jogl/classes/jogamp/opengl/egl/EGLWrappedSurface.java
index e6d43d957..4a5113b51 100644
--- a/src/jogl/classes/jogamp/opengl/egl/EGLWrappedSurface.java
+++ b/src/jogl/classes/jogamp/opengl/egl/EGLWrappedSurface.java
@@ -27,8 +27,4 @@ public class EGLWrappedSurface extends WrappedSurface {
         }
     }
 
-    @Override
-    public final NativeSurface getUpstreamSurface() {
-        return ((EGLUpstreamSurfaceHook)super.getUpstreamSurfaceHook()).getUpstreamSurface();
-    }
 }
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java b/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java
index 9a462105f..568ac20fa 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/DelegatedUpstreamSurfaceHookWithSurfaceSize.java
@@ -10,7 +10,7 @@ public class DelegatedUpstreamSurfaceHookWithSurfaceSize implements UpstreamSurf
 
     /**
      * @param upstream optional upstream UpstreamSurfaceHook used for {@link #create(ProxySurface)} and {@link #destroy(ProxySurface)}.
-     * @param surface mandatory {@link NativeSurface} used for {@link #getSurfaceWidth(ProxySurface)} and {@link #getSurfaceHeight(ProxySurface)}
+     * @param surface mandatory {@link NativeSurface} used for {@link #getSurfaceWidth(ProxySurface)} and {@link #getSurfaceHeight(ProxySurface)}, not used for {@link #getUpstreamSurface()}.
      */
     public DelegatedUpstreamSurfaceHookWithSurfaceSize(UpstreamSurfaceHook upstream, NativeSurface surface) {
         this.upstream = upstream;
@@ -20,6 +20,17 @@ public class DelegatedUpstreamSurfaceHookWithSurfaceSize implements UpstreamSurf
         }
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns <code>null</code>.
+     * </p>
+     */
+    @Override
+    public final NativeSurface getUpstreamSurface() {
+        return null;
+    }
+
     @Override
     public final void create(ProxySurface s) {
         if(null != upstream) {
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java b/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java
index 25e2bbd49..eca64db37 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/UpstreamSurfaceHookMutableSize.java
@@ -1,5 +1,6 @@
 package com.jogamp.nativewindow;
 
+import javax.media.nativewindow.NativeSurface;
 import javax.media.nativewindow.ProxySurface;
 import javax.media.nativewindow.UpstreamSurfaceHook;
 
@@ -41,5 +42,16 @@ public class UpstreamSurfaceHookMutableSize implements UpstreamSurfaceHook.Mutab
         return getClass().getSimpleName()+"[pixel "+ pixWidth + "x" + pixHeight + "]";
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Returns <code>null</code>.
+     * </p>
+     */
+    @Override
+    public final NativeSurface getUpstreamSurface() {
+        return null;
+    }
+
 }
 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
index 0af2bdaf9..7a69b9a40 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
@@ -69,10 +69,10 @@ public interface ProxySurface extends MutableSurface {
     public void setGraphicsConfiguration(AbstractGraphicsConfiguration cfg);
 
     /**
-     * Return the upstream {@link NativeSurface} if used, otherwise <code>null</code>.
+     * Returns the optional upstream {@link NativeSurface} if used by implementation, otherwise <code>null</code>.
      * <p>
-     * An upstream {@link NativeSurface} may backup this {@link ProxySurface} instance's representation,
-     * e.g. via a {@link #setUpstreamSurfaceHook(UpstreamSurfaceHook) set} {@link UpstreamSurfaceHook}.
+     * The upstream {@link NativeSurface} is retrieved via {@link #getUpstreamSurfaceHook() the UpstreamSurfaceHook},
+     * i.e.  {@link UpstreamSurfaceHook#getUpstreamSurface()}.
      * </p>
      * <p>
      * One example is the JOGL EGLWrappedSurface, which might be backed up by a
@@ -85,7 +85,7 @@ public interface ProxySurface extends MutableSurface {
     public UpstreamSurfaceHook getUpstreamSurfaceHook();
 
     /**
-     * Sets the {@link UpstreamSurfaceHook} and returns the previous value.
+     * Overrides the {@link UpstreamSurfaceHook}.
      */
     public void setUpstreamSurfaceHook(UpstreamSurfaceHook hook);
 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
index 1a13b050a..572649875 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
@@ -38,6 +38,15 @@ public interface UpstreamSurfaceHook {
     /** called within {@link ProxySurface#destroyNotify()} within lock, before clearing fields. */
     public void destroy(ProxySurface s);
 
+    /**
+     * Returns the optional upstream {@link NativeSurface} if used by implementation, otherwise <code>null</code>.
+     * <p>
+     * One example is the JOGL EGLWrappedSurface, which might be backed up by a
+     * native platform NativeSurface (X11, WGL, CGL, ..).
+     * </p>
+     */
+    public NativeSurface getUpstreamSurface();
+
     /** Returns the width of the upstream surface in pixels, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */
     public int getSurfaceWidth(ProxySurface s);
     /** Returns the height of the upstream surface in pixels, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */
diff --git a/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java b/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
index 969e012a6..53daa2acd 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/ProxySurfaceImpl.java
@@ -36,7 +36,6 @@ import javax.media.nativewindow.ProxySurface;
 import javax.media.nativewindow.SurfaceUpdatedListener;
 import javax.media.nativewindow.UpstreamSurfaceHook;
 
-
 import com.jogamp.common.util.locks.LockFactory;
 import com.jogamp.common.util.locks.RecursiveLock;
 
@@ -74,7 +73,9 @@ public abstract class ProxySurfaceImpl implements ProxySurface {
     }
 
     @Override
-    public NativeSurface getUpstreamSurface() { return null; }
+    public final NativeSurface getUpstreamSurface() {
+        return upstream.getUpstreamSurface();
+    }
 
     @Override
     public final UpstreamSurfaceHook getUpstreamSurfaceHook() { return upstream; }