From 2d4108fa4cb7cb0ea703e8e86e8a15c26e177eca Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Tue, 15 May 2012 17:49:16 +0200
Subject: Clarify API Doc: GLRunnable and it's GLAutoDrawable::invoke(..)
---
.../classes/javax/media/opengl/GLAutoDrawable.java | 16 ++++++++------
.../classes/javax/media/opengl/GLRunnable.java | 25 +++++++++++++---------
2 files changed, 25 insertions(+), 16 deletions(-)
(limited to 'src/jogl/classes')
diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index f0101a90c..c676535c8 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -181,22 +181,26 @@ public interface GLAutoDrawable extends GLDrawable {
/**
* <p>
- * Enqueues a one-shot {@link javax.media.opengl.GLRunnable GLRunnable},
- * which will be executed with the next {@link #display()} call.</p>
+ * Enqueues a one-shot {@link GLRunnable},
+ * which will be executed within the next {@link #display()} call
+ * after all registered {@link GLEventListener}s
+ * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)}
+ * methods has been called.
+ * </p>
* <p>
- * If no {@link javax.media.opengl.GLAnimatorControl GLAnimatorControl} is animating (default),<br>
+ * If no {@link GLAnimatorControl} is animating (default),<br>
* or if the current thread is the animator thread,<br>
* a {@link #display()} call is issued after enqueue the <code>GLRunnable</code>.<br>
* No extra synchronization is performed in case <code>wait</code> is true, since it is executed in the current thread.</p>
* <p>
- * If an {@link javax.media.opengl.GLAnimatorControl GLAnimatorControl} is animating,<br>
+ * If an {@link GLAnimatorControl} is animating,<br>
* no {@link #display()} call is issued, since the animator thread performs it.<br>
* If <code>wait</code> is true, the implementation waits until the <code>GLRunnable</code> is executed.<br>
* </p><br>
*
- * @see #setAnimator(javax.media.opengl.GLAnimatorControl)
+ * @see #setAnimator(GLAnimatorControl)
* @see #display()
- * @see javax.media.opengl.GLRunnable
+ * @see GLRunnable
*/
public void invoke(boolean wait, GLRunnable glRunnable);
diff --git a/src/jogl/classes/javax/media/opengl/GLRunnable.java b/src/jogl/classes/javax/media/opengl/GLRunnable.java
index 141d07c19..1ae1c9b22 100644
--- a/src/jogl/classes/javax/media/opengl/GLRunnable.java
+++ b/src/jogl/classes/javax/media/opengl/GLRunnable.java
@@ -30,23 +30,28 @@ package javax.media.opengl;
/**
* <p>
- * Declares one-shot OpenGL commands usable for injection into a {@link GLAutoDrawable},<br>
+ * Declares a one-shot OpenGL command usable for injection
* via {@link GLAutoDrawable#invoke(boolean, javax.media.opengl.GLRunnable)}.<br>
- * {@link GLAutoDrawable} executes these commands within it's {@link GLAutoDrawable#display()}
- * method while the OpenGL context is current.<br>
+ * {@link GLAutoDrawable} executes the GLRunnables within it's {@link GLAutoDrawable#display() display()}
+ * method after all registered {@link GLEventListener}s
+ * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)}
+ * methods has been called.
+ * </p>
+ * <p>
+ * The OpenGL context is current while executing the GLRunnable.
+ * </p>
* <p>
* This might be useful to inject OpenGL commands from an I/O event listener.
+ * </p>
*/
public interface GLRunnable {
/**
- * Initiate one-shot OpenGL commands with a valid current context,
- * processed by {@link GLAutoDrawable#display()}, enqueued by
- * {@link GLAutoDrawable#invoke(boolean, GLRunnable)}.
- *
* @param drawable the associated drawable and current context for this call
- * @return true if the GL [back] framebuffer remain intact by this runnable, otherwise false.
- * If returning false and hence the impl signals an invalidated back buffer,
- * another {@link GLEventListener#display(GLAutoDrawable)} call will be issued.
+ * @return true if the GL [back] framebuffer remains intact by this runnable, otherwise false.
+ * If returning false {@link GLAutoDrawable} will call
+ * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)}
+ * of all registered {@link GLEventListener}s once more.
+ * @see GLRunnable
*/
boolean run(GLAutoDrawable drawable);
}
--
cgit v1.2.3