From b642b87c85329b37a181f96e1d7adeea9fb6b79f Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Sun, 27 Oct 2013 10:15:48 +0100
Subject: API doc: GLStateKeeper (wording), GLAutoDrawable (enh. init desc.),
GLDrawable (Shared Context)
---
.../classes/javax/media/opengl/GLAutoDrawable.java | 23 +++++++++++++---------
.../classes/javax/media/opengl/GLDrawable.java | 9 +++++----
2 files changed, 19 insertions(+), 13 deletions(-)
(limited to 'src/jogl/classes/javax')
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.
</p>
+ <h5><a name="initialization">GLAutoDrawable Initialization</a></h5>
<p>
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 <i>after</i> the attached {@link javax.media.nativewindow.NativeSurface NativeSurface} becomes visible and and is realized.<br>
+ The following initialization sequence should be implemented:
<ul>
<li> Create the {@link GLDrawable} with the requested {@link GLCapabilities}</li>
<li> Notify {@link GLDrawable} to validate the {@link GLCapabilities} by calling {@link GLDrawable#setRealized setRealized(true)}.</li>
<li> Create the new {@link GLContext}.</li>
<li> Initialize all OpenGL resources by calling {@link GLEventListener#init init(..)} for all
- registered {@link GLEventListener}s. This can be done immediatly, or with the followup {@link #display display(..)} call.</li>
+ registered {@link GLEventListener}s. This can be done immediately, or with the followup {@link #display display(..)} call.</li>
<li> Send a reshape event by calling {@link GLEventListener#reshape reshape(..)} for all
registered {@link GLEventListener}s. This shall be done after the {@link GLEventListener#init init(..)} calls.</li>
- </ul></P>
+ </ul>
+ 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}.
+ </p>
+ <h5><a name="reconfiguration">GLAutoDrawable Reconfiguration</a></h5>
<p>
- 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}.<br/>
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 <code>boolean</code> system property <code>jogl.screenchange.action</code> will control the
screen change action as follows:<br/>
<PRE>
- -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
</PRE>
</p>
*/
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. <P>
- *
+ * optionally share buffer objects, textures and other server-side OpenGL
+ * objects with the specified GLContext.
+ * <p>
* The GLContext <code>share</code> 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
- * <a href="../../../overview-summary.html#SHARING">context sharing</a>.
+ * <a href="../../../spec-overview.html#SHARING">context sharing</a>.
+ * </p>
*/
public GLContext createContext(GLContext shareWith);
--
cgit v1.2.3