Magnum::GL::DebugGroup class

Debug group.

Contents

Allows marking portions of 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.

Easiest way is to push debug group by creating instance and pop it automatically at the end of scope:

{
    /* Push debug group */
    GL::DebugGroup group{GL::DebugGroup::Source::Application, 42, "Scene rendering"};

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

    /* The debug group is popped automatically at the end of the scope */
}

If, for some reason, you need to pop in different scope, you can call push() and pop() manually:

GL::DebugGroup group;

group.push(GL::DebugGroup::Source::Application, 42, "Scene rendering");

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

group.pop();

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 the default debug output callback is enabled for these kinds of messages, the group entering and leaving will be printed on standard output in the following form:

Debug output: application debug group enter (42): Scene rendering
Debug output: application debug group leave (42): Scene rendering

If only EXT_debug_marker is available, the group can be seen only through graphics debugger.

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

Interaction with debug output volume control

Besides putting hierarchical messages in debug output, the group also affects settings done by DebugOutput::setEnabled(). Entering debug group inherits the settings from previously active debug group, call to DebugOutput::setEnabled() will be remembered only for the time in which given group is active and leaving it will revert the setting to state set in parent debug group. No state is preserved, thus calling push() after previous pop() will not restore settings done when the group was active previously.

Performance notes

If you ensure that you always use the const char overload of push() 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.

Public static functions

static auto maxStackDepth() -> Int
Max debug group stack depth.

Constructors, destructors, conversion operators

DebugGroup() explicit
Default constructor.
DebugGroup(Source source, UnsignedInt id, const std::string& message) explicit
Constructor.
template<std::size_t size>
DebugGroup(Source source, UnsignedInt id, const char(&message)[size]) explicit
~DebugGroup()
Destructor.

Public functions

void push(Source source, UnsignedInt id, const std::string& message)
Push debug group onto the stack.
template<std::size_t size>
void push(Source source, UnsignedInt id, const char(&message)[size])
void pop()
Pop debug group from the stack.

Enum documentation

enum class Magnum::GL::DebugGroup::Source: GLenum

Message source.

Enumerators
ThirdParty

External debugger or third-party middleware
Application

The application

Function documentation

static Int Magnum::GL::DebugGroup::maxStackDepth()

Max debug group stack depth.

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.

Magnum::GL::DebugGroup::DebugGroup() explicit

Default constructor.

Doesn't do anything. Call push() to enter debug group.

Magnum::GL::DebugGroup::DebugGroup(Source source, UnsignedInt id, const std::string& message) explicit

Constructor.

Calls push().

template<std::size_t size>
Magnum::GL::DebugGroup::DebugGroup(Source source, UnsignedInt id, const char(&message)[size]) explicit

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

Magnum::GL::DebugGroup::~DebugGroup()

Destructor.

If the group is active, calls pop().

void Magnum::GL::DebugGroup::push(Source source, UnsignedInt id, const std::string& message)

Push debug group onto the stack.

Expects that the group isn't already pushed on the stack. The group entering message is put into debug output with DebugOutput::Type::PushGroup and DebugOutput::Severity::Notification.

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 is available, this function does nothing. If KHR_debug is not available and only EXT_debug_marker is available, only message is used and all other parameters are ignored.

template<std::size_t size>
void Magnum::GL::DebugGroup::push(Source source, UnsignedInt id, const char(&message)[size])

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

void Magnum::GL::DebugGroup::pop()

Pop debug group from the stack.

Expects that the group is currently pushed on the stack. Leaving the group will also revert all DebugOutput::setEnabled() settings done when the group was active. See class documentation for more information. The group leaving message is put into debug output with DebugOutput::Type::PopGroup and DebugOutput::Severity::Notification.

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 is available, this function does nothing.

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

Debug output operator.