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.

clutter/cogl/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 },
+/* XXX: If you add a debug option, please also scroll down to
-  { "texture", COGL_DEBUG_TEXTURE },
+ * cogl_arg_debug_cb() and add a "help" description of the option too.
-  { "material", COGL_DEBUG_MATERIAL },
+ */
-  { "shader", COGL_DEBUG_SHADER },
+
-  { "offscreen", COGL_DEBUG_OFFSCREEN },
+/* NB: Only these options get enabled if COGL_DEBUG=all is
-  { "draw", COGL_DEBUG_DRAW },
+ * used since they don't affect the behaviour of Cogl they
-  { "pango", COGL_DEBUG_PANGO },
+ * simply print out verbose information */
-  { "rectangles", COGL_DEBUG_RECTANGLES },
+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 },
-  { "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 },
+  { "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 },
+  { "disable-batching", COGL_DEBUG_DISABLE_BATCHING },
+  { "disable-vbos", COGL_DEBUG_DISABLE_VBOS },
+  { "disable-software-transform", COGL_DEBUG_DISABLE_SOFTWARE_TRANSFORM },
   { "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 |=
+  cogl_debug_flags |= _cogl_parse_debug_string (value, FALSE);
-    g_parse_debug_string (value,
-                          cogl_debug_keys,
-                          n_cogl_debug_keys);
   return TRUE;
 }
 
@@ -76,21 +149,16 @@ cogl_arg_no_debug_cb (const char *key,
                       const char *value,
                       gpointer    user_data)
 {
-  cogl_debug_flags &=
+  cogl_debug_flags &= ~_cogl_parse_debug_string (value, TRUE);
-    ~g_parse_debug_string (value,
-                           cogl_debug_keys,
-                           n_cogl_debug_keys);
   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 =
+      cogl_debug_flags |= _cogl_parse_debug_string (env_string, FALSE);
-        g_parse_debug_string (env_string,
-                              cogl_debug_keys,
-                              n_cogl_debug_keys);
       env_string = NULL;
     }
 #endif /* COGL_ENABLE_DEBUG */

clutter/cogl/cogl/cogl-debug.h

@@ -29,26 +29,23 @@
 G_BEGIN_DECLS
 
 typedef enum {
-  COGL_DEBUG_MISC             = 1 << 0,
+  COGL_DEBUG_SLICING          = 1 << 1,
-  COGL_DEBUG_TEXTURE          = 1 << 1,
+  COGL_DEBUG_OFFSCREEN        = 1 << 2,
-  COGL_DEBUG_MATERIAL         = 1 << 2,
+  COGL_DEBUG_DRAW             = 1 << 3,
-  COGL_DEBUG_SHADER           = 1 << 3,
+  COGL_DEBUG_PANGO            = 1 << 4,
-  COGL_DEBUG_OFFSCREEN        = 1 << 4,
+  COGL_DEBUG_RECTANGLES       = 1 << 5,
-  COGL_DEBUG_DRAW             = 1 << 5,
+  COGL_DEBUG_HANDLE           = 1 << 6,
-  COGL_DEBUG_PANGO            = 1 << 6,
+  COGL_DEBUG_BLEND_STRINGS    = 1 << 7,
-  COGL_DEBUG_RECTANGLES       = 1 << 7,
+  COGL_DEBUG_DISABLE_BATCHING = 1 << 8,
-  COGL_DEBUG_HANDLE           = 1 << 8,
+  COGL_DEBUG_DISABLE_VBOS     = 1 << 9,
-  COGL_DEBUG_BLEND_STRINGS    = 1 << 9,
+  COGL_DEBUG_JOURNAL          = 1 << 10,
-  COGL_DEBUG_DISABLE_BATCHING = 1 << 10,
+  COGL_DEBUG_BATCHING         = 1 << 11,
-  COGL_DEBUG_DISABLE_VBOS     = 1 << 11,
+  COGL_DEBUG_DISABLE_SOFTWARE_TRANSFORM = 1 << 12,
-  COGL_DEBUG_JOURNAL          = 1 << 12,
+  COGL_DEBUG_MATRICES         = 1 << 13,
-  COGL_DEBUG_BATCHING         = 1 << 13,
+  COGL_DEBUG_FORCE_SCANLINE_PATHS = 1 << 14,
-  COGL_DEBUG_DISABLE_SOFTWARE_TRANSFORM = 1 << 14,
+  COGL_DEBUG_ATLAS            = 1 << 15,
-  COGL_DEBUG_MATRICES         = 1 << 15,
+  COGL_DEBUG_DUMP_ATLAS_IMAGE = 1 << 16,
-  COGL_DEBUG_FORCE_SCANLINE_PATHS = 1 << 16,
+  COGL_DEBUG_DISABLE_ATLAS    = 1 << 17
-  COGL_DEBUG_ATLAS            = 1 << 17,
-  COGL_DEBUG_DUMP_ATLAS_IMAGE = 1 << 18,
-  COGL_DEBUG_DISABLE_ATLAS    = 1 << 19
 } CoglDebugFlags;
 
 #ifdef COGL_ENABLE_DEBUG

clutter/cogl/cogl/cogl-texture-2d-sliced.c

@@ -841,7 +841,7 @@ _cogl_texture_2d_sliced_slices_create (CoglTexture2DSliced *tex_2ds,
         {
           x_span = &g_array_index (tex_2ds->slice_x_spans, CoglSpan, x);
 
-          COGL_NOTE (TEXTURE, "CREATE SLICE (%d,%d)\tsize (%d,%d)",
+          COGL_NOTE (SLICING, "CREATE SLICE (%d,%d)\tsize (%d,%d)",
                      x, y,
                      x_span->size - x_span->waste,
                      y_span->size - y_span->waste);