Bug 776 GLContext Sharing: Refine API for relaxed and lazy GLContext sharing ; Fix GLContext memory contract (volatile)

(Unit test remarks see below)

- Add shared GLContext queries
  - Refined GLContextShareSet:
    - Use IdentityHashMap since GLContext's can only be identical w/ same reference (footprint, performance)
    - Add API doc for clarification
    - Add methods:
       - ArrayList<GLContext> getCreatedShares(final GLContext context)
       - ArrayList<GLContext> getDestroyedShares(final GLContext context)
    - Use 'final' where possible

  - Add GLContext methods:
      - boolean isShared()
      - List<GLContext> getCreatedShares()
      - List<GLContext> getDestroyedShares()

- Add GLSharedContextSetter interface defining setting a shared GLContext
  directly (GLContext) or via a GLAutoDrawable:
  - setSharedContext(GLContext)
  - setSharedAutoDrawable(GLAutoDrawable)

  Both cause initialization/creation of GLAutoDrawable's drawable/context to be postponed,
  if the shared GLContext is not yet created natively or
  the shared GLAutoDrawable's GLContext does not yet exist.

  Most of impl. resides in GLDrawableHelper

  Implemented in:
    - GLAutoDrawableBase, GLOffscreenAutoDrawable
    - GLWindow
    - AWT GLCanvas

  TODO:
    - GLJPanel
    - SWT GLCanvas

- GLDrawableFactory:
   - Add 'GLOffscreenAutoDrawable createOffscreenAutoDrawable(..)' variant w/o passing the
     optional shared GLContext _and_ specifying lazy GLContext
     creation. This allows to benefit from GLSharedContextSetter contract.
     Lazy GLContext creation is performed at 2st display() call at the latest.

     All JOGL code and unit tests use this new method now.

  - Mark 'createOffscreenAutoDrawable(..)' w/ shared GLContext argument
    and immediate GLContext creation deprecated - shall be removed in 2.2.0

- Make reference to GLContext and it's native handle volatile
  Since we rely on the query 'GLContext.isCreated()' to properly allow GLAutoDrawable's to query whether
  a shared GLContext is natively created (already), the handle must be volatile
  since such query and the actual creation may operate on different threads.

+++++

- Add/Refine shared GLContext unit tests demonstrating diff. sharing methods.

  All variants of using shared GLContext:
      com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBO*

  Most convenient way to share via setSharedAutoDrawable(GLAutoDrawable):
      com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2[NEWT|AWT]3

  AWT use w/ JTabbedPane using setSharedAutoDrawable(GLAutoDrawable):
      com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextWithJTabbedPaneAWT

1 files changed, 78 insertions, 0 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
new file mode 100644
index 000000000..d5a10931e
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
@@ -0,0 +1,78 @@
+/**
+ * Copyright 2013 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;
+
+/**
+ * Adds capabilities to set a shared {@link GLContext} directly or via an {@link GLAutoDrawable}.
+ * <p>
+ * Warning: Don't reference this interface directly, since it may end up in {@link GLAutoDrawable}
+ * </p>
+ */
+public interface GLSharedContextSetter extends GLAutoDrawable {
+    /**
+     * Specifies an {@link GLContext OpenGL context}, which shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
+     * <p>
+     * Since the {@link GLDrawable drawable} and {@link GLContext context} is created
+     * at {@link GLAutoDrawable#initialization GLAutoDrawable initialization}
+     * this method shall be called beforehand to have any effect.
+     * </p>
+     * <p>
+     * A set <i>sharedContext</i> will block context creation, i.e. {@link GLAutoDrawable#initialization GLAutoDrawable initialization},
+     * as long it is not {@link GLContext#isCreated() created natively}.
+     * </p>
+     *
+     * @param sharedContext The OpenGL context to be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
+     * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext}
+     *                               or {@link #setSharedAutoDrawable(GLAutoDrawable) shared GLAutoDrawable} is already set,
+     *                               the given sharedContext is null or equal to this {@link GLAutoDrawable}'s context.
+     * @see #setSharedAutoDrawable(GLAutoDrawable)
+     */
+    void setSharedContext(GLContext sharedContext) throws IllegalStateException;
+
+    /**
+     * Specifies an {@link GLAutoDrawable}, which {@link GLContext OpenGL context} shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
+     * <p>
+     * Since the {@link GLDrawable drawable} and {@link GLContext context} is created
+     * at {@link GLAutoDrawable#initialization GLAutoDrawable initialization}
+     * this method shall be called beforehand to have any effect.
+     * </p>
+     * <p>
+     * A set <i>sharedAutoDrawable</i> will block context creation, i.e. {@link GLAutoDrawable#initialization GLAutoDrawable initialization},
+     * as long it's {@link GLContext} is <code>null</code>
+     * or has not been {@link GLContext#isCreated() created natively}.
+     * </p>
+     *
+     * @param sharedContext The GLAutoDrawable, which OpenGL context shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
+     * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext}
+     *                               or {@link #setSharedAutoDrawable(GLAutoDrawable) shared GLAutoDrawable} is already set,
+     *                               the given sharedAutoDrawable is null or equal to this GLAutoDrawable.
+     * @see #setSharedContext(GLContext)
+     */
+    void setSharedAutoDrawable(GLAutoDrawable sharedAutoDrawable) throws IllegalStateException;
+}