From 5e9c02bce7b241a0bf95c8abca9a91cd25e51ed3 Mon Sep 17 00:00:00 2001
From: Harvey Harrison
- Since the {@link GLContext} {@link GLContext#makeCurrent makeCurrent}
- implementation is synchronized, i.e. blocks if the context
+ Since the {@link GLContext} {@link GLContext#makeCurrent makeCurrent}
+ implementation is synchronized, i.e. blocks if the context
is current on another thread, the internal
{@link GLContext} for the GLAutoDrawable can be used for the event
based rendering mechanism and by end users directly.
@@ -123,7 +123,7 @@ public interface GLAutoDrawable extends GLDrawable {
* otherwise return
* The current context will be destroyed if
- * The new context will be associated with this auto-drawable
+ * The new context will be associated with this auto-drawable
* via {@link GLContext#setGLDrawable(GLDrawable, boolean) newCtx.setGLDrawable(drawable, true);}.
- * this
instance.
*/
public GLDrawable getDelegatedDrawable();
-
+
/**
* Returns the context associated with this drawable. The returned
* context will be synchronized.
@@ -135,38 +135,38 @@ public interface GLAutoDrawable extends GLDrawable {
* Associate the new context, newtCtx
, to this auto-drawable.
* destroyPrevCtx
is true
,
- * otherwise it will be dis-associated from this auto-drawable
+ * otherwise it will be dis-associated from this auto-drawable
* via {@link GLContext#setGLDrawable(GLDrawable, boolean) setGLDrawable(null, true);} first.
*
* If the old or new context was current on this thread, it is being released before switching the association. - * The new context will be made current afterwards, if it was current before. + * The new context will be made current afterwards, if it was current before. * However the user shall take extra care that no other thread * attempts to make this context current. *
- * + * * @param newCtx the new context, maybenull
for dis-association.
- * @param destroyPrevCtx if true
, destroy the previous context if exists
+ * @param destroyPrevCtx if true
, destroy the previous context if exists
* @return the previous GLContext, maybe null
- *
+ *
* @see GLContext#setGLDrawable(GLDrawable, boolean)
* @see GLContext#setGLReadDrawable(GLDrawable)
* @see jogamp.opengl.GLDrawableHelper#switchContext(GLDrawable, GLContext, boolean, GLContext, int)
*/
public GLContext setContext(GLContext newCtx, boolean destroyPrevCtx);
-
+
/**
* Adds the given {@link GLEventListener listener} to the end of this drawable queue.
* The {@link GLEventListener listeners} are notified of events in the order of the queue.
* - * The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)} + * The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)} * method will be called once before any other of it's callback methods. * See {@link #getGLEventListenerInitState(GLEventListener)} for details. - *
+ * * @param listener The GLEventListener object to be inserted */ public void addGLEventListener(GLEventListener listener); @@ -175,10 +175,10 @@ public interface GLAutoDrawable extends GLDrawable { * Adds the given {@link GLEventListener listener} at the given index of this drawable queue. * The {@link GLEventListener listeners} are notified of events in the order of the queue. *- * The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)} + * The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)} * method will be called once before any other of it's callback methods. * See {@link #getGLEventListenerInitState(GLEventListener)} for details. - *
+ * * @param index Position where the listener will be inserted. * Should be within (0 <= index && index <= size()). * An index value of -1 is interpreted as the end of the list, size(). @@ -192,7 +192,7 @@ public interface GLAutoDrawable extends GLDrawable { * @return The number of GLEventListener objects of this drawable queue. */ public int getGLEventListenerCount(); - + /** * Returns the {@link GLEventListener} at the given index of this drawable queue. * @param index Position of the listener to be returned. @@ -202,18 +202,18 @@ public interface GLAutoDrawable extends GLDrawable { * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index < size()), or -1 */ public GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException; - + /** * Retrieves whether the given {@link GLEventListener listener} is initialized or not. *- * After {@link #addGLEventListener(GLEventListener) adding} a {@link GLEventListener} it is + * After {@link #addGLEventListener(GLEventListener) adding} a {@link GLEventListener} it is * marked uninitialized and added to a list of to be initialized {@link GLEventListener}. - * If such uninitialized {@link GLEventListener}'s handler methods (reshape, display) + * If such uninitialized {@link GLEventListener}'s handler methods (reshape, display) * are about to be invoked, it's {@link GLEventListener#init(GLAutoDrawable) init(..)} method is invoked first. * Afterwards the {@link GLEventListener} is marked initialized * and removed from the list of to be initialized {@link GLEventListener}. *
- *+ *
* This methods returns the {@link GLEventListener} initialized state,
* i.e. returns false
if it is included in the list of to be initialized {@link GLEventListener},
* otherwise true
.
@@ -221,17 +221,17 @@ public interface GLAutoDrawable extends GLDrawable {
* @param listener the GLEventListener object to query it's initialized state.
*/
public boolean getGLEventListenerInitState(GLEventListener listener);
-
+
/**
* Sets the given {@link GLEventListener listener's} initialized state.
- *
+ *
* This methods allows manually setting the {@link GLEventListener} initialized state, * i.e. adding it to, or removing it from the list of to be initialized {@link GLEventListener}. * See {@link #getGLEventListenerInitState(GLEventListener)} for details. *
** Warning: This method does not validate whether the given {@link GLEventListener listener's} - * is member of this drawable queue, i.e. {@link #addGLEventListener(GLEventListener) added}. + * is member of this drawable queue, i.e. {@link #addGLEventListener(GLEventListener) added}. *
** This method is only exposed to allow users full control over the {@link GLEventListener}'s state @@ -239,16 +239,16 @@ public interface GLAutoDrawable extends GLDrawable { *
** One use case is moving a {@link GLContext} and their initialized {@link GLEventListener} - * from one {@link GLAutoDrawable} to another, + * from one {@link GLAutoDrawable} to another, * where a subsequent {@link GLEventListener#init(GLAutoDrawable) init(..)} call after adding it - * to the new owner is neither required nor desired. + * to the new owner is neither required nor desired. * See {@link com.jogamp.opengl.util.GLDrawableUtil#swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable) swapGLContextAndAllGLEventListener(..)}. *
* @param listener the GLEventListener object to perform a state change. - * @param initialized iftrue
, mark the listener initialized, otherwise uninitialized.
+ * @param initialized if true
, mark the listener initialized, otherwise uninitialized.
*/
public void setGLEventListenerInitState(GLEventListener listener, boolean initialized);
-
+
/**
* Disposes the given {@link GLEventListener listener} via {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)}
* if it has been initialized and added to this queue.
@@ -257,7 +257,7 @@ public interface GLAutoDrawable extends GLDrawable {
* otherwise marked uninitialized.
*
* - * If an {@link GLAnimatorControl} is being attached and the current thread is different + * If an {@link GLAnimatorControl} is being attached and the current thread is different * than {@link GLAnimatorControl#getThread() the animator's thread}, it is paused during the operation. *
*@@ -268,8 +268,8 @@ public interface GLAutoDrawable extends GLDrawable { * Use {@link #removeGLEventListener(GLEventListener) removeGLEventListener(listener)} instead * if you just want to remove the {@link GLEventListener listener} and don't care about the disposal of the it's (OpenGL) resources. *
- *- * Also note that this is done from within a particular drawable's + *
+ * Also note that this is done from within a particular drawable's
* {@link GLEventListener} handler (reshape, display, etc.), that it is not
* guaranteed that all other listeners will be evaluated properly
* during this update cycle.
@@ -277,30 +277,30 @@ public interface GLAutoDrawable extends GLDrawable {
* @param listener The GLEventListener object to be disposed and removed if remove
is true
* @param remove pass true
to have the listener
removed from this drawable queue, otherwise pass false
* @return the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added
- */
+ */
public GLEventListener disposeGLEventListener(GLEventListener listener, boolean remove);
-
- /**
+
+ /**
* Removes the given {@link GLEventListener listener} from this drawable queue.
*
- * This is an inexpensive operation, since the removed listener's + * This is an inexpensive operation, since the removed listener's * {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)} method will not be called. *
*- * Use {@link #disposeGLEventListener(GLEventListener, boolean) disposeGLEventListener(listener, true)} + * Use {@link #disposeGLEventListener(GLEventListener, boolean) disposeGLEventListener(listener, true)} * instead to ensure disposal of the {@link GLEventListener listener}'s (OpenGL) resources. - *
- *- * Note that if this is done from within a particular drawable's + *
+ *+ * Note that if this is done from within a particular drawable's * {@link GLEventListener} handler (reshape, display, etc.), that it is not * guaranteed that all other listeners will be evaluated properly * during this update cycle. *
* @param listener The GLEventListener object to be removed * @return the removed GLEventListener, or null if listener was not added - */ + */ public GLEventListener removeGLEventListener(GLEventListener listener); - + /** * Registers the usage of an animator, an {@link javax.media.opengl.GLAnimatorControl} implementation. * The animator will be queried whether it's animating, ie periodically issuing {@link #display()} calls or not. @@ -334,17 +334,17 @@ public interface GLAutoDrawable extends GLDrawable { /** * Dedicates this instance's {@link GLContext} to the given thread.setExclusiveContextThread(null)
has been called.
+ * until {@link #destroy()} or setExclusiveContextThread(null)
has been called.
*
* Default non-exclusive behavior is requested via setExclusiveContextThread(null)
,
- * which will cause the next call of {@link #display()} on the exclusive thread to
- * release the {@link GLContext}. Only after it's async release, {@link #getExclusiveContextThread()}
+ * which will cause the next call of {@link #display()} on the exclusive thread to
+ * release the {@link GLContext}. Only after it's async release, {@link #getExclusiveContextThread()}
* will return null
.
*
* To release a previous made exclusive thread, a user issues setExclusiveContextThread(null)
- * and may poll {@link #getExclusiveContextThread()} until it returns null
,
- * while the exclusive thread is still running.
+ * and may poll {@link #getExclusiveContextThread()} until it returns null
,
+ * while the exclusive thread is still running.
*
* Note: Setting a new exclusive thread without properly releasing a previous one @@ -359,17 +359,17 @@ public interface GLAutoDrawable extends GLDrawable { * and spare redundant context switches, see {@link com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)}. *
* @param t the exclusive thread to claim the context, ornull
for default operation.
- * @return previous exclusive context thread
+ * @return previous exclusive context thread
* @throws GLException If an exclusive thread is still active but a new one is attempted to be set
* @see com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)
*/
public Thread setExclusiveContextThread(Thread t) throws GLException;
-
+
/**
- * @see #setExclusiveContextThread(Thread)
+ * @see #setExclusiveContextThread(Thread)
*/
public Thread getExclusiveContextThread();
-
+
/**
* Enqueues a one-shot {@link GLRunnable},
* which will be executed within the next {@link #display()} call
@@ -391,7 +391,7 @@ public interface GLAutoDrawable extends GLDrawable {
* has been executed by the {@link GLAnimatorControl animator}, otherwise the method returns immediately.
*
*
- * If wait
is true
and
+ * If wait
is true
and
* {@link #isRealized()} returns false
or {@link #getContext()} returns null
,
* the call is ignored and returns false
.
* This helps avoiding deadlocking the caller.
@@ -404,16 +404,16 @@ public interface GLAutoDrawable extends GLDrawable {
* @param wait if true
block until execution of glRunnable
is finished, otherwise return immediately w/o waiting
* @param glRunnable the {@link GLRunnable} to execute within {@link #display()}
* @return true
if the {@link GLRunnable} has been processed or queued, otherwise false
.
- *
+ *
* @see #setAnimator(GLAnimatorControl)
* @see #display()
* @see GLRunnable
* @see #invoke(boolean, List)
*/
public boolean invoke(boolean wait, GLRunnable glRunnable);
-
+
/**
- * Extends {@link #invoke(boolean, GLRunnable)} functionality
+ * Extends {@link #invoke(boolean, GLRunnable)} functionality
* allowing to inject a list of {@link GLRunnable}s.
* @param wait if true
block until execution of the last glRunnable
is finished, otherwise return immediately w/o waiting
* @param glRunnables the {@link GLRunnable}s to execute within {@link #display()}
@@ -494,16 +494,16 @@ public interface GLAutoDrawable extends GLDrawable {
*
* This GLAutoDrawable implementation holds it's own GLContext reference, * thus created a GLContext using this methods won't replace it implicitly. - * To replace or set this GLAutoDrawable's GLContext you need to call {@link #setContext(GLContext, boolean)}. + * To replace or set this GLAutoDrawable's GLContext you need to call {@link #setContext(GLContext, boolean)}. *
*- * The GLAutoDrawable implementation shall also set the - * context creation flags as customized w/ {@link #setContextCreationFlags(int)}. + * The GLAutoDrawable implementation shall also set the + * context creation flags as customized w/ {@link #setContextCreationFlags(int)}. *
*/ @Override public GLContext createContext(GLContext shareWith); - + /** Returns the {@link GL} pipeline object this GLAutoDrawable uses. If this method is called outside of the {@link GLEventListener}'s callback methods (init, display, etc.) it may @@ -522,13 +522,13 @@ public interface GLAutoDrawable extends GLDrawable { demos for examples. @return the set GL pipeline or null if not successful */ public GL setGL(GL gl); - + /** * Method may return the upstream UI toolkit object * holding this {@link GLAutoDrawable} instance, if exist. ** Currently known Java UI toolkits and it's known return types are: - * + * *
Toolkit | GLAutoDrawable Implementation | ~ | Return Type of getUpstreamWidget() | *
NEWT | {@link com.jogamp.newt.opengl.GLWindow} | has a | {@link com.jogamp.newt.Window} | @@ -536,7 +536,7 @@ public interface GLAutoDrawable extends GLDrawable { *
AWT | {@link javax.media.opengl.awt.GLCanvas} | is a | {@link java.awt.Canvas} | *
AWT | {@link javax.media.opengl.awt.GLJPanel} | is a | {@link javax.swing.JPanel} | *
-- cgit v1.2.3