ClockObject

from panda3d.core import ClockObject

class ClockObject

Bases:

Bases: ReferenceCount

A ClockObject keeps track of elapsed real time and discrete time. In normal mode, getFrameTime() returns the time as of the last time tick() was called. This is the “discrete” time, and is usually used to get the time as of, for instance, the beginning of the current frame.

In other modes, as set by setMode() or the clock-mode config variable, getFrameTime() may return other values to simulate different timing effects, for instance to perform non-real-time animation. See setMode().

In all modes, getRealTime() always returns the elapsed real time in seconds since the ClockObject was constructed, or since it was last reset.

You can create your own ClockObject whenever you want to have your own local timer. There is also a default, global ClockObject intended to represent global time for the application; this is normally set up to tick every frame so that its getFrameTime() will return the time for the current frame.

Inheritance diagram

enum Mode

enumerator M_normal = 0

enumerator M_non_real_time = 1

enumerator M_forced = 2

enumerator M_degrade = 3

enumerator M_slave = 4

enumerator M_limited = 5

enumerator M_integer = 6

enumerator M_integer_limited = 7

__init__(copy: ClockObject)

__init__(mode: Mode)

property average_frame_rate → float

Returns the average frame rate in number of frames per second over the last getAverageFrameRateInterval() seconds. This measures the virtual frame rate if the clock is in M_non_real_time mode.

property average_frame_rate_interval → float

Getter

Returns the interval of time (in seconds) over which getAverageFrameRate() averages the number of frames per second to compute the frame rate.

Setter

Specifies the interval of time (in seconds) over which getAverageFrameRate() averages the number of frames per second to compute the frame rate. Changing this does not necessarily immediately change the result of getAverageFrameRate(), until this interval of time has elapsed again.

Setting this to zero disables the computation of getAverageFrameRate().

calcFrameRateDeviation(current_thread: Thread) → float

Returns the standard deviation of the frame times of the frames rendered over the past getAverageFrameRateInterval() seconds. This number gives an estimate of the chugginess of the frame rate; if it is large, there is a large variation in the frame rate; if is small, all of the frames are consistent in length.

A large value might also represent just a recent change in frame rate, for instance, because the camera has just rotated from looking at a simple scene to looking at a more complex scene.

checkErrors(current_thread: Thread) → bool

Returns true if a clock error was detected since the last time checkErrors() was called. A clock error means that something happened, an OS or BIOS bug, for instance, that makes the current value of the clock somewhat suspect, and an application may wish to resynchronize with any external clocks.

property degrade_factor → float

In degrade mode, returns/sets the ratio by which the performance is degraded. A value of 2.0 causes the clock to be slowed down by a factor of two (reducing performance to 1/2 what would be otherwise).

This has no effect if mode is not M_degrade.

property dt → float

Getter

Returns the elapsed time for the previous frame: the number of seconds elapsed between the last two calls to tick().

Setter

In non-real-time mode, sets the number of seconds that should appear to elapse between frames. In forced mode or limited mode, sets our target dt. In normal mode, this has no effect.

Also see setFrameRate(), which is a different way to specify the same quantity.

property frame_count → int

Getter

Returns the number of times tick() has been called since the ClockObject was created, or since it was last reset. This is generally the number of frames that have been rendered.

Setter

Resets the number of frames counted to the indicated number. Also see reset(), setRealTime(), and setFrameTime().

property frame_time → float

Getter

Returns the time in seconds as of the last time tick() was called (typically, this will be as of the start of the current frame).

This is generally the kind of time you want to ask for in most rendering and animation contexts, since it’s important that all of the animation for a given frame remains in sync with each other.

Setter

Changes the time as reported for the current frame to the indicated time. Normally, the way to adjust the frame time is via tick(); this function is provided only for occasional special adjustments.

getAverageFrameRate(current_thread: Thread) → float

Returns the average frame rate in number of frames per second over the last getAverageFrameRateInterval() seconds. This measures the virtual frame rate if the clock is in M_non_real_time mode.

getAverageFrameRateInterval() → float

Returns the interval of time (in seconds) over which getAverageFrameRate() averages the number of frames per second to compute the frame rate.

static getClassType() → TypeHandle

getDegradeFactor() → float

In degrade mode, returns the ratio by which the performance is degraded. A value of 2.0 causes the clock to be slowed down by a factor of two (reducing performance to 1/2 what would be otherwise).

This has no effect if mode is not M_degrade.

getDt(current_thread: Thread) → float

