1 //============================================================================= 2 // 3 // Adventure Game Studio (AGS) 4 // 5 // Copyright (C) 1999-2011 Chris Jones and 2011-20xx others 6 // The full list of copyright holders can be found in the Copyright.txt 7 // file, which is part of this source code distribution. 8 // 9 // The AGS source code is provided under the Artistic License 2.0. 10 // A copy of this license can be found in the file License.txt and at 11 // http://www.opensource.org/licenses/artistic-license-2.0.php 12 // 13 //============================================================================= 14 // 15 // Debug output interface provides functions which send a formatted message 16 // tagged with group ID and message type to the registered output handlers. 17 // 18 // Depending on configuration this message may be printed by any of those 19 // handlers, or none of them. The calling unit should not worry about where the 20 // message goes. 21 // 22 //----------------------------------------------------------------------------- 23 // 24 // On using message types. 25 // 26 // Please keep in mind, that there are different levels of errors. AGS logging 27 // system allows to classify debug message by two parameters: debug group and 28 // message type. Sometimes message type alone is not enough. Debug groups can 29 // also be used to distinct messages that has less (or higher) importance. 30 // 31 // For example, there are engine errors and user (game-dev) mistakes. Script 32 // commands that cannot be executed under given circumstances are user 33 // mistakes, and usually are not as severe as internal engine errors. This is 34 // why it is advised to use a separate debug group for mistakes like that to 35 // distinct them from reports on the internal engine's problems and make 36 // verbosity configuration flexible. 37 // 38 // kDbgMsg_Init - is a type for startup initialization notifications; use them 39 // when declaring that certain component got initialized (or not initialized), 40 // optionally noting working mode, where applicable. Such messages are intended 41 // for core engine components and plugin startup only, not work modes and game 42 // states that are normally changing during gameplay. 43 // 44 // kDbgMsg_Debug - is the most common type of message (if the printing function 45 // argument list does not specify message type, it is probably kDbgMsg_Debug). 46 // You can use it for almost anything, from noting some process steps to 47 // displaying current object state. If certain messages are meant to be printed 48 // very often, consider using another distinct debug group so that it may be 49 // disabled to reduce log verbosity. 50 // 51 // kDbgMsg_Warn - this is suggested for more significant cases, when you find 52 // out that something is not right, but is not immediately affecting engine 53 // processing. For example: certain object was constructed in a way that 54 // would make them behave unexpectedly, or certain common files are missing but 55 // it is not clear yet whether the game will be accessing them. 56 // In other words: use kDbgMsg_Warn when there is no problem right away, but 57 // you are *anticipating* that one may happen under certain circumstances. 58 // 59 // kDbgMsg_Error - use this kind of message is for actual serious problems. 60 // If certain operation assumes both positive and negative results are 61 // acceptable, it is preferred to report such negative result with simple 62 // kDbgMsg_Debug message. kDbgMsg_Error is for negative results that are not 63 // considered acceptable for normal run. 64 // 65 // kDbgMsg_Fatal - is the message type to be reported when the program or 66 // component abortion is imminent. 67 // 68 //============================================================================= 69 #ifndef __AGS_CN_DEBUG__OUT_H 70 #define __AGS_CN_DEBUG__OUT_H 71 72 #include "util/string.h" 73 74 namespace AGS 75 { 76 namespace Common 77 { 78 79 // Message types provide distinction for debug messages by their intent. 80 enum MessageType 81 { 82 kDbgMsg_None = 0, 83 // Initialization messages, notify about certain engine components 84 // being created and important modes initialized. 85 kDbgMsg_Init = 0x0001, 86 // Debug reason is for arbitrary information about events and current 87 // game state 88 kDbgMsg_Debug = 0x0002, 89 // Warnings are made when unexpected or non-standart behavior 90 // is detected in program, which is not immediately critical, 91 // but may be a symptom of a bigger problem. 92 kDbgMsg_Warn = 0x0004, 93 // Error messages are about engine not being able to perform requested 94 // operation in a situation when that will affect game playability and 95 // further execution. 96 kDbgMsg_Error = 0x0008, 97 // Fatal errors are ones that make program abort immediately 98 kDbgMsg_Fatal = 0x0010, 99 100 // Convenient aliases 101 kDbgMsg_Default = kDbgMsg_Debug, 102 kDbgMsgSet_NoDebug = 0x001D, 103 kDbgMsgSet_Errors = 0x0019, 104 // Output everything 105 kDbgMsgSet_All = 0xFFFF 106 }; 107 108 // This enumeration is a list of common hard-coded groups, but more could 109 // be added via debugging configuration interface (see 'debug/debug.h'). 110 enum CommonDebugGroup 111 { 112 kDbgGroup_None = -1, 113 // Main debug group is for reporting general engine status and issues 114 kDbgGroup_Main = 0, 115 // Sprite cache logging 116 kDbgGroup_SprCache, 117 // Script group is for reporting script (commands) execution 118 kDbgGroup_Script, 119 // Group for debugging managed object state (can slow engine down!) 120 kDbgGroup_ManObj 121 }; 122 123 // Debug group identifier defining either numeric or string id, or both 124 struct DebugGroupID 125 { 126 uint32_t ID; 127 String SID; 128 DebugGroupIDDebugGroupID129 DebugGroupID() : ID(kDbgGroup_None) {} IDDebugGroupID130 DebugGroupID(uint32_t id, const String &sid = "") : ID(id), SID(sid) {} DebugGroupIDDebugGroupID131 DebugGroupID(const String &sid) : ID(kDbgGroup_None), SID(sid) {} 132 // Tells if any of the id components is valid IsValidDebugGroupID133 bool IsValid() const { return ID != kDbgGroup_None || !SID.IsEmpty(); } 134 // Tells if both id components are properly set IsCompleteDebugGroupID135 bool IsComplete() const { return ID != kDbgGroup_None && !SID.IsEmpty(); } 136 }; 137 138 struct DebugMessage 139 { 140 String Text; 141 uint32_t GroupID; 142 String GroupName; 143 MessageType MT; 144 DebugMessageDebugMessage145 DebugMessage() : GroupID(kDbgGroup_None), MT(kDbgMsg_None) {} DebugMessageDebugMessage146 DebugMessage(const String &text, uint32_t group_id, const String &group_name, MessageType mt) 147 : Text(text) 148 , GroupID(group_id) 149 , GroupName(group_name) 150 , MT(mt) 151 {} 152 }; 153 154 namespace Debug 155 { 156 // 157 // Debug output 158 // 159 // Output formatted message of default group and default type 160 void Printf(const char *fmt, ...); 161 // Output formatted message of default group and given type 162 void Printf(MessageType mt, const char *fmt, ...); 163 // Output formatted message of given group and type 164 void Printf(DebugGroupID group_id, MessageType mt, const char *fmt, ...); 165 166 } // namespace Debug 167 168 } // namespace Common 169 } // namespace AGS 170 171 #endif // __AGS_CN_DEBUG__OUT_H 172