com.jogamp.opengl.util

## Class AnimatorBase

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

- All Implemented Interfaces:
    FPSCounter, GLAnimatorControl
  Direct Known Subclasses:
    Animator, FPSAnimator

      public abstract class AnimatorBase
      extends Object
      implements GLAnimatorControl

  Base implementation of GLAnimatorControl

  The change synchronization is done via synchronized blocks on the AnimatorBase instance.
  Status get / set activity is synced with a RecursiveLock, used as a memory barrier.
  This is suitable, since all change requests are allowed to be expensive as they are not expected to be called at every frame.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `AnimatorBase.AnimatorImpl`
    `static class` | `AnimatorBase.UncaughtAnimatorException`

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

      `GLAnimatorControl.UncaughtExceptionHandler`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MODE_EXPECT_AWT_RENDERING_THREAD` If present in `modeBits` field and `AWT is available`, implementation is aware of the AWT EDT, otherwise not.

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

      `DEFAULT_FRAMES_PER_INTERVAL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AnimatorBase()` Creates a new, empty Animator instance while expecting an AWT rendering thread if AWT is available.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(GLAutoDrawable drawable)` Adds a drawable to this animator's list of rendering drawables.
    `Thread` | `getExclusiveContextThread()` Returns the exclusive context thread if `isExclusiveContextEnabled()` and `isStarted()`, otherwise `null`.
    `long` | `getFPSStartTime()` Returns the time of the first display call in milliseconds after enabling this feature via `FPSCounter.setUpdateFPSFrames(int, PrintStream)`. This value is reset via `FPSCounter.resetFPSCounter()`.
    `float` | `getLastFPS()`
    `long` | `getLastFPSPeriod()`
    `long` | `getLastFPSUpdateTime()` Returns the time of the last update interval in milliseconds, if this feature is enabled via `FPSCounter.setUpdateFPSFrames(int, PrintStream)`. This value is reset via `FPSCounter.resetFPSCounter()`.
    `int` | `getModeBits()`
    `Thread` | `getThread()`
    `float` | `getTotalFPS()`
    `long` | `getTotalFPSDuration()`
    `int` | `getTotalFPSFrames()`
    `GLAnimatorControl.UncaughtExceptionHandler` | `getUncaughtExceptionHandler()` Returns the `GLAnimatorControl.UncaughtExceptionHandler` invoked when this `animator` abruptly `stops` due to an uncaught exception from one of its `GLAutoDrawable`s.
    `int` | `getUpdateFPSFrames()`
    `boolean` | `isExclusiveContextEnabled()` Returns `true`, if the exclusive context thread is enabled, otherwise `false`.
    `boolean` | `isStarted()` Indicates whether this animator has been `started`.
    `void` | `remove(GLAutoDrawable drawable)` Removes a drawable from the animator's list of rendering drawables.
    `void` | `resetFPSCounter()` Reset all performance counter (startTime, currentTime, frame number)
    `boolean` | `setExclusiveContext(boolean enable)` Dedicate all `GLAutoDrawable`'s context to this animator thread.
    `Thread` | `setExclusiveContext(Thread t)` Dedicate all `GLAutoDrawable`'s context to the given exclusive context thread.
    `void` | `setIgnoreExceptions(boolean ignoreExceptions)` Sets a flag causing this Animator to ignore exceptions produced while redrawing the drawables.
    `void` | `setModeBits(boolean enable, int bitValues)` Enables or disables the given `bitValues` in this Animators `modeBits`.
    `void` | `setPrintExceptions(boolean printExceptions)` Sets a flag indicating that when exceptions are being ignored by this Animator (see `setIgnoreExceptions(boolean)`), to print the exceptions' stack traces for diagnostic information.
    `void` | `setUncaughtExceptionHandler(GLAnimatorControl.UncaughtExceptionHandler handler)` Set the handler invoked when this `animator` abruptly `stops` due to an uncaught exception from one of its `GLAutoDrawable`s.
    `void` | `setUpdateFPSFrames(int frames, PrintStream out)`
    `String` | `toString()`

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

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

    - ### Methods inherited from interface javax.media.opengl.GLAnimatorControl

      `isAnimating, isPaused, pause, resume, start, stop`

