Bug 942: Bug 942 - Review GLBuffer[State|Size]Tracker and NIO mapped buffers

Commit f8a74c9831c65725a699320c27e62161a0378241 reverted
commit 7c5483d5b20aed9c87c5ce3f6bc840b6546edcd1
due to the fact that the buffer binding itself is _not_
shared across shared GLContext!

Apply uncritical changes of 7c5483d5b20aed9c87c5ce3f6bc840b6546edcd1:

+++

Simplify GLBufferSizeTracker creation @ GLContextImpl ctor,
make it final.

+++

Clear the GLBufferSizeTracker (@destruction) only if no more
created shares are left!

+++

Refine API doc.

+++

1 files changed, 22 insertions, 21 deletions

diff --git a/src/jogl/classes/jogamp/opengl/GLBufferStateTracker.java b/src/jogl/classes/jogamp/opengl/GLBufferStateTracker.java
index 16b7edca8..8f79990a8 100644
--- a/src/jogl/classes/jogamp/opengl/GLBufferStateTracker.java
+++ b/src/jogl/classes/jogamp/opengl/GLBufferStateTracker.java
@@ -50,8 +50,13 @@ import com.jogamp.common.util.IntIntHashMap;
  * GLBufferStateTracker objects are allocated on a per-OpenGL-context basis.
  * This class is used to verify that e.g. the vertex
  * buffer object extension is in use when the glVertexPointer variant
- * taking a long as argument is called. <P>
- *
+ * taking a long as argument is called.
+ * <p>
+ * The buffer binding state is local to it's OpenGL context,
+ * i.e. not shared across multiple OpenGL context.
+ * Hence this code is thread safe due to no multithreading usage.
+ * </p>
+ * <p>
  * Note that because the enumerated value used for the binding of a
  * buffer object (e.g. GL_ARRAY_BUFFER) is different than that used to
  * query the binding using glGetIntegerv (e.g.
@@ -61,19 +66,15 @@ import com.jogamp.common.util.IntIntHashMap;
  * to a particular state. It turns out that for some uses, such as
  * finding the size of the currently bound buffer, this doesn't
  * matter, though of course without knowing the buffer object we can't
- * re-associate the queried size with the buffer object ID. <P>
- *
- * Because the namespace of buffer objects is the unsigned integers
- * with 0 reserved by the GL, and because we have to be able to return
- * both 0 and other integers as valid answers from
- * getBoundBufferObject(), we need a second query, which is to ask
- * whether we know the state of the binding for a given target. For
- * "unknown" targets such as GL_TRANSFORM_FEEDBACK_BUFFER_NV we return
+ * re-associate the queried size with the buffer object ID.
+ * </p>
+ * <p>
+ * For <i>unknown</i> targets such as GL_TRANSFORM_FEEDBACK_BUFFER_NV we return
  * false from this, but we also clear the valid bit and later refresh
  * the binding state if glPushClientAttrib / glPopClientAttrib are
  * called, since we don't want the complexity of tracking stacks of
  * these attributes.
- *
+ * </p>
  */
 
 public class GLBufferStateTracker {
@@ -90,13 +91,13 @@ public class GLBufferStateTracker {
   // OpenGL specifications.
   // http://www.opengl.org/sdk/docs/man/xhtml/glBindBuffer.xml
   private final IntIntHashMap bindingMap;
-  private final int keyNotFound = 0xFFFFFFFF;
+  private final int bindingNotFound = 0xFFFFFFFF;
 
   private final int[] bufTmp = new int[1];
 
   public GLBufferStateTracker() {
     bindingMap = new IntIntHashMap();
-    bindingMap.setKeyNotFoundValue(keyNotFound);
+    bindingMap.setKeyNotFoundValue(bindingNotFound);
 
     // Start with known unbound targets for known keys
     // setBoundBufferObject(GL2ES3.GL_VERTEX_ARRAY_BINDING, 0); // not using default VAO (removed in GL3 core) - only explicit
@@ -139,20 +140,20 @@ public class GLBufferStateTracker {
       return value is valid. */
   public final int getBoundBufferObject(int target, GL caller) {
     int value = bindingMap.get(target);
-    if (keyNotFound == value) {
+    if (bindingNotFound == value) {
       // User probably either called glPushClientAttrib /
       // glPopClientAttrib or is querying an unknown target. See
       // whether we know how to fetch this state.
       boolean gotQueryTarget = true;
-      int queryTarget = 0;
+      final int queryTarget;
       switch (target) {
         case GL2ES3.GL_VERTEX_ARRAY_BINDING: queryTarget = GL2ES3.GL_VERTEX_ARRAY_BINDING;  break;
-        case GL.GL_ARRAY_BUFFER:          queryTarget = GL.GL_ARRAY_BUFFER_BINDING;         break;
-        case GL.GL_ELEMENT_ARRAY_BUFFER:  queryTarget = GL.GL_ELEMENT_ARRAY_BUFFER_BINDING; break;
-        case GL2.GL_PIXEL_PACK_BUFFER:    queryTarget = GL2.GL_PIXEL_PACK_BUFFER_BINDING;    break;
-        case GL2.GL_PIXEL_UNPACK_BUFFER:  queryTarget = GL2.GL_PIXEL_UNPACK_BUFFER_BINDING;  break;
-        case GL4.GL_DRAW_INDIRECT_BUFFER: queryTarget = GL4.GL_DRAW_INDIRECT_BUFFER_BINDING;  break;
-        default:                          gotQueryTarget = false; break;
+        case GL.GL_ARRAY_BUFFER:             queryTarget = GL.GL_ARRAY_BUFFER_BINDING;         break;
+        case GL.GL_ELEMENT_ARRAY_BUFFER:     queryTarget = GL.GL_ELEMENT_ARRAY_BUFFER_BINDING; break;
+        case GL2.GL_PIXEL_PACK_BUFFER:       queryTarget = GL2.GL_PIXEL_PACK_BUFFER_BINDING;    break;
+        case GL2.GL_PIXEL_UNPACK_BUFFER:     queryTarget = GL2.GL_PIXEL_UNPACK_BUFFER_BINDING;  break;
+        case GL4.GL_DRAW_INDIRECT_BUFFER:    queryTarget = GL4.GL_DRAW_INDIRECT_BUFFER_BINDING;  break;
+        default:                             queryTarget = 0; gotQueryTarget = false; break;
       }
       if (gotQueryTarget) {
         final int glerrPre = caller.glGetError(); // clear