From b642b87c85329b37a181f96e1d7adeea9fb6b79f Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Sun, 27 Oct 2013 10:15:48 +0100 Subject: API doc: GLStateKeeper (wording), GLAutoDrawable (enh. init desc.), GLDrawable (Shared Context) --- .../classes/com/jogamp/opengl/GLStateKeeper.java | 6 +++--- .../classes/javax/media/opengl/GLAutoDrawable.java | 23 +++++++++++++--------- .../classes/javax/media/opengl/GLDrawable.java | 9 +++++---- 3 files changed, 22 insertions(+), 16 deletions(-) (limited to 'src') diff --git a/src/jogl/classes/com/jogamp/opengl/GLStateKeeper.java b/src/jogl/classes/com/jogamp/opengl/GLStateKeeper.java index b98c4431d..2b452e138 100644 --- a/src/jogl/classes/com/jogamp/opengl/GLStateKeeper.java +++ b/src/jogl/classes/com/jogamp/opengl/GLStateKeeper.java @@ -62,14 +62,14 @@ public interface GLStateKeeper { /** * If set to true, the next {@link GLAutoDrawable#destroy()} operation will - * {@link #pullGLEventListenerState() pull} to preserve the {@link GLEventListenerState}. + * {@link #preserveGLEventListenerState() preserve} the {@link GLEventListenerState}. *

* This is a one-shot flag, i.e. after preserving the {@link GLEventListenerState}, * the flag is cleared. *

*

- * A preserved {@link GLEventListenerState} will be {@link #pushGLEventListenerState() pushed} - * if realized again. + * A preserved {@link GLEventListenerState} will be + * {@link #restoreGLEventListenerState() restored} again. *

* @return true if supported and successful, false otherwise. * @see #isGLStatePreservationSupported() diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java index 38824ce8f..bf8fe65ac 100644 --- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java +++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java @@ -56,21 +56,26 @@ import jogamp.opengl.Debug; {@link GLContext} for the GLAutoDrawable can be used for the event based rendering mechanism and by end users directly.

+
GLAutoDrawable Initialization

The implementation shall initialize itself as soon as possible, - ie if the attached {@link javax.media.nativewindow.NativeSurface NativeSurface} becomes visible/realized. - The following protocol shall be satisfied: + which is only possible after the attached {@link javax.media.nativewindow.NativeSurface NativeSurface} becomes visible and and is realized.
+ The following initialization sequence should be implemented:

+ + Note: The last to {@link GLEventListener} actions shall be also performed, when {@link #addGLEventListener(GLEventListener) adding} + a new one to an already initialized {@link GLAutoDrawable}. +

+
GLAutoDrawable Reconfiguration

- Another implementation detail is the drawable reconfiguration. One use case is where a window is being + Another implementation detail is the {@link GLDrawable} reconfiguration. One use case is where a window is being dragged to another screen with a different pixel configuration, ie {@link GLCapabilities}. The implementation shall be able to detect such cases in conjunction with the associated {@link javax.media.nativewindow.NativeSurface NativeSurface}.
For example, AWT's {@link java.awt.Canvas} 's {@link java.awt.Canvas#getGraphicsConfiguration getGraphicsConfiguration()} @@ -107,14 +112,14 @@ import jogamp.opengl.Debug; mentioned above, the boolean system property jogl.screenchange.action will control the screen change action as follows:

-    -Djogl.screenchange.action=false Disable the drawable reconfiguration (the default)
-    -Djogl.screenchange.action=true  Enable  the drawable reconfiguration
+    -Djogl.screenchange.action=false Disable the {@link GLDrawable} reconfiguration (the default)
+    -Djogl.screenchange.action=true  Enable  the {@link GLDrawable} reconfiguration

*/ public interface GLAutoDrawable extends GLDrawable { - /** Flag reflecting wheather the drawable reconfiguration will be issued in - * case a screen device change occured, e.g. in a multihead environment, + /** Flag reflecting whether the {@link GLDrawable} reconfiguration will be issued in + * case a screen device change occurred, e.g. in a multihead environment, * where you drag the window to another monitor. */ public static final boolean SCREEN_CHANGE_ACTION_ENABLED = Debug.getBooleanProperty("jogl.screenchange.action", true); diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java index 5a032db29..3c354a240 100644 --- a/src/jogl/classes/javax/media/opengl/GLDrawable.java +++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java @@ -53,14 +53,15 @@ import javax.media.nativewindow.NativeSurface; public interface GLDrawable { /** * Creates a new context for drawing to this drawable that will - * optionally share display lists and other server-side OpenGL - * objects with the specified GLContext.

- * + * optionally share buffer objects, textures and other server-side OpenGL + * objects with the specified GLContext. + *

* The GLContext share need not be associated with this * GLDrawable and may be null if sharing of display lists and other * objects is not desired. See the note in the overview * documentation on - * context sharing. + * context sharing. + *

*/ public GLContext createContext(GLContext shareWith); -- cgit v1.2.3