Fix: Locking/Threading; Common IntIntHashMap and Buffers; Fix: glMap*Buffer*; GLX/WGL/CgGL: All runtime dynamic; Misc ..

TODO: Compile and test on MacOSX ..

Fix:
=====

Multithreading/Locking:
    See jogl/doc/Implementation/MultiThreading.txt

    - Locking layer is not platform agnostic, ie GLContextImpl, GLDrawableImpl, ..
      and NEWT: Window/Display
    - No more use of JAWT global lock necessary, removed.
    - No need for X11 Display lock, on the contrary,
      this made the NV driver hang.
    - Use common window/surface lock
    - All NativeWindow surfaceLock's are recursive now

glMapBuffer: If size is 0, don't do cont with the native call.
glMapBufferRange: Fix capacity.
glNamedBufferDataEXT: Track the size.
glMapNamedBufferEXT: Manual impl. - use the tracked size

glXGetVisualFromFBConfig, glXChooseFBConfig, glXChooseVisual: Instead of
ignoring and implement a renamed version (*Copied), we just use ManualImplementation
for the proper copy-result code.

DesktopGLDynamicLookupHelper: Initialize _hasGLBinding* attributes
in the determing loadGLJNILibrary() method, which is called by super().
Otherwise static init will overwrite them after the super() call.

X11GLXDrawableFactory: Don't release anything at shutdown (removed sharedContext.destroy()),
since this caused a freeze/SEGV sometimes.

Fixed NEWT's reparentWindow() functionality incl NewtCanvasAWT usage.
    - Native: if not visible, don't focus, etc
    - NewtCanvasAWT: Use the container size to start with
    - Run the command on the EDT

Using GlueGen's new DynamicLibraryBundle utility:
  - X11, Windows and MacOSX OpenGL adapted to DynamicLibraryBundleInfo.
  - X11GLXDynamicLookupHelper -> X11GLXDynamicLibraryBundleInfo
    - Remove all path from lib names.
    - GL order:  libGL.so.1, libGL.so, GL
    - shallLinkGlobal: true -> to server some 'old' DRI systems
        -> http://dri.sourceforge.net/doc/DRIuserguide.html
    - shallLookupGlobal: false
    - Try both : glXGetProcAddressARB and glXGetProcAddress
    - Using bootstrap: GLX.glXGetProcAddress(long glxGetProcAddressHandle, String glFuncName)

Found the issue with LIBGL_DRIVERS_PATH, ie if not set
no valid GL instance can be found (ie ATI fglrx/DRI).
This may happen if using a differen user than the desktop user
for whom the env var is set within some /etc/X11/Xsession.d/ script.

Enhancements:
=============

GLBufferSizeTracker: Use IntIntHashMap and add DirectState size tracking.
GLBufferStateTracker: Use IntIntHashMap.
GLStateTracker: Use IntIntHashMap.

GLDynamicLookupHelper: More generic (global loading/lookup and GetProcAddress function name list),
                       remove redundant code.
   FIXME:
    MacOSXCGLDynamicLookupHelper:
        - Not tested
        - Not using NSImage lookup anymore as recommended by OSX API Doc,
          so dlsym is used always (to be tested)

    WindowsWGLDynamicLookupHelper:
        - Not tested

GLX/WGL/CgGL is all runtime-dynamic as now, ie loaded and looked-up at runtime,
no compile time dependencies to GL anymore, nor a need to specify CgGL.

Split up WGL in GDI and WGL, to allow proper dynamic runtime linkage of OpenGL32
while using static binding to GDI32

NEWT events generated by native code are enqueued and not send directly.
This should ease locking mechanisms .. if any are necessary.

NEWT: More platform specific code moved to *Impl method,
simplifying the generic code of the superclass and impl protocol.

Cleanup:
=========

Replace all InternalBufferUtil's with com.jogamp.common.nio.Buffers

Removed all InternalBufferUtil's from repository

Removed GLContextImpl notion of 'optimized' surface locking,
where the surface gets unlocked during makeCurrent/release.
This just makes no sense and would impact multithreading in a horrible way.

1 files changed, 94 insertions, 0 deletions

diff --git a/doc/Implementation/MultiThreading.txt b/doc/Implementation/MultiThreading.txt
new file mode 100644
index 000000000..fb586e1ec
--- /dev/null
+++ b/doc/Implementation/MultiThreading.txt
@@ -0,0 +1,94 @@
+
+Locking
+=========
+
+Interface AbstractGraphicsDevice: lock() / unlock()
+
+    - Used to exclusively lock the device
+    - Current implementations: 
+        - X11GraphicsDevice: XLockDisplay/XUnlockDisplay
+
+    - Shall only be used, where race conditions may happen with
+      device toolkit calls in regards to windowing resources,
+      ie create/destroy .. etc
+
+    - We call XInitThreads ASAP and a global X11 lock 
+      is not necessary.
+
+    - To ensure XInitThreads can be issued at first,
+      GLProfile.initSingleton() shall be called
+      in the static initializer block of the main class.
+
+      TODO: 
+      However, we have to investigate how to incooperate this
+      with Applet loading.
+      If such call ain't possible, a workaround could be to not
+      call XInitThreads() and utilize AWT locks.
+
+Interface NativeWindow: lockSurface() / unlockSurface()
+
+    - Used to exclusively lock the surface
+
+    - Implementations: 
+
+        - JAWTWindow:
+            - Recursive Lock
+            - JAWT SurfaceLock
+
+        - NEWT Window:
+            - Recursive Lock
+            - May have platform specific surface lock, currently: None
+
+
+GLContext/GLDrawable Locking:
+
+    - MakeCurrent: NativeWindow:lockSurface()
+    - Release: NativeWindow:unlockSurface()
+
+    - Create/Destroy/Realize/Swap: 
+        - NativeWindow:lockSurface()
+            - CreateImpl/DestroyImpl/Realize/Swap
+        - NativeWindow:unlockSurface()
+
+    - The Window impl. class shall lock the window recursive lock
+      for all modifying operations.
+      This should be the same lock as surfaceHandle!
+
+
+Summary:
+
+    Locking is implemented in the platform agnostic code layer.
+
+    Locks and Order:
+        1: - NativeWindow Surface/Window Lock
+            - Locked: 
+                - [makeCurrent .. release]
+                - create/destroy  
+
+    GLContextImpl:
+        - makeCurrent
+            - Surface i       - out only in error
+
+        - release
+            - Surface o - makeCurrentImpl
+
+        - create
+            - Surface i/o
+
+        - destroy
+            - Surface i/o
+
+        - copy
+            - Surface i/o
+
+        - setSwapIntervalImpl
+            - Surface i/o
+
+
+    GLDrawableImpl
+        - setRealizedImpl
+            - Surface i/o
+
+        - swapBuffersImpl
+            - [Surface i/o] - if not locked already
+