# Module 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 functions.
| ClockDisplay Display current clock values, such as FPS.

## Functions

| set_default(default) Set the default clock to use for all module-level functions.
Clock | get_default() Return the Clock instance that is used by all module-level clock functions.
float | tick(poll=False) Signify that one frame has passed on the default clock.
float | get_sleep_time(sleep_idle) Get the time until the next item is scheduled on the default clock.
float | get_fps() Return the current measured FPS of the default clock.
| set_fps_limit(fps_limit) Set the framerate limit for the default clock.
| get_fps_limit() Get the framerate limit for the default clock.
| schedule(func, *args, **kwargs) Schedule 'func' to be called every frame on the default clock.
| schedule_interval(func, interval, *args, **kwargs) Schedule 'func' to be called every 'interval' seconds on the default clock.
| schedule_interval_soft(func, interval, *args, **kwargs) 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.
| unschedule(func) Remove 'func' from the default clock's schedule.
| test_clock()

## Variables

| __package__ = ``'``pyglet``'``

## Function Details

### set_default

set_default(default)

Set the default clock to use for all module-level functions.

By default an instance of Clock is used.

Parameters:
  default : Clock
    The default clock to use.

### get_default

get_default()
Return the Clock instance that is used by all module-level clock functions.

Returns:
  Clock: The default clock.

### tick

tick(poll=False)

Signify that one frame has passed on the default clock.

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(sleep_idle)

Get the time until the next item is scheduled on the default clock.

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.
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(fps_limit)
Set the framerate limit for the default clock.

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()
Get the framerate limit for the default clock.

Returns:
  The framerate limit previously set by set_fps_limit, or None if no limit was set.

### schedule

schedule(func, *args, **kwargs)

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.

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

### schedule_interval

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

Schedule 'func' to be called every 'interval' seconds on the default clock.

The arguments passed to 'func' are 'dt' (time since last function call), followed by any `*args` and `**kwargs` given here.

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(func, interval, *args, **kwargs)

Schedule 'func' to be called every 'interval' seconds on the default clock, beginning at a time that does not coincide with other scheduled events.

The arguments passed to 'func' are 'dt' (time since last function call), followed by any `*args` and `**kwargs` given here.

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

See Also: Clock.schedule_interval_soft

Since: pyglet 1.1

### schedule_once

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

Schedule 'func' to be called once after 'delay' seconds (can be a float) on the default clock. The arguments passed to 'func' are 'dt' (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.

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(func)
Remove 'func' from the default clock's schedule. No error is raised if the func was never scheduled.

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