class
#include <Magnum/GL/DebugOutput.h>
DebugOutput 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_
With OpenGL 4.3 / OpenGL ES 3.2 or KHR_
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::
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_
If OpenGL 4.3 is not supported and neither KHR_
Besides inserting messages into GL command stream you can also annotate OpenGL objects with labels. See AbstractQuery::
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_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_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_
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::
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.