cogl debug: Makes COGL_DEBUG=all|verbose|help more useful

COGL_DEBUG=all wasn't previously useful as there are several options
that change the behaviour of Cogl and all together wouldn't help anyone
debug anything.

This patch makes it so COGL_DEBUG=all|verbose now only enables options
that don't change the behaviour of Cogl, i.e. they only affect the
amount of noise we'll print to a terminal.

In addition to that this patch also improves the output from
COGL_DEBUG=help so we now print a table of options including one liner
descriptions of what each option enables.

1 files changed, 93 insertions, 28 deletions

diff --git a/cogl/cogl-debug.c b/cogl/cogl-debug.c
index b1b146fd..37ae266a 100644
--- a/cogl/cogl-debug.c
+++ b/cogl/cogl-debug.c
@@ -25,49 +25,122 @@
 #include "config.h"
 #endif
 
+#include <stdlib.h>
 #include <glib/gi18n-lib.h>
 
 #include "cogl-debug.h"
 
 #ifdef COGL_ENABLE_DEBUG
-static const GDebugKey cogl_debug_keys[] = {
-  { "misc", COGL_DEBUG_MISC },
-  { "texture", COGL_DEBUG_TEXTURE },
-  { "material", COGL_DEBUG_MATERIAL },
-  { "shader", COGL_DEBUG_SHADER },
-  { "offscreen", COGL_DEBUG_OFFSCREEN },
+
+/* XXX: If you add a debug option, please also scroll down to
+ * cogl_arg_debug_cb() and add a "help" description of the option too.
+ */
+
+/* NB: Only these options get enabled if COGL_DEBUG=all is
+ * used since they don't affect the behaviour of Cogl they
+ * simply print out verbose information */
+static const GDebugKey cogl_log_debug_keys[] = {
+  { "handle", COGL_DEBUG_HANDLE },
+  { "slicing", COGL_DEBUG_SLICING },
+  { "atlas", COGL_DEBUG_ATLAS },
+  { "blend-strings", COGL_DEBUG_BLEND_STRINGS },
+  { "journal", COGL_DEBUG_JOURNAL },
+  { "batching", COGL_DEBUG_BATCHING },
+  { "matrices", COGL_DEBUG_MATRICES },
   { "draw", COGL_DEBUG_DRAW },
   { "pango", COGL_DEBUG_PANGO },
+};
+static const int n_cogl_log_debug_keys =
+  G_N_ELEMENTS (cogl_log_debug_keys);
+
+static const GDebugKey cogl_behavioural_debug_keys[] = {
   { "rectangles", COGL_DEBUG_RECTANGLES },
-  { "handle", COGL_DEBUG_HANDLE },
-  { "blend-strings", COGL_DEBUG_BLEND_STRINGS },
   { "disable-batching", COGL_DEBUG_DISABLE_BATCHING },
   { "disable-vbos", COGL_DEBUG_DISABLE_VBOS },
-  { "journal", COGL_DEBUG_JOURNAL },
-  { "batching", COGL_DEBUG_BATCHING },
   { "disable-software-transform", COGL_DEBUG_DISABLE_SOFTWARE_TRANSFORM },
-  { "matrices", COGL_DEBUG_MATRICES },
   { "force-scanline-paths", COGL_DEBUG_FORCE_SCANLINE_PATHS },
-  { "atlas", COGL_DEBUG_ATLAS },
   { "dump-atlas-image", COGL_DEBUG_DUMP_ATLAS_IMAGE },
   { "disable-atlas", COGL_DEBUG_DISABLE_ATLAS }
 };
+static const int n_cogl_behavioural_debug_keys =
+  G_N_ELEMENTS (cogl_behavioural_debug_keys);
 
-static const int n_cogl_debug_keys = G_N_ELEMENTS (cogl_debug_keys);
 #endif /* COGL_ENABLE_DEBUG */
 
 unsigned int cogl_debug_flags = 0;
 
 #ifdef COGL_ENABLE_DEBUG
+static unsigned int
+_cogl_parse_debug_string (const char *value,
+                          gboolean ignore_help)
+{
+  unsigned int flags = 0;
+
+  if (ignore_help && strcmp (value, "help") == 0)
+    return 0;
+
+  /* We don't want to let g_parse_debug_string handle "all" because
+   * literally enabling all the debug options wouldn't be useful to
+   * anyone; instead the all option enables all non behavioural
+   * options.
+   */
+  if (strcmp (value, "all") == 0 ||
+      strcmp (value, "verbose") == 0)
+    {
+      int i;
+      for (i = 0; i < n_cogl_log_debug_keys; i++)
+        flags |= cogl_log_debug_keys[i].value;
+    }
+  else if (strcmp (value, "help") == 0)
+    {
+      g_printerr ("\n\n%28s\n", "Supported debug values:");
+#define OPT(NAME, HELP) \
+      g_printerr ("%28s %s\n", NAME, HELP);
+      OPT ("handle:", "debug ref counting issues for Cogl objects");
+      OPT ("slicing:", "debug the creation of texture slices");
+      OPT ("atlas:", "debug texture atlas management");
+      OPT ("blend-strings:", "debug blend-string parsing");
+      OPT ("journal:", "view all geometry passing through the journal");
+      OPT ("batching:", "show how geometry is being batched in the journal");
+      OPT ("matrices:", "trace all matrix manipulation");
+      /* XXX: we should replace the "draw" option its very hand wavy... */
+      OPT ("draw:", "misc tracing of some drawing operations");
+      OPT ("pango:", "trace the pango renderer");
+      OPT ("rectangles:", "add wire outlines for all rectangular geometry");
+      OPT ("disable-batching:", "disable the journal batching");
+      OPT ("disable-vbos:", "disable use of OpenGL vertex buffer objects");
+      OPT ("disable-software-transform",
+           "use the GPU to transform rectangular geometry");
+      OPT ("force-scanline-paths:", "use a scanline based path rasterizer");
+      OPT ("dump-atlas-image:", "dump atlas changes to an image file");
+      OPT ("disable-atlas:", "disable texture atlasing");
+      g_printerr ("\n%28s\n", "Special debug values:");
+      OPT ("all:", "Enables all non-behavioural debug options");
+      OPT ("verbose:", "Enables all non-behavioural debug options");
+#undef OPT
+      exit (1);
+    }
+  else
+    {
+      flags |=
+        g_parse_debug_string (value,
+                              cogl_log_debug_keys,
+                              n_cogl_log_debug_keys);
+      flags |=
+        g_parse_debug_string (value,
+                              cogl_behavioural_debug_keys,
+                              n_cogl_behavioural_debug_keys);
+    }
+
+  return flags;
+}
+
 static gboolean
 cogl_arg_debug_cb (const char *key,
                    const char *value,
                    gpointer    user_data)
 {
-  cogl_debug_flags |=
-    g_parse_debug_string (value,
-                          cogl_debug_keys,
-                          n_cogl_debug_keys);
+  cogl_debug_flags |= _cogl_parse_debug_string (value, FALSE);
   return TRUE;
 }
 
@@ -76,21 +149,16 @@ cogl_arg_no_debug_cb (const char *key,
                       const char *value,
                       gpointer    user_data)
 {
-  cogl_debug_flags &=
-    ~g_parse_debug_string (value,
-                           cogl_debug_keys,
-                           n_cogl_debug_keys);
+  cogl_debug_flags &= ~_cogl_parse_debug_string (value, TRUE);
   return TRUE;
 }
-#endif /* CLUTTER_ENABLE_DEBUG */
+#endif /* COGL_ENABLE_DEBUG */
 
 static GOptionEntry cogl_args[] = {
-#ifdef COGL_ENABLE_DEBUG
   { "cogl-debug", 0, 0, G_OPTION_ARG_CALLBACK, cogl_arg_debug_cb,
     N_("COGL debugging flags to set"), "FLAGS" },
   { "cogl-no-debug", 0, 0, G_OPTION_ARG_CALLBACK, cogl_arg_no_debug_cb,
     N_("COGL debugging flags to unset"), "FLAGS" },
-#endif /* COGL_ENABLE_DEBUG */
   { NULL, },
 };
 
@@ -106,10 +174,7 @@ pre_parse_hook (GOptionContext  *context,
   env_string = g_getenv ("COGL_DEBUG");
   if (env_string != NULL)
     {
-      cogl_debug_flags =
-        g_parse_debug_string (env_string,
-                              cogl_debug_keys,
-                              n_cogl_debug_keys);
+      cogl_debug_flags |= _cogl_parse_debug_string (env_string, FALSE);
       env_string = NULL;
     }
 #endif /* COGL_ENABLE_DEBUG */