Module amethyst_core::frame_limiter

Frame rate limiting.

An amethyst Application runs in a loop, executing game update logic each frame. In order to reduce CPU usage and keep frame timing predictable, amethyst uses a configurable frame limiting strategy to introduce a delay before starting each frame if the previous frame completed sufficiently quickly.

The frame rate limiting strategy has two parts: A maximum frame rate, given as a number of frames per second, and a strategy for returning any remaining time in the frame to the operating system. Based on the specified maximum frame rate, each frame has a budget for how long it can take. For example, at 60 fps each frame has 16.6 milliseconds to perform any work it needs to. If a frame takes less time than is budgeted, amethyst will attempt to yield the remaining time back to the operating system, using the chosen strategy.

By default, amethyst will set the maximum frame rate to 144 fps, and will use a yield-only limiting strategy.

Examples

use std::time::Duration;

use amethyst::prelude::*;
use amethyst::core::frame_limiter::FrameRateLimitStrategy;

let assets_dir = "./";
let mut game = Application::build(assets_dir, GameState)?
    .with_frame_limit(
        FrameRateLimitStrategy::SleepAndYield(Duration::from_millis(2)),
        144,
    )
    .build(GameDataBuilder::new())?;

Frame Rate Limiting Strategies

The four possible strategies described by FrameRateLimitStrategy are as follows:

• Unlimited will not try to limit the frame rate to the specified maximum. Amethyst will call thread::yield_now once and then continue to the next frame.
• Yield will call thread::yield_now repeatedly until the frame duration has passed. This will result in the most accurate frame timings, but effectively guarantees that one CPU core will be fully utilized during the frame's idle time.
• Sleep will call thread::sleep with a duration of 0 milliseconds until the frame duration has passed. This will result in lower CPU usage while the game is idle, but risks fluctuations in frame timing if the operating system doesn't wake the game until after the frame should have started.
• SleepAndYield will sleep until there's only a small amount of time left in the frame, and then will yield until the next frame starts. This approach attempts to get the consistent frame timings of yielding, while reducing CPU usage compared to the yield-only approach.

By default amethyst will use the Yield strategy, which is fine for desktop and console games that aren't as affected by extra CPU usage. For mobile devices, the Sleep strategy will help conserve battery life.

SleepAndYield can potentially be as accurate as Yield while using less CPU time, but you will have to test different grace period timings to determine how much time needs to be left to ensure that the main thread doesn't sleep too long and miss the start of the next frame.

Structs

FrameLimiter	Frame limiter resource.
FrameRateLimitConfig	Frame limiting configuration loaded from a configuration file.

Enums

FrameRateLimitStrategy

Frame rate limiting strategy.