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

5 files changed, 40 insertions, 7 deletions

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; }