nCine::FrameStatistics class
#include <nCine/Base/FrameStatistics.h>

Frame timing and backend counters, averaged for an on-screen overlay.

Collects nothing until SetEnabled() switches it on, so a build that never displays the numbers pays a branch per phase of the frame and nothing else. While it is on, Application::Step() times every phase of the frame, RenderQueue counts the draw calls, and the graphics backend adds what only it can know through AddCounter() - the GPU time, how long it blocked on the GPU or the display, hardware counters. Every AveragingInterval the accumulated values are averaged into the snapshot GetSnapshot() returns, so the numbers change a few times a second instead of flickering every frame, while a single long frame still shows in Snapshot::MaxFrameTime.

Public types

struct Counter: Counter reported by a backend, averaged over an interval.
struct Snapshot: Values averaged over the last complete interval.
enum class Phase : std::uint8_t { BeginFrame, Update, PostUpdate, Visit, Draw, Audio, EndFrame, Present, Wait, Count }: Phase of a frame, in the order Application::Step() runs them.
enum class Unit : std::uint8_t { Milliseconds, Percent, Bytes, Number }: Unit of a counter value.

Public static functions

static auto IsEnabled() -> bool: Returns true while the statistics are being collected.
static void SetEnabled(bool enabled): Starts or stops collecting the statistics.
static void AddDrawCalls(std::uint32_t drawCalls, std::uint32_t renderCommands): Adds the draw calls of one render queue to the current frame.
static void AddCounter(const char* name, float value, Unit unit, float limit = 0.0f): Adds a value of a counter to the current frame.
static void EndFrame(const float* phaseTimes, float frameTime): Closes the current frame.
static auto GetSnapshot() -> const Snapshot&: Returns the values averaged over the last complete interval.

Constructors, destructors, conversion operators

FrameStatistics() deleted
~FrameStatistics() deleted

Constants

static std::uint32_t MaxCounters constexpr: Maximum number of distinct counters, further ones are dropped.
static float AveragingInterval constexpr: Interval in seconds the values are averaged over.

Enum documentation

enum class nCine::FrameStatistics::Phase : std::uint8_t

Phase of a frame, in the order Application::Step() runs them.

Enumerators
BeginFrame	IAppEventHandler::OnBeginFrame()
Update	Scene graph update
PostUpdate	IAppEventHandler::OnPostUpdate()
Visit	Scene graph visit, which culls the nodes and collects their render commands
Draw	Sorting, batching and submitting the render commands
Audio	Updating the audio players, which is also where the streams are decoded
EndFrame	IAppEventHandler::OnEndFrame()
Present	Presenting the frame, including any wait for the GPU or the vertical blank
Wait	Frame rate limiter
Count	Count of phases

enum class nCine::FrameStatistics::Unit : std::uint8_t

Unit of a counter value.

Enumerators
Milliseconds	Time in milliseconds
Percent	Percentage
Bytes	Size in bytes
Number	Plain number

Function documentation

static void nCine::FrameStatistics::SetEnabled(bool enabled)

Starts or stops collecting the statistics.

Starting throws away whatever was collected before, so the first snapshot after it describes only frames that were measured whole.

static void nCine::FrameStatistics::AddCounter(const char* name, float value, Unit unit, float limit = 0.0f)

Adds a value of a counter to the current frame.

Values reported under the same name within one frame add up, and the snapshot averages them over the frames that reported the counter at all - a GPU timer whose result arrives only every other frame is not halved by the frames in between. Does nothing while the statistics are not being collected, but a caller whose value is expensive to obtain should check IsEnabled() before it gets it.

static void nCine::FrameStatistics::EndFrame(const float* phaseTimes, float frameTime)

Closes the current frame.

Parameters
phaseTimes	Duration of each Phase in seconds
frameTime	Duration of the whole frame in seconds, measured from its start to the start of the next one

nCine::FrameStatistics class #include <nCine/Base/FrameStatistics.h>