Module frame_cap 

The frame cap: the most frames a second the platform shows (FrameCap), 60 unless the game or the player says otherwise, so a simple game doesn’t run as fast as it can and keep a CPU core busy (fans, heat, the battery).

The cap is the player’s setting (Settings::frame_cap), whose default and choices are the game’s (GameSettings::DEFAULT_FRAME_CAP, FRAME_CAP_CHOICES). Only the platform can apply it, so a change is a request it confirms: every change of the cap takes the next serial number, the platform is handed the cap with its serial each frame, and before each frame it reports what it applied (Pacing, through Game::set_pacing). A game that asks for a cap (Ctx::request_frame_cap) gets a CapRequest and checks it like a promise (Ctx::frame_cap_status): pending until the platform reports that serial, then applied, with the report.

With vsync and variable refresh (VRR). The platform never waits twice: when vsync, the display or a slow machine already keeps the frames as far apart as the cap asks, it doesn’t wait at all, so a cap of 60 on a 60 Hz display with vsync on never misses a vblank. On a VRR display (G-Sync, FreeSync, adaptive sync), a cap a few frames under the display’s refresh (141 on a 144 Hz display) keeps it in its variable range, so the display follows the frames.

With fixed steps. A tick stage steps 60 times a second. At a cap above 60 each step shows for whole frames: evenly at 120 and 240, but 2 and 3 frames in turn at 144 and 165, which moves unevenly. A cap that is a multiple of 60 avoids it.

Structs

CapRequest

A request for a frame cap (Ctx::request_frame_cap): a handle to check it with (Ctx::frame_cap_status), as a promise is, without waiting on it.

Pacing

What the platform reports of its pacing, before each frame (Game::set_pacing): the cap it applied and its serial, whether it asked for vsync, and the frames a second it measured. Built with Pacing::new; the rest is assigned.

Enums

CapError

Why FrameCap::fps refused a cap.

CapStatus

Where a CapRequest is.

FrameCap

The most frames a second the platform shows.

Constants

CHOICES

The choices an options screen offers when the game doesn’t give its own (GameSettings::FRAME_CAP_CHOICES): the common refresh rates, then no cap.

FPS_KEY

Text key (Ctx::text) of a cap’s name, with the number of frames a second as {n} ("{n} FPS").

MAX_FPS

The highest cap FrameCap::fps takes, in frames a second. Tunable.

MIN_FPS

The lowest cap FrameCap::fps takes, in frames a second. Tunable.

UNLIMITED_KEY

Text key of no cap’s name ("Unlimited").