Returns the elapsed time for the previous frame: the number of seconds elapsed between the last two calls to tick().

getFrameCount(current_thread: Thread) → int

Returns the number of times tick() has been called since the ClockObject was created, or since it was last reset. This is generally the number of frames that have been rendered.

getFrameTime(current_thread: Thread) → float

Returns the time in seconds as of the last time tick() was called (typically, this will be as of the start of the current frame).

This is generally the kind of time you want to ask for in most rendering and animation contexts, since it’s important that all of the animation for a given frame remains in sync with each other.

static getGlobalClock() → ClockObject

Returns a pointer to the global ClockObject. This is the ClockObject that most code should use for handling scene graph rendering and animation.

getLongTime() → float

Returns the actual number of seconds elapsed since the ClockObject was created, or since it was last reset.

This is similar to getRealTime(), except that it uses the most accurate counter we have over a long period of time, and so it is less likely to drift. However, it may not be very precise for measuring short intervals. On Windows, for instace, this is only accurate to within about 55 milliseconds.

getMaxDt() → float

Returns the current maximum allowable time elapsed between any two frames. See setMaxDt().

getMaxFrameDuration(current_thread: Thread) → float

Returns the maximum frame duration over the last getAverageFrameRateInterval() seconds.

getMode() → Mode

Returns the current mode of the clock. See setMode().

getNetFrameRate(current_thread: Thread) → float

Returns the average frame rate since the last reset. This is simply the total number of frames divided by the total elapsed time. This reports the virtual frame rate if the clock is in (or has been in) M_non_real_time mode.

getRealTime() → float

Returns the actual number of seconds elapsed since the ClockObject was created, or since it was last reset. This is useful for doing real timing measurements, e.g. for performance statistics.

This returns the most precise timer we have for short time intervals, but it may tend to drift over the long haul. If more accurate timekeeping is needed over a long period of time, use getLongTime() instead.

property long_time → float

Returns the actual number of seconds elapsed since the ClockObject was created, or since it was last reset.

This is similar to getRealTime(), except that it uses the most accurate counter we have over a long period of time, and so it is less likely to drift. However, it may not be very precise for measuring short intervals. On Windows, for instace, this is only accurate to within about 55 milliseconds.

property max_dt → float

Getter

Returns the current maximum allowable time elapsed between any two frames. See setMaxDt().

Setter

Sets a limit on the value returned by getDt(). If this value is less than zero, no limit is imposed; otherwise, this is the maximum value that will ever be returned by getDt(), regardless of how much time has actually elapsed between frames.

This limit is only imposed in real-time mode; in non-real-time mode, the dt is fixed anyway and max_dt is ignored.

This is generally used to guarantee reasonable behavior even in the presence of a very slow or chuggy frame rame.

property max_frame_duration → float

Returns the maximum frame duration over the last getAverageFrameRateInterval() seconds.

property mode → Mode

Getter

Returns the current mode of the clock. See setMode().

Setter

Changes the mode of the clock. Normally, the clock is in mode M_normal. In this mode, each call to tick() will set the value returned by getFrameTime() to the current real time; thus, the clock simply reports time advancing.

Other possible modes:

M_non_real_time - the clock ignores real time completely; at each call to tick(), it pretends that exactly dt seconds have elapsed since the last call to tick(). You may set the value of dt with setDt() or setFrameRate().

M_limited - the clock will run as fast as it can, as in M_normal, but will not run faster than the rate specified by setFrameRate(). If the application would run faster than this rate, the clock will slow down the application.

M_integer - the clock will run as fast as it can, but the rate will be constrained to be an integer multiple or divisor of the rate specified by setFrameRate(). The clock will slow down the application a bit to guarantee this.

M_integer_limited - a combination of M_limited and M_integer; the clock will not run faster than setFrameRate(), and if it runs slower, it will run at a integer divisor of that rate.

M_forced - the clock forces the application to run at the rate specified by setFrameRate(). If the application would run faster than this rate, the clock will slow down the application; if the application would run slower than this rate, the clock slows down time so that the application believes it is running at the given rate.

M_degrade - the clock runs at real time, but the application is slowed down by a set factor of its frame rate, specified by setDegradeFactor().

M_slave - the clock does not advance, but relies on the user to call setFrameTime() and/or setFrameCount() each frame.

property real_time → float

Getter

Returns the actual number of seconds elapsed since the ClockObject was created, or since it was last reset. This is useful for doing real timing measurements, e.g. for performance statistics.

