Magnum::GL::OpenGLTester class
#include <Magnum/GL/OpenGLTester.h>

Base class for OpenGL tests and benchmarks.

Extends Corrade::TestSuite::Tester with features for OpenGL testing and benchmarking. Be sure to read its documentation first to have an overview of the base features.

This class is available on platforms with corresponding Platform::Windowless*Application implementation, which currently means all platforms. It is built into a separate static library and only if MAGNUM_WITH_OPENGLTESTER is enabled when building Magnum. To use it with CMake, request the OpenGLTester component of the Magnum package. Derive your test class from this class instead of Corrade::TestSuite::Tester and either link to Magnum::OpenGLTester target or add it to the LIBRARIES section of the corrade_add_test() macro:

find_package(Magnum REQUIRED OpenGLTester)

# ...
corrade_add_test(YourTest YourTest.cpp LIBRARIES Magnum::OpenGLTester)

Additionally, if you're using Magnum as a CMake subproject, ensure it's enabled as it's not built by default:

set(MAGNUM_WITH_OPENGLTESTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

See Downloading and building, Usage with CMake and Testing and benchmarking for more information.

Running the test executables

Implicitly, running the test executables requires presence of a GPU with OpenGL drivers. In addition, on desktop, unless Magnum is built with MAGNUM_TARGET_EGL, OpenGL context creation requires a graphical desktop to be running. On embedded systems (and iOS, Android in particular) running the tests has no special requirements. On Emscripten the tests have to be running in a browser, as Node.js environment doesn't provide a WebGL context.

On virtualized systems and systems without a GPU (e.g. CI servers) it's possible to link against e.g. Mesa softpipe or SwiftShader, but be prepared to expect reduced performance, reduced feature set and possible non-comformant behavior on such drivers.

See Compiling and running tests for more information about running the tests on particular platforms.

OpenGL context creation

Upon construction the class creates an OpenGL context, meaning you don't have to worry about OpenGL context being available during the tests. If the context creation fails, the test executable exits with non-zero return code. The tester uses a single OpenGL context for all test cases, meaning you can share precalculated state among test cases, but on the other hand potential OpenGL misuses will propagate to following test cases. See command-line option overview for a way to run single isolated test cases.

Debug context and error checking

Because DebugOutput can be quite spammy in some cases, especially when compiling more complex shaders or doing benchmarks, it's not implicitly enabled by default to make the test output more readable. Instead of relying on debug output to report errors, the MAGNUM_VERIFY_NO_GL_ERROR() macro should be used to reliably check for errors regardless of platform support. For easier debugging of OpenGL errors users are encuraged to use the --magnum-gpu-validation command line option, which is supported here as well as in all other application implementations.

GPU time benchmarks

This class adds BenchmarkType::GpuTime to the benchmark type enum, allowing you to measure time spent on GPU as opposed to CPU or wall clock time. If ARB_timer_query desktop extension (part of OpenGL 3.3), EXT_disjoint_timer_query OpenGL ES extension, EXT_disjoint_timer_query WebGL 1 extension or EXT_disjoint_timer_query_webgl2 WebGL 2 extension is not available, GPU time benchmarks will get automatically skipped, producing a SKIP message on the output.

Note that GPUs are subject to the same frequency scaling as CPUs, and depending on the vendor and driver the variance may be so high that the measurements are useless. This is particlarly the case with Intel integrated GPUs, which heavily downclock for power saving, and do so independently on the CPU power mode. On Linux it's possible to tune the behavior by setting the min and max frequency to the same value, for example:

cat /sys/class/drm/card1/gt/gt0/rps_max_freq_mhz > /sys/class/drm/card1/gt/gt0/rps_min_freq_mhz

On systems that have multiple GPUs, pick cardN based on whether it has a gt/ subdirectory, NVidia GPUs for example don't have it. Discrete GPUs have additional tunables, see the official Intel docs for more information.

Public types

enum class BenchmarkType { Default = Int(Tester::BenchmarkType::Default), WallTime = Int(Tester::BenchmarkType::WallTime), CpuTime = Int(Tester::BenchmarkType::CpuTime), CpuCycles = Int(Tester::BenchmarkType::CpuCycles), GpuTime = 32 }: Benchmark type.

Constructors, destructors, conversion operators

OpenGLTester() explicit: Constructor.

Public functions

template<class Derived> void addBenchmarks(std::initializer_list<void(Derived::*)()> benchmarks, std::size_t batchCount, BenchmarkType benchmarkType = BenchmarkType::Default): Add benchmarks.
template<class Derived> void addBenchmarks(std::initializer_list<void(Derived::*)()> benchmarks, std::size_t batchCount, void(Derived::*)() setup, void(Derived::*)() teardown, BenchmarkType benchmarkType = BenchmarkType::Default): Add benchmarks with explicit setup and teardown functions.
template<class Derived> void addInstancedBenchmarks(std::initializer_list<void(Derived::*)()> benchmarks, std::size_t batchCount, std::size_t instanceCount, BenchmarkType benchmarkType = BenchmarkType::Default): Add instanced benchmarks.
template<class Derived> void addInstancedBenchmarks(std::initializer_list<void(Derived::*)()> benchmarks, std::size_t batchCount, std::size_t instanceCount, void(Derived::*)() setup, void(Derived::*)() teardown, BenchmarkType benchmarkType = BenchmarkType::Default): Add instanced benchmarks with explicit setup and teardown functions.

Enum documentation

enum class Magnum::GL::OpenGLTester::BenchmarkType

Benchmark type.

Extends Corrade::TestSuite::Tester::BenchmarkType with GPU benchmark types.

Enumerators
Default	See Corrade::TestSuite::Tester::BenchmarkType::Default for details.
WallTime	See Corrade::TestSuite::Tester::BenchmarkType::WallTime for details.
CpuTime	See Corrade::TestSuite::Tester::BenchmarkType::CpuTime for details.
CpuCycles	See Corrade::TestSuite::Tester::BenchmarkType::CpuCycles for details.
GpuTime	GPU time, measured using TimeQuery::Target::TimeElapsed. Note that the result of the query is retrieved synchronously and thus may cause a pipeline bubble. Increase number of iterations passed to CORRADE_BENCHMARK() to amortize the measurement error. If ARB_timer_query desktop extension (part of OpenGL 3.3), EXT_disjoint_timer_query OpenGL ES extension, EXT_disjoint_timer_query WebGL 1 extension or EXT_disjoint_timer_query_webgl2 WebGL 2 extension is not available, GPU time benchmarks will get automatically skipped.

Function documentation

Magnum::GL::OpenGLTester::OpenGLTester() explicit

Constructor.

Creates an OpenGL context.

template<class Derived>
void Magnum::GL::OpenGLTester::addBenchmarks(std::initializer_list<void(Derived::*)()> benchmarks, std::size_t batchCount, BenchmarkType benchmarkType = BenchmarkType::Default)

Add benchmarks.

Extends Corrade::TestSuite::Tester::addBenchmarks(std::initializer_list<void(Derived::*)()>, std::size_t, BenchmarkType) with support for GPU benchmark types.

If ARB_timer_query desktop extension (part of OpenGL 3.3), EXT_disjoint_timer_query OpenGL ES extension, EXT_disjoint_timer_query WebGL 1 extension or EXT_disjoint_timer_query_webgl2 WebGL 2 extension is not available, BenchmarkType::GpuTime benchmarks will get automatically skipped.

template<class Derived>
void Magnum::GL::OpenGLTester::addBenchmarks(std::initializer_list<void(Derived::)()> benchmarks, std::size_t batchCount, void(Derived::)() setup, void(Derived::*)() teardown, BenchmarkType benchmarkType = BenchmarkType::Default)

Add benchmarks with explicit setup and teardown functions.

Extends Corrade::TestSuite::Tester::addBenchmarks(std::initializer_list<void(Derived::*)()>, std::size_t, void(Derived::*)(), void(Derived::*)(), BenchmarkType) with support for GPU benchmark types.

template<class Derived>
void Magnum::GL::OpenGLTester::addInstancedBenchmarks(std::initializer_list<void(Derived::*)()> benchmarks, std::size_t batchCount, std::size_t instanceCount, BenchmarkType benchmarkType = BenchmarkType::Default)

Add instanced benchmarks.

Extends Corrade::TestSuite::Tester::addInstancedBenchmarks(std::initializer_list<void(Derived::*)()>, std::size_t, std::size_t, BenchmarkType) with support for GPU benchmark types.

template<class Derived>
void Magnum::GL::OpenGLTester::addInstancedBenchmarks(std::initializer_list<void(Derived::)()> benchmarks, std::size_t batchCount, std::size_t instanceCount, void(Derived::)() setup, void(Derived::*)() teardown, BenchmarkType benchmarkType = BenchmarkType::Default)

Add instanced benchmarks with explicit setup and teardown functions.

Extends Corrade::TestSuite::Tester::addInstancedBenchmarks(std::initializer_list<void(Derived::*)()>, std::size_t, std::size_t, void(Derived::*)(), void(Derived::*)(), BenchmarkType) with support for GPU benchmark types.