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

2 files changed, 13 insertions, 4 deletions

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. */