JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.opengl.util.Animator Class Reference
Inheritance diagram for com.jogamp.opengl.util.Animator:
Collaboration diagram for com.jogamp.opengl.util.Animator:

Classes

class  MainLoop
 

Public Member Functions

 Animator ()
 Creates a new, empty Animator instance while expecting an AWT rendering thread if AWT is available. More...
 
 Animator (final int modeBits)
 Creates a new, empty Animator instance with given modeBits. More...
 
 Animator (final ThreadGroup tg)
 Creates a new Animator w/ an associated ThreadGroup. More...
 
 Animator (final GLAutoDrawable drawable)
 Creates a new Animator for a particular drawable. More...
 
 Animator (final ThreadGroup tg, final GLAutoDrawable drawable)
 Creates a new Animator w/ an associated ThreadGroup for a particular drawable. More...
 
 Animator (final int modeBits, final ThreadGroup tg, final GLAutoDrawable drawable)
 Creates a new Animator w/ an associated ThreadGroup for a particular drawable. More...
 
final synchronized void setRunAsFastAsPossible (final boolean runFast)
 Sets a flag in this Animator indicating that it is to run as fast as possible. More...
 
final synchronized boolean isAnimating ()
 Indicates whether this animator is started and is not paused. More...
 
final synchronized boolean isPaused ()
 Indicates whether this animator is started and either manually paused or paused automatically due to no added GLAutoDrawables. More...
 
final synchronized void setThreadGroup (final ThreadGroup tg) throws GLException
 Set a ThreadGroup for the animation thread. More...
 
final synchronized boolean start ()
 Starts this animator, if not running. More...
 
final synchronized boolean stop ()
 Stops this animator. More...
 
final synchronized boolean pause ()
 Pauses this animator. More...
 
final synchronized boolean resume ()
 Resumes animation if paused. More...
 
- Public Member Functions inherited from com.jogamp.opengl.util.AnimatorBase
 AnimatorBase ()
 Creates a new, empty Animator instance while expecting an AWT rendering thread if AWT is available. More...
 
 AnimatorBase (final int modeBits)
 Creates a new, empty Animator instance with given modeBits. More...
 
final synchronized void setModeBits (final boolean enable, final int bitValues) throws GLException
 Enables or disables the given bitValues in this Animators modeBits. More...
 
synchronized int getModeBits ()
 
final synchronized void add (final GLAutoDrawable drawable)
 Adds a drawable to this animator's list of rendering drawables. More...
 
final synchronized void remove (final GLAutoDrawable drawable)
 Removes a drawable from the animator's list of rendering drawables. More...
 
final synchronized Thread setExclusiveContext (final Thread t)
 Dedicate all GLAutoDrawable's context to the given exclusive context thread. More...
 
final boolean setExclusiveContext (final boolean enable)
 Dedicate all GLAutoDrawable's context to this animator thread. More...
 
final synchronized boolean isExclusiveContextEnabled ()
 Returns true, if the exclusive context thread is enabled, otherwise false. More...
 
final synchronized Thread getExclusiveContextThread ()
 Returns the exclusive context thread if isExclusiveContextEnabled() and isStarted(), otherwise null. More...
 
final synchronized Thread getThread ()
 
final void setUpdateFPSFrames (final int frames, final PrintStream out)
 
final void resetFPSCounter ()
 Reset all performance counter (startTime, currentTime, frame number) More...
 
final int getUpdateFPSFrames ()
 
final long getFPSStartTime ()
 Returns the time of the first display call in milliseconds after enabling this feature via setUpdateFPSFrames(int, PrintStream). More...
 
final long getLastFPSUpdateTime ()
 Returns the time of the last update interval in milliseconds, if this feature is enabled via setUpdateFPSFrames(int, PrintStream). More...
 
final long getLastFPSPeriod ()
 
final float getLastFPS ()
 
final int getTotalFPSFrames ()
 
final long getTotalFPSDuration ()
 
final float getTotalFPS ()
 
final void setIgnoreExceptions (final boolean ignoreExceptions)
 Sets a flag causing this Animator to ignore exceptions produced while redrawing the drawables. More...
 
final void setPrintExceptions (final boolean printExceptions)
 Sets a flag indicating that when exceptions are being ignored by this Animator (see setIgnoreExceptions), to print the exceptions' stack traces for diagnostic information. More...
 
