gillcup.clock

Gillcup’s Clock Class

In Gillcup, animation means two things: running code at specified times, and changing object properties with time.

You will notice that the preceding sentence mentions time quite a lot. But what is this time?

You could determine time by looking at the computer’s clock, but that would only work with real-time animations. When you’d want to render a movie, where each frame takes 2 seconds to draw and there are 25 frames per second, you’d be stuck. That’s why Gillcup introduces a flexible source of time, the Clock, which keeps track of time and schedules actions.

Time is measured in “time units”. What a time unit means is entirely up to the application – it could be seconds, movie/simulation frames, etc.

class gillcup.Clock

Keeps track of time and schedules events.

Attributes:

time

The current time on the clock. Never assign to it directly; use advance() instead.

Animated Properties:

speed

Speed of the clock.

When calling update(), the interval is multiplied by this value.

The speed is an AnimatedProperty. When changing, beware that it is only checked when advance() is called or when a scheduled action is run, so speed animations will be only approximate. For better accuracy, call advance() with small dt, or schedule a periodic dummy action at small inervals.

Basic methods:

advance(dt)

Call to advance the clock’s time

Steps the clock dt units to the future, pausing at times when actions are scheduled, and running them.

Attempting to move to the past (dt<0) will raise an error.

schedule(action, dt=0)

Schedule an action to be run “dt” time units from the current time

Scheduling is stable: if two things are scheduled for the same time, they will be called in the order they were scheduled.

Scheduling an action in the past (dt<0) will raise an error.

If the scheduled callable has a “schedule_callback” method, it will be called with the clock and the time it’s been scheduled at.

Update function registration:

schedule_update_function(function)

Schedule a function to be called every time the clock advances

Then function will be called a lot, so it shouldn’t be very expensive.

Only a weak reference is made to the function, so the caller should ensure another reference to it is retained as long as it should be called.

unschedule_update_function(function)

Unschedule a function scheduled by schedule_update_function

class gillcup.Subclock(parent, speed=1)

A Clock that advances in sync with another Clock

A Subclock advances whenever its parent clock does. Its speed attribute specifies the relative speed relative to the parent clock. For example, if speed==2, the subclock will run twice as fast as its parent clock.

Unlike clocks synchronized via actions or update functions, the actions scheduled on a parent Clock and all subclocks are run in the correct sequence, with all clocks at the correct times when each action is run.