Bug 1033: Guarantee atomicity of high-level GLAutoDrawable operations, avoiding race conditions.

GLAutoDrawable (API CHANGE) allowing atomic operations:
  - Add class API-doc chapter about 'GLAutoDrawable Locking'

  - Add method invoke(..) API-doc description about throwing IllegalStateException in case of a detected deadlock situation ahead
    (Note: Implemented in GLDrawableHelper.invoke(..) for all implementations)

  - Add new methods for proper multithread handling:
    - public RecursiveLock getUpstreamLock();
    - public boolean isThreadGLCapable();

+++

GLEventListenerState/GLDrawableUtil:

  - Perform operation in a atomic fashion,
    i.e. lock GLAutoDrawable during whole operations:
      - GLDrawableUtil.swapGLContext(..)
      - GLDrawableUtil.swapGLContextAndAllGLEventListener(..)
      - GLEventListenerState.moveFrom(..)
      - GLEventListenerState.moveTo(..)

  - ReshapeGLEventListener:
    - Moved from GLEventListenerState.ReshapeGLEventListener -> GLDrawableUtil.ReshapeGLEventListener
    - Takes 'displayAfterReshape' case into account.

+++

javax.media.opengl.Threading Clarifications:
  - Public 'enum Mode', i.e. Threading.Mode

  - Public getMode()

  - Clarified 'isOpenGLThread()':
    - Take 'singleThreaded' into account directly,
      i.e. always return 'true' if singleThreaded == false
Fixed and Changed NVidia Windows Driver Threaded optimization bug workaround of commit 5166d6a6b617ccb15c40fcb8d4eac2800527aa7b

Commit 5166d6a6b617ccb15c40fcb8d4eac2800527aa7b added a workaround
for the NVidia driver 260.99 for Window from 2010-12-11 issue.

[1] The workaround sets a process affinity while JOGL initialization
to mitigate NVidia driver's 'Threaded optimization := On' race conditions.
The process affinity is reset reset after initialization.

[2] The process affinity reset code had a bug, i.e. instead to restore the
original process's affinity mask, we restored the system's default affinity mask.

[3] Further more, there seem to be issues with changing a process affinity mask
regarding the process group.

This patch:
  - Solves issue [2] by using the original process affinity mask

  - Solves issue [3] by allowing a custom
    affinity mode via the property 'jogl.debug.windows.cpu_affinity_mode':

      - 0 - none (default, no affinity required for Windows NV driver >= 266.58 from 2011-01-24)
      - 1 - process affinity (was required w/ Windows NV driver 260.99 from 2010-12-11, see commit 5166d6a6b617ccb15c40fcb8d4eac2800527aa7b)
      - 2 - thread affinity (experimental)

    Hence the workaround is disabled by default,
    since the crash as dicumented in commit 5166d6a6b617ccb15c40fcb8d4eac2800527aa7b
    could not be reproduced with NV driver 266.58 from 2011-01-24.
Bug 1035 - Allow Gamma [Brightness, Contrast] settings to be performed on display/screen of a NativeSurface

Currently GLDrawableFactoryImpl's gamma settings are performed
only on the main screen.

Allow passing a NativeSurface, so it's display/screen
gamma values will be changed.

Further, promote low-level gamma settings to GLDrawableFactory
for direct usage.

Change com.jogamp.opengl.util.Gamma to use a GLDrawable
instead of a GL object to clarify that we use the drawable.

Also add a GLAutoDrawable variant, allowing proper locking
of its 'upstream-lock' to guarantee atomicity.

+++

Tested manually w/ TestGearsES2NEWT on X11 and Windows
using the 'g' and 'G' to modify gamma.
Value is properly reset on exit.
Bug 1029 - Memory leak in GLDrawableHelper: 'perThreadInitAction' shall use a WeakReference

Static ThreadLocal 'perThreadInitAction' leaks memory if using a hard reference,
utilizing a WeakReference allows the passed 'initAction' owner to be garbage collected.
Bug 1037 - FBObject/GLFBODrawable: Do not assume using a TextureAttachment for a Colorbuffer, also make DEPTH optional.

API Change

+++

In certain cases a TextureAttachment for the FBO's color buffer
is not desired, either for performance reasons where texture functionality
is not required or to avoid texture restrictions like size, etc.

+++

GLFBODrawable shall use TextureAttachment for the FBO's color buffer
and a DEPTH buffer per default.
However, the user shall be allowed to use a plain ColorAttachment (renderbuffer)
and also no DEPTH buffer.

+++

FBObject Details:
 - Colorbuffer interface exposes Attachment details
   like format, size, etc as well as it's implementation
   specifics, isTextureAttachment() and getTextureAttachment() allowing a clean cast and type query.

 - Allow ColorAttachment to be used for non MSAA

 - Make TextureAttachment optional for method 'use(GL, TextureAttachment)'

 - Only validate size against MAX_TEXTURESIZE if using a TextureAttachment

 - API Change:
   - rename: getColorAttachmentCount() -> getColorbufferCount()
   - add: getTextureAttachmentCount()
   - change 'TextureAttachment getSamplingSink()' -> 'Colorbuffer getSamplingSink()'