Platform: ask for debug context if --magnum-gpu-validation is enabled.

Also mention the option more prominently in related docs.

doc/changelog.dox

@@ -125,7 +125,10 @@ See also:
     for more information.
 -   New `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
     and a corresponding environment variable to conveniently enable
-    @gl_extension{KHR,debug} debug output
+    @gl_extension{KHR,debug} debug output. This flag also causes
+    @ref Platform::Sdl2Application::GLConfiguration::Flag::Debug "GLConfiguration::Flag::Debug"
+    to be enabled for context creation on both windowed and windowless
+    applications
 -   Detection of SwiftShader and ARM Mali drivers with
     @ref GL::Context::DetectedDriver::SwiftShader and
     @ref GL::Context::DetectedDriver::ArmMali

src/Magnum/GL/Context.h

@@ -138,7 +138,11 @@ Arguments:
     (environment: `MAGNUM_DISABLE_EXTENSIONS`)
 -   `--magnum-gpu-validation off|on` --- GPU validation using
     @gl_extension{KHR,debug}, if present (environment:
-    `MAGNUM_GPU_VALIDATION`) (default: `off`)
+    `MAGNUM_GPU_VALIDATION`) (default: `off`). This sets up @ref DebugOutput
+    callbacks and also causes
+    @ref Platform::Sdl2Application::GLConfiguration::Flag::Debug "GLConfiguration::Flag::Debug"
+    to be enabled for context creation for both windowed and windowless
+    applications on supported platforms
 -   `--magnum-log default|quiet|verbose` --- console logging
     (environment: `MAGNUM_LOG`) (default: `default`)
 
@@ -190,7 +194,10 @@ class MAGNUM_GL_EXPORT Context {
          */
         enum class Flag: GLint {
             /**
-             * Debug context
+             * Debug context. Enabled automatically by @ref Platform windowed
+             * and windowless application implementations if the
+             * `--magnum-gpu-validation`
+             * @ref GL-Context-command-line "command-line option" is present.
              * @requires_gl43 Extension @gl_extension{KHR,debug}
              * @requires_gles32 Extension @gl_extension{ANDROID,extension_pack_es31a} /
              *      @gl_extension{KHR,debug}
@@ -705,6 +712,15 @@ class MAGNUM_GL_EXPORT Context {
     #ifdef DOXYGEN_GENERATING_OUTPUT
     private:
     #endif
+        /* Applications want an easy way to know if GPU validation is enabled */
+        enum class InternalFlag: UnsignedByte {
+            DisplayInitializationLog = 1 << 0,
+            DisplayVerboseInitializationLog = DisplayInitializationLog|(1 << 1),
+            GpuValidation = 1 << 2
+        };
+        typedef Containers::EnumSet<InternalFlag> InternalFlags;
+        CORRADE_ENUMSET_FRIEND_OPERATORS(InternalFlags)
+
         bool isDriverWorkaroundDisabled(const char* workaround);
         Implementation::State& state() { return *_state; }
 
@@ -712,6 +728,8 @@ class MAGNUM_GL_EXPORT Context {
            state() pointer is not ready yet so we have to pass it directly */
         MAGNUM_GL_LOCAL bool isCoreProfileInternal(Implementation::ContextState& state);
 
+        InternalFlags internalFlags() const { return _internalFlags; }
+
     #ifdef DOXYGEN_GENERATING_OUTPUT
     private:
     #else
@@ -731,14 +749,6 @@ class MAGNUM_GL_EXPORT Context {
         friend Implementation::ContextState;
         #endif
 
-        enum class InternalFlag: UnsignedByte {
-            DisplayInitializationLog = 1 << 0,
-            DisplayVerboseInitializationLog = DisplayInitializationLog|(1 << 1),
-            GpuValidation = 1 << 2
-        };
-        typedef Containers::EnumSet<InternalFlag> InternalFlags;
-        CORRADE_ENUMSET_FRIEND_OPERATORS(InternalFlags)
-
         void disableDriverWorkaround(const std::string& workaround);
 
         /* Defined in Implementation/driverSpecific.cpp */

src/Magnum/GL/DebugOutput.h

@@ -62,7 +62,7 @@ provided also by @gl_extension{EXT,debug_marker} (desktop/ES extensions) or
 
 With OpenGL 4.3 / OpenGL ES 3.2 or @gl_extension{KHR,debug} desktop/ES extension,
 the debug output needs to be enabled first. It can be enabled globally using
-@ref Platform::Sdl2Application::GLConfiguration::Flag::Debug "Platform::*Application::Configuration::Flag::Debug"
+@ref Platform::Sdl2Application::GLConfiguration::Flag::Debug "Platform::*Application::GLConfiguration::Flag::Debug"
 when creating context or only for some portions of the code using
 @ref Renderer::Feature::DebugOutput. If enabled globally, some OpenGL drivers
 may provide additional debugging information. In addition to that you can
@@ -72,7 +72,19 @@ You can gather the messages either through graphics debugger or in the
 application itself by setting up message callback using @ref setCallback() or
 @ref setDefaultCallback(). You might also want to enable
 @ref Renderer::Feature::DebugOutputSynchronous. Example usage, completely with
-@ref DebugGroup and @link DebugMessage @endlink:
+@ref DebugGroup and @ref DebugMessage is below.
+
+@m_class{m-block m-success}
+
+@par Enabling debug output from the command line / environment
+    Apart from setting up the debug output callbacks manually, it's also
+    possible to enable it conveniently using the `--magnum-gpu-validation`
+    @ref GL-Context-command-line "command-line or environment option" --- ideal
+    for quick debugging of rendering issues. If you are using application
+    classes from the @ref Platform namespace, this option also ensures that
+    @ref Platform::Sdl2Application::GLConfiguration::Flag::Debug "GLConfiguration::Flag::Debug"
+    is passed for context creation, both with windowed and windowless
+    application implementations.
 
 @snippet MagnumGL.cpp DebugOutput-usage
 

src/Magnum/Platform/GlfwApplication.cpp

@@ -330,12 +330,16 @@ bool GlfwApplication::tryCreate(const Configuration& configuration, const GLConf
     glfwWindowHint(GLFW_SAMPLES, glConfiguration.sampleCount());
     glfwWindowHint(GLFW_SRGB_CAPABLE, glConfiguration.isSrgbCapable());
 
-    const GLConfiguration::Flags& flags = glConfiguration.flags();
+    /* Request debug context if --magnum-gpu-validation is enabled */
+    GLConfiguration::Flags glFlags = glConfiguration.flags();
+    if(_context->internalFlags() & GL::Context::InternalFlag::GpuValidation)
+        glFlags |= GLConfiguration::Flag::Debug;
+
     #ifdef GLFW_CONTEXT_NO_ERROR
-    glfwWindowHint(GLFW_CONTEXT_NO_ERROR, flags >= GLConfiguration::Flag::NoError);
+    glfwWindowHint(GLFW_CONTEXT_NO_ERROR, glFlags >= GLConfiguration::Flag::NoError);
     #endif
-    glfwWindowHint(GLFW_OPENGL_DEBUG_CONTEXT, flags >= GLConfiguration::Flag::Debug);
+    glfwWindowHint(GLFW_OPENGL_DEBUG_CONTEXT, glFlags >= GLConfiguration::Flag::Debug);
-    glfwWindowHint(GLFW_STEREO, flags >= GLConfiguration::Flag::Stereo);
+    glfwWindowHint(GLFW_STEREO, glFlags >= GLConfiguration::Flag::Stereo);
 
     /* Set context version, if requested */
     if(glConfiguration.version() != GL::Version::None) {
@@ -346,7 +350,7 @@ bool GlfwApplication::tryCreate(const Configuration& configuration, const GLConf
         #ifndef MAGNUM_TARGET_GLES
         if(glConfiguration.version() >= GL::Version::GL320) {
             glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
-            glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, flags >= GLConfiguration::Flag::ForwardCompatible);
+            glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, glFlags >= GLConfiguration::Flag::ForwardCompatible);
         }
         #else
         glfwWindowHint(GLFW_CLIENT_API, GLFW_OPENGL_ES_API);
@@ -362,7 +366,7 @@ bool GlfwApplication::tryCreate(const Configuration& configuration, const GLConf
         glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
         glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 2);
         glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
-        glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, flags >= GLConfiguration::Flag::ForwardCompatible);
+        glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, glFlags >= GLConfiguration::Flag::ForwardCompatible);
         #else
         /* For ES the major context version is compile-time constant */
         #ifdef MAGNUM_TARGET_GLES3

src/Magnum/Platform/GlfwApplication.h

@@ -622,7 +622,13 @@ class GlfwApplication::GLConfiguration {
             NoError = 1 << 1,
             #endif
 
-            Debug = 1 << 2,     /**< Debug context */
+            /**
+             * Debug context. Enabled automatically if the
+             * `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
+             * is present.
+             */
+            Debug = 1 << 2,
+
             Stereo = 1 << 3     /**< Stereo rendering */
         };
 

