Magnum::DebugTools::FrameProfiler class new in 2020.06

#include <Magnum/DebugTools/FrameProfiler.h>

Basic usage

Measurements are performed by calling beginFrame() and endFrame() at designated points in the frame:

void MyApp::drawEvent() {
    _profiler.beginFrame();

    // actual drawing code …

    _profiler.endFrame();

    // possibly other code (such as UI) you don't want to have included in the
    // measurements …

    swapBuffers();
    redraw();
}

In order to have stable profiling results, the application needs to redraw constantly. However for applications that otherwise redraw only on change it might be wasteful — to account for this, it's possible to toggle the profiler operation using enable() / disable() and then redraw() can be called only if isEnabled() returns true.

Data for all measurements is then available through measurementName(), measurementUnits() and measurementMean(). For a convenient overview of all measured values you can call statistics() and feed its output to a UI library or something that can render text. Alternatively, if you don't want to bother with text rendering, call printStatistics() to have the output periodically printed to the console. If an interactive terminal is detected, the output will be colored and refreshing itself in place. Together with the on-demand profiling, it could look like this, refreshing the output every 10 frames:

    _profiler.endFrame();
    _profiler.printStatistics(10);

    swapBuffers();
    if(_profiler.isEnabled()) redraw();
}

And here's a sample output on the terminal — using a fully configured FrameProfilerGL:

Last 50 frames:
  Frame time: 16.65 ms
  CPU duration: 14.72 ms
  GPU duration: 10.89 ms
  Vertex fetch ratio: 0.24
  Primitives clipped: 59.67 %

Setting up measurements

Unless you're using this class through FrameProfilerGL, measurements have to be set up by passing Measurement instances to the setup() function or to the constructor, together with specifying count of frames for the moving average. A CPU duration measurements using the std::chrono APIs over last 50 frames can be done like this:

using std::chrono::high_resolution_clock;

high_resolution_clock::time_point frameBeginTime;
DebugTools::FrameProfiler profiler{{
    DebugTools::FrameProfiler::Measurement{"CPU time",
        DebugTools::FrameProfiler::Units::Nanoseconds,
        [](void* state) {
            *static_cast<high_resolution_clock::time_point*>(state)
                = high_resolution_clock::now();
        },
        [](void* state) {
            return UnsignedLong(
                std::chrono::duration_cast<std::chrono::nanoseconds>(
                    *static_cast<high_resolution_clock::time_point*>(state)
                    - high_resolution_clock::now()).count());
        }, &frameBeginTime}
}, 50};

In the above case, the measurement result is available immediately on frame end. That's not always the case, and for example GPU queries need a few frames delay to avoid stalls from CPU/GPU synchronization. The following snippet sets up sample count measurement with a delay, using three separate GL::SampleQuery instances that are cycled through each frame and retrieved two frames later. The profiler automatically takes care of choosing one of the three instances for each measurement via additional current / previous parameters passed to each callback:

GL::SampleQuery queries[3]{
    GL::SampleQuery{GL::SampleQuery::Target::SamplesPassed},
    GL::SampleQuery{GL::SampleQuery::Target::SamplesPassed},
    GL::SampleQuery{GL::SampleQuery::Target::SamplesPassed}
};
DebugTools::FrameProfiler _profiler{{
    DebugTools::FrameProfiler::Measurement{"Samples",
        DebugTools::FrameProfiler::Units::Count,
        UnsignedInt(Containers::arraySize(queries)),
        [](void* state, UnsignedInt current) {
            static_cast<GL::SampleQuery*>(state)[current].begin();
        },
        [](void* state, UnsignedInt current) {
            static_cast<GL::SampleQuery*>(state)[current].end();
        },
        [](void* state, UnsignedInt previous, UnsignedInt) {
            return static_cast<GL::SampleQuery*>(state)[previous]
                .result<UnsignedLong>();
        }, queries}
}, 50};

Derived classes

class FrameProfilerGL new in 2020.06

OpenGL frame profiler.

Public types

class Measurement

Measurement.

enum class Units: UnsignedByte { Nanoseconds, Bytes, Count, RatioThousandths, PercentageThousandths }

Measurement units.

Constructors, destructors, conversion operators

FrameProfiler() explicit noexcept

Default constructor.

FrameProfiler(Containers::Array<Measurement>&& measurements, UnsignedInt maxFrameCount) explicit noexcept

Constructor.

FrameProfiler(std::initializer_list<Measurement> measurements, UnsignedInt maxFrameCount) explicit

FrameProfiler(const FrameProfiler&) deleted

Copying is not allowed.

FrameProfiler(FrameProfiler&&) noexcept

Move constructor.

Public functions

auto operator=(const FrameProfiler&) -> FrameProfiler& deleted

Copying is not allowed.

auto operator=(FrameProfiler&&) -> FrameProfiler& noexcept

Move assignment.

void setup(Containers::Array<Measurement>&& measurements, UnsignedInt maxFrameCount)

Setup measurements.

void setup(std::initializer_list<Measurement> measurements, UnsignedInt maxFrameCount)

auto isEnabled() const -> bool

Whether the profiling is enabled.

void enable()

Enable the profiler.

void disable()

Disable the profiler.

void beginFrame()

Begin a frame.

void endFrame()

End a frame.

auto maxFrameCount() const -> UnsignedInt

Max count of measured frames.

auto measuredFrameCount() const -> UnsignedInt

Count of measured frames.

auto measurementCount() const -> UnsignedInt

Measurement count.

auto measurementName(UnsignedInt id) const -> Containers::StringView

Measurement name.

auto measurementUnits(UnsignedInt id) const -> Units

Measurement units.

auto measurementDelay(UnsignedInt id) const -> UnsignedInt

Measurement delay.

auto isMeasurementAvailable(UnsignedInt id) const -> bool

Whether given measurement is available.

auto measurementData(UnsignedInt id, UnsignedInt frame) const -> UnsignedLong

Measurement data at given frame.

auto measurementMean(UnsignedInt id) const -> Double

Measurement mean.

auto statistics() const -> Containers::String

Overview of all measurements.

void printStatistics(UnsignedInt frequency) const

Print an overview of all measurements to a console at given rate.

void printStatistics(Debug& out, UnsignedInt frequency) const

Print an overview of all measurements to given output at given rate.

void printStatistics(Debug&& out, UnsignedInt frequency) const

Related

auto operator<<(Debug& debug, FrameProfiler::Units value) -> Debug& new in 2020.06

Debug output operator.

Enum documentation

Function documentation