Initial commit

engines/ags/shared/debugging/out.h

@@ -0,0 +1,173 @@
+/* ScummVM - Graphic Adventure Engine
+ *
+ * ScummVM is the legal property of its developers, whose names
+ * are too numerous to list here. Please refer to the COPYRIGHT
+ * file distributed with this source distribution.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+//=============================================================================
+//
+// Debug output interface provides functions which send a formatted message
+// tagged with group ID and message type to the registered output handlers.
+//
+// Depending on configuration this message may be printed by any of those
+// handlers, or none of them. The calling unit should not worry about where the
+// message goes.
+//
+//-----------------------------------------------------------------------------
+//
+// On using message types.
+//
+// Please keep in mind, that there are different levels of errors. AGS logging
+// system allows to classify debug message by two parameters: debug group and
+// message type. Sometimes message type alone is not enough. Debug groups can
+// also be used to distinct messages that has less (or higher) importance.
+//
+// For example, there are engine errors and user (game-dev) mistakes. Script
+// commands that cannot be executed under given circumstances are user
+// mistakes, and usually are not as severe as internal engine errors. This is
+// why it is advised to use a separate debug group for mistakes like that to
+// distinct them from reports on the internal engine's problems and make
+// verbosity configuration flexible.
+//
+// kDbgMsg_Debug - is the most mundane type of message (if the printing function
+// argument list does not specify message type, it is probably kDbgMsg_Debug).
+// You can use it for almost anything, from noting some process steps to
+// displaying current object state. If certain messages are meant to be printed
+// very often, consider using another distinct debug group so that it may be
+// disabled to reduce log verbosity.
+//
+// kDbgMsg_Info - is a type for important notifications, such as initialization
+// and stopping of engine components.
+//
+// kDbgMsg_Warn - this is suggested for more significant cases, when you find
+// out that something is not right, but is not immediately affecting engine
+// processing. For example: certain object was constructed in a way that
+// would make them behave unexpectedly, or certain common files are missing but
+// it is not clear yet whether the game will be accessing them.
+// In other words: use kDbgMsg_Warn when there is no problem right away, but
+// you are *anticipating* that one may happen under certain circumstances.
+//
+// kDbgMsg_Error - use this kind of message is for actual serious problems.
+// If certain operation assumes both positive and negative results are
+// acceptable, it is preferred to report such negative result with simple
+// kDbgMsg_Debug message. kDbgMsg_Error is for negative results that are not
+// considered acceptable for normal run.
+//
+// kDbgMsg_Fatal - is the message type to be reported when the program or
+// component abortion is imminent.
+//
+//=============================================================================
+
+#ifndef AGS_SHARED_CORE_DEBUGGING_OUT_H
+#define AGS_SHARED_CORE_DEBUGGING_OUT_H
+
+#include "ags/shared/util/string.h"
+
+namespace AGS3 {
+namespace AGS {
+namespace Shared {
+
+// Message types provide distinction for debug messages by their intent.
+enum MessageType {
+	kDbgMsg_None = 0,
+	// Alerts may be informative messages with topmost level of importance,
+	// such as reporting engine startup and shutdown.
+	kDbgMsg_Alert,
+	// Fatal errors are ones that make program abort immediately.
+	kDbgMsg_Fatal,
+	// Error messages are about engine not being able to perform requested
+	// operation in a situation when that will affect game playability and
+	// further execution.
+	kDbgMsg_Error,
+	// Warnings are made when unexpected or non-standart behavior
+	// is detected in program, which is not immediately critical,
+	// but may be a symptom of a bigger problem.
+	kDbgMsg_Warn,
+	// General information messages.
+	kDbgMsg_Info,
+	// Debug reason is for arbitrary information about events and current
+	// game state.
+	kDbgMsg_Debug,
+
+
+	// Convenient aliases
+	kDbgMsg_Default = kDbgMsg_Debug,
+	kDbgMsg_All = kDbgMsg_Debug
+};
+
+// This enumeration is a list of common hard-coded groups, but more could
+// be added via debugging configuration interface (see 'debug/debug.h').
+enum CommonDebugGroup : uint32 {
+	kDbgGroup_None = UINT32_MAX,
+	// Main debug group is for reporting general engine status and issues
+	kDbgGroup_Main = 0,
+	// Game group is for logging game logic state and issues
+	kDbgGroup_Game,
+	// Log from the game script
+	kDbgGroup_Script,
+	// Sprite cache logging
+	kDbgGroup_SprCache,
+	// Group for debugging managed object state (can slow engine down!)
+	kDbgGroup_ManObj
+};
+
+// Debug group identifier defining either numeric or string id, or both
+struct DebugGroupID {
+	uint32_t    ID;
+	String      SID;
+
+	DebugGroupID() : ID((uint32_t)kDbgGroup_None) {
+	}
+	DebugGroupID(uint32_t id, const String &sid = "") : ID(id), SID(sid) {
+	}
+	DebugGroupID(const String &sid) : ID((uint32_t)kDbgGroup_None), SID(sid) {
+	}
+	// Tells if any of the id components is valid
+	bool IsValid() const {
+		return ID != (uint32_t)kDbgGroup_None || !SID.IsEmpty();
+	}
+	// Tells if both id components are properly set
+	bool IsComplete() const {
+		return ID != (uint32_t)kDbgGroup_None && !SID.IsEmpty();
+	}
+};
+
+namespace Debug {
+//
+// Debug output
+//
+// Output a plain message of default group and default type
+void Printf(const String &text);
+// Output a plain message of default group and given type
+void Printf(MessageType mt, const String &text);
+// Output a plain message of given group and type
+void Printf(DebugGroupID group_id, MessageType mt, const String &text);
+// Output formatted message of default group and default type
+void Printf(const char *fmt, ...);
+// Output formatted message of default group and given type
+void Printf(MessageType mt, const char *fmt, ...);
+// Output formatted message of given group and type
+void Printf(DebugGroupID group_id, MessageType mt, const char *fmt, ...);
+
+} // namespace Debug
+
+} // namespace Shared
+} // namespace AGS
+} // namespace AGS3
+
+#endif