Clock Class

Inheritance diagram of Clock

class Clock(fps_limit=None, time_function=<built-in function time>)

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

Constructor:

__init__(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.2.
  • 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.

Methods:

call_scheduled_functions(dt) Call scheduled functions that elapsed on the last update_time.
get_fps() Get the average FPS of recent history.
get_fps_limit() Get the framerate limit.
get_sleep_time(sleep_idle) Get the time until the next item is scheduled.
schedule(func, *args, **kwargs) Schedule a function to be called every frame.
schedule_interval(func, interval, *args, ...) Schedule a function to be called every interval seconds.
schedule_interval_soft(func, interval, ...) Schedule a function to be called every interval seconds, beginning at a time that does not coincide with other scheduled events.
schedule_once(func, delay, *args, **kwargs) Schedule a function to be called once after delay seconds.
set_fps_limit(fps_limit) Set the framerate limit.
sleep(microseconds)
tick([poll]) Signify that one frame has passed.
unschedule(func) Remove a function from the schedule.
update_time() Get the elapsed time since the last call to update_time.

Attributes:

MIN_SLEEP Type: float
SLEEP_UNDERSHOOT Type: float

Methods

Clock.call_scheduled_functions(dt)

Call scheduled functions that elapsed on the last update_time.

Note

Since pyglet 1.2

Parameters:dt (float) – The elapsed time since the last update to pass to each scheduled function. This is not used to calculate which functions have elapsed.
Return type:bool
Returns:True if any functions were called, otherwise False.
Clock.get_fps()

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.

Return type:float
Returns:The measured frames per second.
Clock.get_fps_limit()

Get the framerate limit.

Return type:float
Returns:The framerate limit previously set in the constructor or set_fps_limit, or None if no limit was set.
Clock.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.

Note

Since pyglet 1.1

Clock.schedule(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.
Clock.schedule_interval(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.
Clock.schedule_interval_soft(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.

Note

Since pyglet 1.1

Parameters:
  • func (function) – The function to call when the timer lapses.
  • interval (float) – The number of seconds to wait between each call.
Clock.schedule_once(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.
Clock.set_fps_limit(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.

Warning

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

Clock.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.
Clock.unschedule(func)

Remove a function from the schedule.

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

Parameters:func (function) – The function to remove from the schedule.
Clock.update_time()

Get the elapsed time since the last call to update_time.

This updates the clock’s internal measure of time and returns the difference since the last update (or since the clock was created).

Note

Since pyglet 1.2

Return type:float
Returns:The number of seconds since the last update_time, or 0 if this was the first time it was called.

Attributes

Clock.MIN_SLEEP = 0.005

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.

Clock.SLEEP_UNDERSHOOT = 0.004

The amount of time in seconds this clock subtracts from sleep values to compensate for lazy operating systems.

Inherited members

Methods

Clock.sleep(microseconds)

Table Of Contents

Previous topic

unschedule Function

Next topic

ClockDisplay Class