FpsMetrics Class

Aggregates and analyzes frame timing data over a rolling window. More...

Declaration

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

Public Member Functions Index

void	addFrame (const helios::engine::tooling::FrameStats &stats)
	Adds a frame's statistics to the metrics history. More...
void	setHistorySize (size_t size)
	Sets the size of the frame history buffer. More...
size_t	getHistorySize () const noexcept
	Gets the current history buffer size. More...
float	getFps () noexcept
	Gets the average frames per second. More...
float	getFrameTimeMs () noexcept
	Gets the average frame time in milliseconds. More...
float	getWorkTimeMs () noexcept
	Gets the most recent frame's work time. More...
float	getIdleTimeMs () noexcept
	Gets the most recent frame's idle time. More...
unsigned long long	getFrameCount () const noexcept
	Gets the frame count. More...
float	getFrameTimeSeconds () noexcept
	Gets the average frame time in seconds. More...
float	getWorkTimeSeconds () noexcept
	Gets the most recent frame's work time in seconds. More...
float	getIdleTimeSeconds () noexcept
	Gets the most recent frame's idle time in seconds. More...
const std::deque< helios::engine::tooling::FrameStats > &	getHistory () const noexcept
	Gets the complete frame history. More...
void	reset ()
	Clears all collected metrics and resets to initial state. More...

Private Member Functions Index

void	update () noexcept
	Recomputes cached metrics if needed. More...

Private Member Attributes Index

std::deque< helios::engine::tooling::FrameStats >	history_
	Stores a rolling history of frame statistics. More...
size_t	historySize_ = 60
	Size of the history buffer for storing frame statistics. More...
float	avgFps_ = 0.0f
	Stores the calculated average frames per second (FPS). More...
float	avgFrameTime_ = 0.0f
	Stores the average frame time in milliseconds. More...
float	lastWorkTime_ = 0.0f
	Tracks the most recent frame's work time in milliseconds. More...
float	lastWaitTime_ = 0.0f
	Tracks the idle time in milliseconds for the most recent frame. More...
unsigned long long	frameCount_ = 0
	Tracks the total number of frames processed since initialization. More...
bool	needsUpdate_ = true
	Indicates whether cached metrics need to be recomputed. More...

Description

Aggregates and analyzes frame timing data over a rolling window.

FpsMetrics collects FrameStats data from multiple frames and calculates average FPS and frame times. It maintains a configurable history buffer for smoothing out momentary fluctuations in frame rate.

This class is particularly useful for debugging, profiling, and displaying performance metrics in development tools or debug overlays.

Usage Example:

```cpp helios::engine::tooling::FpsMetrics metrics; metrics.setHistorySize(120);

// In game loop: helios::engine::tooling::FrameStats stats = framePacer.sync(); metrics.addFrame(stats);

float fps = metrics.getFps(); float avgFrameTime = metrics.getFrameTimeMs(); ```

Definition at line 40 of file FpsMetrics.ixx.

Public Member Functions

addFrame()

void helios::engine::tooling::FpsMetrics::addFrame (const helios::engine::tooling::FrameStats & stats)

inline

Adds a frame's statistics to the metrics history.

Processes the provided FrameStats, updates the rolling history, and marks cached values as dirty so they will be recomputed on the next query. Old frames are automatically removed when the history buffer exceeds the configured size. Additionally, the `frameCount_` member is increased by one for each call.

Parameters

stats

Frame statistics to add to the history.

info

When used together with FramePacer, a typical usage pattern is:

 helios::engine::tooling::FrameStats stats = framePacer.sync();

 metrics.addFrame(stats);

This should usually be called once per frame at the end of the frame loop, after timing information for the current frame has been measured.

Definition at line 181 of file FpsMetrics.ixx.

181 void addFrame(const helios::engine::tooling::FrameStats& stats) {

182 needsUpdate_ = true;

183

184 history_.push_back(stats);

185 if (history_.size() > historySize_) {

186 history_.pop_front();

187 }

188

189 frameCount_++;

190 }

getFps()

float helios::engine::tooling::FpsMetrics::getFps ()

inline nodiscard noexcept

Gets the average frames per second.

Triggers a lazy recomputation of the underlying metrics if new frames have been added since the last query.

Returns

Average FPS calculated over the frames stored in the history buffer.

Definition at line 228 of file FpsMetrics.ixx.

228 [[nodiscard]] float getFps() noexcept {

229 update();

230 return avgFps_;

231 }

getFrameCount()

unsigned long long helios::engine::tooling::FpsMetrics::getFrameCount ()

inline nodiscard noexcept

Gets the frame count.

Returns

The total number of frames that have been added via `addFrame()`.

Definition at line 274 of file FpsMetrics.ixx.

274 [[nodiscard]] unsigned long long getFrameCount() const noexcept {

275 return frameCount_;

276 }

getFrameTimeMs()

float helios::engine::tooling::FpsMetrics::getFrameTimeMs ()

inline nodiscard noexcept

Gets the average frame time in milliseconds.

