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

3 files changed, 26 insertions, 19 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
index ce58d29c1..6b1bb0e5e 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
@@ -64,11 +64,18 @@ import jogamp.opengl.GLDrawableImpl;
  */
 public class GLAutoDrawableDelegate extends GLAutoDrawableBase implements GLAutoDrawable {
     /**
+     * <p>
+     * The {@link GLContext} can be assigned later manually via {@link GLAutoDrawable#setContext(GLContext, boolean) setContext(ctx)}
+     * <i>or</i> it will be created <i>lazily</i> at the 1st {@link GLAutoDrawable#display() display()} method call.<br>
+     * <i>Lazy</i> {@link GLContext} creation will take a shared {@link GLContext} into account
+     * which has been set {@link #setSharedContext(GLContext) directly}
+     * or {@link #setSharedAutoDrawable(GLAutoDrawable) via another GLAutoDrawable}.
+     * </p>
      * @param drawable a valid {@link GLDrawable}, may not be {@link GLDrawable#isRealized() realized} yet.
      * @param context a valid {@link GLContext},
      *                may not have been made current (created) yet,
      *                may not be associated w/ <code>drawable<code> yet,
-     *                may be <code>null</code> for lazy initialization
+     *                may be <code>null</code> for lazy initialization at 1st {@link #display()}.
      * @param upstreamWidget optional UI element holding this instance, see {@link #getUpstreamWidget()}.
      * @param ownDevice pass <code>true</code> if {@link AbstractGraphicsDevice#close()} shall be issued,
      *                  otherwise pass <code>false</code>. Closing the device is required in case
diff --git a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
index 1a3e1e0c0..5e3731984 100644
--- a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
+++ b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
@@ -242,7 +242,7 @@ public class GLCanvas extends Canvas implements GLAutoDrawable {
 
    private class DisposeGLEventListenerAction implements Runnable {
        private GLEventListener listener;
-       private boolean remove;
+       private final boolean remove;
        private DisposeGLEventListenerAction(GLEventListener listener, boolean remove) {
            this.listener = listener;
            this.remove = remove;
@@ -677,7 +677,7 @@ public class GLCanvas extends Canvas implements GLAutoDrawable {
 
    @Override
    public GLContext getContext() {
-      return null != drawable ? context : null;
+      return context;
    }
 
    @Override
diff --git a/src/jogl/classes/com/jogamp/opengl/util/awt/TextRenderer.java b/src/jogl/classes/com/jogamp/opengl/util/awt/TextRenderer.java
index 3662223f4..46dc73003 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/awt/TextRenderer.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/awt/TextRenderer.java
@@ -159,20 +159,20 @@ public class TextRenderer {
     static final int kTotalBufferSizeBytesTex = kTotalBufferSizeCoordsTex * 4;
     static final int kSizeInBytes_OneVertices_VertexData = kCoordsPerVertVerts * 4;
     static final int kSizeInBytes_OneVertices_TexData = kCoordsPerVertTex * 4;
-    private Font font;
-    private boolean antialiased;
-    private boolean useFractionalMetrics;
+    private final Font font;
+    private final boolean antialiased;
+    private final boolean useFractionalMetrics;
 
     // Whether we're attempting to use automatic mipmap generation support
     private boolean mipmap;
     private RectanglePacker packer;
     private boolean haveMaxSize;
-    private RenderDelegate renderDelegate;
+    private final RenderDelegate renderDelegate;
     private TextureRenderer cachedBackingStore;
     private Graphics2D cachedGraphics;
     private FontRenderContext cachedFontRenderContext;
-    private Map<String, Rect> stringLocations = new HashMap<String, Rect>();
-    private GlyphProducer mGlyphProducer;
+    private final Map<String, Rect> stringLocations = new HashMap<String, Rect>();
+    private final GlyphProducer mGlyphProducer;
 
     private int numRenderCycles;
 
@@ -905,8 +905,8 @@ public class TextRenderer {
     private void debug(GL gl) {
         dbgFrame = new Frame("TextRenderer Debug Output");
 
-        GLCanvas dbgCanvas = new GLCanvas(new GLCapabilities(gl.getGLProfile()), null,
-                                          GLContext.getCurrent(), null);
+        GLCanvas dbgCanvas = new GLCanvas(new GLCapabilities(gl.getGLProfile()));
+        dbgCanvas.setSharedContext(GLContext.getCurrent());
         dbgCanvas.addGLEventListener(new DebugListener(gl, dbgFrame));
         dbgFrame.add(dbgCanvas);
 
@@ -1085,7 +1085,7 @@ public class TextRenderer {
     static class TextData {
         // Back-pointer to String this TextData describes, if it
         // represents a String rather than a single glyph
-        private String str;
+        private final String str;
 
         // If this TextData represents a single glyph, this is its
         // unicode ID
@@ -1096,7 +1096,7 @@ public class TextRenderer {
         // 2D coordinate system) at which the string must be rasterized in
         // order to fit within the rectangle -- the leftmost point of the
         // baseline.
-        private Point origin;
+        private final Point origin;
 
         // This represents the pre-normalized rectangle, which fits
         // within the rectangle on the backing store. We keep a
@@ -1104,7 +1104,7 @@ public class TextRenderer {
         // prevent bleeding of adjacent letters when using GL_LINEAR
         // filtering for rendering. The origin of this rectangle is
         // equivalent to the origin above.
-        private Rectangle2D origRect;
+        private final Rectangle2D origRect;
 
         private boolean used; // Whether this text was used recently
 
@@ -1375,7 +1375,7 @@ public class TextRenderer {
     //
 
     // A temporary to prevent excessive garbage creation
-    private char[] singleUnicode = new char[1];
+    private final char[] singleUnicode = new char[1];
 
     /** A Glyph represents either a single unicode glyph or a
         substring of characters to be drawn. The reason for the dual
@@ -1497,10 +1497,10 @@ public class TextRenderer {
                 int width = (int) origRect.getWidth();
                 int height = (int) origRect.getHeight();
 
-                float tx1 = xScale * (float) texturex / (float) renderer.getWidth();
+                float tx1 = xScale * texturex / renderer.getWidth();
                 float ty1 = yScale * (1.0f -
                                       ((float) texturey / (float) renderer.getHeight()));
-                float tx2 = xScale * (float) (texturex + width) / (float) renderer.getWidth();
+                float tx2 = xScale * (texturex + width) / renderer.getWidth();
                 float ty2 = yScale * (1.0f -
                                       ((float) (texturey + height) / (float) renderer.getHeight()));
 
@@ -1829,7 +1829,7 @@ public class TextRenderer {
                 GL2 gl = GLContext.getCurrentGL().getGL2();
 
                 TextureRenderer renderer = getBackingStore();
-                Texture texture = renderer.getTexture(); // triggers texture uploads.  Maybe this should be more obvious?
+                renderer.getTexture(); // triggers texture uploads.  Maybe this should be more obvious?
 
                 mVertCoords.rewind();
                 mTexCoords.rewind();
@@ -1872,7 +1872,7 @@ public class TextRenderer {
         private void drawIMMEDIATE() {
             if (mOutstandingGlyphsVerticesPipeline > 0) {
                 TextureRenderer renderer = getBackingStore();
-                Texture texture = renderer.getTexture(); // triggers texture uploads.  Maybe this should be more obvious?
+                renderer.getTexture(); // triggers texture uploads.  Maybe this should be more obvious?
 
                 GL2 gl = GLContext.getCurrentGL().getGL2();
                 gl.glBegin(GL2.GL_QUADS);