pyglet.clock

Precise framerate calculation, scheduling and framerate limiting.

Measuring time

The tick and get_fps functions can be used in conjunction to fulfil most games’ basic requirements:

from pyglet import clock
while True:
    dt = clock.tick()
    # ... update and render ...
    print 'FPS is %f' % clock.get_fps()

The dt value returned gives the number of seconds (as a float) since the last “tick”.

The get_fps function averages the framerate over a sliding window of approximately 1 second. (You can calculate the instantaneous framerate by taking the reciprocal of dt).

Always remember to tick the clock!

Limiting frame-rate

The framerate can be limited:

clock.set_fps_limit(60)

This causes clock to sleep during each tick in an attempt to keep the number of ticks (frames) per second below 60.

The implementation uses platform-dependent high-resolution sleep functions to achieve better accuracy with busy-waiting than would be possible using just the time module.

Scheduling

You can schedule a function to be called every time the clock is ticked:

def callback(dt):
    print '%f seconds since last callback' % dt

clock.schedule(callback)

The schedule_interval method causes a function to be called every “n” seconds:

clock.schedule_interval(callback, .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 of the schedule methods will pass on any additional args or keyword args you specify to the callback function:

def animate(dt, velocity, sprite):
   sprite.position += dt * velocity

clock.schedule(animate, velocity=5.0, sprite=alien)

You can cancel a function scheduled with any of these methods using unschedule:

clock.unschedule(animate)

Displaying FPS

The ClockDisplay class provides a simple FPS counter. You should create an instance of ClockDisplay once during the application’s start up:

fps_display = clock.ClockDisplay()

Call draw on the ClockDisplay object for each frame:

fps_display.draw()

There are several options to change the font, color and text displayed within the __init__ method.

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 = clock.get_default()

You can also replace the default clock with your own:

myclk = clock.Clock() clock.set_default(myclk)

Each clock maintains its own set of scheduled functions and FPS limiting/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.

Classes

Clock Class for calculating and limiting framerate, and for calling scheduled
ClockDisplay Display current clock values, such as FPS.

Functions

get_default() Return the Clock instance that is used by all module-level
get_fps() Return the current measured FPS of the default clock.
get_fps_limit() Get the framerate limit for the default clock.
get_sleep_time(sleep_idle) Get the time until the next item is scheduled on the default clock.
schedule(func, *args, **kwargs) Schedule ‘func’ to be called every frame on the default clock.
schedule_interval(func, interval, *args, ...) Schedule ‘func’ to be called every ‘interval’ seconds on the default clock.
schedule_interval_soft(func, interval, ...) Schedule ‘func’ to be called every ‘interval’ seconds on the default clock, beginning at a time that does not coincide with other scheduled events.
schedule_once(func, delay, *args, **kwargs) Schedule ‘func’ to be called once after ‘delay’ seconds (can be a float) on the default clock.
set_default(default) Set the default clock to use for all module-level functions.
set_fps_limit(fps_limit) Set the framerate limit for the default clock.
test_clock()
tick([poll]) Signify that one frame has passed on the default clock.
unschedule(func) Remove ‘func’ from the default clock’s schedule.

Notes

Defined

  • pyglet
  • sys
  • time

Table Of Contents

Previous topic

get_display Function

Next topic

Clock Class