Triggers a lazy recomputation of the underlying metrics if needed.

Returns

Average total frame time (work + wait) in milliseconds.

Definition at line 240 of file FpsMetrics.ixx.

240 [[nodiscard]] float getFrameTimeMs() noexcept {

241 update();

242 return avgFrameTime_;

243 }

getFrameTimeSeconds()

float helios::engine::tooling::FpsMetrics::getFrameTimeSeconds ()

inline nodiscard noexcept

Gets the average frame time in seconds.

Convenience wrapper returning the same value as `getFrameTimeMs()` converted from milliseconds to seconds.

Returns

Average total frame time (work + wait) in seconds.

Definition at line 286 of file FpsMetrics.ixx.

286 [[nodiscard]] float getFrameTimeSeconds() noexcept {

287 update();

288 return avgFrameTime_ * 0.001f;

289 }

getHistory()

const std::deque< helios::engine::tooling::FrameStats > & helios::engine::tooling::FpsMetrics::getHistory ()

inline nodiscard noexcept

Gets the complete frame history.

Returns

Const reference to the deque containing the full frame statistics history.

info

Useful for rendering frame time graphs or diagnostic views in debug overlays.

Definition at line 326 of file FpsMetrics.ixx.

326 [[nodiscard]] const std::deque<helios::engine::tooling::FrameStats>& getHistory() const noexcept {

327 return history_;

328 }

getHistorySize()

size_t helios::engine::tooling::FpsMetrics::getHistorySize ()

inline nodiscard noexcept

Gets the current history buffer size.

Returns

Maximum number of frames kept in history.

Definition at line 216 of file FpsMetrics.ixx.

216 [[nodiscard]] size_t getHistorySize() const noexcept {

217 return historySize_;

218 }

getIdleTimeMs()

float helios::engine::tooling::FpsMetrics::getIdleTimeMs ()

inline nodiscard noexcept

Gets the most recent frame's idle time.

Triggers a lazy recomputation if required.

Returns

Wait/idle time of the last processed frame in milliseconds.

Definition at line 264 of file FpsMetrics.ixx.

264 [[nodiscard]] float getIdleTimeMs() noexcept {

265 update();

266 return lastWaitTime_;

267 }

getIdleTimeSeconds()

float helios::engine::tooling::FpsMetrics::getIdleTimeSeconds ()

inline nodiscard noexcept

Gets the most recent frame's idle time in seconds.

Convenience wrapper returning the same value as `getIdleTimeMs()` converted from milliseconds to seconds.

Returns

Wait/idle time of the last processed frame in seconds.

Definition at line 312 of file FpsMetrics.ixx.

312 [[nodiscard]] float getIdleTimeSeconds() noexcept {

313 update();

314 return lastWaitTime_ * 0.001f;

315 }

getWorkTimeMs()

float helios::engine::tooling::FpsMetrics::getWorkTimeMs ()

inline nodiscard noexcept

Gets the most recent frame's work time.

Triggers a lazy recomputation if required.

Returns

Work time of the last processed frame in milliseconds.

Definition at line 252 of file FpsMetrics.ixx.

252 [[nodiscard]] float getWorkTimeMs() noexcept {

253 update();

254 return lastWorkTime_;

255 }

getWorkTimeSeconds()

float helios::engine::tooling::FpsMetrics::getWorkTimeSeconds ()

inline nodiscard noexcept

Gets the most recent frame's work time in seconds.

Convenience wrapper returning the same value as `getWorkTimeMs()` converted from milliseconds to seconds.

Returns

Work time of the last processed frame in seconds.

Definition at line 299 of file FpsMetrics.ixx.

299 [[nodiscard]] float getWorkTimeSeconds() noexcept {

300 update();

301 return lastWorkTime_ * 0.001f;

302 }

reset()

void helios::engine::tooling::FpsMetrics::reset ()

inline

Clears all collected metrics and resets to initial state.

Removes all stored frame statistics and resets cached metrics and counters to their default values. After calling this function, all query functions will report zeros until new frames are added.

Definition at line 337 of file FpsMetrics.ixx.

337 void reset() {

338 history_.clear();

339 avgFps_ = 0.0f;

340 avgFrameTime_ = 0.0f;

341 lastWorkTime_ = 0.0f;

342 lastWaitTime_ = 0.0f;

343 frameCount_ = 0;

344 needsUpdate_ = false;

345 }

setHistorySize()

void helios::engine::tooling::FpsMetrics::setHistorySize (size_t size)

inline

Sets the size of the frame history buffer.

Determines how many frames are used for calculating averages. Larger values produce smoother metrics but respond slower to changes.

Parameters

size	Number of frames to keep in history (default: 60).

info

Common values: 30 for roughly half-second average at 60 FPS, 60 for roughly one-second average at 60 FPS.

Definition at line 203 of file FpsMetrics.ixx.

203 void setHistorySize(size_t size) {

204 historySize_ = size;

205 while (history_.size() > historySize_) {

206 history_.pop_front();

207 }

208 needsUpdate_ = true;

209 }

Private Member Functions

