# Class pyglet.clock.Clock

    _ClockBase --+
                 |
                Clock

Class for calculating and limiting framerate, and for calling scheduled functions.

## Methods

| __init__(self, fps_limit=None, time_function=<built-in function time>) Initialise a Clock, with optional framerate limit and custom time function.
float | tick(self, poll=False) Signify that one frame has passed.
float | get_sleep_time(self, sleep_idle) Get the time until the next item is scheduled.
| set_fps_limit(self, fps_limit) Set the framerate limit.
float | get_fps_limit(self) Get the framerate limit.
float | get_fps(self) Get the average FPS of recent history.
| schedule(self, func, *args, **kwargs) Schedule a function to be called every frame.
| schedule_interval(self, func, interval, *args, **kwargs) Schedule a function to be called every `interval` seconds.
| schedule_interval_soft(self, func, interval, *args, **kwargs) Schedule a function to be called every `interval` seconds, beginning at a time that does not coincide with other scheduled events.
| schedule_once(self, func, delay, *args, **kwargs) Schedule a function to be called once after `delay` seconds.
| unschedule(self, func) Remove a function from the schedule.
Inherited from `_ClockBase`: `sleep`

## Constants

| MIN_SLEEP = `0.005` The minimum amount of time in seconds this clock will attempt to sleep for when framerate limiting.
| SLEEP_UNDERSHOOT = `0.004` The amount of time in seconds this clock subtracts from sleep values to compensate for lazy operating systems.

## Method Details

### __init__

(Constructor) __init__(self, fps_limit=None, time_function=<built-in function time>)
Initialise a Clock, with optional framerate limit and custom time function.

Parameters:
  fps_limit : float
    If not None, the maximum allowable framerate. Defaults to None. Deprecated in pyglet 1.1.
  time_function : function
    Function to return the elapsed time of the application, in seconds. Defaults to time.time, but can be replaced to allow for easy time dilation effects or game pausing.

### tick

tick(self, 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.

Returns:
  float: The number of seconds since the last "tick", or 0 if this was the first frame.

### get_sleep_time

get_sleep_time(self, 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.
Returns:
  float: Time until the next scheduled event in seconds, or `None` if there is no event scheduled.

Since: pyglet 1.1

### set_fps_limit

set_fps_limit(self, fps_limit)

Set the framerate limit.

The framerate limit applies only when a function is scheduled for every frame. That is, the framerate limit can be exceeded by scheduling a function for a very small period of time.

Parameters:
  fps_limit : float
    Maximum frames per second allowed, or None to disable limiting.

Deprecated: Use pyglet.app.run and schedule_interval instead.

### get_fps_limit

get_fps_limit(self)
Get the framerate limit.

Returns:
  float: The framerate limit previously set in the constructor or set_fps_limit, or None if no limit was set.

### get_fps

get_fps(self)

Get the average FPS of recent history.

The result is the average of a sliding window of the last "n" frames, where "n" is some number designed to cover approximately 1 second.

Returns:
  float: The measured frames per second.

### schedule

schedule(self, func, *args, **kwargs)

Schedule a function to be called every frame.

The function should have a prototype that includes `dt` as the first argument, which gives the elapsed time, in seconds, since the last clock tick. Any additional arguments given to this function are passed on to the callback:

    def callback(dt, *args, **kwargs):
        pass

Parameters:
  func : function
    The function to call each frame.

### schedule_interval

schedule_interval(self, func, interval, *args, **kwargs)

Schedule a function to be called every `interval` seconds.

Specifying an interval of 0 prevents the function from being called again (see schedule to call a function as often as possible).

The callback function prototype is the same as for schedule.

Parameters:
  func : function
    The function to call when the timer lapses.
  interval : float
    The number of seconds to wait between each call.

### schedule_interval_soft

schedule_interval_soft(self, func, interval, *args, **kwargs)

Schedule a function to be called every `interval` seconds, beginning at a time that does not coincide with other scheduled events.

This method is similar to schedule_interval, except that the clock will move the interval out of phase with other scheduled functions so as to distribute CPU more load evenly over time.

This is useful for functions that need to be called regularly, but not relative to the initial start time. pyglet.media does this for scheduling audio buffer updates, which need to occur regularly -- if all audio updates are scheduled at the same time (for example, mixing several tracks of a music score, or playing multiple videos back simultaneously), the resulting load on the CPU is excessive for those intervals but idle outside. Using the soft interval scheduling, the load is more evenly distributed.

Soft interval scheduling can also be used as an easy way to schedule graphics animations out of phase; for example, multiple flags waving in the wind.

Parameters:
  func : function
    The function to call when the timer lapses.
  interval : float
    The number of seconds to wait between each call.

Since: pyglet 1.1

### schedule_once

schedule_once(self, func, delay, *args, **kwargs)

Schedule a function to be called once after `delay` seconds.

The callback function prototype is the same as for schedule.

Parameters:
  func : function
    The function to call when the timer lapses.
  delay : float
    The number of seconds to wait before the timer lapses.

### unschedule

unschedule(self, func)

Remove a function from the schedule.

If the function appears in the schedule more than once, all occurances are removed. If the function was not scheduled, no error is raised.

Parameters:
  func : function
    The function to remove from the schedule.

## Constant Details

### MIN_SLEEP

The minimum amount of time in seconds this clock will attempt to sleep for when framerate limiting. Higher values will increase the accuracy of the limiting but also increase CPU usage while busy-waiting. Lower values mean the process sleeps more often, but is prone to over-sleep and run at a potentially lower or uneven framerate than desired.

Value:

      0.005