# cocos.custom_clocks module

Custom clocks used by cocos to perform special tasks, like:

  - recording a cocos app as a sequence of snapshots with an exact, fixed framerate

  - jump in a predefined sequence of timestamps taking snapshots

dev notes: There’s code duplication here, but having separated codepaths would help to follow changes in pyglet 1.2dev. When released, we could refactor this with some confidence.

References to the classes defined here are discouraged in code outside this module because of possible changes.

The public interface should be

  - get_recorder_clock

  - set_app_clock

class `AutotestClock`(screen_sampler)

  Bases: `pyglet.clock.Clock`

  Make frames follow a test plan

  This class is compatible with pyglet 1.1.4release, it is not compatible with pyglet 1.2dev

  `get_sleep_time`(sleep_idle)

    Get the time until the next item is scheduled.

    This method considers all scheduled items and the current `fps_limit`, if any.

    Applications can choose to continue receiving updates at the maximum framerate during idle time (when no functions are scheduled), or they can sleep through their idle time and allow the CPU to switch to other processes or run in low-power mode.

    If sleep_idle is `True` the latter behaviour is selected, and `None` will be returned if there are no scheduled items.

    Otherwise, if sleep_idle is `False`, a sleep time allowing the maximum possible framerate (considering `fps_limit`) will be returned; or an earlier time if a scheduled function is ready.

    Parameters
      sleep_idle bool

        If True, the application intends to sleep through its idle time; otherwise it will continue ticking at the maximum frame rate allowed.

    Return type

      float

    Returns

      Time until the next scheduled event in seconds, or `None` if there is no event scheduled.

    New in version 1.1.

  `tick`(poll=False)

    Signify that one frame has passed.

    This will call any scheduled functions that have elapsed.

    Parameters
      poll bool

        If True, the function will call any scheduled functions but will not sleep or busy-wait for any reason. Recommended for advanced applications managing their own sleep timers only.

        Since pyglet 1.1.

    Return type

      float

    Returns

      The number of seconds since the last “tick”, or 0 if this was the first frame.

class `AutotestClock_12dev`(screen_sampler)

  Bases: `pyglet.clock.Clock`

  Make frames follow a test plan

  This class is compatible with pyglet 1.2dev, it is not compatible with pyglet 1.1.4release

  `get_sleep_time`(sleep_idle)

    sleep time between frames; 0.0 as as we want to run as fast as possible

  `update_time`()
    Get the (fake) elapsed time since the last call to update_time

      Additionally, take snapshots.

    Return type

      float

    Returns

      The number of seconds since the last update_time, or 0 if this was the first time it was called.

class `ScreenReaderClock`(framerate, template, duration)

  Bases: `pyglet.clock.Clock`

  Make frames happen every 1/framerate and takes screenshots

  This class is compatible with pyglet 1.1.4release, it is not compatible with pyglet 1.2dev

  `tick`(poll=False)

    Signify that one frame has passed.

class `ScreenReaderClock_12dev`(framerate, template, duration)

  Bases: `pyglet.clock.Clock`

  Make frames happen every 1/framerate and takes screenshots

  This class is compatible with pyglet 1.2dev, it is not compatible with pyglet 1.1.4release

  `get_sleep_time`(sleep_idle)

    sleep time between frames; 0.0 as as we want to run as fast as possible

  `update_time`()
    Get the (fake) elapsed time since the last call to update_time

      Additionally, take snapshots.

    Return type

      float

    Returns

      The number of seconds since the last update_time, or 0 if this was the first time it was called.

`get_autotest_clock`(sampler)

  Returns a clock object suitable to be used as a pyglet app clock, which will follow a test plan to advance time and take snapshots.

  The clock object class depends on the pyglet version, and is determined automatically.

  Parameters
    sampler obj

      obj with interface sampler.next(last_app_time) -> next_app_time Drives the app trough the desired states, take snapshots and handles the app termination conditions.

`get_recorder_clock`(framerate, template, duration=0)

  Returns a clock object suitable to be used as a pyglet app clock, which will provide a steady framerate, and saves a snapshot for each frame from time=0 to time=duration

  The clock object class depends on the pyglet version, and is set automatically

  Parameters
    framerate int

      the number of frames per second

    template str

      snapshot filenames will be template%frame_number (ex: “s%d.png” -> s0.png, s1.png…)

    duration float

      the amount of seconds to record, or 0 for infinite

`set_app_clock`(clock)

  Sets the cocos (or pyglet) app clock to a custom one