Magnum::GL::DebugMessage class

Debug message.

Contents

Allows inserting messages GL command stream with labels, useful for example with conjunction with various graphics debuggers, such as ApiTrace or gDEBugger.

Basic usage

See DebugOutput for introduction.

If OpenGL 4.3 / OpenGL ES 3.2 is supported or KHR_debug desktop or ES extension (covered also by ANDROID_extension_pack_es31a) is available and default debug output callback is enabled for given kind of messages, the inserted message will be printed on standard output in the following form:

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!

If only EXT_debug_marker or GREMEDY_string_marker are available, the message 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, the function is essentially a no-op.

Performance notes

If you ensure that you always use the const char overload of insert() and the debug output is either not supported or turned off, the calls will not result in any allocations and thus won't have any negative performance effects.

Public types

enum class Source: GLenum { ThirdParty = GL_DEBUG_SOURCE_THIRD_PARTY, Application = GL_DEBUG_SOURCE_APPLICATION }
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, Other = GL_DEBUG_TYPE_OTHER }
Message type.

Public static functions

static void insert(Source source, Type type, UnsignedInt id, DebugOutput::Severity severity, const std::string& string)
Insert message.
template<std::size_t size>
static void insert(Source source, Type type, UnsignedInt id, DebugOutput::Severity severity, const char(&string)[size])

Constructors, destructors, conversion operators

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

Enum documentation

enum class Magnum::GL::DebugMessage::Source: GLenum

Message source.

Enumerators
ThirdParty

External debugger or third-party middleware
Application

The application

enum class Magnum::GL::DebugMessage::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
Other

Any other type

Function documentation

static void Magnum::GL::DebugMessage::insert(Source source, Type type, UnsignedInt id, DebugOutput::Severity severity, const std::string& string)

Insert message.

Parameters
source Message source
type Message type
id Message-specific ID
severity Message severity
string The actual message

If OpenGL 4.3 / OpenGL ES 3.2 is not supported and neither KHR_debug (covered also by ANDROID_extension_pack_es31a) nor EXT_debug_marker (desktop or ES extensions) nor GREMEDY_string_marker (desktop only extension) are available, this function does nothing.

If KHR_debug is not available and only EXT_debug_marker or GREMEDY_string_marker are available, only string is used and all other parameters are ignored.

template<std::size_t size>
static void Magnum::GL::DebugMessage::insert(Source source, Type type, UnsignedInt id, DebugOutput::Severity severity, const char(&string)[size])

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

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

Debug output operator.

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

Debug output operator.