com.jogamp.opengl.util

## Class Animator

- java.lang.Object
- - com.jogamp.opengl.util.AnimatorBase
  - - com.jogamp.opengl.util.Animator

- All Implemented Interfaces:
    FPSCounter, GLAnimatorControl

      public class Animator
      extends AnimatorBase

  An Animator can be attached to one or more `GLAutoDrawable`s 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(boolean)` 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.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class com.jogamp.opengl.util.AnimatorBase

      `AnimatorBase.AnimatorImpl, AnimatorBase.UncaughtAnimatorException`

    - ### Nested classes/interfaces inherited from interface javax.media.opengl.GLAnimatorControl

      `GLAnimatorControl.UncaughtExceptionHandler`

  - ### Field Summary

    - ### Fields inherited from class com.jogamp.opengl.util.AnimatorBase

      `MODE_EXPECT_AWT_RENDERING_THREAD`

    - ### Fields inherited from interface javax.media.opengl.FPSCounter

      `DEFAULT_FRAMES_PER_INTERVAL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Animator()` Creates a new, empty Animator.
    `Animator(GLAutoDrawable drawable)` Creates a new Animator for a particular drawable.
    `Animator(ThreadGroup tg)` Creates a new Animator w/ an associated ThreadGroup.
    `Animator(ThreadGroup tg, GLAutoDrawable drawable)` Creates a new Animator w/ an associated ThreadGroup for a particular drawable.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isAnimating()` Indicates whether this animator `is started` and `is not paused`.
    `boolean` | `isPaused()` Indicates whether this animator `is started` and either `manually paused` or paused automatically due to no `added` `GLAutoDrawable`s.
    `boolean` | `pause()` Pauses this animator.
    `boolean` | `resume()` Resumes animation if paused.
    `void` | `setRunAsFastAsPossible(boolean runFast)` Sets a flag in this Animator indicating that it is to run as fast as possible.
    `void` | `setThreadGroup(ThreadGroup tg)` Set a `ThreadGroup` for the `animation thread`.
    `boolean` | `start()` Starts this animator, if not running.
    `boolean` | `stop()` Stops this animator.

    - ### Methods inherited from class com.jogamp.opengl.util.AnimatorBase

      `add, getExclusiveContextThread, getFPSStartTime, getLastFPS, getLastFPSPeriod, getLastFPSUpdateTime, getModeBits, getThread, getTotalFPS, getTotalFPSDuration, getTotalFPSFrames, getUncaughtExceptionHandler, getUpdateFPSFrames, isExclusiveContextEnabled, isStarted, remove, resetFPSCounter, setExclusiveContext, setExclusiveContext, setIgnoreExceptions, setModeBits, setPrintExceptions, setUncaughtExceptionHandler, setUpdateFPSFrames, toString`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Animator

          public Animator()

      Creates a new, empty Animator.

    - #### Animator

          public Animator(ThreadGroup tg)

      Creates a new Animator w/ an associated ThreadGroup.

    - #### Animator

          public Animator(GLAutoDrawable drawable)

      Creates a new Animator for a particular drawable.

    - #### Animator

          public Animator(ThreadGroup tg,
                  GLAutoDrawable drawable)

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

  - ### Method Detail

    - #### setRunAsFastAsPossible

          public final void setRunAsFastAsPossible(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.

    - #### isAnimating

          public final boolean isAnimating()

      Description copied from interface: `GLAnimatorControl`
      Indicates whether this animator `is started` and `is not paused`.
      See Also:
        `GLAnimatorControl.start()`, `GLAnimatorControl.stop()`, `GLAnimatorControl.pause()`, `GLAnimatorControl.resume()`

    - #### isPaused

          public final boolean isPaused()

      Description copied from interface: `GLAnimatorControl`
      Indicates whether this animator `is started` and either `manually paused` or paused automatically due to no `added` `GLAutoDrawable`s.
      See Also:
        `GLAnimatorControl.start()`, `GLAnimatorControl.stop()`, `GLAnimatorControl.pause()`, `GLAnimatorControl.resume()`

    - #### setThreadGroup

          public final void setThreadGroup(ThreadGroup tg)
                                    throws GLException

      Set a `ThreadGroup` for the `animation thread`.
      Parameters:
        `tg` - the `ThreadGroup`
      Throws:
        `GLException` - if the animator has already been started

    - #### start

          public final boolean start()

      Description copied from interface: `GLAnimatorControl`
      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:
        `GLAnimatorControl.stop()`, `GLAnimatorControl.isAnimating()`, `GLAnimatorControl.isPaused()`, `GLAnimatorControl.getThread()`

    - #### stop

          public final boolean stop()

      Description copied from interface: `GLAnimatorControl`
      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:
        `GLAnimatorControl.start()`, `GLAnimatorControl.isAnimating()`, `GLAnimatorControl.getThread()`

    - #### pause

          public final boolean pause()

      Description copied from interface: `GLAnimatorControl`
      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:
        `GLAnimatorControl.resume()`, `GLAnimatorControl.isAnimating()`

    - #### resume

          public final boolean resume()

      Description copied from interface: `GLAnimatorControl`
      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:
        `GLAnimatorControl.pause()`, `GLAnimatorControl.isAnimating()`

Copyright 2010 JogAmp Community.