NewtFactory/GLWindow: Cleanup API doc (Display lifecycle, copy or reuse, etc ..)

2 files changed, 102 insertions, 22 deletions

diff --git a/src/newt/classes/com/jogamp/newt/NewtFactory.java b/src/newt/classes/com/jogamp/newt/NewtFactory.java
index f38876128..2a8a8182d 100644
--- a/src/newt/classes/com/jogamp/newt/NewtFactory.java
+++ b/src/newt/classes/com/jogamp/newt/NewtFactory.java
@@ -85,53 +85,120 @@ public class NewtFactory {
     public static boolean useEDT() { return useEDT; }
 
     /**
-     * Create a Display entity, incl native creation
+     * Create a Display entity.
+     * <p>
+     * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
+     * </p>
+     * <p>
+     * An already existing display connection of the same <code>name</code> will be reused.  
+     * </p>
+     * @param name the display connection name
+     * @return the new or reused Display instance
      */
     public static Display createDisplay(String name) {
         return createDisplay(name, true);
     }
 
+    /**
+     * Create a Display entity.
+     * <p>
+     * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
+     * </p>
+     * <p>
+     * An already existing display connection of the same <code>name</code> will be reused
+     * <b>if</b> <code>reuse</code> is <code>true</code>, otherwise a new instance is being created.
+     * </p>
+     * @param name the display connection name
+     * @param reuse attempt to reuse an existing Display with same <code>name</code> if set true, otherwise create a new instance.
+     * @return the new or reused Display instance
+     */
     public static Display createDisplay(String name, boolean reuse) {
       return DisplayImpl.create(NativeWindowFactory.getNativeWindowType(true), name, 0, reuse);
     }
 
     /**
-     * Create a Display entity using the given implementation type, incl native creation
+     * Create a Display entity.
+     * <p>
+     * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
+     * </p>
+     * <p>
+     * An already existing display connection of the same <code>name</code> will be reused.
+     * </p>
+     * @param type explicit NativeWindow type eg. {@link NativeWindowFactory#TYPE_AWT}
+     * @param name the display connection name
+     * @return the new or reused Display instance
      */
     public static Display createDisplay(String type, String name) {
         return createDisplay(type, name, true);
     }
 
+    /**
+     * Create a Display entity.
+     * <p>
+     * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
+     * </p>
+     * <p>
+     * An already existing display connection of the same <code>name</code> will be reused
+     * <b>if</b> <code>reuse</code> is <code>true</code>, otherwise a new instance is being created.
+     * </p>
+     * @param type explicit NativeWindow type eg. {@link NativeWindowFactory#TYPE_AWT}
+     * @param name the display connection name
+     * @param reuse attempt to reuse an existing Display with same <code>name</code> if set true, otherwise create a new instance.
+     * @return the new or reused Display instance
+     */
     public static Display createDisplay(String type, String name, boolean reuse) {
       return DisplayImpl.create(type, name, 0, reuse);
     }
 
     /**
-     * Create a Screen entity, incl native creation
+     * Create a Screen entity.
+     * <p>
+     * Native creation is lazily done at usage, ie. {@link Screen#addReference()}.
+     * </p>
+     * <p>
+     * The lifecycle of this Screen's Display is handled via {@link Display#addReference()}
+     * and {@link Display#removeReference()}.
+     * </p>
      */
     public static Screen createScreen(Display display, int index) {
       return ScreenImpl.create(display, index);
     }
 
     /**
-     * Create a top level Window entity, incl native creation.<br>
-     * The Display/Screen is created and owned, ie destructed atomatically.<br>
-     * A new Display is only created if no preexisting one could be found via {@link Display#getLastDisplayOf(java.lang.String, java.lang.String, int)}.
+     * Create a top level Window entity on the default Display and default Screen.
+     * <p>
+     * Native creation is lazily done at usage, ie. {@link Window#setVisible(boolean)}.
+     * </p>
+     * <p>
+     * An already existing default Display will be reused.
+     * </p>
+     * <p>
+     * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
+     * and {@link Screen#removeReference()}.
+     * </p>
      */
     public static Window createWindow(CapabilitiesImmutable caps) {
         return createWindowImpl(NativeWindowFactory.getNativeWindowType(true), caps);
     }
 
     /**
-     * Create a top level Window entity, incl native creation
+     * Create a top level Window entity.
+     * <p>
+     * Native creation is lazily done at usage, ie. {@link Window#setVisible(boolean)}.
+     * </p>
+     * <p>
+     * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
+     * and {@link Screen#removeReference()}.
+     * </p>
      */
     public static Window createWindow(Screen screen, CapabilitiesImmutable caps) {
         return createWindowImpl(screen, caps);
     }
 
     /**
-     * Create a child Window entity attached to the given parent, incl native creation.<br>
-     * The Screen and Display information is regenerated utilizing the parents information.<br>
+     * Create a child Window entity attached to the given parent.<br>
+     * The Screen and Display information is regenerated utilizing the parents information,
+     * while reusing an existing Display.<br>
      * <p>
      * In case <code>parentWindowObject</code> is a {@link com.jogamp.newt.Window} instance,<br>
      * the new window is added to it's list of children.<br>
@@ -143,6 +210,10 @@ public class NewtFactory {
      * In case <code>parentWindowObject</code> is a different {@link javax.media.nativewindow.NativeWindow} implementation,<br>
      * you have to handle all events appropriate.<br></p>
      * <p>
+     * <p>
+     * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
+     * and {@link Screen#removeReference()}.
+     * </p>
      *
      * @param parentWindowObject either a NativeWindow instance
      */
diff --git a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
index b2a44dbf6..d03a475ee 100644
--- a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
+++ b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
@@ -122,12 +122,13 @@ public class GLWindow implements GLAutoDrawable, Window, NEWTEventConsumer, FPSC
     }
 
     /**
-     * Creates a new GLWindow attaching a new Window referencing a new Screen
-     * with the given GLCapabilities.
-     * <P>
-     * The resulting GLWindow owns the Window, Screen and Device, ie it will be destructed.
-     * <P>
-     * The default display connection will be used and reused if already in process.  
+     * Creates a new GLWindow attaching a new Window referencing a 
+     * new default Screen and default Display with the given GLCapabilities.
+     * <p>
+     * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
+     * and {@link Screen#removeReference()}.
+     * </p>
+     * The default Display will be reused if already instantiated.  
      */
     public static GLWindow create(GLCapabilitiesImmutable caps) {
         return new GLWindow(NewtFactory.createWindow(caps));
@@ -136,8 +137,10 @@ public class GLWindow implements GLAutoDrawable, Window, NEWTEventConsumer, FPSC
     /**
      * Creates a new GLWindow attaching a new Window referencing the given Screen
      * with the given GLCapabilities.
-     * <P>
-     * The resulting GLWindow owns the Window, ie it will be destructed.
+     * <p>
+     * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
+     * and {@link Screen#removeReference()}.
+     * </p>
      */
     public static GLWindow create(Screen screen, GLCapabilitiesImmutable caps) {
         return new GLWindow(NewtFactory.createWindow(screen, caps));
@@ -145,8 +148,10 @@ public class GLWindow implements GLAutoDrawable, Window, NEWTEventConsumer, FPSC
 
     /** 
      * Creates a new GLWindow attaching the given window.
-     * <P>
-     * The resulting GLWindow does not own the given Window, ie it will not be destructed. 
+     * <p>
+     * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
+     * and {@link Screen#removeReference()}.
+     * </p>
      */
     public static GLWindow create(Window window) {
         return new GLWindow(window);
@@ -155,11 +160,15 @@ public class GLWindow implements GLAutoDrawable, Window, NEWTEventConsumer, FPSC
     /** 
      * Creates a new GLWindow attaching a new child Window 
      * of the given <code>parentNativeWindow</code> with the given GLCapabilities.
-     * <P>
+     * <p>
      * The Display/Screen will be compatible with the <code>parentNativeWindow</code>,
      * or even identical in case it's a Newt Window.
-     * <P>
-     * The resulting GLWindow owns the Window, ie it will be destructed. 
+     * An already instantiated compatible Display will be reused.  
+     * </p>
+     * <p>
+     * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
+     * and {@link Screen#removeReference()}.
+     * </p>
      */
     public static GLWindow create(NativeWindow parentNativeWindow, GLCapabilitiesImmutable caps) {
         return new GLWindow(NewtFactory.createWindow(parentNativeWindow, caps));