src/Magnum/Platform/Sdl2Application.cpp

@@ -328,6 +328,11 @@ bool Sdl2Application::tryCreate(const Configuration& configuration, const GLConf
     _dpiScaling = dpiScaling(configuration);
     const Vector2i scaledWindowSize = configuration.size()*_dpiScaling;
 
+    /* Request debug context if --magnum-gpu-validation is enabled */
+    GLConfiguration::Flags glFlags = glConfiguration.flags();
+    if(_context->internalFlags() & GL::Context::InternalFlag::GpuValidation)
+        glFlags |= GLConfiguration::Flag::Debug;
+
     /* Set context version, if user-specified */
     if(glConfiguration.version() != GL::Version::None) {
         Int major, minor;
@@ -342,7 +347,7 @@ bool Sdl2Application::tryCreate(const Configuration& configuration, const GLConf
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_ES);
         #endif
 
-        SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, int(glConfiguration.flags()));
+        SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, int(glFlags));
 
     /* Request usable version otherwise */
     } else {
@@ -359,7 +364,7 @@ bool Sdl2Application::tryCreate(const Configuration& configuration, const GLConf
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 1);
         #endif
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_CORE);
-        SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, int(glConfiguration.flags()));
+        SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, int(glFlags));
         #else
         /* For ES the major context version is compile-time constant */
         #ifdef MAGNUM_TARGET_GLES3
