ProxySurface: Add 'NativeSurface getUpstreamSurface()' ; ProxySurfaceImpl: Don't cache 'displayHandle'

- ProxySurface: Add 'NativeSurface getUpstreamSurface()' allowing querying direct access of a backing surface representing this instance.
  - Use case: EGLWrappedSurface
  - Default impl. returns null

- ProxySurfaceImpl: Don't cache 'displayHandle'
  - getDisplayHandle() is 'final', no more 'shortcut' code allowed
    due to re-association incl. display handle.

  - See commit b738983638703bb721ee4c9820c8ef43e2252e73

1 files changed, 14 insertions, 1 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
index 395fdc818..a83739a1d 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
@@ -65,7 +65,20 @@ public interface ProxySurface extends MutableSurface {
     /** Allow redefining the AbstractGraphicsConfiguration */
     public void setGraphicsConfiguration(AbstractGraphicsConfiguration cfg);    
 
-    /** Returns the set {@link UpstreamSurfaceHook}, or null if not set. */
+    /**
+     * Return the upstream {@link NativeSurface} if used, 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}.
+     * </p>
+     * <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 {@link UpstreamSurfaceHook} if {@link #setUpstreamSurfaceHook(UpstreamSurfaceHook) set}, otherwise <code>null</code>. */
     public UpstreamSurfaceHook getUpstreamSurfaceHook();
     
     /**