final UncaughtExceptionHandler getUncaughtExceptionHandler ()
 Returns the UncaughtExceptionHandler invoked when this animator abruptly stops due to an uncaught exception from one of its GLAutoDrawables. More...
 
final void setUncaughtExceptionHandler (final UncaughtExceptionHandler handler)
 Set the handler invoked when this animator abruptly stops due to an uncaught exception from one of its GLAutoDrawables. More...
 
synchronized boolean isStarted ()
 Indicates whether this animator has been started. More...
 
String toString ()
 
boolean isStarted ()
 Indicates whether this animator has been started. More...
 
boolean isAnimating ()
 Indicates whether this animator is started and is not paused. More...
 
boolean isPaused ()
 Indicates whether this animator is started and either manually paused or paused automatically due to no added GLAutoDrawables. More...
 
Thread getThread ()
 
boolean start ()
 Starts this animator, if not running. More...
 
boolean stop ()
 Stops this animator. More...
 
boolean pause ()
 Pauses this animator. More...
 
boolean resume ()
 Resumes animation if paused. More...
 
void add (GLAutoDrawable drawable)
 Adds a drawable to this animator's list of rendering drawables. More...
 
void remove (GLAutoDrawable drawable)
 Removes a drawable from the animator's list of rendering drawables. More...
 
UncaughtExceptionHandler getUncaughtExceptionHandler ()
 Returns the UncaughtExceptionHandler invoked when this animator abruptly stops due to an uncaught exception from one of its GLAutoDrawables. More...
 
void setUncaughtExceptionHandler (final UncaughtExceptionHandler handler)
 Set the handler invoked when this animator abruptly stops due to an uncaught exception from one of its GLAutoDrawables. More...
 
void setUpdateFPSFrames (int frames, PrintStream out)
 
void resetFPSCounter ()
 Reset all performance counter (startTime, currentTime, frame number) More...
 
int getUpdateFPSFrames ()
 
long getFPSStartTime ()
 Returns the time of the first display call in milliseconds after enabling this feature via setUpdateFPSFrames(int, PrintStream). More...
 
long getLastFPSUpdateTime ()
 Returns the time of the last update interval in milliseconds, if this feature is enabled via setUpdateFPSFrames(int, PrintStream). More...
 
long getLastFPSPeriod ()
 
float getLastFPS ()
 
int getTotalFPSFrames ()
 
long getTotalFPSDuration ()
 
float getTotalFPS ()
 

Protected Member Functions

final String getBaseName (final String prefix)
 
- Protected Member Functions inherited from com.jogamp.opengl.util.AnimatorBase
final synchronized void initImpl (final boolean force)
 Initializes implementation details post setup, invoked at add(GLAutoDrawable), start(), . More...
 
abstract String getBaseName (String prefix)
 
final synchronized void setDrawablesExclCtxState (final boolean enable)
 Should be called at start() and stop() from within the animator thread. More...
 
final boolean validateDrawablesExclCtxState (final Thread expected)
 
final void display () throws UncaughtAnimatorException
 Called every frame to cause redrawing of all of the GLAutoDrawables this Animator manages. More...
 
final synchronized boolean handleUncaughtException (final UncaughtAnimatorException ue)
 Should be called in case of an uncaught exception from within the animator thread, throws given exception if no handler has been installed. More...
 
final void flushGLRunnables ()
 Should be called in case of an uncaught exception from within the animator thread to flush all animator. More...
 
final synchronized boolean finishLifecycleAction (final Condition waitCondition, long pollPeriod)
 

Additional Inherited Members

- Static Public Attributes inherited from com.jogamp.opengl.util.AnimatorBase
static final int MODE_EXPECT_AWT_RENDERING_THREAD = 1 << 0
 If present in modeBits field and AWT is available, implementation is aware of the AWT EDT, otherwise not. More...
 
- Static Public Attributes inherited from com.jogamp.opengl.FPSCounter
static final int DEFAULT_FRAMES_PER_INTERVAL = 5*60
 
- Static Protected Member Functions inherited from com.jogamp.opengl.util.AnimatorBase
static String getThreadName ()
 
- Protected Attributes inherited from com.jogamp.opengl.util.AnimatorBase
int modeBits
 
AnimatorImpl impl
 
String baseName
 
ArrayList< GLAutoDrawabledrawables = new ArrayList<GLAutoDrawable>()
 
boolean drawablesEmpty
 
