Skip to main content

FpsMetrics Class

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

Declaration​

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

Public Member Functions Index​

voidaddFrame (const helios::engine::tooling::FrameStats &stats)

Adds a frame's statistics to the metrics history. More...

voidsetHistorySize (size_t size)

Sets the size of the frame history buffer. More...

size_tgetHistorySize () const noexcept

Gets the current history buffer size. More...

floatgetFps () noexcept

Gets the average frames per second. More...

floatgetFrameTimeMs () noexcept

Gets the average frame time in milliseconds. More...

floatgetWorkTimeMs () noexcept

Gets the most recent frame's work time. More...

floatgetIdleTimeMs () noexcept

Gets the most recent frame's idle time. More...

unsigned long longgetFrameCount () const noexcept

Gets the frame count. More...

floatgetFrameTimeSeconds () noexcept

Gets the average frame time in seconds. More...

floatgetWorkTimeSeconds () noexcept

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

floatgetIdleTimeSeconds () 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...

voidreset ()

Clears all collected metrics and resets to initial state. More...

Private Member Functions Index​

voidupdate () 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_thistorySize_ = 60

Size of the history buffer for storing frame statistics. More...

floatavgFps_ = 0.0f

Stores the calculated average frames per second (FPS). More...

floatavgFrameTime_ = 0.0f

Stores the average frame time in milliseconds. More...

floatlastWorkTime_ = 0.0f

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

floatlastWaitTime_ = 0.0f

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

unsigned long longframeCount_ = 0

Tracks the total number of frames processed since initialization. More...

boolneedsUpdate_ = 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:
 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 41 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 182 of file FpsMetrics.ixx.

182 void addFrame(const helios::engine::tooling::FrameStats& stats) {
183 needsUpdate_ = true;
184
185 history_.push_back(stats);
186 if (history_.size() > historySize_) {
187 history_.pop_front();
188 }
189
190 frameCount_++;
191 }

Reference helios::registerComponents.

getFps()​

float helios::engine::tooling::FpsMetrics::getFps ()
 inline 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 229 of file FpsMetrics.ixx.

229 [[nodiscard]] float getFps() noexcept {
230 update();
231 return avgFps_;
232 }

getFrameCount()​

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

Gets the frame count.

Returns

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

Definition at line 275 of file FpsMetrics.ixx.

275 [[nodiscard]] unsigned long long getFrameCount() const noexcept {
276 return frameCount_;
277 }

getFrameTimeMs()​

float helios::engine::tooling::FpsMetrics::getFrameTimeMs ()
 inline 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 241 of file FpsMetrics.ixx.

241 [[nodiscard]] float getFrameTimeMs() noexcept {
242 update();
243 return avgFrameTime_;
244 }

getFrameTimeSeconds()​

float helios::engine::tooling::FpsMetrics::getFrameTimeSeconds ()
 inline 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 287 of file FpsMetrics.ixx.

287 [[nodiscard]] float getFrameTimeSeconds() noexcept {
288 update();
289 return avgFrameTime_ * 0.001f;
290 }

getHistory()​

const std::deque< helios::engine::tooling::FrameStats > & helios::engine::tooling::FpsMetrics::getHistory ()
 inline 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 327 of file FpsMetrics.ixx.

327 [[nodiscard]] const std::deque<helios::engine::tooling::FrameStats>& getHistory() const noexcept {
328 return history_;
329 }

getHistorySize()​

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

Gets the current history buffer size.

Returns

Maximum number of frames kept in history.

Definition at line 217 of file FpsMetrics.ixx.

217 [[nodiscard]] size_t getHistorySize() const noexcept {
218 return historySize_;
219 }

getIdleTimeMs()​

float helios::engine::tooling::FpsMetrics::getIdleTimeMs ()
 inline 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 265 of file FpsMetrics.ixx.

265 [[nodiscard]] float getIdleTimeMs() noexcept {
266 update();
267 return lastWaitTime_;
268 }

getIdleTimeSeconds()​

float helios::engine::tooling::FpsMetrics::getIdleTimeSeconds ()
 inline 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 313 of file FpsMetrics.ixx.

313 [[nodiscard]] float getIdleTimeSeconds() noexcept {
314 update();
315 return lastWaitTime_ * 0.001f;
316 }

getWorkTimeMs()​

float helios::engine::tooling::FpsMetrics::getWorkTimeMs ()
 inline 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 253 of file FpsMetrics.ixx.

253 [[nodiscard]] float getWorkTimeMs() noexcept {
254 update();
255 return lastWorkTime_;
256 }

getWorkTimeSeconds()​

float helios::engine::tooling::FpsMetrics::getWorkTimeSeconds ()
 inline 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 300 of file FpsMetrics.ixx.

300 [[nodiscard]] float getWorkTimeSeconds() noexcept {
301 update();
302 return lastWorkTime_ * 0.001f;
303 }

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 338 of file FpsMetrics.ixx.

338 void reset() {
339 history_.clear();
340 avgFps_ = 0.0f;
341 avgFrameTime_ = 0.0f;
342 lastWorkTime_ = 0.0f;
343 lastWaitTime_ = 0.0f;
344 frameCount_ = 0;
345 needsUpdate_ = false;
346 }

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 204 of file FpsMetrics.ixx.

204 void setHistorySize(size_t size) {
205 historySize_ = size;
206 while (history_.size() > historySize_) {
207 history_.pop_front();
208 }
209 needsUpdate_ = true;
210 }

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 139 of file FpsMetrics.ixx.

139 void update() noexcept {
140 if (!needsUpdate_ || history_.empty()) {
141 return;
142 }
143
144 const auto& stats = history_.back();
145
146 lastWorkTime_ = stats.workTime * 1000.0f;
147 lastWaitTime_ = stats.waitTime * 1000.0f;
148
149 float sumMs = 0.0f;
150 for (const auto& s : history_) {
151 sumMs += s.totalFrameTime * 1000.0f;
152 }
153
154 avgFrameTime_ = sumMs / static_cast<float>(history_.size());
155 avgFps_ = (avgFrameTime_ > 0.0001f) ? (1000.0f / avgFrameTime_) : 0.0f;
156
157 needsUpdate_ = false;
158 }

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 76 of file FpsMetrics.ixx.

76 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 86 of file FpsMetrics.ixx.

86 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 115 of file FpsMetrics.ixx.

115 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 53 of file FpsMetrics.ixx.

53 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 66 of file FpsMetrics.ixx.

66 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 106 of file FpsMetrics.ixx.

106 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 96 of file FpsMetrics.ixx.

96 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 124 of file FpsMetrics.ixx.

124 bool needsUpdate_ = true;

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

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.