Bug 942: GLBufferObjectTracker: Tracking GLBufferStorage accurately, synchronized and secure [1/2]

GLBufferSizeTracker becomes GLBufferObjectTracker
and tracks the buffer's data store, GLBufferStorage, accurately, synchronized and secure.

Synchronization is required, since the GLBufferStorage can be
shared across many GLContext on multiple threads.

This requires all GLBufferStorage lifecycle affecting GL functions
to utilize synchronized GLBufferObjectTracker methods
while passing a native GL-func callback.

These GL functions are:
  - glBufferData, glBufferStorage (GL 4.4), glNamedBufferDataEXT
    Creating the GLBufferStorage object
  - glMapBuffer, glMapBufferRange, and their *Named*EXT variants
  - glUnmapBuffer, glUnmapNamedBufferEXT

'glDeleteBuffers' can simply notify the GLBufferObjectTracker

No more HashMap is required to associate the mapped buffer address
to the mapped ByteBuffer.

GLBufferObjectTracker simply utilizes a
   buffer-name (int) -> GLBufferStorage
map.

+++

The security aspect shall be implemented by validating all arguments
whether they match the required GL constraints,
as well as validating tracked states like 'size'.

The following functions will throw an GLException accordingly:
  - glBufferData, glNamedBufferDataEXT
     * @throws GLException if size is less-than zero
     * @throws GLException if a native GL-Error occurs

  - glBufferStorage (GL 4.4)
     * @throws GLException if size is less-or-eqaul zero
     * @throws GLException if a native GL-Error occurs

  - glMapBuffer, and it's *Named*EXT variant
    * @throws GLException if buffer is not bound to target
    * @throws GLException if buffer is not tracked
    * @throws GLException if buffer is already mapped
    * @throws GLException if buffer has invalid store size, i.e. less-than zero

  - glMapBufferRange, and it's *Named*EXT variant
    * @throws GLException if buffer is not bound to target
    * @throws GLException if buffer is not tracked
    * @throws GLException if buffer is already mapped
    * @throws GLException if buffer has invalid store size, i.e. less-than zero
    * @throws GLException if buffer mapping range does not fit, incl. offset

  - glMapBufferRange, and it's *Named*EXT variant
    Only clear mapped buffer reference of GLBufferStorage
    if native unmap was successful.

Further more special error handling shall be applied to:
  - glMapBuffer, and it's *Named*EXT variant,
    glMapBuffer, and it's *Named*EXT variant
    - A zero GLBufferStorage size will avoid a native call and
      returns null
    - A null native mapping result indicating an error will
     not cause a GLException but returns null
     This allows the user to handle this case.

1 files changed, 68 insertions, 11 deletions

diff --git a/make/config/jogl/gl-common.cfg b/make/config/jogl/gl-common.cfg
index e9996c64b..74ead0498 100644
--- a/make/config/jogl/gl-common.cfg
+++ b/make/config/jogl/gl-common.cfg
@@ -56,12 +56,66 @@ Ignore glDebugMessageCallbackARB
 Ignore glDebugMessageCallbackKHR
 Ignore glDebugMessageCallback
 
-# Manually implement glMapBuffer and glMapBufferRange as the size of the returned buffer
-# can only be computed by calling another routine
+#
+# Manually implement following GL functions to be redirected 
+# to GLBufferObjectTracker.
+#
+ManuallyImplement glBufferData
+ForceProcAddressGen glBufferData
+MethodJavadoc glBufferData * <p>
+MethodJavadoc glBufferData * Throws a {@link GLException} if GL-function constraints are not met or the native GL-function fails.
+MethodJavadoc glBufferData * </p>
+MethodJavadoc glBufferData * <p>
+MethodJavadoc glBufferData * @throws GLException if buffer is not bound to target
+MethodJavadoc glBufferData * @throws GLException if size is less-than zero
+MethodJavadoc glBufferData * @throws GLException if a native GL-Error occurs
+MethodJavadoc glBufferData * </p>
+
+# FIXME: Add for OpenGL 4.4
+#Ignore glBufferStorage
+#ManuallyImplement glBufferStorage
+#ForceProcAddressGen glBufferStorage
+#MethodJavadoc glBufferStorage * <p>
+#MethodJavadoc glBufferStorage * Throws a {@link GLException} if GL-function constraints are not met or the native GL-function fails.
+#MethodJavadoc glBufferStorage * </p>
+#MethodJavadoc glBufferStorage * <p>
+#MethodJavadoc glBufferStorage * @throws GLException if buffer is not bound to target
+#MethodJavadoc glBufferStorage * @throws GLException if size is less-or-equal zero
+#MethodJavadoc glBufferStorage * @throws GLException if a native GL-Error occurs
+#MethodJavadoc glBufferStorage * </p>
+
 ManuallyImplement glMapBuffer
 ForceProcAddressGen glMapBuffer