Thread animThread
 
boolean ignoreExceptions
 
boolean printExceptions
 
boolean exclusiveContext
 
Thread userExclusiveContextThread
 
UncaughtExceptionHandler uncaughtExceptionHandler
 
FPSCounterImpl fpsCounter = new FPSCounterImpl()
 
- Static Protected Attributes inherited from com.jogamp.opengl.util.AnimatorBase
static final boolean DEBUG = Debug.debug("Animator")
 
static final long TO_WAIT_FOR_FINISH_LIFECYCLE_ACTION = 1000
 A 1s timeout while waiting for a native action response, limiting finishLifecycleAction(Condition, long). More...
 
static final long POLLP_WAIT_FOR_FINISH_LIFECYCLE_ACTION = 32
 

Detailed Description

An Animator can be attached to one or more GLAutoDrawables to drive their display() methods in a loop.

The Animator class creates a background thread in which the calls to display() are performed. After each drawable has been redrawn, a brief pause is performed to avoid swamping the CPU, unless setRunAsFastAsPossible has been called.

The Animator execution thread does not run as a daemon thread, so it is able to keep an application from terminating.
Call stop() to terminate the animation and it's execution thread.

Definition at line 64 of file Animator.java.

Constructor & Destructor Documentation

◆ Animator() [1/6]

com.jogamp.opengl.util.Animator.Animator ( )

Creates a new, empty Animator instance while expecting an AWT rendering thread if AWT is available.

See also
AnimatorBase::MODE_EXPECT_AWT_RENDERING_THREAD
Animator(int, ThreadGroup, GLAutoDrawable)
GLProfile::isAWTAvailable()
AnimatorBase::setModeBits(boolean, int)

Definition at line 81 of file Animator.java.

◆ Animator() [2/6]

com.jogamp.opengl.util.Animator.Animator ( final int  modeBits)

Creates a new, empty Animator instance with given modeBits.

Passing AnimatorBase#MODE_EXPECT_AWT_RENDERING_THREAD is considered default. However, passing 0 is recommended if not using AWT in your application.

See also
AnimatorBase::MODE_EXPECT_AWT_RENDERING_THREAD
Animator(int, ThreadGroup, GLAutoDrawable)
GLProfile::isAWTAvailable()
AnimatorBase::setModeBits(boolean, int)

Definition at line 98 of file Animator.java.

◆ Animator() [3/6]

com.jogamp.opengl.util.Animator.Animator ( final ThreadGroup  tg)

Creates a new Animator w/ an associated ThreadGroup.

This ctor variant expects an AWT rendering thread if AWT is available.

See also
AnimatorBase::MODE_EXPECT_AWT_RENDERING_THREAD
Animator(int, ThreadGroup, GLAutoDrawable)
GLProfile::isAWTAvailable()
AnimatorBase::setModeBits(boolean, int)

Definition at line 112 of file Animator.java.

◆ Animator() [4/6]

com.jogamp.opengl.util.Animator.Animator ( final GLAutoDrawable  drawable)

Creates a new Animator for a particular drawable.

This ctor variant expects an AWT rendering thread if AWT is available.

See also
AnimatorBase::MODE_EXPECT_AWT_RENDERING_THREAD
Animator(int, ThreadGroup, GLAutoDrawable)
GLProfile::isAWTAvailable()
AnimatorBase::setModeBits(boolean, int)

Definition at line 126 of file Animator.java.

◆ Animator() [5/6]

com.jogamp.opengl.util.Animator.Animator ( final ThreadGroup  tg,
final GLAutoDrawable  drawable 
)

Creates a new Animator w/ an associated ThreadGroup for a particular drawable.

This ctor variant expects an AWT rendering thread if AWT is available.

See also
AnimatorBase::MODE_EXPECT_AWT_RENDERING_THREAD
Animator(int, ThreadGroup, GLAutoDrawable)
GLProfile::isAWTAvailable()
AnimatorBase::setModeBits(boolean, int)

Definition at line 140 of file Animator.java.

◆ Animator() [6/6]

com.jogamp.opengl.util.Animator.Animator ( final int  modeBits,
final ThreadGroup  tg,
final GLAutoDrawable  drawable 
)

Creates a new Animator w/ an associated ThreadGroup for a particular drawable.

Passing AnimatorBase#MODE_EXPECT_AWT_RENDERING_THREAD is considered default. However, passing 0 is recommended if not using AWT in your application.

