diff options
Diffstat (limited to 'src/newt/classes')
-rw-r--r-- | src/newt/classes/com/jogamp/newt/NewtFactory.java | 89 | ||||
-rw-r--r-- | src/newt/classes/com/jogamp/newt/opengl/GLWindow.java | 35 |
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)); |