+MethodJavadoc glMapBuffer * <p>
+MethodJavadoc glMapBuffer * Throws a {@link GLException} if GL-function constraints are not met.
+MethodJavadoc glMapBuffer * </p>
+MethodJavadoc glMapBuffer * <p>
+MethodJavadoc glMapBuffer * Returns {@link GL#mapBuffer(int, int)}'s {@link GLBufferStorage#getMappedBuffer()}.
+MethodJavadoc glMapBuffer * </p>
+MethodJavadoc glMapBuffer * @throws GLException if buffer is not bound to target
+MethodJavadoc glMapBuffer * @throws GLException if buffer is not tracked
+MethodJavadoc glMapBuffer * @throws GLException if buffer is already mapped
+MethodJavadoc glMapBuffer * @throws GLException if buffer has invalid store size, i.e. less-than zero
+MethodJavadoc glMapBuffer * </p>
+
 ManuallyImplement glMapBufferRange
 ForceProcAddressGen glMapBufferRange
+MethodJavadoc glMapBufferRange * <p>
+MethodJavadoc glMapBufferRange * Throws a {@link GLException} if GL-function constraints are not met.
+MethodJavadoc glMapBufferRange * </p>
+MethodJavadoc glMapBufferRange * <p>
+MethodJavadoc glMapBufferRange * Returns {@link GL#mapBufferRange(int, long, long, int)}'s {@link GLBufferStorage#getMappedBuffer()}.
+MethodJavadoc glMapBufferRange * </p>
+MethodJavadoc glMapBufferRange * <p>
+MethodJavadoc glMapBufferRange * @throws GLException if buffer is not bound to target
+MethodJavadoc glMapBufferRange * @throws GLException if buffer is not tracked
+MethodJavadoc glMapBufferRange * @throws GLException if buffer is already mapped
+MethodJavadoc glMapBufferRange * @throws GLException if buffer has invalid store size, i.e. less-than zero
+MethodJavadoc glMapBufferRange * @throws GLException if buffer mapping range does not fit, incl. offset
+MethodJavadoc glMapBufferRange * </p>
+
+ManuallyImplement glUnmapBuffer
+ForceProcAddressGen glUnmapBuffer
 
 # Ignore the ATI_map_object_buffer extension for now unless someone
 # claims they need it, as it will undoubtedly require a similar
@@ -550,15 +604,18 @@ JavaEpilogue glBindFramebuffer  _context.setBoundFramebuffer(target, framebuffer
 # 
 JavaPrologue glBegin inBeginEndPair = true;
 JavaEpilogue glEnd   inBeginEndPair = false;
-JavaEpilogue glBindBuffer       bufferStateTracker.setBoundBufferObject({0}, {1});
-JavaEpilogue glBindBufferARB    bufferStateTracker.setBoundBufferObject({0}, {1});
-JavaEpilogue glBindVertexArray  bufferStateTracker.setBoundBufferObject(GL2GL3.GL_VERTEX_ARRAY_BINDING, {0});
-JavaEpilogue glPushClientAttrib bufferStateTracker.clearBufferObjectState();
-JavaEpilogue glPushClientAttrib glStateTracker.pushAttrib(mask);
-JavaEpilogue glPopClientAttrib  bufferStateTracker.clearBufferObjectState();
-JavaEpilogue glPopClientAttrib  glStateTracker.popAttrib();
-JavaPrologue glBufferData       synchronized(bufferSizeTracker) {
-JavaEpilogue glBufferData       bufferSizeTracker.setBufferSize(bufferStateTracker, {0}, this, {1}); }
+
+JavaEpilogue glBindBuffer          bufferStateTracker.setBoundBufferObject({0}, {1});
+JavaEpilogue glBindBufferARB       bufferStateTracker.setBoundBufferObject({0}, {1});
+JavaEpilogue glBindBufferBase      bufferStateTracker.setBoundBufferObject({0}, {2});
+JavaEpilogue glBindBufferRange     bufferStateTracker.setBoundBufferObject({0}, {2});
+JavaEpilogue glBindVertexArray     bufferStateTracker.setBoundBufferObject(GL2GL3.GL_VERTEX_ARRAY_BINDING, {0});
+JavaEpilogue glPushClientAttrib    bufferStateTracker.clear();
+JavaEpilogue glPushClientAttrib    glStateTracker.pushAttrib(mask);
+JavaEpilogue glPopClientAttrib     bufferStateTracker.clear();
+JavaEpilogue glPopClientAttrib     glStateTracker.popAttrib();
+
+JavaPrologue glDeleteBuffers       bufferObjectTracker.notifyBuffersDeleted({0}, {1});
 
 BufferObjectKind Array glColorPointer
 BufferObjectKind Array glEdgeFlagPointer