174 lines
6.7 KiB
C++
174 lines
6.7 KiB
C++
/* 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
|