Seamless Integration of an FBObject based GLFBODrawable as GLOffscreenAutoDrawable.FBO and as an OffscreenLayerSurface's drawable (OSX) - Fix Bugs 569 and 599

Summary:
=========
The new FBObject based GLFBODrawable implementation allows the seamless utilization of
FBO offscreen rendering in single buffer, double buffer and MSAA mode.

The GLFBODrawable uses a parent drawable based on a
dummy surface to allow a GLOffscreenAutoDrawable.FBO creation
or a mutable surface supporting an existing offscreen layer surface (OSX CALayer).

Offscreen GLDrawable's and GLOffscreenAutoDrawable's can be selected via the
GLCapabilities. If simply !onscreen is selected in the caps instance w/o enabling FBO, PBuffer or Bitmap,
the factory will automatically choose regarding availability:
   FBO > PBuffer > Bitmap

Double buffering is supported in MSAA more (intrinsic) and explicit in non MSAA.
It is preferred when delivering resources (texture id's or framebuffer names)
to a shared GLContext.
This is demonstrated in (emulates our OSX CALayer implementation):
  TestFBOOffThreadSharedContextMix2DemosES2NEWT,
  TestFBOOnThreadSharedContext1DemoES2NEWT
and with the OSX JAWT OffscreenLayerSurface itself. FBO is the preferred choice.

+++

Offscreen drawables can be resized while maintaining a bound GLContext (e.g. w/ GLAutoDrawable).
Previously both, drawable and context, needed to be destroyed and recreated at offscreen resize.
Common implementation in GLDrawableHelper is used in the implementations
(NEWT's GLWindow, AWT GLCanvas, SWT GLCanvas).

+++

Tested:
=======

Manually run all unit tests on:
  - Linux x86_64 NVidia/AMD/Mesa3d(ES)
  - OSX x86_64 NVidia
  - Windows x86_64 NVidia
  - Android arm Mali-400/Tegra-2

No regressions.

Disclaimer:
===========
This feature is committed almost in one patch.

Both previous commits were introducing / fixing the capabilities behavior:
 90d45928186f2be99999461cfe45f76a783cc961
 9036376b7806a5fc61590bf49404eb71830de92f

I have to appologize for the huge size and impact (files and platforms) of this commit
however, I could not find a better way to inject this feature in one sane piece.

NativeWindow Details:
=====================

Complete decoupling of platform impl. detail of surfaces
implementing ProxySurface. Used to generalize dummy surfaces and EGL surfaces
on top of a native platform surface.
  - ProxySurface.UpstreamSurfaceHook -> UpstreamSurfaceHook
  - abstract class ProxySurface -> interface ProxySurface + ProxySurfaceImpl
  - Misc. implementations

JOGL Details:
=====================

FBOObject: API Change / Simplification & Usability
  - Removed reference counter to remove complexity, allow user to choose.
  - Add 'dispose' flag for detachColorbuffer(..), allowing to keep attachment alive
  - Fix equals operation of Attachment
  - Check pre-exising GL errors
  - Interface Colobuffer gets lifecycle methods
  - Add static factory methods to create Attachments w/o FBObject instance
  - Reset:
    - Clip min size to 1
    - Keep alive samplingSink, i.e. don't issue resetMSAATexture2DSink(..).
      It gets called at syncFramebuffer()/use(..) later on before actual usage.
      This allows the consumer to utilize the GL_FRONT buffer until (e.g.) swap.
  - misc bugfixes

GLOffscreenAutoDrawable: API Change
  - Reloc and interfacing
  - class com.jogamp.opengl.OffscreenAutoDrawable -> javax.media.opengl.*
    interfaces GLOffscreenAutoDrawable extends GLAutoDrawable
               GLOffscreenAutoDrawable.FBO extends GLOffscreenAutoDrawable, GLFBODrawable
  - Added general implementation and FBO specialization
  - Replacing GLPBuffer (deprecated) .. usable for any offscreen GLDrawable via factory

GLAutoDrawable:
  - Add 'GLDrawable getDelegatedDrawable()'
  - Refine documentation of setContext(..), remove disclaimer and fixme tags

GLDrawableFactory:
  - Refine API doc and it's selection mechanism for offscreen.
  - Add createOffscreenDrawable(..)
  - Add createOffscreenAutoDrawable(..)
  - Add canCreateFBO(..)
  - Mark createGLPbuffer(..) deprectated

Mark GLPBuffer deprecated

New: GLFBODrawable extends GLDrawable

GLCanvas (AWT and SWT): Add offscreen resize support w/o GLContext recreation

GLAutoDrawableBase .. GLWindow:
  - Add offscreen resize support w/o GLContext recreation
  - Remove double swapBuffer call
  -

GLBase/GLContext:
  - Add:
    - boolean hasBasicFBOSupport()
    - boolean hasFullFBOSupport()
    - int getMaxRenderbufferSamples()
    - boolean isTextureFormatBGRA8888Available()

GLContext: Fix version detection and hasGLSL()
  - Version detection in setGLFunctionAvailability(..)
    - Query GL_VERSION ASAP and parse it and compare w/ given major/minor
    - Use parsed version if valid and lower than given _or_ given is invalid.
    - Use validated version for caching (procaddr, ..), version number, etc.

  - Fix hasGLSL()
    Since 'isGL2ES2()' is true if 'isGL2()'
    and the latter simply alows GL 1.*, we confine the result to a GL >= 2.0
    on desktops. FIXME: May consider GL 1.5 w/ extensions.
    -  return isGL2ES2();
    +      return isGLES2() ||
    +             isGL3() ||
    +             isGL2() && ctxMajorVersion>1 ;

GLDrawableImpl:
  - Add 'associateContext(GLContext, boolean)' allowing impl.
    to have a (weak) reference list of bound context.
    This is was pulled up from the OSX specific drawable impl.
  - swapBuffersImpl() -> swapBuffersImpl(boolean doubleBuffered)
    and call it regardless of single buffering.
    This is required to propagate this event to impl. properly,
    i.e. FBODrawable requires a swap notification.
  - Clarify 'contextMadeCurrent(..)' protocol

GLDrawableHelper:
  - Add resize and recreate offscreen drawable util method
  - Simplify required init/reshape calls for GLEventListener
  -

GLGraphicsConfigurationUtil:
  - fixWinAttribBitsAndHwAccel: Reflect sharede context hw-accel bits
  - OSX has no offscreen bitmap, use pbuffer
  - use proper offscreen auto selection if offscreen and no modes are set

EGL Context/Drawable/DrawableFactory: Abstract native platform code out of base classes
  - Use EGLWrappedSurface w/ UpstreamSurfaceHook to handle upstream (X11, WGL, ..)
    lifecycle - in case the EGL resource is hooked up on it.

Invisible dummy surfaces: All platforms
  - size is now reduced to 64x64 and decoupled of actual generic mutable size
  - fix device  lifecycle, no more leaks

+++

OSX
====

Enable support for GLFBODrawableImpl in offscreen CALayer mode
  - NSOpenGLImpl: hooks to calayer native code
  - calayer code:
    - allows pbuffer and texures (FBO)
    - decouple size and draw calls avoiding flickering
    - enable auto resize of calayer tree

MacOSXCGLContext:
  - NSOpenGLImpl:
  - Fix false pbuffer 'usage', validate the pointer
  - If !pbuffer, copy other window mode bits of caps
  -

MacOSXCGLGraphicsConfiguration:
  - Only assume pbuffer if !onscreen
  - Remove reference of native pixelformat pointer

Native code:
  - use 'respondsToSelector:' query before calling 'new' methods
    avoiding an error message where unsuported (prev. OSX versions)
  - if monitor refresh-rate is queried 0, set to default 60hz
  - add missing NSAutoreleasePool decoration

+++

Android / NEWT:
===============

Issue setVisible(..) w/o wait, i.e. queue on EDT,
@Android surfaceChanged() callback. Otherwise we could deadlock:
   setVisible(..) -> EDT -> setVisibleImpl(..) -> 'GL-display'.
the latter may may cause havoc while Android-EDT is blocked [until it's return].

4 files changed, 112 insertions, 214 deletions

diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
index cec7d4ec3..27462ae70 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeSurface.java
@@ -124,8 +124,11 @@ public interface NativeSurface extends SurfaceUpdatedListener {
   /**
    * Provide a mechanism to utilize custom (pre-) swap surface
    * code. This method is called before the render toolkit (e.g. JOGL) 
-   * swaps the buffer/surface. The implementation may itself apply the swapping,
+   * swaps the buffer/surface if double buffering is enabled.
+   * <p> 
+   * The implementation may itself apply the swapping,
    * in which case true shall be returned.
+   * </p>
    *
    * @return true if this method completed swapping the surface,
    *         otherwise false, in which case eg the GLDrawable 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/OffscreenLayerSurface.java b/src/nativewindow/classes/javax/media/nativewindow/OffscreenLayerSurface.java
index f7dbc6c27..f9800109c 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/OffscreenLayerSurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/OffscreenLayerSurface.java
@@ -50,4 +50,7 @@ public interface OffscreenLayerSurface {
   /** Returns true if a surface layer is attached, otherwise false. */
   public boolean isSurfaceLayerAttached();
   
+  /** Sets the capabilities of this instance, allowing upstream API's to refine it, i.e. OpenGL related settings. */
+  public void setChosenCapabilities(CapabilitiesImmutable caps);
+  
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
index 7fc9789c2..395fdc818 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/ProxySurface.java
@@ -1,5 +1,5 @@
 /**
- * Copyright 2010 JogAmp Community. All rights reserved.
+ * Copyright 2012 JogAmp Community. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification, are
  * permitted provided that the following conditions are met:
@@ -29,242 +29,82 @@
 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, MutableSurface {
+/**
+ * Provides a mutable {@link NativeSurface}, i.e. {@link MutableSurface}, while allowing an
+ * {@link UpstreamSurfaceHook} to influence the lifecycle and information.
+ * 
+ * @see UpstreamSurfaceHook
+ * @see MutableSurface
+ * @see NativeSurface
+ */
+public interface ProxySurface extends MutableSurface {    
     public static final boolean DEBUG = Debug.debug("ProxySurface");
     
     /** 
-     * Implementation specific bitvalue stating the upstream's {@link AbstractGraphicsDevice} is owned by this {@link ProxySurface}.
-     * @see #setImplBitfield(int)
-     * @see #getImplBitfield()
+     * Implementation specific bit-value stating this {@link ProxySurface} owns the upstream's surface handle
+     * @see #addUpstreamOptionBits(int)
+     * @see #getUpstreamOptionBits()
      */ 
-    public static final int OWN_DEVICE = 1 << 7;
+    public static final int OPT_PROXY_OWNS_UPSTREAM_SURFACE = 1 << 6;
+    
+    /** 
+     * Implementation specific bit-value stating this {@link ProxySurface} owns the upstream's {@link AbstractGraphicsDevice}.
+     * @see #addUpstreamOptionBits(int)
+     * @see #getUpstreamOptionBits()
+     */ 
+    public static final int OPT_PROXY_OWNS_UPSTREAM_DEVICE = 1 << 7;
     
     /** 
      * Implementation specific bitvalue stating the upstream's {@link NativeSurface} is an invisible window, i.e. maybe incomplete.
-     * @see #setImplBitfield(int)
-     * @see #getImplBitfield()
+     * @see #addUpstreamOptionBits(int)
+     * @see #getUpstreamOptionBits()
      */ 
-    public static final int INVISIBLE_WINDOW = 1 << 8;
+    public static final int OPT_UPSTREAM_WINDOW_INVISIBLE = 1 << 8;
 
-    /** Interface allowing upstream caller to pass lifecycle actions and size info to a {@link ProxySurface} instance. */ 
-    public interface UpstreamSurfaceHook {
-        /** called within {@link ProxySurface#createNotify()} within lock, before using surface. */
-        public void create(ProxySurface s);
-        /** called within {@link ProxySurface#destroyNotify()} within lock, before clearing fields. */
-        public void destroy(ProxySurface s);
+    /** Allow redefining the AbstractGraphicsConfiguration */
+    public void setGraphicsConfiguration(AbstractGraphicsConfiguration cfg);    
 
-        /** Returns the width of the upstream surface */ 
-        public int getWidth(ProxySurface s);
-        /** Returns the height of the upstream surface */ 
-        public int getHeight(ProxySurface s);
-    }
+    /** Returns the set {@link UpstreamSurfaceHook}, or null if not set. */
+    public UpstreamSurfaceHook getUpstreamSurfaceHook();
     
-    private final SurfaceUpdatedHelper surfaceUpdatedHelper = new SurfaceUpdatedHelper();
-    private final AbstractGraphicsConfiguration config; // control access due to delegation
-    private final UpstreamSurfaceHook upstream;
-    public final int initialWidth;
-    public final int initialHeight;
-    private long surfaceHandle_old;
-    protected RecursiveLock surfaceLock = LockFactory.createRecursiveLock();
-    protected long displayHandle;
-    protected int scrnIndex;
-    protected int implBitfield;
-
     /**
-     * @param cfg the {@link AbstractGraphicsConfiguration} to be used
-     * @param initialWidth the initial width
-     * @param initialHeight the initial height
+     * Sets the {@link UpstreamSurfaceHook} and returns the previous value.
      */
-    protected ProxySurface(AbstractGraphicsConfiguration cfg, int initialWidth, int initialHeight, UpstreamSurfaceHook upstream) {
-        if(null == cfg) {
-            throw new IllegalArgumentException("null config");
-        }
-        this.config = cfg;
-        this.upstream = upstream;
-        this.initialWidth = initialWidth;
-        this.initialHeight = initialHeight;
-        this.displayHandle=config.getNativeGraphicsConfiguration().getScreen().getDevice().getHandle();
-        this.surfaceHandle_old = 0;
-        this.implBitfield = 0;
-    }
-
-    public final UpstreamSurfaceHook getUpstreamSurfaceHook() { return upstream; }
+    public void setUpstreamSurfaceHook(UpstreamSurfaceHook hook);
+    
+    /** 
+     * Enables or disables the {@link UpstreamSurfaceHook} lifecycle functions 
+     * {@link UpstreamSurfaceHook#create(ProxySurface)} and {@link UpstreamSurfaceHook#destroy(ProxySurface)}.
+     * <p>
+     * Use this for small code blocks where the native resources shall not change,
+     * i.e. resizing a derived (OpenGL) drawable.
+     * </p> 
+     */
+    public void enableUpstreamSurfaceHookLifecycle(boolean enable);
     
     /** 
-     * If a valid {@link UpstreamSurfaceHook} instance is passed in the 
-     * {@link ProxySurface#ProxySurface(AbstractGraphicsConfiguration, int, int, UpstreamSurfaceHook) constructor}, 
      * {@link UpstreamSurfaceHook#create(ProxySurface)} is being issued and the proxy surface/window handles shall be set.
      */ 
-    public void createNotify() {
-        if(null != upstream) {
-            upstream.create(this);
-        }
-        this.displayHandle=config.getNativeGraphicsConfiguration().getScreen().getDevice().getHandle();
-        this.surfaceHandle_old = 0;
-    }
+    public void createNotify();
     
     /** 
-     * If a valid {@link UpstreamSurfaceHook} instance is passed in the 
-     * {@link ProxySurface#ProxySurface(AbstractGraphicsConfiguration, int, int, UpstreamSurfaceHook) constructor}, 
-     * {@link UpstreamSurfaceHook#destroy(ProxySurface)} is being issued and all fields are cleared.
+     * {@link UpstreamSurfaceHook#destroy(ProxySurface)} is being issued and all proxy surface/window handles shall be cleared.
      */ 
-    public void destroyNotify() {
-        if(null != upstream) {
-            upstream.destroy(this);
-            invalidateImpl();
-        }
-        this.displayHandle = 0;
-        this.surfaceHandle_old = 0;
-    }
+    public void destroyNotify();
     
-    /** 
-     * Must be overridden by implementations allowing having a {@link UpstreamSurfaceHook} being passed.
-     * @see #destroyNotify() 
-     */
-    protected void invalidateImpl() {
-        throw new InternalError("UpstreamSurfaceHook given, but required method not implemented.");        
-    }
+    public StringBuilder getUpstreamOptionBits(StringBuilder sink);
+    public int getUpstreamOptionBits();
     
-    @Override
-    public final long getDisplayHandle() {
-        return displayHandle;
-    }
-
-    protected final AbstractGraphicsConfiguration getPrivateGraphicsConfiguration() {
-        return config;
-    }
-
-    @Override
-    public final AbstractGraphicsConfiguration getGraphicsConfiguration() {
-        return config.getNativeGraphicsConfiguration();
-    }
-
-    @Override
-    public final int getScreenIndex() {
-        return getGraphicsConfiguration().getScreen().getIndex();
-    }
-
-    @Override
-    public abstract long getSurfaceHandle();
-
-    @Override
-    public abstract void setSurfaceHandle(long surfaceHandle);
+    /** Returns <code>true</code> if the give bit-mask <code>v</code> is set in this instance upstream-option-bits, otherwise <code>false</code>.*/
+    public boolean containsUpstreamOptionBits(int v);
     
-    @Override
-    public final int getWidth() {
-        if(null != upstream) {
-            return upstream.getWidth(this);
-        }
-        return initialWidth;
-    }
-
-    @Override
-    public final int getHeight() {
-        if(null != upstream) {
-            return upstream.getHeight(this);
-        }
-        return initialHeight;
-    }
-
-    @Override
-    public boolean surfaceSwap() {
-        return false;
-    }
-
-    @Override
-    public void addSurfaceUpdatedListener(SurfaceUpdatedListener l) {
-        surfaceUpdatedHelper.addSurfaceUpdatedListener(l);
-    }
-
-    @Override
-    public void addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l) throws IndexOutOfBoundsException {
-        surfaceUpdatedHelper.addSurfaceUpdatedListener(index, l);
-    }
-
-    @Override
-    public void removeSurfaceUpdatedListener(SurfaceUpdatedListener l) {
-        surfaceUpdatedHelper.removeSurfaceUpdatedListener(l);
-    }
-
-    @Override
-    public void surfaceUpdated(Object updater, NativeSurface ns, long when) {
-        surfaceUpdatedHelper.surfaceUpdated(updater, ns, when);
-    }
-
-    @Override
-    public int lockSurface() throws NativeWindowException, RuntimeException  {
-        surfaceLock.lock();
-        int res = surfaceLock.getHoldCount() == 1 ? LOCK_SURFACE_NOT_READY : LOCK_SUCCESS; // new lock ?
-
-        if ( LOCK_SURFACE_NOT_READY == res ) {
-            try {
-                final AbstractGraphicsDevice adevice = getGraphicsConfiguration().getScreen().getDevice();
-                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();
-                    }
-                }
-            } finally {
-                if (LOCK_SURFACE_NOT_READY >= res) {
-                    surfaceLock.unlock();
-                }
-            }
-        }
-        return res;
-    }
-
-    @Override
-    public final void unlockSurface() {
-        surfaceLock.validateLocked();
-        surfaceHandle_old = getSurfaceHandle();
-
-        if (surfaceLock.getHoldCount() == 1) {
-            final AbstractGraphicsDevice adevice = getGraphicsConfiguration().getScreen().getDevice();
-            try {
-                unlockSurfaceImpl();
-            } finally {
-                adevice.unlock();
-            }
-        }
-        surfaceLock.unlock();
-    }
-
-    protected abstract int lockSurfaceImpl();
-
-    protected abstract void unlockSurfaceImpl() ;
-
-    public final void validateSurfaceLocked() {
-        surfaceLock.validateLocked();
-    }
-
-    @Override
-    public final boolean isSurfaceLockedByOtherThread() {
-        return surfaceLock.isLockedByOtherThread();
-    }
-
-    @Override
-    public final Thread getSurfaceLockOwner() {
-        return surfaceLock.getOwner();
-    }
+    /** Add the given bit-mask to this instance upstream-option-bits using bit-or w/ <code>v</code>.*/
+    public void addUpstreamOptionBits(int v);
     
-    @Override
-    public abstract String toString();
+    /** Clear the given bit-mask from this instance upstream-option-bits using bit-and w/ <code>~v</code>*/
+    public void clearUpstreamOptionBits(int v);
     
-    public int getImplBitfield() { return implBitfield; }    
-    public void setImplBitfield(int v) { implBitfield=v; }
+    public StringBuilder toString(StringBuilder sink);
+    public String toString();
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
new file mode 100644
index 000000000..6fe2e5364
--- /dev/null
+++ b/src/nativewindow/classes/javax/media/nativewindow/UpstreamSurfaceHook.java
@@ -0,0 +1,52 @@
+/**
+ * Copyright 2012 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+
+package javax.media.nativewindow;
+
+/** 
+ * Interface allowing upstream caller to pass lifecycle actions and size info 
+ * to a {@link ProxySurface} instance. 
+ */ 
+public interface UpstreamSurfaceHook {
+    /** called within {@link ProxySurface#createNotify()} within lock, before using surface. */
+    public void create(ProxySurface s);
+    /** called within {@link ProxySurface#destroyNotify()} within lock, before clearing fields. */
+    public void destroy(ProxySurface s);
+
+    /** Returns the width of the upstream surface, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */ 
+    public int getWidth(ProxySurface s);
+    /** Returns the height of the upstream surface, used if {@link ProxySurface#UPSTREAM_PROVIDES_SIZE} is set. */ 
+    public int getHeight(ProxySurface s);
+    
+    /**
+     * {@link UpstreamSurfaceHook} w/ mutable size, allowing it's {@link ProxySurface} user to resize.  
+     */ 
+    public interface MutableSize extends UpstreamSurfaceHook {
+        public void setSize(int width, int height);
+    }
+}