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

Debug output.

Manages OpenGL debug output. The debug messages are emitted either from driver (such as GL error descriptions and various performance and optimization hints) or from third party software and the application itself using DebugMessage and DebugGroup, which can be also used to mark various portions of command stream in various graphics debuggers, such as ApiTrace or gDEBugger.

Basic usage

Support for debug output is provided by OpenGL 4.3 / OpenGL ES 3.2 or KHR_debug (desktop/ES extension, covered also by ANDROID_extension_pack_es31a). Subset of the functionality is provided also by EXT_debug_marker (desktop/ES extensions) or GREMEDY_string_marker (desktop only extension).

With OpenGL 4.3 / OpenGL ES 3.2 or KHR_debug desktop/ES extension, the debug output needs to be enabled first. It can be enabled globally using Platform::*Application::GLConfiguration::Flag::Debug when creating context or only for some portions of the code using Renderer::Feature::DebugOutput. If enabled globally, some OpenGL drivers may provide additional debugging information. In addition to that you can control the output at even finer granularity using setEnabled().

You can gather the messages either through graphics debugger or in the application itself by setting up message callback using setCallback() or setDefaultCallback(). You might also want to enable Renderer::Feature::DebugOutputSynchronous. Example usage, completely with DebugGroup and DebugMessage is below.

GL::Renderer::enable(GL::Renderer::Feature::DebugOutput);
GL::Renderer::enable(GL::Renderer::Feature::DebugOutputSynchronous);
GL::DebugOutput::setDefaultCallback();

/* Disable rather spammy "Buffer detailed info" debug messages on NVidia drivers */
GL::DebugOutput::setEnabled(
    GL::DebugOutput::Source::Api, GL::DebugOutput::Type::Other, {131185}, false);

{
    GL::DebugGroup group{GL::DebugGroup::Source::Application, 42,
        "Scene rendering"};

    GL::DebugMessage::insert(GL::DebugMessage::Source::Application,
        GL::DebugMessage::Type::Marker, 1337,
        GL::DebugOutput::Severity::Notification, "Rendering a transparent mesh");

    GL::Renderer::enable(GL::Renderer::Feature::Blending);
    shader.draw(mesh);
    GL::Renderer::disable(GL::Renderer::Feature::Blending);

    // ...
}

With default callback the group entering/leaving and the inserted message (and possibly also other messages) will be printed on standard output:

Debug output: application debug group enter (42): Scene rendering
Debug output: application marker (1337): Rendering transparent mesh
...
Debug output: application debug group leave (42): Scene rendering

If only EXT_debug_marker or GREMEDY_string_marker are supported, only user-inserted messages and debug groups are supported and they can be seen only through graphics debugger.

If OpenGL 4.3 is not supported and neither KHR_debug nor EXT_debug_marker nor GREMEDY_string_marker are available, all the functions are essentially a no-op.

Besides inserting messages into GL command stream you can also annotate OpenGL objects with labels. See AbstractQuery::setLabel(), AbstractShaderProgram::setLabel(), AbstractTexture::setLabel(), Buffer::setLabel(), Framebuffer::setLabel(), Mesh::setLabel(), Renderbuffer::setLabel(), Shader::setLabel() and TransformFeedback::setLabel() for more information.

Public types

enum class Source: GLenum { Api = GL_DEBUG_SOURCE_API, WindowSystem = GL_DEBUG_SOURCE_WINDOW_SYSTEM, ShaderCompiler = GL_DEBUG_SOURCE_SHADER_COMPILER, ThirdParty = GL_DEBUG_SOURCE_THIRD_PARTY, Application = GL_DEBUG_SOURCE_APPLICATION, Other = GL_DEBUG_SOURCE_OTHER }: Message source.
enum class Type: GLenum { Error = GL_DEBUG_TYPE_ERROR, DeprecatedBehavior = GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR, UndefinedBehavior = GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR, Portability = GL_DEBUG_TYPE_PORTABILITY, Performance = GL_DEBUG_TYPE_PERFORMANCE, Marker = GL_DEBUG_TYPE_MARKER, PushGroup = GL_DEBUG_TYPE_PUSH_GROUP, PopGroup = GL_DEBUG_TYPE_POP_GROUP, Other = GL_DEBUG_TYPE_OTHER }: Message type.
enum class Severity: GLenum { High = GL_DEBUG_SEVERITY_HIGH, Medium = GL_DEBUG_SEVERITY_MEDIUM, Low = GL_DEBUG_SEVERITY_LOW, Notification = GL_DEBUG_SEVERITY_NOTIFICATION }: Message severity.
using Callback = void(*)(Source, Type, UnsignedInt, Severity, Containers::StringView, const void*): Debug callback.

