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