Class Clock
Paces a render loop the way pygame.time.Clock does. Human-mode rendering calls Tick(double) with
metadata["render_fps"] once per frame, which sleeps just long enough to hold that frame rate, so a
human-mode episode plays at the env's intended speed.
public sealed class Clock
- Inheritance
-
Clock
- Inherited Members
- Extension Methods
Remarks
Time is wall-clock milliseconds since the clock was created (SDL's SDL_GetTicks counts from SDL's
initialization); only differences are observable, and timing takes no part in parity. The arithmetic is pygame's,
including its float32 frame-time computation and whole-millisecond sleeps, so the pacing matches.
Not thread-safe: tick a clock from the thread that renders, or, with TickAsync(double, CancellationToken), from one loop that awaits each tick before the next (its continuation may resume on another thread).
It lives in the Gym assembly, beside the viewers it paces (namespace Gym.Rendering unchanged), so the
HumanRendering wrapper paces its frames with it as the built-in envs do.
Reference: src_c/time.c (pygame-ce 2.5.8).
Constructors
Clock()
Creates a clock whose first Tick(double) measures from now (pygame's Clock() records the current tick).
public Clock()
Methods
GetFps()
The frame rate averaged over the last ten ticks, 0 until ten have run (pygame's Clock.get_fps()).
public float GetFps()
Returns
- float
Frames per second.
Remarks
Reference: src_c/time.c.
GetRawTime()
The milliseconds between the last two ticks, without the pacing sleep (pygame's Clock.get_rawtime()).
public long GetRawTime()
Returns
- long
The time in milliseconds.
Remarks
Reference: src_c/time.c.
GetTime()
The milliseconds between the last two ticks, the pacing sleep included (pygame's Clock.get_time()).
public long GetTime()
Returns
- long
The time in milliseconds.
Remarks
Reference: src_c/time.c.
Tick(double)
Marks a frame; with a positive framerate, first sleeps until 1000 / framerate ms have
passed since the previous tick, so the loop runs no faster than that rate.
public long Tick(double framerate = 0)
Parameters
frameratedoubleThe frame rate to hold, frames per second; 0 (the default) does not sleep.
Returns
- long
The milliseconds since the previous tick, the sleep included.
Remarks
pygame reads the rate as a C float and computes (int)((1.0f / framerate) * 1000.0f), so the frame
time is whole milliseconds (20 ms at 50 fps). A negative or infinite rate gives a delay clamped at zero, as in
pygame, and nothing sleeps; so does NaN, for which pygame's C conversion is undefined.
Reference: src_c/time.c.
TickAsync(double, CancellationToken)
Tick(double) with an awaited wait instead of a blocking sleep (DR-44): the same arithmetic and the same whole-millisecond delay, during which no thread is held, so a game loop on the thread pool paces itself as pygame's clock does.
public ValueTask<long> TickAsync(double framerate = 0, CancellationToken cancellationToken = default)
Parameters
frameratedoubleThe frame rate to hold, frames per second; 0 (the default) does not wait.
cancellationTokenCancellationTokenEnds the wait early; the tick is then not marked.
Returns
Remarks
A wait shorter than the system timer's period may last a whole period (about 15.6 ms on Windows unless the
process raised the timer resolution), where Tick(double)'s sleep has the same limit: hold rates of 60 fps
and below for even pacing. The other way round, a wait between one and two periods may end at the first, so a
tick can return a few milliseconds less than 1000 / framerate (18 ms for a 20 ms frame was measured on
a GitHub Windows runner); Tick(double)'s sleep, and pygame's tick, which sleeps the same way, have
the same limit. One tick at a time: await each before the next, from any thread.
Exceptions
- OperationCanceledException
Thrown (through the task) when
cancellationTokenis canceled during the wait.