GLAutoDrawable: Refine API doc; Use new abstract impl. GLAutoDrawableBase (GLWindow, ..); Add new GLAutoDrawableDelegate.

- Refine API doc
  - 'void setContext(GLContext)' -> 'GLContext setContext(GLContext)'
  - Add note to createContext(GLContext) override

-Use new abstract impl. GLAutoDrawableBase, used by:
  - GLWindow
  - GLAutoDrawableDelegate
  - GLPbufferImpl

- Add new GLAutoDrawableDelegate incl. unit test

4 files changed, 177 insertions, 21 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index 94e4bad66..e4aaad23d 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -122,10 +122,36 @@ public interface GLAutoDrawable extends GLDrawable {
   public GLContext getContext();
 
   /**
-   * Associate a new context to this drawable.
+   * Associate a new context to this drawable and also propagates the context/drawable switch by 
+   * calling {@link GLContext#setGLDrawable(GLDrawable, boolean) newCtx.setGLDrawable(drawable, true);}.
+   * <code>drawable</code> might be an inner GLDrawable instance if using such a delegation pattern,
+   * or this GLAutoDrawable itself. 
+   * <p>
+   * If the old context's drawable was an {@link GLAutoDrawable}, it's reference to the given drawable
+   * is being cleared by calling 
+   * {@link GLAutoDrawable#setContext(GLContext) ((GLAutoDrawable)oldCtx.getGLDrawable()).setContext(null)}.
+   * </p>
+   * <p>
+   * If the old or new context was current on this thread, it is being released before switching the drawable.
+   * The new context will be made current afterwards, if it was current before. 
+   * However the user shall take extra care that not other thread
+   * attempts to make this context current. Otherwise a race condition may happen.
+   * </p>
+   * <p>
+   * <b>Disclaimer</b>: Even though the API may allows this functionality in theory, your mileage may vary 
+   * switching the drawable of an already established GLContext, i.e. which is already made current once.
+   * FIXME: Validate functionality! 
+   * </p>
+   * 
+   * @param newCtx the new context
+   * @return the replaced GLContext, maybe <code>null</code>
+   *  
+   * @see GLContext#setGLDrawable(GLDrawable, boolean)
+   * @see GLContext#setGLReadDrawable(GLDrawable)
+   * @see jogamp.opengl.GLDrawableHelper#switchContext(GLDrawable, GLContext, GLContext, int)
    */
-  public void setContext(GLContext context);
-
+  public GLContext setContext(GLContext newCtx);
+  
   /** Adds a {@link GLEventListener} to the end of this drawable queue.
       The listeners are notified of events in the order of the queue. */
   public void addGLEventListener(GLEventListener listener);
@@ -271,6 +297,21 @@ public interface GLAutoDrawable extends GLDrawable {
    */
   public int getContextCreationFlags();
 
+  /**
+   * {@inheritDoc}
+   * <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)}. 
+   * </p>
+   * <p>
+   * The GLAutoDrawable implementation shall also set the 
+   * context creation flags as customized w/ {@link #setContextCreationFlags(int)}. 
+   * </p>
+   */
+  @Override
+  public GLContext createContext(GLContext shareWith);
+  
   /** Returns the {@link GL} pipeline object this GLAutoDrawable uses.
       If this method is called outside of the {@link
       GLEventListener}'s callback methods (init, display, etc.) it may
diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawableDelegate.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawableDelegate.java
new file mode 100644
index 000000000..992bf9fee
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawableDelegate.java
@@ -0,0 +1,100 @@
+/**
+ * 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.opengl;
+
+import jogamp.opengl.Debug;
+import jogamp.opengl.GLAutoDrawableBase;
+import jogamp.opengl.GLContextImpl;
+import jogamp.opengl.GLDrawableImpl;
+
+
+/**
+ * Fully functional {@link GLAutoDrawable} implementation
+ * utilizing already created created {@link GLDrawable} and {@link GLContext} instances.
+ * <p>
+ * Since no native windowing system events are being processed, it is recommended
+ * to handle at least {@link com.jogamp.newt.event.WindowListener#windowResized(com.jogamp.newt.event.WindowEvent) resize},
+ * {@link com.jogamp.newt.event.WindowListener#windowDestroyNotify(com.jogamp.newt.event.WindowEvent) destroy-notify} 
+ * and maybe {@link com.jogamp.newt.event.WindowListener#windowRepaint(com.jogamp.newt.event.WindowUpdateEvent) repaint}. 
+ * The latter is only required if no {@link GLAnimatorControl} is being used.
+ * </p> 
+ */
+public class GLAutoDrawableDelegate extends GLAutoDrawableBase {
+    public static final boolean DEBUG = Debug.debug("GLAutoDrawableDelegate");
+    
+    public GLAutoDrawableDelegate(GLDrawable drawable, GLContext context) {
+        super((GLDrawableImpl)drawable, (GLContextImpl)context);
+    }
+    
+    public void defaultRepaintOp() {
+        super.defaultRepaintOp();
+    }
+    
+    public void defaultReshapeOp() {
+        super.defaultReshapeOp();
+    }
+    
+    //
+    // Complete GLAutoDrawable
+    //
+    
+    /**
+     * {@inheritDoc}
+     * <p>
+     * This implementation simply removes references to drawable and context.
+     * </p>
+     */
+    @Override
+    public void destroy() {
+        drawable = null;
+        context = null;
+    }
+
+    @Override
+    public void display() {
+        if( null == drawable || !drawable.isRealized() || null == context ) { return; }
+
+        // surface is locked/unlocked implicit by context's makeCurrent/release
+        helper.invokeGL(drawable, context, defaultDisplayAction, defaultInitAction);
+    }
+    
+    //
+    // GLDrawable delegation
+    //
+    
+    @Override
+    public final GLDrawableFactory getFactory() {
+        return drawable.getFactory();
+    }
+    
+    @Override
+    public final void setRealized(boolean realized) {
+    }
+
+}
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
index 71026a247..8c6e594b5 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
@@ -392,10 +392,15 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
   }
 
   @Override
-  public GLContext createContext(GLContext shareWith) {
-      return (null != drawable) ? drawable.createContext(shareWith) : null;
+  public GLContext createContext(final GLContext shareWith) {
+    if(drawable != null) {
+      final GLContext _ctx = drawable.createContext(shareWith);
+      _ctx.setContextCreationFlags(additionalCtxCreationFlags);
+      return _ctx;
+    }
+    return null;
   }
-
+    
   @Override
   public void setRealized(boolean realized) {
   }
@@ -694,11 +699,14 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
   }
 
   @Override
-  public void setContext(GLContext ctx) {
-    context=(GLContextImpl)ctx;
-    if(null != context) {
-        context.setContextCreationFlags(additionalCtxCreationFlags);
-    }
+  public GLContext setContext(GLContext newCtx) {
+      final GLContext oldCtx = context;
+      final boolean newCtxCurrent = drawableHelper.switchContext(drawable, oldCtx, newCtx, additionalCtxCreationFlags);
+      context=(GLContextImpl)newCtx;
+      if(newCtxCurrent) {
+          context.makeCurrent();
+      }
+      return oldCtx;
   }
 
   @Override
@@ -744,6 +752,9 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
   @Override
   public void setContextCreationFlags(int flags) {
     additionalCtxCreationFlags = flags;
+    if(null != context) {
+      context.setContextCreationFlags(additionalCtxCreationFlags);
+    }
   }
 
   @Override
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
index 152326006..c6c7cf9a1 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
@@ -456,16 +456,20 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
   }
 
   @Override
-  public void setContext(GLContext ctx) {
-    if (backend == null) {
-      return;
-    }
-    if(null != ctx) {
-        ctx.setContextCreationFlags(additionalCtxCreationFlags);
-    }
-    backend.setContext(ctx);
+  public GLContext setContext(GLContext newCtx) {
+      if (backend == null) {
+          return null;
+      }
+      final GLContext oldCtx = backend.getContext();
+      final boolean newCtxCurrent = drawableHelper.switchContext(backend.getDrawable(), oldCtx, newCtx, additionalCtxCreationFlags);
+      backend.setContext(newCtx);
+      if(newCtxCurrent) {
+          newCtx.makeCurrent();
+      }
+      return oldCtx;
   }
 
+
   @Override
   public GLContext getContext() {
     if (backend == null) {
@@ -1160,7 +1164,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
 
     @Override
     public void setContext(GLContext ctx) {
-      if (pbuffer == null && Beans.isDesignTime()) {
+      if (pbuffer == null || Beans.isDesignTime()) {
         return;
       }
       pbuffer.setContext(ctx);
@@ -1169,7 +1173,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
     @Override
     public GLContext getContext() {
       // Workaround for crashes in NetBeans GUI builder
-      if (pbuffer == null && Beans.isDesignTime()) {
+      if (null == pbuffer || Beans.isDesignTime()) {
         return null;
       }
       return pbuffer.getContext();