Doc NEWT-Overview: Add notion about Window Parenting

1 files changed, 56 insertions, 0 deletions

diff --git a/doc/NEWT-Overview.html b/doc/NEWT-Overview.html
index 4f8f71870..953f95b54 100644
--- a/doc/NEWT-Overview.html
+++ b/doc/NEWT-Overview.html
@@ -113,6 +113,62 @@ See it <a href="/deployment/jogamp-next/jogl-test-applets.html"><i>alive</i> her
     [<a href="">v2.0-rc3</a>]
 -->
 
+<h4>Native Window Reparenting Details</h4>
+
+NEWT's reparenting algorithm only issues a <i>destroy</i> if:
+<ul>
+  <li>Becomes CHILD-Window
+  <ul>
+    <li>new parent window is not realized yet, 
+      i.e. parent's window handle is null</li>
+
+    <li>forceRecreate</li>
+
+    <li>moving to a new incompatible screen/device</li>
+  </ul></li>
+
+  <li>Becomes TOP-Level-Window
+  <ul> 
+    <li>forceRecreate</li>
+  </ul></li>
+
+  <li>reparenting failed</li>
+</ul>
+
+In case <i>destroy</i> is issued, recreation will follow
+as soon as the new parent window handle becomes available
+or the instant if becoming a top-level window.
+
+<p>
+In case <i>destroy</i> must be issued, the hint <i>REPARENT_HINT_BECOMES_VISIBLE</i>
+will preserve the GLState at destroy, see below.
+</p>
+
+<p>
+To avoid <i>destroy</i> <b>and</b> the GLState preservation,
+the NEWT window shall simply be reparented before 
+parent's destruction. This is true for 'window hopping' 
+as well as child->top transition.
+
+See TestParenting04AWT for example ..
+</p>
+
+
+<h5>Using GLState Preservation</h5>
+
+A preserved GLState will be recovered when the resource gets recreated,
+e.g. the parent window becomes visible again.
+This mechanism exists to sooth the <i>destroy</i> case.
+
+See: GLStateKeeper, GLEventListenerState
+
+Regularly Used in the following use cases:
+<ul>
+  <li>OSX CALayer/Top-Level NEWT reparenting</li>
+  <li>Android GLState preservation: 'Home Button', 'Rotation' ..</li>
+</ul>
+
+
 <h4>How to pass user input back to the rendering loop ?</h4>
 
 The following example shows you how to use a fifo to pipe events from the EDT (listener) to the rendering loop.