@@ -436,7 +441,7 @@ bool Sdl2Application::tryCreate(const Configuration& configuration, const GLConf
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 1);
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_COMPATIBILITY);
         /** @todo or keep the fwcompat? */
-        SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, int(glConfiguration.flags() & ~GLConfiguration::Flag::ForwardCompatible));
+        SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, int(glFlags) & int(~GLConfiguration::Flag::ForwardCompatible));
 
         if(!(_window = SDL_CreateWindow(configuration.title().data(),
             SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED,

src/Magnum/Platform/Sdl2Application.h

@@ -1056,7 +1056,11 @@ class Sdl2Application::GLConfiguration {
             ForwardCompatible = SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG,
             #endif
 
-            /** Create debug context */
+            /**
+             * Debug context. Enabled automatically if the
+             * `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
+             * is present.
+             */
             Debug = SDL_GL_CONTEXT_DEBUG_FLAG,
 
             /** Create context with robust access */

src/Magnum/Platform/WindowlessEglApplication.cpp

@@ -90,6 +90,13 @@ WindowlessEglContext::WindowlessEglContext(const Configuration& configuration, G
         return;
     }
 
+    #ifndef MAGNUM_TARGET_WEBGL
+    /* Request debug context if --magnum-gpu-validation is enabled */
+    Configuration::Flags flags = configuration.flags();
+    if(magnumContext && magnumContext->internalFlags() & GL::Context::InternalFlag::GpuValidation)
+        flags |= Configuration::Flag::Debug;
+    #endif
+
     #if !defined(MAGNUM_TARGET_GLES) || defined(MAGNUM_TARGET_WEBGL)
     const /* Is modified below to work around a SwiftShader limitation */
     #endif
@@ -111,7 +118,7 @@ WindowlessEglContext::WindowlessEglContext(const Configuration& configuration, G
         #ifndef MAGNUM_TARGET_WEBGL
         /* Needs to be last because we're zeroing this out for SwiftShader (see
            below) */
-        EGL_CONTEXT_FLAGS_KHR, EGLint(configuration.flags()),
+        EGL_CONTEXT_FLAGS_KHR, EGLint(flags),
         #endif
         EGL_NONE
     };

src/Magnum/Platform/WindowlessEglApplication.h

@@ -156,7 +156,12 @@ class WindowlessEglContext::Configuration {
             ForwardCompatible = EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR,
             #endif
 
-            Debug = EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR    /**< Create debug context */
+            /**
+             * Debug context. Enabled automatically if the
+             * `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
+             * is present.
+             */
+            Debug = EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR
         };
 
         /**

src/Magnum/Platform/WindowlessGlxApplication.cpp

@@ -68,6 +68,11 @@ WindowlessGlxContext::WindowlessGlxContext(const WindowlessGlxContext::Configura
     /* Get pointer to proper context creation function */
     const PFNGLXCREATECONTEXTATTRIBSARBPROC glXCreateContextAttribsARB = reinterpret_cast<PFNGLXCREATECONTEXTATTRIBSARBPROC>(glXGetProcAddress(reinterpret_cast<const GLubyte*>("glXCreateContextAttribsARB")));
 
+    /* Request debug context if --magnum-gpu-validation is enabled */
+    Configuration::Flags flags = configuration.flags();
+    if(magnumContext && magnumContext->internalFlags() & GL::Context::InternalFlag::GpuValidation)
+        flags |= Configuration::Flag::Debug;
+
     /* Optimistically choose core context first */
     const GLint contextAttributes[] = {
         #ifdef MAGNUM_TARGET_GLES
@@ -80,12 +85,12 @@ WindowlessGlxContext::WindowlessGlxContext(const WindowlessGlxContext::Configura
         #endif
         GLX_CONTEXT_MINOR_VERSION_ARB, 0,
         GLX_CONTEXT_PROFILE_MASK_ARB, GLX_CONTEXT_ES2_PROFILE_BIT_EXT,
-        GLX_CONTEXT_FLAGS_ARB, GLint(configuration.flags()),
+        GLX_CONTEXT_FLAGS_ARB, GLint(flags),
         #else
         GLX_CONTEXT_MAJOR_VERSION_ARB, 3,
         GLX_CONTEXT_MINOR_VERSION_ARB, 1,
         GLX_CONTEXT_PROFILE_MASK_ARB, GLX_CONTEXT_CORE_PROFILE_BIT_ARB,
-        GLX_CONTEXT_FLAGS_ARB, GLint(configuration.flags()),
+        GLX_CONTEXT_FLAGS_ARB, GLint(flags),
         #endif
         0
     };
@@ -97,7 +102,7 @@ WindowlessGlxContext::WindowlessGlxContext(const WindowlessGlxContext::Configura
         Warning() << "Platform::WindowlessGlxContext: cannot create core context, falling back to compatibility context";
 
         const GLint fallbackContextAttributes[] = {
-            GLX_CONTEXT_FLAGS_ARB, GLint(configuration.flags()),
+            GLX_CONTEXT_FLAGS_ARB, GLint(flags),
             0
         };
         _context = glXCreateContextAttribsARB(_display, configs[0], nullptr, True, fallbackContextAttributes);
@@ -134,7 +139,7 @@ WindowlessGlxContext::WindowlessGlxContext(const WindowlessGlxContext::Configura
             glXDestroyContext(_display, _context);
             const GLint fallbackContextAttributes[] = {
                 /** @todo keep the fwcompat? */
-                GLX_CONTEXT_FLAGS_ARB, GLint(configuration.flags() & ~Configuration::Flag::ForwardCompatible),
+                GLX_CONTEXT_FLAGS_ARB, GLint(flags & ~Configuration::Flag::ForwardCompatible),
                 0
             };
             _context = glXCreateContextAttribsARB(_display, configs[0], nullptr, True, fallbackContextAttributes);

src/Magnum/Platform/WindowlessGlxApplication.h

@@ -165,7 +165,12 @@ class WindowlessGlxContext::Configuration {
             ForwardCompatible = GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB,
             #endif
 
-            Debug = GLX_CONTEXT_DEBUG_BIT_ARB   /**< Create debug context */
+            /**
+             * Debug context. Enabled automatically if the
+             * `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
+             * is present.
+             */
+            Debug = GLX_CONTEXT_DEBUG_BIT_ARB
         };
 
         /**

src/Magnum/Platform/WindowlessWglApplication.cpp

@@ -119,6 +119,11 @@ WindowlessWglContext::WindowlessWglContext(const Configuration& configuration, G
     typedef HGLRC(WINAPI*PFNWGLCREATECONTEXTATTRIBSARBPROC)(HDC, HGLRC, const int*);
     const PFNWGLCREATECONTEXTATTRIBSARBPROC wglCreateContextAttribsARB = reinterpret_cast<PFNWGLCREATECONTEXTATTRIBSARBPROC>( wglGetProcAddress(reinterpret_cast<LPCSTR>("wglCreateContextAttribsARB")));
 
+    /* Request debug context if --magnum-gpu-validation is enabled */
+    Configuration::Flags flags = configuration.flags();
+    if(magnumContext && magnumContext->internalFlags() & GL::Context::InternalFlag::GpuValidation)
+        flags |= Configuration::Flag::Debug;
+
     /* Optimistically choose core context first */
     const GLint contextAttributes[] = {
         #ifdef MAGNUM_TARGET_GLES
@@ -131,12 +136,12 @@ WindowlessWglContext::WindowlessWglContext(const Configuration& configuration, G
         #endif
         WGL_CONTEXT_MINOR_VERSION_ARB, 0,
         WGL_CONTEXT_PROFILE_MASK_ARB, WGL_CONTEXT_ES2_PROFILE_BIT_EXT,
-        WGL_CONTEXT_FLAGS_ARB, GLint(configuration.flags()),
+        WGL_CONTEXT_FLAGS_ARB, GLint(flags),
         #else
         WGL_CONTEXT_MAJOR_VERSION_ARB, 3,
         WGL_CONTEXT_MINOR_VERSION_ARB, 1,
         WGL_CONTEXT_PROFILE_MASK_ARB, WGL_CONTEXT_CORE_PROFILE_BIT_ARB,
-        WGL_CONTEXT_FLAGS_ARB, GLint(configuration.flags()),
+        WGL_CONTEXT_FLAGS_ARB, GLint(flags),
         #endif
         0
     };
@@ -149,7 +154,7 @@ WindowlessWglContext::WindowlessWglContext(const Configuration& configuration, G
 
         const int fallbackContextAttributes[] = {
             /** @todo or keep the fwcompat? */
-            WGL_CONTEXT_FLAGS_ARB, GLint(configuration.flags() & ~Configuration::Flag::ForwardCompatible),
+            WGL_CONTEXT_FLAGS_ARB, GLint(flags & ~Configuration::Flag::ForwardCompatible),
             0
         };
         _context = wglCreateContextAttribsARB(_deviceContext, nullptr, fallbackContextAttributes);
@@ -188,7 +193,7 @@ WindowlessWglContext::WindowlessWglContext(const Configuration& configuration, G
             wglDeleteContext(_context);
             const int fallbackContextAttributes[] = {
                 /** @todo or keep the fwcompat? */
-                WGL_CONTEXT_FLAGS_ARB, GLint(configuration.flags() & ~Configuration::Flag::ForwardCompatible),
+                WGL_CONTEXT_FLAGS_ARB, GLint(flags & ~Configuration::Flag::ForwardCompatible),
                 0
             };
             _context = wglCreateContextAttribsARB(_deviceContext, nullptr, fallbackContextAttributes);

src/Magnum/Platform/WindowlessWglApplication.h

@@ -165,7 +165,12 @@ class WindowlessWglContext::Configuration {
             ForwardCompatible = WGL_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB,
             #endif
 
-            Debug = WGL_CONTEXT_DEBUG_BIT_ARB   /**< Create debug context */
+            /**
+             * Debug context. Enabled automatically if the
+             * `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
+             * is present.
+             */
+            Debug = WGL_CONTEXT_DEBUG_BIT_ARB
         };
 
         /**

src/Magnum/Platform/WindowlessWindowsEglApplication.cpp

@@ -35,7 +35,7 @@
 
 namespace Magnum { namespace Platform {
 
-WindowlessWindowsEglContext::WindowlessWindowsEglContext(const Configuration& configuration, GLContext*) {
+WindowlessWindowsEglContext::WindowlessWindowsEglContext(const Configuration& configuration, GLContext* const magnumContext) {
     /* Register the window class (if not yet done) */
     WNDCLASSW wc;
     if(!GetClassInfoW(GetModuleHandleW(nullptr), L"Magnum Windowless Application", &wc)) {
@@ -110,6 +110,11 @@ WindowlessWindowsEglContext::WindowlessWindowsEglContext(const Configuration& co
         return;
     }
 
+    /* Request debug context if --magnum-gpu-validation is enabled */
+    Configuration::Flags flags = configuration.flags();
+    if(magnumContext && magnumContext->internalFlags() & GL::Context::InternalFlag::GpuValidation)
+        flags |= Configuration::Flag::Debug;
+
     const EGLint attributes[] = {
         #ifdef MAGNUM_TARGET_GLES
         EGL_CONTEXT_CLIENT_VERSION,
@@ -121,7 +126,7 @@ WindowlessWindowsEglContext::WindowlessWindowsEglContext(const Configuration& co
             #error unsupported OpenGL ES version
             #endif
         #endif
-        EGL_CONTEXT_FLAGS_KHR, EGLint(configuration.flags()),
+        EGL_CONTEXT_FLAGS_KHR, EGLint(flags),
         EGL_NONE
     };
 

src/Magnum/Platform/WindowlessWindowsEglApplication.h

@@ -141,7 +141,12 @@ class WindowlessWindowsEglContext::Configuration {
          * @see @ref Flags, @ref setFlags(), @ref Context::Flag
          */
         enum class Flag: int {
-            Debug = EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR    /**< Create debug context */
+            /**
+             * Debug context. Enabled automatically if the
+             * `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
+             * is present.
+             */
+            Debug = EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR
         };
 
         /**