NEWT: Fix AWT Parenting ; Multithreading Issues ; Semantics: destroy(…

…), .. ; Misc.

Due to incapabilities of the previous AWT/NEWT reparenting
the implementation and spec had to be changed to support this feature.
See the first 2 comments below.

- Tested on GNU/Linux (OK), Windows (a few bugs left)
-

TODO:
    - Clarify the size/layout issue, ie who is responsible etc
      In the test, incl AWT/NEWT, we set the size on the GLWindow
      and ie pack the AWT Frame.

    - Fix remaining [Windows] bugs ..

    - Fix/Implement MacOSX port ..

Fix AWT/NEWT reparenting:
===========================

- Now NewtFactory's createWindow() method for parenting handles NativeWindow only
  and is no more responsible for creating a child window upon an AWT Component.
  See class com.jogamp.newt.awt.NewtCanvasAWT for NEWT/AWT parenting.

- New com.jogamp.newt.awt.NewtCanvasAWT, responsible for handling
  AWT's reparent events via addNotify/removeNotify.
  Reparenting is implemented via the new NEWT Window's reparentWindow() method.
  Also sets the background erase to false, if supported.

- Fix zero size semantics in Window (setSize/setVisible)
  Since a zero size window is not supported by many compoenent (Windowing system, OpenGL, ..)
  we use the visibility methodology to not show a 0x0 window. See Javadoc.
  AWT components may start with zero size.

- New NEWT Window: reparentWindow(NativeWindow newParent, Screen newScreen)
  Allowing to change the parent of a window. Similar with the fullscreen toggle,
  but without size/position change.
  Native reparenting allows to keep alive the native
  window while changing the container, hence it is preferred to a destroy/create cycle.
  To benefit from the native reparenting, a NEWT implementation has to implement
    'protected boolean reparentWindowImpl(long newWindowHandle)'
  and return true, otherwise reparenting will be 'emulated' via
  the expensive destroy/create cycle.

- NEWT's Window references all of it's children, if any

- NEWT's Window propagates setVisible/destroy actions to it's children.

- Fix NEWT's destroy() semantics.
  A call of destroy() or destroy(false) shall only result in the destruction of the
  native window (handle) nothing more. A subsequent setVisible(true) shall allow
  the complete recreation of the Window into a usable state.
    A call of destroy(true) destroys all resources the Window holds,
  may include Screen/Display and OpenGL resources in case of GLWindow.
  This is necessary to allow proper reparenting, where a native window may become
  destroyed, but should be recreated via setVisible(true) later on.

- Fix NEWT set[Size|Position|Fullscreen|Visible] synchronization.
  Use a recursive lock instead of the Window instance, otherwise arbitrary Window access
  via AWT's EDT, NEWT's EDT or other threads can block.
  Also removed a use pattern like:
    key.lock()
    try {
        EDT.invoke(action());
    } finally {
        key.unlock();
    }
  Where action() itself uses the same lock object (here key), the result is a deadlock.

NativeWindow Changes:
======================

- We can use XInitThreads() now (concurrent threading support)
  in combination with AWT.
  Might have been some async in our NEWT locking in regards to AWT (sync()),
  and the X11 Display changes made in c787f50d77e2491eb0d8201d534a6fa4885a929e.

- NativeWindow's window handle is _not_ transient like surface handle,
  fixed documentation.

JOGL Changes:
=============

- New 'isRealized()' method in GLDrawable.

-
Misc Fixes
============
- Fix NEWT set[Size|Position|Fullscreen|Visible] duplicate code
  Due to pure abstract signatures, the set[Size|Position|Fullscreen|Visible]
  implementations of X11, OSX, .. contained duplicate code and state handling (size, pos, ..).
  These are now decoupled, ie generic set[Size|Position|Fullscreen|Visible] implementations
  calling simple set[Size|Position|Fullscreen|Visible]Impl implementations.

- Fix NEWT: Renamed setAutoDrawableClient(boolean) to setHandleDestroyNotify(boolean)
  The semantic of
    setAutoDrawableClient(boolean) defaults to false
  was too complicated and specific, hence changed to
    setHandleDestroyNotify(boolean) defaults to true
  since its more clear and the name refers the window itself..

- Fix NEWT: Removed GLWindow's unused global window list

- Fix NEWT: Remove Window's unused event mask

- Rename com.jogamp.newt.impl.awt.AWTNewtFactory -> com.jogamp.newt.awt.NewtFactoryAWT

src/nativewindow/classes/com/jogamp/nativewindow/impl/RecursiveToolkitLock.java

@@ -6,8 +6,8 @@
 // Reentrance locking toolkit
 // 
 public class RecursiveToolkitLock implements ToolkitLock {
-    private Thread owner;
-    private int recursionCount;
+    private Thread owner = null;
+    private int recursionCount = 0;
     private Exception lockedStack = null;
     private static final long timeout = 3000;  // maximum wait 3s
 
@@ -31,6 +31,10 @@ public synchronized boolean isLocked() {
         return null != owner;
     }
 
+    public synchronized int getRecursionCount() {
+        return recursionCount;
+    }
+
     /** Recursive and blocking lockSurface() implementation */
     public synchronized void lock() {
         Thread cur = Thread.currentThread();
@@ -49,10 +53,10 @@ public synchronized void lock() {
         }
         if(owner != null) {
             lockedStack.printStackTrace();
-            throw new RuntimeException("Waited "+timeout+"ms for: "+owner+" - "+cur);
+            throw new RuntimeException("Waited "+timeout+"ms for: "+owner+" - "+cur+", with recursionCount "+recursionCount+", lock: "+this);
         }
         owner = cur;
-        lockedStack = new Exception("Previously locked by "+owner);
+        lockedStack = new Exception("Previously locked by "+owner+", lock: "+this);
     }
 
 
@@ -62,7 +66,7 @@ public synchronized void unlock() {
     }
 
     /** Recursive and unblocking unlockSurface() implementation */
-    public synchronized void unlock(Runnable releaseAfterUnlockBeforeNotify) {
+    public synchronized void unlock(Runnable taskAfterUnlockBeforeNotify) {
         Thread cur = Thread.currentThread();
         if (owner != cur) {
             lockedStack.printStackTrace();
@@ -74,8 +78,8 @@ public synchronized void unlock(Runnable releaseAfterUnlockBeforeNotify) {
         }
         owner = null;
         lockedStack = null;
-        if(null!=releaseAfterUnlockBeforeNotify) {
-            releaseAfterUnlockBeforeNotify.run();
+        if(null!=taskAfterUnlockBeforeNotify) {
+            taskAfterUnlockBeforeNotify.run();
         }
         notifyAll();
     }