Table of Contents

Class Clock

Namespace
Gym.Rendering
Assembly
Gym.dll

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

framerate double

The 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

framerate double

The frame rate to hold, frames per second; 0 (the default) does not wait.

cancellationToken CancellationToken

Ends the wait early; the tick is then not marked.

Returns

ValueTask<long>

A task of the milliseconds since the previous tick, the wait included.

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 cancellationToken is canceled during the wait.