- Call the special debug channels "channels" consistently. (Formerly sometimes they were refered to as "levels").

- Along with it add some more descriptive commentary about what is the intention behind debug channels.

svn-id: r47727

2 files changed, 68 insertions, 52 deletions

diff --git a/common/debug.cpp b/common/debug.cpp
index f6dc065c88..ed18639124 100644
--- a/common/debug.cpp
+++ b/common/debug.cpp
@@ -48,16 +48,14 @@
 // TODO: Move gDebugLevel into namespace Common.
 int gDebugLevel = -1;
 
-
-
 namespace Common {
 
 namespace {
 
-typedef HashMap<String, DebugChannel, IgnoreCase_Hash, IgnoreCase_EqualTo> DebugLevelMap;
+typedef HashMap<String, DebugChannel, IgnoreCase_Hash, IgnoreCase_EqualTo> DebugChannelMap;
 
-static DebugLevelMap gDebugLevels;
-static uint32 gDebugLevelsEnabled = 0;
+static DebugChannelMap gDebugChannels;
+static uint32 gDebugChannelsEnabled = 0;
 
 struct DebugLevelComperator {
 	bool operator()(const DebugChannel &l, const DebugChannel &r) {
@@ -65,27 +63,27 @@ struct DebugLevelComperator {
 	}
 };
 
-}
+} // end of anonymous namespace
 
-bool addDebugChannel(uint32 level, const String &name, const String &description) {
-	if (gDebugLevels.contains(name)) {
-		warning("Duplicate declaration of engine debug level '%s'", name.c_str());
-	}
-	gDebugLevels[name] = DebugChannel(level, name, description);
+bool addDebugChannel(uint32 channel, const String &name, const String &description) {
+	if (gDebugChannels.contains(name))
+		warning("Duplicate declaration of engine debug channel '%s'", name.c_str());
+
+	gDebugChannels[name] = DebugChannel(channel, name, description);
 
 	return true;
 }
 
 void clearAllDebugChannels() {
-	gDebugLevelsEnabled = 0;
-	gDebugLevels.clear();
+	gDebugChannelsEnabled = 0;
+	gDebugChannels.clear();
 }
 
 bool enableDebugChannel(const String &name) {
-	DebugLevelMap::iterator i = gDebugLevels.find(name);
+	DebugChannelMap::iterator i = gDebugChannels.find(name);
 
-	if (i != gDebugLevels.end()) {
-		gDebugLevelsEnabled |= i->_value.level;
+	if (i != gDebugChannels.end()) {
+		gDebugChannelsEnabled |= i->_value.channel;
 		i->_value.enabled = true;
 
 		return true;
@@ -95,10 +93,10 @@ bool enableDebugChannel(const String &name) {
 }
 
 bool disableDebugChannel(const String &name) {
-	DebugLevelMap::iterator i = gDebugLevels.find(name);
+	DebugChannelMap::iterator i = gDebugChannels.find(name);
 
-	if (i != gDebugLevels.end()) {
-		gDebugLevelsEnabled &= ~i->_value.level;
+	if (i != gDebugChannels.end()) {
+		gDebugChannelsEnabled &= ~i->_value.channel;
 		i->_value.enabled = false;
 
 		return true;
@@ -110,19 +108,19 @@ bool disableDebugChannel(const String &name) {
 
 DebugChannelList listDebugChannels() {
 	DebugChannelList tmp;
-	for (DebugLevelMap::iterator i = gDebugLevels.begin(); i != gDebugLevels.end(); ++i)
+	for (DebugChannelMap::iterator i = gDebugChannels.begin(); i != gDebugChannels.end(); ++i)
 		tmp.push_back(i->_value);
 	sort(tmp.begin(), tmp.end(), DebugLevelComperator());
 
 	return tmp;
 }
 
-bool isDebugChannelEnabled(uint32 level) {
+bool isDebugChannelEnabled(uint32 channel) {
 	// Debug level 11 turns on all special debug level messages
 	if (gDebugLevel == 11)
 		return true;
-//	return gDebugLevelsEnabled & (1 << level);
-	return gDebugLevelsEnabled & level;
+	else
+		return (gDebugChannelsEnabled & channel) != 0;
 }
 
 bool isDebugChannelEnabled(const String &name) {
@@ -131,10 +129,11 @@ bool isDebugChannelEnabled(const String &name) {
 		return true;
 
 	// Search for the debug level with the given name and check if it is enabled
-	DebugLevelMap::iterator i = gDebugLevels.find(name);
-	if (i != gDebugLevels.end())
+	DebugChannelMap::iterator i = gDebugChannels.find(name);
+	if (i != gDebugChannels.end())
 		return i->_value.enabled;
-	return false;
+	else
+		return false;
 }
 
 
@@ -220,7 +219,7 @@ void debugC(int level, uint32 debugChannels, const char *s, ...) {
 
 	// Debug level 11 turns on all special debug level messages
 	if (gDebugLevel != 11)
-		if (level > gDebugLevel || !(Common::gDebugLevelsEnabled & debugChannels))
+		if (level > gDebugLevel || !(Common::gDebugChannelsEnabled & debugChannels))
 			return;
 
 	va_start(va, s);
@@ -233,7 +232,7 @@ void debugCN(int level, uint32 debugChannels, const char *s, ...) {
 
 	// Debug level 11 turns on all special debug level messages
 	if (gDebugLevel != 11)
-		if (level > gDebugLevel || !(Common::gDebugLevelsEnabled & debugChannels))
+		if (level > gDebugLevel || !(Common::gDebugChannelsEnabled & debugChannels))
 			return;
 
 	va_start(va, s);
@@ -246,7 +245,7 @@ void debugC(uint32 debugChannels, const char *s, ...) {
 
 	// Debug level 11 turns on all special debug level messages
 	if (gDebugLevel != 11)
-		if (!(Common::gDebugLevelsEnabled & debugChannels))
+		if (!(Common::gDebugChannelsEnabled & debugChannels))
 			return;
 
 	va_start(va, s);
@@ -259,7 +258,7 @@ void debugCN(uint32 debugChannels, const char *s, ...) {
 
 	// Debug level 11 turns on all special debug level messages
 	if (gDebugLevel != 11)
-		if (!(Common::gDebugLevelsEnabled & debugChannels))
+		if (!(Common::gDebugChannelsEnabled & debugChannels))
 			return;
 
 	va_start(va, s);
diff --git a/common/debug.h b/common/debug.h
index 488f0951d4..f4fbb9ff1e 100644
--- a/common/debug.h
+++ b/common/debug.h
@@ -35,42 +35,58 @@ namespace Common {
 
 
 struct DebugChannel {
-	DebugChannel() : level(0), enabled(false) {}
-	DebugChannel(uint32 l, const String &n, const String &d)
-		: name(n), description(d), level(l), enabled(false) {}
+	DebugChannel() : channel(0), enabled(false) {}
+	DebugChannel(uint32 c, const String &n, const String &d)
+		: name(n), description(d), channel(c), enabled(false) {}
 
 	String name;
 	String description;
 
-	uint32 level;
+	uint32 channel;
 	bool enabled;
 };
 
 /**
- * Adds a engine debug level.
- * @param level the level flag (should be OR-able i.e. first one should be 1 than 2,4,...)
+ * Adds a debug channel.
+ *
+ * A debug channel is considered roughly similar to what our debug levels described by
+ * gDebugLevel try to achieve:
+ *
+ *  Debug channels should only affect the display of additional debug output, based on
+ *  their state. That is if they are enabled, channel specific debug messages should
+ *  be shown. If they are disabled on the other hand, those messages will be hidden.
+ *
+ * @see gDebugLevel.
+ *
+ * Note that we have debug* functions which depend both on the debug level set and
+ * specific debug channels. Those functions will only show output, when *both* criteria
+ * are satisfied.
+ *
+ * @param channel the channel flag (should be OR-able i.e. first one should be 1 then 2, 4, etc.)
  * @param name the option name which is used in the debugger/on the command line to enable
- *               this special debug level (case will be ignored)
+ *             this special debug level (case will be ignored)
  * @param description the description which shows up in the debugger
  * @return true on success false on failure
  */
-bool addDebugChannel(uint32 level, const String &name, const String &description);
+bool addDebugChannel(uint32 channel, const String &name, const String &description);
 
 /**
- * Resets all engine debug levels.
+ * Resets all engine specific debug channels.
  */
 void clearAllDebugChannels();
 
 /**
- * Enables an engine debug level.
- * @param name the name of the debug level to enable
+ * Enables an debug channel.
+ *
+ * @param name the name of the debug channel to enable
  * @return true on success, false on failure
  */
 bool enableDebugChannel(const String &name);
 
 /**
- * Disables an engine debug level
- * @param name the name of the debug level to disable
+ * Disables an debug channel.
+ *
+ * @param name the name of the debug channel to disable
  * @return true on success, false on failure
  */
 bool disableDebugChannel(const String &name);
@@ -80,19 +96,20 @@ bool disableDebugChannel(const String &name);
 typedef List<DebugChannel> DebugChannelList;
 
 /**
- * Lists all debug levels
- * @return returns a arry with all debug levels
+ * Lists all engine specific debug channels.
+ *
+ * @return returns a arry with all debug channels
  */
 DebugChannelList listDebugChannels();
 
 
 /**
- * Test whether the given debug level is enabled.
+ * Test whether the given debug channel is enabled.
  */
-bool isDebugChannelEnabled(uint32 level);
+bool isDebugChannelEnabled(uint32 channel);
 
 /**
- * Test whether the given debug level is enabled.
+ * Test whether the given debug channel is enabled.
  */
 bool isDebugChannelEnabled(const String &name);
 
@@ -111,10 +128,10 @@ void setDebugOutputFormatter(OutputFormatter f);
 inline void debug(const char *s, ...) {}
 inline void debug(int level, const char *s, ...) {}
 inline void debugN(int level, const char *s, ...) {}
-inline void debugC(int level, uint32 engine_level, const char *s, ...) {}
-inline void debugC(uint32 engine_level, const char *s, ...) {}
-inline void debugCN(int level, uint32 engine_level, const char *s, ...) {}
-inline void debugCN(uint32 engine_level, const char *s, ...) {}
+inline void debugC(int level, uint32 engineChannel, const char *s, ...) {}
+inline void debugC(uint32 engineChannel, const char *s, ...) {}
+inline void debugCN(int level, uint32 engineChannel, const char *s, ...) {}
+inline void debugCN(uint32 engineChannel, const char *s, ...) {}
 
 
 #else