FramePacer Class

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

Declaration

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

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

helios::engine::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:

 auto stopwatch = std::make_unique<helios::engine::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 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 91 of file FramePacer.ixx.

91 void beginFrame() {

92 stopwatch_.start();

93 }

Reference helios::engine::util::time::Stopwatch::start.

getTargetFps()

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

inline 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 80 of file FramePacer.ixx.

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

81 return targetFps_;

82 }

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 65 of file FramePacer.ixx.

65 void setTargetFps(float fps) {

66 targetFps_ = fps;

67 }

Reference helios::registerComponents.

sync()

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

inline

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.

Definition at line 111 of file FramePacer.ixx.

111 [[nodiscard]] FrameStats sync() {

112 float workTime = stopwatch_.elapsedSeconds();

113

114 float waitTime = 0.0f;

115 float totalTime = workTime;

116

117 if (targetFps_ > 0.0f) {

118 float targetTime = 1.0f / targetFps_;

119 if (targetTime > workTime) {

120 auto requestedWaitTime = targetTime - workTime;

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

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

123 totalTime = stopwatch_.elapsedSeconds();

124 waitTime = totalTime - workTime;

125 }

126 }

127

128 return FrameStats{ totalTime, workTime, waitTime };

129 }

References helios::engine::util::time::Stopwatch::elapsedSeconds and helios::registerComponents.

Private Member Attributes

stopwatch_

helios::engine::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 helios::engine::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.9.8.