Magnum::GL::DebugOutput class

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.

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 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.

static void Magnum::GL::DebugOutput::setEnabled(Source source, Type type, Severity severity, bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setEnabled(Source source, Type type, bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setEnabled(Source source, Severity severity, bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setEnabled(Source source, bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setEnabled(Type type, Severity severity, bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setEnabled(Type type, bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setEnabled(Severity severity, bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setEnabled(bool enabled)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void Magnum::GL::DebugOutput::setCallback(Callback callback, const void* userParam = nullptr)

Set debug message callback.

The messages are sent to the callback only if Renderer::Feature::DebugOutput is enabled. 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.

static void Magnum::GL::DebugOutput::setCallback(void(*)(Source, Type, UnsignedInt, Severity, const std::string&, const void*) callback, const void* userParam = nullptr)

Set debug message callback.

static void Magnum::GL::DebugOutput::setDefaultCallback()

Set default debug message callback.

See setCallback() for more information. The message is printed to Debug output in the following format:

GL::DebugMessage::insert(GL::DebugMessage::Source::Application,
    GL::DebugMessage::Type::Marker, 1337, GL::DebugOutput::Severity::Notification,
    "Hello from OpenGL command stream!");

Debug output: application marker (1337): Hello from OpenGL command stream!

Debug& operator<<(Debug& debug, DebugOutput::Source value)

Debug output operator.

Debug& operator<<(Debug& debug, DebugOutput::Type value)

Debug output operator.

Debug& operator<<(Debug& debug, DebugOutput::Severity value)

Debug output operator.