Parameters
modeBitspass AnimatorBase#MODE_EXPECT_AWT_RENDERING_THREAD if an AWT rendering thread is expected, otherwise 0.
tgdesired ThreadGroup or null
drawableadded GLAutoDrawable or null
See also
AnimatorBase::MODE_EXPECT_AWT_RENDERING_THREAD
GLProfile::isAWTAvailable()
AnimatorBase::setModeBits(boolean, int)

Definition at line 157 of file Animator.java.

Here is the call graph for this function:

Member Function Documentation

◆ getBaseName()

final String com.jogamp.opengl.util.Animator.getBaseName ( final String  prefix)
protected

Reimplemented from com.jogamp.opengl.util.AnimatorBase.

Definition at line 171 of file Animator.java.

◆ isAnimating()

final synchronized boolean com.jogamp.opengl.util.Animator.isAnimating ( )

Indicates whether this animator is started and is not paused.

See also
start()
stop()
pause()
resume()

Implements com.jogamp.opengl.GLAnimatorControl.

Definition at line 321 of file Animator.java.

◆ isPaused()

final synchronized boolean com.jogamp.opengl.util.Animator.isPaused ( )

Indicates whether this animator is started and either manually paused or paused automatically due to no added GLAutoDrawables.

See also
start()
stop()
pause()
resume()

Implements com.jogamp.opengl.GLAnimatorControl.

Definition at line 326 of file Animator.java.

Here is the caller graph for this function:

◆ pause()

final synchronized boolean com.jogamp.opengl.util.Animator.pause ( )

Pauses this animator.

In most situations this method blocks until completion, except when called from the animation thread itself or in some cases from an implementation-internal thread like the AWT event queue thread.

Returns
false if not started, already paused or failed to pause, otherwise true
See also
resume()
#isAnimating()

Implements com.jogamp.opengl.GLAnimatorControl.

Definition at line 382 of file Animator.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ resume()

final synchronized boolean com.jogamp.opengl.util.Animator.resume ( )

Resumes animation if paused.

In most situations this method blocks until completion, except when called from the animation thread itself or in some cases from an implementation-internal thread like the AWT event queue thread.

If resumed, all counters (time, frames, ..) are reset to zero.

Returns
false if not started, not paused or unable to resume, otherwise true
See also
pause()
#isAnimating()

Implements com.jogamp.opengl.GLAnimatorControl.

Definition at line 397 of file Animator.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setRunAsFastAsPossible()

final synchronized void com.jogamp.opengl.util.Animator.setRunAsFastAsPossible ( final boolean  runFast)

Sets a flag in this Animator indicating that it is to run as fast as possible.

By default there is a brief pause in the animation loop which prevents the CPU from getting swamped. This method may not have an effect on subclasses.

Definition at line 181 of file Animator.java.

◆ setThreadGroup()

final synchronized void com.jogamp.opengl.util.Animator.setThreadGroup ( final ThreadGroup  tg) throws GLException

Set a ThreadGroup for the animation thread.

Parameters
tgthe ThreadGroup
Exceptions
GLExceptionif the animator has already been started

Definition at line 336 of file Animator.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ start()

final synchronized boolean com.jogamp.opengl.util.Animator.start ( )

Starts this animator, if not running.

In most situations this method blocks until completion, except when called from the animation thread itself or in some cases from an implementation-internal thread like the AWT event queue thread.

Note that an animator w/o added drawables will be paused automatically.

If started, all counters (time, frames, ..) are reset to zero.

Returns
true is started due to this call, otherwise false, ie started already or unable to start.
See also
stop()
#isAnimating()
isPaused()
getThread()

Implements com.jogamp.opengl.GLAnimatorControl.

Definition at line 344 of file Animator.java.

Here is the call graph for this function:

◆ stop()

final synchronized boolean com.jogamp.opengl.util.Animator.stop ( )

Stops this animator.

In most situations this method blocks until completion, except when called from the animation thread itself or in some cases from an implementation-internal thread like the AWT event queue thread.

Returns
true is stopped due to this call, otherwise false, ie not started or unable to stop.
See also
start()
#isAnimating()
getThread()

Implements com.jogamp.opengl.GLAnimatorControl.

Definition at line 368 of file Animator.java.

Here is the call graph for this function:

The documentation for this class was generated from the following file: