From 8a7ebf29156ac886a267fe32d78baede009a638f Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Sat, 26 Nov 2011 06:14:35 +0100 Subject: NewtFactory/GLWindow: Cleanup API doc (Display lifecycle, copy or reuse, etc ..) --- src/newt/classes/com/jogamp/newt/NewtFactory.java | 89 +++++++++++++++++++--- .../classes/com/jogamp/newt/opengl/GLWindow.java | 35 +++++---- 2 files changed, 102 insertions(+), 22 deletions(-) (limited to 'src/newt/classes') 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. + *

+ * Native creation is lazily done at usage, ie. {@link Display#addReference()}. + *

+ *

+ * An already existing display connection of the same name will be reused. + *

+ * @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. + *

+ * Native creation is lazily done at usage, ie. {@link Display#addReference()}. + *

+ *

+ * An already existing display connection of the same name will be reused + * if reuse is true, otherwise a new instance is being created. + *

+ * @param name the display connection name + * @param reuse attempt to reuse an existing Display with same name 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. + *

+ * Native creation is lazily done at usage, ie. {@link Display#addReference()}. + *

+ *

+ * An already existing display connection of the same name will be reused. + *

+ * @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. + *

+ * Native creation is lazily done at usage, ie. {@link Display#addReference()}. + *

+ *

+ * An already existing display connection of the same name will be reused + * if reuse is true, otherwise a new instance is being created. + *

+ * @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 name 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. + *

+ * Native creation is lazily done at usage, ie. {@link Screen#addReference()}. + *

+ *

+ * The lifecycle of this Screen's Display is handled via {@link Display#addReference()} + * and {@link Display#removeReference()}. + *

*/ public static Screen createScreen(Display display, int index) { return ScreenImpl.create(display, index); } /** - * Create a top level Window entity, incl native creation.
- * The Display/Screen is created and owned, ie destructed atomatically.
- * 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. + *

+ * Native creation is lazily done at usage, ie. {@link Window#setVisible(boolean)}. + *

+ *

+ * An already existing default Display will be reused. + *

+ *

+ * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()} + * and {@link Screen#removeReference()}. + *

*/ 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. + *

+ * Native creation is lazily done at usage, ie. {@link Window#setVisible(boolean)}. + *

+ *

+ * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()} + * and {@link Screen#removeReference()}. + *

*/ 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.
- * The Screen and Display information is regenerated utilizing the parents information.
+ * Create a child Window entity attached to the given parent.
+ * The Screen and Display information is regenerated utilizing the parents information, + * while reusing an existing Display.
*

* In case parentWindowObject is a {@link com.jogamp.newt.Window} instance,
* the new window is added to it's list of children.
@@ -143,6 +210,10 @@ public class NewtFactory { * In case parentWindowObject is a different {@link javax.media.nativewindow.NativeWindow} implementation,
* you have to handle all events appropriate.

*

+ *

+ * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()} + * and {@link Screen#removeReference()}. + *

* * @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. - *

- * The resulting GLWindow owns the Window, Screen and Device, ie it will be destructed. - *

- * 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. + *

+ * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()} + * and {@link Screen#removeReference()}. + *

+ * 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. - *

- * The resulting GLWindow owns the Window, ie it will be destructed. + *

+ * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()} + * and {@link Screen#removeReference()}. + *

*/ 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. - *

- * The resulting GLWindow does not own the given Window, ie it will not be destructed. + *

+ * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()} + * and {@link Screen#removeReference()}. + *

*/ 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 parentNativeWindow with the given GLCapabilities. - *

+ *

* The Display/Screen will be compatible with the parentNativeWindow, * or even identical in case it's a Newt Window. - *

- * The resulting GLWindow owns the Window, ie it will be destructed. + * An already instantiated compatible Display will be reused. + *

+ *

+ * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()} + * and {@link Screen#removeReference()}. + *

*/ public static GLWindow create(NativeWindow parentNativeWindow, GLCapabilitiesImmutable caps) { return new GLWindow(NewtFactory.createWindow(parentNativeWindow, caps)); -- cgit v1.2.3