This is a snapshot of a work-in-progress documentation theme. If you feel lost, miss something, or want to see the original Doxygen docs instead, head over to the archived version of this documentation page.

Magnum::OpenGLTester class

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 only on platforms with corresponding Platform::Windowless*Application implementation. That currently means all platforms except Android and Emscripten. It is built into a separate static library and only if WITH_OPENGLTESTER is enabled when building Magnum. To use it with CMake, you need to 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)

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

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

On platforms that support it, the OpenGL context is created with synchronous debug output, meaning that every OpenGL error is directly reported to standard output. While it is possible, the tester class doesn't abort the test cases upon encountering a GL error – this should be done explicitly with MAGNUM_VERIFY_NO_ERROR() instead, as the debug output is not available on all platforms and not all GL errors are fatal.

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.

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::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 pipeline bubble. Increase number of iterations passed to CORRADE_BENCHMARK() to amortize the measurement error.

Function documentation

Magnum::OpenGLTester::OpenGLTester() explicit

Constructor.

Creates an OpenGL context.

template<class Derived>
void Magnum::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.

template<class Derived>
void Magnum::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::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::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.

Define documentation

#define MAGNUM_VERIFY_NO_ERROR()

Verify that no OpenGL error occurred.

Equivalent to

CORRADE_COMPARE(Magnum::Renderer::error(), Magnum::Renderer::Error::NoError)