GL: new --magnum-gpu-validation command-line option.

Enables KHR_debug, if available. This should have been here since ages.

doc/changelog.dox

@@ -55,6 +55,9 @@ See also:
     and @cpp "mesa-implementation-color-read-format-dsa-explicit-binding" @ce,
     because it's 2019 and GL drivers are *still* awful. See
     @ref opengl-workarounds 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
 
 @subsection changelog-latest-changes Changes and improvements
 

doc/troubleshooting.dox

@@ -57,12 +57,16 @@ crashes on GL calls, you might want to try these things:
     @ref GL::Context::isExtensionSupported() "available on your system".
 -   Check that you didn't exceed any implementation-defined limit (see
     @ref magnum-gl-info output for list of all of them).
--   Enable @ref GL::DebugMessage "debug output" to see more detailed errors,
-    warnings and performance hints.
+-   Enable @ref GL::DebugOutput "debug output" to see more detailed errors,
+    warnings and performance hints. You can do that easily through the
+    `--magnum-gpu-validation` @ref GL-Context-command-line "command-line option"
+    or an environment variable.
 -   If using framebuffer objects,
     @ref GL::Framebuffer::checkStatus() "check that they are complete".
 -   Change @ref GL::Renderer::setClearColor() "framebuffer clear color" to
-    something else than black to verify that at least something is drawn.
+    something else than black to verify that at least something is drawn. The
+    engine sets it to @cpp 0x1f1f1f_rgbf @ce by default to help you a bit in
+    this regard.
 -   If nothing is drawn, use @ref GL::PrimitiveQuery to check that at least
     some primitives were generated. Use @ref GL::SampleQuery to check whether
     fragments were drawn.
@@ -91,8 +95,6 @@ crashes on GL calls, you might want to try these things:
 
 @section troubleshooting-debugging Debugging rendering
 
--   Enable @ref GL::DebugMessage "debug output" to see additional performance
-    hints and implementation-dependent information.
 -   Use @ref GL::TimeQuery to find hot spots in the rendering code.
 -   @ref GL::DebugMessage::insert() "Mark relevant parts of code" to find them
     easier in the debugger.

src/Magnum/GL/Context.cpp

@@ -43,6 +43,9 @@
 #ifndef MAGNUM_TARGET_GLES
 #include "Magnum/GL/BufferTexture.h"
 #endif
+#ifndef MAGNUM_TARGET_WEBGL
+#include "Magnum/GL/DebugOutput.h"
+#endif
 #include "Magnum/GL/DefaultFramebuffer.h"
 #include "Magnum/GL/Extensions.h"
 #include "Magnum/GL/Framebuffer.h"
@@ -457,9 +460,11 @@ Context::Context(NoCreateT, Utility::Arguments& args, Int argc, const char** arg
     args.addOption("disable-workarounds")
         .setHelp("disable-workarounds", "driver workarounds to disable\n      (see https://doc.magnum.graphics/magnum/opengl-workarounds.html for detailed info)", "LIST")
         .addOption("disable-extensions").setHelp("disable-extensions", "OpenGL extensions to disable", "LIST")
+        .addOption("gpu-validation", "off").setHelp("gpu-validation", "GPU validation using KHR_debug (if present)", "off|on")
         .addOption("log", "default").setHelp("log", "console logging", "default|quiet|verbose")
         .setFromEnvironment("disable-workarounds")
         .setFromEnvironment("disable-extensions")
+        .setFromEnvironment("gpu-validation")
         .setFromEnvironment("log")
         .parse(argc, argv);
 
@@ -467,6 +472,10 @@ Context::Context(NoCreateT, Utility::Arguments& args, Int argc, const char** arg
     if(!(args.value("log") == "quiet" || args.value("log") == "QUIET"))
         _internalFlags |= InternalFlag::DisplayInitializationLog;
 
+    /* Decide whether to enable GPU validation */
+    if(args.value("gpu-validation") == "on" || args.value("gpu-validation") == "ON")
+        _internalFlags |= InternalFlag::GpuValidation;
+
     /* Disable driver workarounds */
     for(auto&& workaround: Utility::String::splitWithoutEmptyParts(args.value("disable-workarounds")))
         disableDriverWorkaround(workaround);
@@ -729,6 +738,19 @@ bool Context::tryCreate() {
     DefaultFramebuffer::initializeContextBasedFunctionality(*this);
     Renderer::initializeContextBasedFunctionality();
 
+    /* Enable GPU validation, if requested */
+    if(_internalFlags & InternalFlag::GpuValidation) {
+        #ifndef MAGNUM_TARGET_WEBGL
+        if(Context::current().isExtensionSupported<Extensions::KHR::debug>()) {
+            Renderer::enable(Renderer::Feature::DebugOutput);
+            Renderer::enable(Renderer::Feature::DebugOutputSynchronous);
+            DebugOutput::setDefaultCallback();
+        } else Warning{} << "GL::Context: GPU validation requested, but GL_KHR_debug not supported";
+        #else
+        Warning{} << "GL::Context: GPU validation is not available on WebGL";
+        #endif
+    }
+
     /* Everything okay */
     return true;
 }

src/Magnum/GL/Context.h

@@ -121,6 +121,7 @@ either from the `Platform::*Application` classes or from the
 @code{.sh}
 <application> [--magnum-help] [--magnum-disable-workarounds LIST]
               [--magnum-disable-extensions LIST]
+              [--magnum-gpu-validation off|on]
               [--magnum-log default|quiet|verbose] ...
 @endcode
 
@@ -129,9 +130,13 @@ Arguments:
 -   `...` --- main application arguments (see `-h` or `--help` for details)
 -   `--magnum-help` --- display this help message and exit
 -   `--magnum-disable-workarounds LIST` --- driver workarounds to disable (see
-    @ref opengl-workarounds for detailed info) (environment: `MAGNUM_DISABLE_WORKAROUNDS`)
+    @ref opengl-workarounds for detailed info) (environment:
+    `MAGNUM_DISABLE_WORKAROUNDS`)
 -   `--magnum-disable-extensions LIST` --- OpenGL extensions to disable
     (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-log default|quiet|verbose` --- console logging
     (environment: `MAGNUM_LOG`) (default: `default`)
 
@@ -668,7 +673,8 @@ class MAGNUM_GL_EXPORT Context {
         #endif
 
         enum class InternalFlag: UnsignedByte {
-            DisplayInitializationLog = 1 << 0
+            DisplayInitializationLog = 1 << 0,
+            GpuValidation = 1 << 1
         };
         typedef Containers::EnumSet<InternalFlag> InternalFlags;
         CORRADE_ENUMSET_FRIEND_OPERATORS(InternalFlags)

src/Magnum/GL/OpenGLTester.h

@@ -125,6 +125,10 @@ upon encountering a GL error --- this should be done explicitly with
 @ref MAGNUM_VERIFY_NO_GL_ERROR() instead, as the debug output is not available
 on all platforms and not all GL errors are fatal.
 
+@note This overrides the `--magnum-gpu-validation`
+    @ref GL-Context-command-line "command line option", making it always
+    enabled.
+
 @section GL-OpenGLTester-benchmarks GPU time benchmarks
 
 This class adds @ref BenchmarkType::GpuTime to the benchmark type enum,