Bug 665: Allow re-association of GLContext/GLEventListener to a GLDrawable (Part 4)

Note:

  - GLEventListenerState preservs the GLAutoDrawable state,
    i.e. GLContext, all GLEventListener and the GLAnimatorControl association.

  - GLEventListenerState may be utilized to move the state from a dying GLAutoDrawable,
    to be moved to a new created GLAutoDrawable at a later time.

  - GLEventListenerState will be made public soon.

+++

Exessive unit tests cover the new feature, tested manually on GNU/Linux/X11 and OSX(Java6/Java7).

+++

- GLAutoDrawable
  - Change 'setContext(..)' to allow the destruction of the unbound old context:
      'setContext(GLContext newCtx)' -> 'setContext(GLContext newCtx, boolean destroyPrevCtx)'

  - Implementations: Properly implement 'setRealized(..)' incl. obeying threading constraints if exists.
    Method is being utilized at least for GLEventListenerState.moveTo(..)
    to unrealize and realize the drawable resources.

+++

Fix propagation of GLContext/GLDrawable association change (Bottom -> Top):

  GLDrawableImpl.associateContext
      GLContextImpl.associateDrawable
          GLContextImpl.makeCurrent
          GLContextImpl.destroy
          GLContext.setGLDrawable
              ...
              GLDrawableHelper.switchContext
                  GLAutoDrawble.setContext

associateDrawable(..)/associateContext(..) unifies and hence:
    - GLContextImpl.contextRealized() (removed)
    - GLDrawableImpl.contextRealized() (removed)
    - GLDrawableImpl.associateContext(..) (merged)
    - MacOSXCGLContext.drawableChangedNotify(..) (removed)

+++

- EGLUpstreamSurfaceHook.evalUpstreamSurface() validates the surface's device for reusage,
  which is valid in case of GLEventListenerState.moveTo(..)

- MacOSXCGLContext.NSOpenGLImpl: pixelFormat replaces NSOpenGLLayerPfmt and has simplified lifecycle [create..destroy],
  while native NSOpenGLLayer code only holds the reference until released.

1 files changed, 6 insertions, 15 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index 6abe4308b..bdbbd96a5 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -132,7 +132,8 @@ public interface GLAutoDrawable extends GLDrawable {
   /**
    * Associate the new context, <code>newtCtx</code>, to this auto-drawable.
    * <p>
-   * The current context will be dis-associated from this auto-drawable 
+   * The current context will be destroyed if <code>destroyPrevCtx</code> is <code>true</code>,
+   * otherwise it will be dis-associated from this auto-drawable 
    * via {@link GLContext#setGLDrawable(GLDrawable, boolean) setGLDrawable(null, true);} first.
    * </p>
    * <p>
@@ -145,26 +146,16 @@ public interface GLAutoDrawable extends GLDrawable {
    * However the user shall take extra care that no other thread
    * attempts to make this context current.
    * </p>
-   * <p>
-   * In case you do not intend to use the old context anymore, i.e. 
-   * not assigning it to another drawable, it shall be
-   * destroyed, i.e.:
-   * <pre>
-            GLContext oldCtx = glad.setContext(newCtx);
-            if(null != oldCtx) {
-                oldCtx.destroy();
-            }
-   * </pre> 
-   * </p>
    * 
    * @param newCtx the new context, maybe <code>null</code> for dis-association.
+   * @param destroyPrevCtx if <code>true</code>, destroy the previous context if exists  
    * @return the previous GLContext, maybe <code>null</code>
    *  
    * @see GLContext#setGLDrawable(GLDrawable, boolean)
    * @see GLContext#setGLReadDrawable(GLDrawable)
-   * @see jogamp.opengl.GLDrawableHelper#switchContext(GLDrawable, GLContext, GLContext, int)
+   * @see jogamp.opengl.GLDrawableHelper#switchContext(GLDrawable, GLContext, boolean, GLContext, int)
    */
-  public GLContext setContext(GLContext newCtx);
+  public GLContext setContext(GLContext newCtx, boolean destroyPrevCtx);
   
   /**
    * Adds the given {@link GLEventListener listener} to the end of this drawable queue.
@@ -500,7 +491,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * <p>
    * This GLAutoDrawable implementation holds it's own GLContext reference,
    * thus created a GLContext using this methods won't replace it implicitly.
-   * To replace or set this GLAutoDrawable's GLContext you need to call {@link #setContext(GLContext)}. 
+   * To replace or set this GLAutoDrawable's GLContext you need to call {@link #setContext(GLContext, boolean)}. 
    * </p>
    * <p>
    * The GLAutoDrawable implementation shall also set the