Changes

API doc: GLStateKeeper (wording), GLAutoDrawable (enh. init desc.), GLDrawable (Shared Context)

spec-overview.html: Shared OpenGL context must be supported .. (GL spec)

Bug 776 GLContext Sharing: Refine API for relaxed and lazy GLContext sharing ; Fix GLContext memory contract (volatile)

(Unit test remarks see below)

- Add shared GLContext queries
  - Refined GLContextShareSet:
    - Use IdentityHashMap since GLContext's can only be identical w/ same reference (footprint, performance)
    - Add API doc for clarification
    - Add methods:
       - ArrayList<GLContext> getCreatedShares(final GLContext context)
       - ArrayList<GLContext> getDestroyedShares(final GLContext context)
    - Use 'final' where possible

  - Add GLContext methods:
      - boolean isShared()
      - List<GLContext> getCreatedShares()
      - List<GLContext> getDestroyedShares()

- Add GLSharedContextSetter interface defining setting a shared GLContext
  directly (GLContext) or via a GLAutoDrawable:
  - setSharedContext(GLContext)
  - setSharedAutoDrawable(GLAutoDrawable)

  Both cause initialization/creation of GLAutoDrawable's drawable/context to be postponed,
  if the shared GLContext is not yet created natively or
  the shared GLAutoDrawable's GLContext does not yet exist.

  Most of impl. resides in GLDrawableHelper

  Implemented in:
    - GLAutoDrawableBase, GLOffscreenAutoDrawable
    - GLWindow
    - AWT GLCanvas

  TODO:
    - GLJPanel
    - SWT GLCanvas

- GLDrawableFactory:
   - Add 'GLOffscreenAutoDrawable createOffscreenAutoDrawable(..)' variant w/o passing the
     optional shared GLContext _and_ specifying lazy GLContext
     creation. This allows to benefit from GLSharedContextSetter contract.
     Lazy GLContext creation is performed at 2st display() call at the latest.

     All JOGL code and unit tests use this new method now.

  - Mark 'createOffscreenAutoDrawable(..)' w/ shared GLContext argument
    and immediate GLContext creation deprecated - shall be removed in 2.2.0

- Make reference to GLContext and it's native handle volatile
  Since we rely on the query 'GLContext.isCreated()' to properly allow GLAutoDrawable's to query whether
  a shared GLContext is natively created (already), the handle must be volatile
  since such query and the actual creation may operate on different threads.

+++++

- Add/Refine shared GLContext unit tests demonstrating diff. sharing methods.

  All variants of using shared GLContext:
      com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBO*

  Most convenient way to share via setSharedAutoDrawable(GLAutoDrawable):
      com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2[NEWT|AWT]3

  AWT use w/ JTabbedPane using setSharedAutoDrawable(GLAutoDrawable):
      com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextWithJTabbedPaneAWT

Fix GLCanvas ctor shared GLContext: Use helper.setSharedContext(..) remove local shared ctx fields.

Regression of 7f7a23dd0ddf106e6f0c69fc2a05ff92ac56200e

Bug 776 GLContext Sharing: Add GLSharedContextSetter to GLJPanel

Bug 776 GLContext Sharing: Add note about driver stability (destruction order) ; Fix unit tests (Shared Gears, wait for created context and destruction order)

- Add note about driver stability (destruction order)
  - See GLSharedContextSetter: Don't destroy master context before slaves!

- Fix spec-overview.html#SHARED links, add link to GLSharedContextSetter in SHARED subsection.

- Fix unit tests (Shared Gears, wait for created context and destruction order)
  - The GearsObject sharing was completly bogus!
    It simply used the _same_ GLArrayDataServer instance for sharing,
    but it should use a _copy_ of the shared GLArrayDataServer while
    only preserving the VBO object!
    Fixed, while adding required methods to GLArrayDataServer.

  - Waiting for the created GLContext of a GLAutoDrawable required us
    to pass the latter _and_ check whether it's GLContext exists and is natively created.

  - Accomodated the destruction order - see above!

Bug 776 GLContext Sharing: Add GLSharedContextSetter to SWT GLCanvas

GLDrawableHelper.reshape(): Catch pre-existing GL errors before glViewport(..) and dump it (Add stack trace if DEBUG)

Fix TestSharedContextNewtAWTBug523: Don't use VAO's w/ GL2 context - No VAO on GL2 ctx on OSX ; GLWindow #2 shall also use sharedDrawable; Cleanup  ..

