pyglet.clock¶
Precise framerate calculation function scheduling.
The clock
module allows you to schedule functions
to run periodically, or for one-shot future execution. pyglet’s default
event loop (run()
) keeps an internal instance of
a Clock
, which is ticked automatically.
- ..note:: Some internal modules will schedule items on the clock. If you
- are using a custom event loop, always remember to tick the clock!
Scheduling¶
You can schedule a function to be called every time the clock is ticked:
def callback(dt):
print(f"{dt} seconds since last callback")
clock.schedule(callback)
The schedule_interval method causes a function to be called every “n” seconds:
clock.schedule_interval(callback, 0.5) # called twice a second
The schedule_once method causes a function to be called once “n” seconds in the future:
clock.schedule_once(callback, 5) # called in 5 seconds
All the schedule methods will pass on any additional args or keyword args you specify to the callback function:
def move(dt, velocity, sprite):
sprite.position += dt * velocity
clock.schedule(move, velocity=5.0, sprite=alien)
You can cancel a function scheduled with any of these methods using unschedule:
clock.unschedule(move)
Using multiple clocks¶
The clock functions are all relayed to an instance of
Clock
which is initialised with the module. You can
get this instance to use directly:
clk = pyglet.clock.get_default()
You can also replace the default clock with your own:
myclk = pyglet.clock.Clock() pyglet.clock.set_default(myclk)
Each clock maintains its own set of scheduled functions and frequency measurement. Each clock must be “ticked” separately.
Multiple and derived clocks potentially allow you to separate “game-time” and “wall-time”, or to synchronise your clock to an audio or video stream instead of the system clock.
-
class
Clock
(time_function=<built-in function perf_counter>)¶ Class for calculating and limiting framerate.
It is also used for calling scheduled functions.
-
call_scheduled_functions
(dt)¶ Call scheduled functions that elapsed on the last update_time.
New in version 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.
-
get_frequency
()¶ Get the average clock update frequency of recent history.
The result is the average of a sliding window of the last “n” updates, where “n” is some number designed to cover approximately 1 second. This is not the Window redraw rate.
Return type: float Returns: The measured updates per second.
-
get_sleep_time
(sleep_idle)¶ Get the time until the next item is scheduled.
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, andNone
will be returned if there are no scheduled items.Otherwise, if sleep_idle is
False
, or if any scheduled items exist, a value of 0 is returned.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.
-
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 : callable
The function to call each frame.
-
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 : callable
The function to call when the timer lapses.
- interval : float
The number of seconds to wait between each call.
-
schedule_interval_soft
(func, interval, *args, **kwargs)¶ Schedule a function to be called every
interval
seconds.This method is similar to schedule_interval, except that the clock will move the interval out of phase with other scheduled functions in order to distribute CPU load more evenly.
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.
New in version 1.1.
Parameters: - func : callable
The function to call when the timer lapses.
- interval : float
The number of seconds to wait between each call.
-
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 : callable
The function to call when the timer lapses.
- delay : float
The number of seconds to wait before the timer lapses.
-
static
sleep
(microseconds)¶
-
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.
-
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 : callable
The function to remove from the schedule.
-
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).
New in version 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.
-
-
get_default
()¶ Get the pyglet default Clock.
Return the
Clock
instance that is used by all module-level clock functions.
-
get_frequency
() → float¶ Get the average clock update frequency.
The result is the sliding average of the last “n” updates, where “n” is some number designed to cover approximately 1 second. This is the internal clock update rate, not the Window redraw rate. Platform events, such as moving the mouse rapidly, will cause the clock to refresh more often.
-
get_sleep_time
(sleep_idle: bool) → float¶ Get the time until the next item is scheduled on the default clock.
Returns the time until the next scheduled event in seconds, or
None
if there is no event scheduled.See Clock.get_sleep_time for details.
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.
-
schedule
(func: Callable, *args, **kwargs) → None¶ Schedule ‘func’ to be called every frame on the default clock.
The arguments passed to func are
dt
, followed by any*args
and**kwargs
given here.
-
schedule_interval
(func: Callable, interval: float, *args, **kwargs) → None¶ Schedule
func
on the default clock everyinterval
seconds.The arguments passed to
func
aredt
(time since last function call), followed by any*args
and**kwargs
given here.
-
schedule_interval_soft
(func: Callable, interval: float, *args, **kwargs) → None¶ Schedule
func
on the default clock every interval seconds.The clock will move the interval out of phase with other scheduled functions in order to distribute CPU load more evenly.
The arguments passed to
func
aredt
(time since last function call), followed by any*args
and**kwargs
given here.See: Clock.schedule_interval_soft
-
schedule_once
(func: Callable, delay: float, *args, **kwargs) → None¶ Schedule
func
to be called once afterdelay
seconds.This function uses the default clock.
delay
can be a float. The arguments passed tofunc
aredt
(time since last function call), followed by any*args
and**kwargs
given here.If no default clock is set, the func is queued and will be scheduled on the default clock as soon as it is created.
-
set_default
(default) → None¶ Set the default clock to use for all module-level functions.
By default, an instance of
Clock
is used.
-
tick
(poll: bool = False) → float¶ Signify that one frame has passed on the default clock.
This will call any scheduled functions that have elapsed, and return the elapsed seconds since the last tick. The return value will be 0.0 if this is the first tick.
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.
-
unschedule
(func: Callable) → None¶ Remove
func
from the default clock’s schedule.No error is raised if the
func
was never scheduled.