- - ### Field Detail

    - #### MODE_EXPECT_AWT_RENDERING_THREAD

          public static final int MODE_EXPECT_AWT_RENDERING_THREAD

      If present in `modeBits` field and `AWT is available`, implementation is aware of the AWT EDT, otherwise not.

      This is the default.

      See Also:
        `setModeBits(boolean, int)`, Constant Field Values

  - ### Constructor Detail

    - #### AnimatorBase

          public AnimatorBase()

      Creates a new, empty Animator instance while expecting an AWT rendering thread if AWT is available.
      See Also:
        `GLProfile.isAWTAvailable()`

  - ### Method Detail

    - #### setModeBits

          public final void setModeBits(boolean enable,
                         int bitValues)
                                 throws GLException

      Enables or disables the given `bitValues` in this Animators `modeBits`.
      Parameters:
        `enable` -
        `bitValues` -
      Throws:
        `GLException` - if Animator is `isStarted()` and `MODE_EXPECT_AWT_RENDERING_THREAD` about to change
      See Also:
        `MODE_EXPECT_AWT_RENDERING_THREAD`

    - #### getModeBits

          public int getModeBits()

    - #### add

          public final void add(GLAutoDrawable drawable)

      Description copied from interface: `GLAnimatorControl`
      Adds a drawable to this animator's list of rendering drawables.

      This allows the animator thread to become `animating`, in case the first drawable is added and the animator `is started`.

      Specified by:
        `add` in interface `GLAnimatorControl`
      Parameters:
        `drawable` - the drawable to be added

    - #### remove

          public final void remove(GLAutoDrawable drawable)

      Description copied from interface: `GLAnimatorControl`
      Removes a drawable from the animator's list of rendering drawables.

      This method should get called in case a drawable becomes invalid, and will not be recovered.

      This allows the animator thread to become `not animating`, in case the last drawable has been removed.

      Specified by:
        `remove` in interface `GLAnimatorControl`
      Parameters:
        `drawable` - the drawable to be removed

    - #### setExclusiveContext

          public final Thread setExclusiveContext(Thread t)

      Dedicate all `GLAutoDrawable`'s context to the given exclusive context thread.

      The given thread will be exclusive to all `GLAutoDrawable`'s context while `GLAnimatorControl.isAnimating()`.

      If already started and disabling, method waits until change is propagated to all `GLAutoDrawable` if not called from the animator thread or `exclusive context thread`.

      Note: Utilizing this feature w/ AWT could lead to an AWT-EDT deadlock, depending on the AWT implementation. Hence it is advised not to use it with native AWT GLAutoDrawable like GLCanvas.

      Parameters:
        `enable` -
      Returns:
        previous value
      See Also:
        `setExclusiveContext(boolean)`, `getExclusiveContextThread()`, `isExclusiveContextEnabled()`

    - #### setExclusiveContext

          public final boolean setExclusiveContext(boolean enable)

      Dedicate all `GLAutoDrawable`'s context to this animator thread.

      The given thread will be exclusive to all `GLAutoDrawable`'s context while `GLAnimatorControl.isAnimating()`.

      If already started and disabling, method waits until change is propagated to all `GLAutoDrawable` if not called from the animator thread or `exclusive context thread`.

      Note: Utilizing this feature w/ AWT could lead to an AWT-EDT deadlock, depending on the AWT implementation. Hence it is advised not to use it with native AWT GLAutoDrawable like GLCanvas.

      Parameters:
        `enable` -
      Returns:
        previous value
      See Also:
        `setExclusiveContext(Thread)`, `getExclusiveContextThread()`, `isExclusiveContextEnabled()`

    - #### isExclusiveContextEnabled

          public final boolean isExclusiveContextEnabled()

      Returns `true`, if the exclusive context thread is enabled, otherwise `false`.
      See Also:
        `setExclusiveContext(boolean)`, `setExclusiveContext(Thread)`

    - #### getExclusiveContextThread

          public final Thread getExclusiveContextThread()

      Returns the exclusive context thread if `isExclusiveContextEnabled()` and `isStarted()`, otherwise `null`.

      If exclusive context is enabled via `setExclusiveContext(boolean)` the `animator thread` is returned if above conditions are met.

      If exclusive context is enabled via `setExclusiveContext(Thread)` the user passed thread is returned if above conditions are met.

      See Also:
        `setExclusiveContext(boolean)`, `setExclusiveContext(Thread)`

    - #### getThread

          public final Thread getThread()

      Specified by:
        `getThread` in interface `GLAnimatorControl`
      Returns:
        The animation thread if running, otherwise null.
      See Also:
        `GLAnimatorControl.start()`, `GLAnimatorControl.stop()`

    - #### setUpdateFPSFrames

          public final void setUpdateFPSFrames(int frames,
                                PrintStream out)

      Specified by:
        `setUpdateFPSFrames` in interface `FPSCounter`
      Parameters:
        `frames` - Update interval in frames.
        At every rendered frames interval the currentTime and fps values are updated. If the frames interval is <= 0, no update will be issued, ie the FPSCounter feature is turned off. You may choose `FPSCounter.DEFAULT_FRAMES_PER_INTERVAL`.
        `out` - optional print stream where the fps values gets printed if not null at every frames interval

    - #### resetFPSCounter

          public final void resetFPSCounter()

      Description copied from interface: `FPSCounter`
      Reset all performance counter (startTime, currentTime, frame number)
      Specified by:
        `resetFPSCounter` in interface `FPSCounter`

    - #### getUpdateFPSFrames

          public final int getUpdateFPSFrames()

      Specified by:
        `getUpdateFPSFrames` in interface `FPSCounter`
      Returns:
        update interval in frames
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`

    - #### getFPSStartTime

          public final long getFPSStartTime()

      Description copied from interface: `FPSCounter`
      Returns the time of the first display call in milliseconds after enabling this feature via `FPSCounter.setUpdateFPSFrames(int, PrintStream)`.
      This value is reset via `FPSCounter.resetFPSCounter()`.
      Specified by:
        `getFPSStartTime` in interface `FPSCounter`
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`, `FPSCounter.resetFPSCounter()`

    - #### getLastFPSUpdateTime

          public final long getLastFPSUpdateTime()

      Description copied from interface: `FPSCounter`
      Returns the time of the last update interval in milliseconds, if this feature is enabled via `FPSCounter.setUpdateFPSFrames(int, PrintStream)`.
      This value is reset via `FPSCounter.resetFPSCounter()`.
      Specified by:
        `getLastFPSUpdateTime` in interface `FPSCounter`
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`, `FPSCounter.resetFPSCounter()`

    - #### getLastFPSPeriod

          public final long getLastFPSPeriod()

      Specified by:
        `getLastFPSPeriod` in interface `FPSCounter`
      Returns:
        Duration of the last update interval in milliseconds.
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`, `FPSCounter.resetFPSCounter()`

    - #### getLastFPS

          public final float getLastFPS()

      Specified by:
        `getLastFPS` in interface `FPSCounter`
      Returns:
        Last update interval's frames per seconds, `FPSCounter.getUpdateFPSFrames()` / `FPSCounter.getLastFPSPeriod()`
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`, `FPSCounter.resetFPSCounter()`

    - #### getTotalFPSFrames

          public final int getTotalFPSFrames()

      Specified by:
        `getTotalFPSFrames` in interface `FPSCounter`
      Returns:
        Number of frame rendered since `FPSCounter.getFPSStartTime()` up to `FPSCounter.getLastFPSUpdateTime()`
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`, `FPSCounter.resetFPSCounter()`

    - #### getTotalFPSDuration

          public final long getTotalFPSDuration()

      Specified by:
        `getTotalFPSDuration` in interface `FPSCounter`
      Returns:
        Total duration in milliseconds, `FPSCounter.getLastFPSUpdateTime()` - `FPSCounter.getFPSStartTime()`
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`, `FPSCounter.resetFPSCounter()`

    - #### getTotalFPS

          public final float getTotalFPS()

      Specified by:
        `getTotalFPS` in interface `FPSCounter`
      Returns:
        Total frames per seconds, `FPSCounter.getTotalFPSFrames()` / `FPSCounter.getTotalFPSDuration()`
      See Also:
        `FPSCounter.setUpdateFPSFrames(int, PrintStream)`, `FPSCounter.resetFPSCounter()`

    - #### setIgnoreExceptions

          public final void setIgnoreExceptions(boolean ignoreExceptions)

      Sets a flag causing this Animator to ignore exceptions produced while redrawing the drawables. By default this flag is set to false, causing any exception thrown to halt the Animator.

    - #### setPrintExceptions

          public final void setPrintExceptions(boolean printExceptions)

      Sets a flag indicating that when exceptions are being ignored by this Animator (see `setIgnoreExceptions(boolean)`), to print the exceptions' stack traces for diagnostic information. Defaults to false.

    - #### getUncaughtExceptionHandler

          public final GLAnimatorControl.UncaughtExceptionHandler getUncaughtExceptionHandler()

      Description copied from interface: `GLAnimatorControl`
      Returns the `GLAnimatorControl.UncaughtExceptionHandler` invoked when this `animator` abruptly `stops` due to an uncaught exception from one of its `GLAutoDrawable`s.

      Default is `null`.

      Specified by:
        `getUncaughtExceptionHandler` in interface `GLAnimatorControl`

    - #### setUncaughtExceptionHandler

          public final void setUncaughtExceptionHandler(GLAnimatorControl.UncaughtExceptionHandler handler)

      Description copied from interface: `GLAnimatorControl`
      Set the handler invoked when this `animator` abruptly `stops` due to an uncaught exception from one of its `GLAutoDrawable`s.
      Specified by:
        `setUncaughtExceptionHandler` in interface `GLAnimatorControl`
      Parameters:
        `handler` - the `GLAnimatorControl.UncaughtExceptionHandler` to use as this `animator`'s uncaught exception handler. Pass `null` to unset the handler.
      See Also:
        `GLAnimatorControl.UncaughtExceptionHandler.uncaughtException(GLAnimatorControl, GLAutoDrawable, Throwable)`

    - #### isStarted

          public boolean isStarted()

      Description copied from interface: `GLAnimatorControl`
      Indicates whether this animator has been `started`.
      Specified by:
        `isStarted` in interface `GLAnimatorControl`
      See Also:
        `GLAnimatorControl.start()`, `GLAnimatorControl.stop()`, `GLAnimatorControl.isPaused()`, `GLAnimatorControl.pause()`, `GLAnimatorControl.resume()`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright 2010 JogAmp Community.