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, 43 insertions, 4 deletions

diff --git a/make/config/jogl/gl-gl4bc.cfg b/make/config/jogl/gl-gl4bc.cfg
index 48ecb7378..6ccbace44 100644
--- a/make/config/jogl/gl-gl4bc.cfg
+++ b/make/config/jogl/gl-gl4bc.cfg
@@ -55,12 +55,51 @@ Include gl3-desktop.cfg
 Include gl3-common.cfg
 Include gl2_es2-CustomJavaCode.cfg
 
-# Manually implement glMapNamedBufferEXT 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 glNamedBufferDataEXT
+ForceProcAddressGen glNamedBufferDataEXT
+MethodJavadoc glNamedBufferDataEXT * <p>
+MethodJavadoc glNamedBufferDataEXT * Throws a {@link GLException} if GL-function constraints are not met or the native GL-function fails.
+MethodJavadoc glNamedBufferDataEXT * </p>
+MethodJavadoc glNamedBufferDataEXT * <p>
+MethodJavadoc glNamedBufferDataEXT * @throws GLException if size is less-than zero
+MethodJavadoc glNamedBufferDataEXT * @throws GLException if a native GL-Error occurs
+MethodJavadoc glNamedBufferDataEXT * </p>
+
 ManuallyImplement glMapNamedBufferEXT
 ForceProcAddressGen glMapNamedBufferEXT
-JavaPrologue glNamedBufferDataEXT synchronized(bufferSizeTracker) {
-JavaEpilogue glNamedBufferDataEXT bufferSizeTracker.setDirectStateBufferSize({0}, this, {1}); }
+MethodJavadoc glMapNamedBufferEXT * <p>
+MethodJavadoc glMapNamedBufferEXT * Throws a {@link GLException} if GL-function constraints are not met.
+MethodJavadoc glMapNamedBufferEXT * </p>
+MethodJavadoc glMapNamedBufferEXT * <p>
+MethodJavadoc glMapNamedBufferEXT * Returns {@link GL2#mapNamedBuffer(int, int)}'s {@link GLBufferStorage#getMappedBuffer()}.
+MethodJavadoc glMapNamedBufferEXT * </p>
+MethodJavadoc glMapNamedBufferEXT * <p>
+MethodJavadoc glMapNamedBufferEXT * @throws GLException if buffer is not tracked
+MethodJavadoc glMapNamedBufferEXT * @throws GLException if buffer is already mapped
+MethodJavadoc glMapNamedBufferEXT * @throws GLException if buffer has invalid store size, i.e. less-than zero
+MethodJavadoc glMapNamedBufferEXT * </p>
+
+ManuallyImplement glMapNamedBufferRangeEXT
+ForceProcAddressGen glMapNamedBufferRangeEXT
+MethodJavadoc glMapNamedBufferRangeEXT * <p>
+MethodJavadoc glMapNamedBufferRangeEXT * Throws a {@link GLException} if GL-function constraints are not met.
+MethodJavadoc glMapNamedBufferRangeEXT * </p>
+MethodJavadoc glMapNamedBufferRangeEXT * <p>
+MethodJavadoc glMapNamedBufferRangeEXT * Returns {@link GL2#mapNamedBufferRange(int, long, long, int)}'s {@link GLBufferStorage#getMappedBuffer()}.
+MethodJavadoc glMapNamedBufferRangeEXT * </p>
+MethodJavadoc glMapNamedBufferRangeEXT * <p>
+MethodJavadoc glMapNamedBufferRangeEXT * @throws GLException if buffer is not tracked
+MethodJavadoc glMapNamedBufferRangeEXT * @throws GLException if buffer is already mapped
+MethodJavadoc glMapNamedBufferRangeEXT * @throws GLException if buffer has invalid store size, i.e. less-than zero
+MethodJavadoc glMapNamedBufferRangeEXT * @throws GLException if buffer mapping range does not fit, incl. offset
+MethodJavadoc glMapNamedBufferRangeEXT * </p>
+
+ManuallyImplement glUnmapNamedBufferEXT
+ForceProcAddressGen glUnmapNamedBufferEXT
 
 # Manuall implement glDebugMessageCallback* using the proc address resolver
 ForceProcAddressGen glDebugMessageCallback