This returns the most precise timer we have for short time intervals, but it may tend to drift over the long haul. If more accurate timekeeping is needed over a long period of time, use getLongTime() instead.

Setter

Resets the clock to the indicated time. This changes only the real time of the clock as reported by getRealTime(), but does not immediately change the time reported by get_frame_time()–that will change after the next call to tick(). Also see reset(), setFrameTime(), and setFrameCount().

reset()

Simultaneously resets both the time and the frame count to zero.

setAverageFrameRateInterval(time: float)

Specifies the interval of time (in seconds) over which getAverageFrameRate() averages the number of frames per second to compute the frame rate. Changing this does not necessarily immediately change the result of getAverageFrameRate(), until this interval of time has elapsed again.

Setting this to zero disables the computation of getAverageFrameRate().

setDegradeFactor(degrade_factor: float)

In degrade mode, sets the ratio by which the performance is degraded. A value of 2.0 causes the clock to be slowed down by a factor of two (reducing performance to 1/2 what would be otherwise).

This has no effect if mode is not M_degrade.

setDt(dt: float)

In non-real-time mode, sets the number of seconds that should appear to elapse between frames. In forced mode or limited mode, sets our target dt. In normal mode, this has no effect.

Also see setFrameRate(), which is a different way to specify the same quantity.

setFrameCount(frame_count: int, current_thread: Thread)

Resets the number of frames counted to the indicated number. Also see reset(), setRealTime(), and setFrameTime().

setFrameRate(frame_rate: float)

In non-real-time mode, sets the number of frames per second that we should appear to be running. In forced mode or limited mode, sets our target frame rate. In normal mode, this has no effect.

Also see setDt(), which is a different way to specify the same quantity.

setFrameTime(time: float, current_thread: Thread)

Changes the time as reported for the current frame to the indicated time. Normally, the way to adjust the frame time is via tick(); this function is provided only for occasional special adjustments.

setMaxDt(max_dt: float)

Sets a limit on the value returned by getDt(). If this value is less than zero, no limit is imposed; otherwise, this is the maximum value that will ever be returned by getDt(), regardless of how much time has actually elapsed between frames.

This limit is only imposed in real-time mode; in non-real-time mode, the dt is fixed anyway and max_dt is ignored.

This is generally used to guarantee reasonable behavior even in the presence of a very slow or chuggy frame rame.

setMode(mode: Mode)

Changes the mode of the clock. Normally, the clock is in mode M_normal. In this mode, each call to tick() will set the value returned by getFrameTime() to the current real time; thus, the clock simply reports time advancing.

Other possible modes:

M_non_real_time - the clock ignores real time completely; at each call to tick(), it pretends that exactly dt seconds have elapsed since the last call to tick(). You may set the value of dt with setDt() or setFrameRate().

M_limited - the clock will run as fast as it can, as in M_normal, but will not run faster than the rate specified by setFrameRate(). If the application would run faster than this rate, the clock will slow down the application.

M_integer - the clock will run as fast as it can, but the rate will be constrained to be an integer multiple or divisor of the rate specified by setFrameRate(). The clock will slow down the application a bit to guarantee this.

M_integer_limited - a combination of M_limited and M_integer; the clock will not run faster than setFrameRate(), and if it runs slower, it will run at a integer divisor of that rate.

M_forced - the clock forces the application to run at the rate specified by setFrameRate(). If the application would run faster than this rate, the clock will slow down the application; if the application would run slower than this rate, the clock slows down time so that the application believes it is running at the given rate.

M_degrade - the clock runs at real time, but the application is slowed down by a set factor of its frame rate, specified by setDegradeFactor().

M_slave - the clock does not advance, but relies on the user to call setFrameTime() and/or setFrameCount() each frame.

setRealTime(time: float)

Resets the clock to the indicated time. This changes only the real time of the clock as reported by getRealTime(), but does not immediately change the time reported by get_frame_time()–that will change after the next call to tick(). Also see reset(), setFrameTime(), and setFrameCount().

syncFrameTime(current_thread: Thread)

Resets the frame time to the current real time. This is similar to tick(), except that it does not advance the frame counter and does not affect dt. This is intended to be used in the middle of a particularly long frame to compensate for the time that has already elapsed.

In non-real-time mode, this function has no effect (because in this mode all frames take the same length of time).

tick(current_thread: Thread)

Instructs the clock that a new frame has just begun. In normal, real-time mode, getFrameTime() will henceforth report the time as of this instant as the current start-of-frame time. In non-real-time mode, getFrameTime() will be incremented by the value of dt.