FramePacer Class

Controls and maintains a target frame rate through precise timing and pacing. More...

Declaration

class helios::engine::tooling::FramePacer { ... }

Public Constructors Index

	FramePacer (std::unique_ptr< helios::util::time::Stopwatch > stopwatch)
	Constructs a FramePacer with the given stopwatch. More...

Public Member Functions Index

void	setTargetFps (float fps)
	Sets the desired target frame rate. More...
float	getTargetFps () const noexcept
	Retrieves the current target frame rate. More...
void	beginFrame ()
	Marks the beginning of a new frame. More...
FrameStats	sync ()
	Synchronizes frame timing and returns frame statistics. More...

Private Member Attributes Index

std::unique_ptr< helios::util::time::Stopwatch >	stopwatch_
	The stopwatch used for high-resolution time measurement. More...
float	targetFps_ = 0.0f
	The target frame rate in Frames Per Second (FPS). More...

Description

Controls and maintains a target frame rate through precise timing and pacing.

The FramePacer class utilizes a `Stopwatch` to measure frame execution time and introduces necessary sleep delays to maintain a consistent target frame rate. It returns detailed timing statistics via the `FrameStats` structure upon synchronization.

The pacing mechanism helps in achieving smoother frame delivery by minimizing jitter, although strict adherence depends on the OS scheduler's precision.

info

If `targetFps` is set to 0.0f, no frame pacing is performed, and frames run as fast as the hardware and OS allow (unlocked framerate).

Usage Example:

```cpp auto stopwatch = std::make_unique<helios::util::time::Stopwatch>(); FramePacer pacer(std::move(stopwatch)); pacer.setTargetFps(60.0f);

while (running) { pacer.beginFrame(); // ... game logic and rendering ... FrameStats stats = pacer.sync(); } ```

Definition at line 46 of file FramePacer.ixx.

Public Constructors

FramePacer()

helios::engine::tooling::FramePacer::FramePacer (std::unique_ptr< helios::util::time::Stopwatch > stopwatch)

inline explicit

Constructs a FramePacer with the given stopwatch.

Initializes a new FramePacer instance in unlimited FPS mode (targetFps = 0.0f).

Parameters

stopwatch

Unique pointer to a valid `Stopwatch` instance. Ownership is transferred to the FramePacer.

Definition at line 66 of file FramePacer.ixx.

66 explicit FramePacer(std::unique_ptr<helios::util::time::Stopwatch> stopwatch) :

67 stopwatch_(std::move(stopwatch)) {

68 assert(stopwatch_ && "FramePacer requires a valid Stopwatch (non-null)");

69 }

Public Member Functions

beginFrame()

void helios::engine::tooling::FramePacer::beginFrame ()

inline

Marks the beginning of a new frame.

Starts the internal stopwatch to begin measuring the frame's work time. This method must be called at the very beginning of each frame cycle, before any game logic, physics, or rendering operations.

Definition at line 103 of file FramePacer.ixx.

103 void beginFrame() {

104 stopwatch_->start();

105 }

getTargetFps()

float helios::engine::tooling::FramePacer::getTargetFps ()

inline nodiscard noexcept

Retrieves the current target frame rate.

Returns the frame rate target that has been set for pacing, expressed in Frames Per Second (FPS). If the target frame rate is set to 0.0f, frame pacing is disabled, and the frame rate is unlocked.

Returns

The target frame rate in FPS.

info

A return value of 0.0f indicates that the frame pacing mechanism is not active.

Definition at line 92 of file FramePacer.ixx.

92 [[nodiscard]] float getTargetFps() const noexcept {

93 return targetFps_;

94 }

setTargetFps()

void helios::engine::tooling::FramePacer::setTargetFps (float fps)

inline

Sets the desired target frame rate.

Parameters

fps	The target frame rate in Frames Per Second (FPS). Set to 0.0f to disable pacing (unlocked framerate).

Definition at line 77 of file FramePacer.ixx.

77 void setTargetFps(float fps) {

78 targetFps_ = fps;

79 }

sync()

FrameStats helios::engine::tooling::FramePacer::sync ()

inline nodiscard

Synchronizes frame timing and returns frame statistics.

Measures the elapsed work time since `beginFrame()`. If a target FPS is set and the work time is less than the target frame duration, this method sleeps the current thread to meet the target timing.

Returns

A `FrameStats` structure containing the total frame time (including wait), the actual work time (CPU processing), and the wait time (idle).

info

If `targetFps` is 0.0f or the frame took longer than the target duration, no sleeping occurs, and `waitTime` in the returned stats will be 0.0f.

Todo

Implement hybrid spinning for the last millisecond of the wait time to improve timing precision and mitigate OS scheduler wake-up latency.

Definition at line 123 of file FramePacer.ixx.

123 [[nodiscard]] FrameStats sync() {

124 float workTime = stopwatch_->elapsedSeconds();

125

126 float waitTime = 0.0f;

127 float totalTime = workTime;

128

129 if (targetFps_ > 0.0f) {

130 float targetTime = 1.0f / targetFps_;

131 if (targetTime > workTime) {

132 auto requestedWaitTime = targetTime - workTime;

133 auto sleepDuration = std::chrono::duration<float>(requestedWaitTime);

134 std::this_thread::sleep_for(sleepDuration);

135 totalTime = stopwatch_->elapsedSeconds();

136 waitTime = totalTime - workTime;

137 }

138 }

139

140 return FrameStats{ totalTime, workTime, waitTime };

141 }

Private Member Attributes

stopwatch_

std::unique_ptr<helios::util::time::Stopwatch> helios::engine::tooling::FramePacer::stopwatch_

The stopwatch used for high-resolution time measurement.

Definition at line 50 of file FramePacer.ixx.

50 std::unique_ptr<helios::util::time::Stopwatch> stopwatch_;

targetFps_

float helios::engine::tooling::FramePacer::targetFps_ = 0.0f

The target frame rate in Frames Per Second (FPS).

Definition at line 55 of file FramePacer.ixx.

55 float targetFps_ = 0.0f;

---

The documentation for this class was generated from the following file:

• FramePacer.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.