org.gicentre.utils

## Class FrameTimer

- java.lang.Object
- - org.gicentre.utils.FrameTimer

-     public class FrameTimer
      extends java.lang.Object

  Class for displaying frame rates in a sketch. To use, declare a `FrameTimer` object at the top of a sketch, initialise it in the `setup()` method, and call one and only one of the methods for reporting frame rates (`displayFrameRate()`, `getFrameRate()`, `getFrameRateAsText()`) in the `draw()` method. Frame rates can be reported either every n frames or every t seconds depending on which constructor is used.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FrameTimer()` Creates a timer that will report the frame rate once in every 50 frames.
    `FrameTimer(float delay, float reportRateInSeconds)` Creates a timer that will report the frame rate once in every `reportRateInSeconds` seconds.
    `FrameTimer(int reportRateInFrames)` Creates a timer that will report the frame rate once in every `reportRateInFrames` frames.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `displayFrameRate()` Displays the current frame rate.
    `float` | `getElapsedTime()` Retrieves the time since the last call to `startTimer()`
    `float` | `getFrameRate()` Reports the current frame rate as a number.
    `java.lang.String` | `getFrameRateAsText()` Reports the current frame rate as formatted text.
    `void` | `startTimer()` Starts a timer that can be used for timing specific parts of a program.
    `void` | `update()` Updates the frame counter.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### FrameTimer

          public FrameTimer()

      Creates a timer that will report the frame rate once in every 50 frames.

    - #### FrameTimer

          public FrameTimer(int reportRateInFrames)

      Creates a timer that will report the frame rate once in every `reportRateInFrames` frames.
      Parameters:
        `reportRateInFrames` - Number of frames to elapse before recalculation of the current frame rate.

    - #### FrameTimer

          public FrameTimer(float delay,
                            float reportRateInSeconds)

      Creates a timer that will report the frame rate once in every `reportRateInSeconds` seconds.
      Parameters:
        `delay` - Number of seconds delay before the first frame rate calculation. This can be useful if you wish to ignore frame rates during the initialisation part of a sketch.
        `reportRateInSeconds` - Number of seconds between recalculations of the current frame rate.

  - ### Method Detail

    - #### displayFrameRate

          public void displayFrameRate()

      Displays the current frame rate. To use this method, it should be called every time a new frame is drawn, but will only display results one in every n frames or once in every t seconds depending on the constructor used. Note that if using a 'by-frame' counter, you should not call this in combination with any of the other frame reporting methods in the same draw() loop as this would over-estimate the actual frame rate.

    - #### getFrameRateAsText

          public java.lang.String getFrameRateAsText()

      Reports the current frame rate as formatted text. To use this method, it should be called every time a new frame is drawn, but will only update results one in every n frames or once in every t seconds depending on the constructor used. Note that if using a 'by-frame' counter, you should not call this in combination with any of the other frame reporting methods in the same draw() loop as this would over-estimate the actual frame rate.
      Returns:
        String reporting the frame rate in frames per second.

    - #### getFrameRate

          public float getFrameRate()

      Reports the current frame rate as a number. To use this method, it should be called every time a new frame is drawn, but will only update results one in every n frames or once in every t seconds depending on the constructor used. Note that if using a 'by-frame' counter, you should not call this in combination with any of the other frame reporting methods in the same draw() loop as this would over-estimate the actual frame rate.
      Returns:
        Number of frames per second.

    - #### update

          public void update()

      Updates the frame counter. This method should only be called if a frame counter that reports by time is to be used. If so, it should be called once per draw() cycle. There is no need to call this method if frame rate reporting is on a 'per-frame' basis.

    - #### startTimer

          public void startTimer()

      Starts a timer that can be used for timing specific parts of a program. Call `getElapsedTime` to retrieve the number of seconds since a call was made to this method.

    - #### getElapsedTime

          public float getElapsedTime()

      Retrieves the time since the last call to `startTimer()`
      Returns:
        Time in seconds since `startTimer` was last called, or 0 if it has not been called.