update()

void helios::engine::tooling::FpsMetrics::update ()

inline noexcept

Recomputes cached metrics if needed.

If `needsUpdate_` is true and the history is non-empty, this function updates `lastWorkTime_`, `lastWaitTime_`, `avgFrameTime_` and `avgFps_` based on the current contents of `history_` and then clears the flag.

If the history is empty or the cache is already up to date, this function returns immediately without modifying any values.

info

This function is safe to call in hot paths and does not throw under normal conditions; it is therefore marked `noexcept`.

Definition at line 138 of file FpsMetrics.ixx.

138 void update() noexcept {

139 if (!needsUpdate_ || history_.empty()) {

140 return;

141 }

142

143 const auto& stats = history_.back();

144

145 lastWorkTime_ = stats.workTime * 1000.0f;

146 lastWaitTime_ = stats.waitTime * 1000.0f;

147

148 float sumMs = 0.0f;

149 for (const auto& s : history_) {

150 sumMs += s.totalFrameTime * 1000.0f;

151 }

152

153 avgFrameTime_ = sumMs / static_cast<float>(history_.size());

154 avgFps_ = (avgFrameTime_ > 0.0001f) ? (1000.0f / avgFrameTime_) : 0.0f;

155

156 needsUpdate_ = false;

157 }

Private Member Attributes

avgFps_

float helios::engine::tooling::FpsMetrics::avgFps_ = 0.0f

Stores the calculated average frames per second (FPS).

The `avgFps_` variable holds the computed average FPS value based on the accumulated frame timing data in `history_`. It is recomputed lazily when one of the query functions (e.g. `getFps()`) is called after new frames have been added.

Definition at line 75 of file FpsMetrics.ixx.

75 float avgFps_ = 0.0f;

avgFrameTime_

float helios::engine::tooling::FpsMetrics::avgFrameTime_ = 0.0f

Stores the average frame time in milliseconds.

Represents the total frame time (including work and wait) averaged over the frames currently stored in the history buffer. The value is stored in milliseconds and recomputed lazily when queried via the public getters after new frames have been added.

Definition at line 85 of file FpsMetrics.ixx.

85 float avgFrameTime_ = 0.0f;

frameCount_

unsigned long long helios::engine::tooling::FpsMetrics::frameCount_ = 0

Tracks the total number of frames processed since initialization.

The frameCount_ variable accumulates the count of frames that have been added via `addFrame()`. It starts at 0 and increments with each call, serving as a global counter independent of the current history size.

Definition at line 114 of file FpsMetrics.ixx.

114 unsigned long long frameCount_ = 0;

history_

std::deque<helios::engine::tooling::FrameStats> helios::engine::tooling::FpsMetrics::history_

Stores a rolling history of frame statistics.

`history_` holds the full timing data (work time, wait time, total frame time) for a specified number of recent frames. This buffer is used to compute average frame rate and frame time metrics over a configurable window.

The use of a `std::deque` allows efficient addition and removal of frame timing records while maintaining the order of events.

Definition at line 52 of file FpsMetrics.ixx.

52 std::deque<helios::engine::tooling::FrameStats> history_;

historySize_

size_t helios::engine::tooling::FpsMetrics::historySize_ = 60

Size of the history buffer for storing frame statistics.

Determines the maximum number of frames for which the frame timing data is retained to calculate performance metrics such as average FPS and frame times. A larger history size smooths out short-term variations but may reduce responsiveness to sudden changes in performance.

This variable is initialized to a default value of 60 but can be adjusted based on the application's requirements for performance analysis.

Definition at line 65 of file FpsMetrics.ixx.

65 size_t historySize_ = 60;

lastWaitTime_

float helios::engine::tooling::FpsMetrics::lastWaitTime_ = 0.0f

Tracks the idle time in milliseconds for the most recent frame.

Represents the duration the system waited (idle time) during the last processed frame. This value is derived from the most recent `FrameStats` in the history and expressed in milliseconds. It is updated when the metrics are recomputed (lazy evaluation triggered by the getters).

Definition at line 105 of file FpsMetrics.ixx.

105 float lastWaitTime_ = 0.0f;

lastWorkTime_

float helios::engine::tooling::FpsMetrics::lastWorkTime_ = 0.0f

Tracks the most recent frame's work time in milliseconds.

Represents the duration of work performed during the last processed frame. This value is derived from the most recent `FrameStats` in the history and expressed in milliseconds. It is updated when the metrics are recomputed (lazy evaluation triggered by the getters).

Definition at line 95 of file FpsMetrics.ixx.

95 float lastWorkTime_ = 0.0f;

needsUpdate_

bool helios::engine::tooling::FpsMetrics::needsUpdate_ = true

Indicates whether cached metrics need to be recomputed.

Set to true whenever new frame data is added or the history changes in a way that invalidates the cached values. The next call to one of the public query functions will trigger a recomputation in `update()`.

Definition at line 123 of file FpsMetrics.ixx.

123 bool needsUpdate_ = true;

---

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

• FpsMetrics.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.