Bug 876: BuildComposablePipeline: getGL*() shall not return downstream.getGL*() [TraceGL* / DebugGL*] ; Simplify GLContextImpl's set Debug/Trace Pipeline

Regression of commit 0002fccdcd6383874b2813dc6bbe3e33f5f00924:
  "Trace/Debug shall utilize downstream identification for isGL*() and getGL*() methods."

  Using the downstream identification commit is right for the isGL*() case,
  however, getGL*() returned the downstream object which makes the caller loosing the pipeline!

  Instead, we shall produce !GEN_GL_IDENTITY_BY_ASSIGNABLE_CLASS:

     "if( isGL<type>() ) { return this; }
     throw new GLException("Not a <type> implementation");"

  or for GEN_GL_IDENTITY_BY_ASSIGNABLE_CLASS:

     "return this;"

GLDrawableFactory: Add 'GLAutoDrawable createDummyAutoDrawable(..)' for convenience

Added:
  GLAutoDrawable createDummyAutoDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLProfile glp)

Bug 776 GLContext Sharing: Add copy-ctor to GLArrayData* w/ sliced Buffer; Refine GearsObject* GLArrayDataServer copying; GearsES*: Init VBO eagerly

Add copy-ctor to GLArrayData* w/ sliced Buffer to allow general sharing of VBO via these high-level types.

Refine GearsObject* GLArrayDataServer copying (commit bcfaa149b9803ce33c5a356cbcb45f7dfd3e4361):
  Utilize new GLArrayData* copy-ctor.

GearsES*: Init VBO eagerly, allowing VBO usage after init(..).

Fix #875 - ES version should be strictly validated

When initializing the context in GLContextImpl.setGLFuncAvailability
ES devices must be validated by strictly matching the major version,
otherwise on ES3 devices we were mixing ES1 implementation with ES3
contexts, ultimately crashing in a safeguard.

Signed-off-by: Brice Figureau <brice@daysofwonder.com>

Bug 877 Concurrency Discussion: Update doc MultiThreading.txt, volatile field usage; GLDrawableImpl: Make read-only fields final.

Bug 776 GLContext Sharing: Fix copy-ctor GLArrayDataClient: Create new instance of GLArrayHandler of same type; Simplify GLArrayHandler inheritance.

Refines commit 9f2a9df0a4b7093925c8854b37fba053469a4b35

Bug 776 GLContext Sharing: GLSharedContextSetter API Doc: No 'Driver stability constraints' ; Fixing Test cases: Enable all, GearsObject*: Check VBO

- GLSharedContextSetter API Doc: No 'Driver stability constraints'
  - No driver issues ..
  - Use 'Lifecycle Considerations' to describe usage issues ..

- Fixing Test cases: Enable all, GearsObject*: Check VBO
  - GearsObject* needs to check whether VBO is 'still alive'
    if sharing is enabled.

  - Enable all unit tests.

Bug 776 GLContext Sharing: GLSharedContextSetter API Doc: Add 'glFinish()' to lifecycle considerations ; GearsES2: Add glFinish() after init().

Bug 875: Safeguard setGLFunctionAvailability(.. strictMatch=false.. ) operation, throw InternalError if failing

Fix Bug 875 - Cleanup branch using VersionNumber (fix 'Int' check strictMatch minor) and reuse isES; EGLContext: Use strictMatch for setGLFunctionAvailability() and handle failure; EGLDrawableFactory: Either detect ES3 or ES2.

- Cleanup branch using VersionNumber (fix 'Int' check strictMatch minor) and reuse isES

- EGLContext: Use strictMatch for setGLFunctionAvailability() and handle failure
  On ES, we require strictMatch, cleanup if failing.

- EGLDrawableFactory: Either detect ES3 or ES2.
  Both only available with proper EGL context creation for ES profiles (TODO)

Android NEWT.ScreenDriver MonitorSize: Use xdpi for for width (fix); Add DEBUG output.

Add GLES1Impl 'finalizeInit()' to avoid a 'catched exception roundtrip'

Fix Unit Test Regression (commit 9f2a9df0a4b7093925c8854b37fba053469a4b35): GearsObject used getGL2ES2(), which is not allowed.

TestSharedContextVBOES2NEWT1: Fix copy/paste (mistakenly used sharedGears), add println; GearsES: Add init/shared state to 'toString()'

Add functions for converting to and from binary16 half-precision floating point values. Derived from http://mvn.io7m.com/ieee754b16, of which I am the original author.