Public static functions

static auto maxLoggedMessages() -> Int: Max count of debug messages in log.
static auto maxMessageLength() -> Int: Max debug message length.
static void setEnabled(Source source, Type type, std::initializer_list<UnsignedInt> ids, bool enabled): Enable or disable particular output type.
static void setEnabled(Source source, Type type, Severity severity, bool enabled)
static void setEnabled(Source source, Type type, bool enabled)
static void setEnabled(Source source, Severity severity, bool enabled)
static void setEnabled(Source source, bool enabled)
static void setEnabled(Type type, Severity severity, bool enabled)
static void setEnabled(Type type, bool enabled)
static void setEnabled(Severity severity, bool enabled)
static void setEnabled(bool enabled)
static void setCallback(Callback callback, const void* userParam = nullptr): Set debug message callback.
static void setCallback(void(*)(Source, Type, UnsignedInt, Severity, const std::string&, const void*) callback, const void* userParam = nullptr) deprecated in Git master: Set debug message callback.
static void setDefaultCallback(): Set default debug message callback.

Constructors, destructors, conversion operators

DebugOutput() deleted: There's no point in having an instance of this class.

Enum documentation

enum class Magnum::GL::DebugOutput::Source: GLenum

Message source.

Enumerators
Api	OpenGL
WindowSystem	Window system (GLX, WGL)
ShaderCompiler	Shader compiler
ThirdParty	External debugger or third-party middleware
Application	The application
Other	Any other source

enum class Magnum::GL::DebugOutput::Type: GLenum

Message type.

Enumerators
Error	OpenGL error
DeprecatedBehavior	Behavior that has been marked for deprecation
UndefinedBehavior	Behavior that is undefined according to the specification
Portability	Non-portable usage of extensions or shaders
Performance	Implementation-dependent performance warning
Marker	Annotation of the command stream
PushGroup	Entering a debug group
PopGroup	Leaving a debug group
Other	Any other type

enum class Magnum::GL::DebugOutput::Severity: GLenum

Message severity.

Enumerators
High	Any OpenGL error, dangerous undefined behavior, shader compilation errors.
Medium	Severe performance warnings, shader compilation warnings, use of deprecated behavior.
Low	Minor performance warnings, trivial undefined behavior.
Notification	Any message other than error or performance warning.

Typedef documentation

typedef void(Magnum::GL::DebugOutput::Callback)(Source, Type, UnsignedInt, Severity, Containers::StringView, const void)

Debug callback.

Function documentation

static Int Magnum::GL::DebugOutput::maxLoggedMessages()

Max count of debug messages in log.

The result is cached, repeated queries don't result in repeated OpenGL calls. If OpenGL 4.3 / OpenGL ES 3.2 is not supported and KHR_debug desktop or ES extension (covered also by ANDROID_extension_pack_es31a) is not available, returns 0.

static Int Magnum::GL::DebugOutput::maxMessageLength()

Max debug message length.

static void Magnum::GL::DebugOutput::setEnabled(Source source, Type type, std::initializer_list<UnsignedInt> ids, bool enabled)

Enable or disable particular output type.

If OpenGL 4.3 / OpenGL ES 3.2 is not supported and KHR_debug desktop or ES extension (covered also by ANDROID_extension_pack_es31a) is not available, this function does nothing.