本随笔介绍如何在UE4 C++项目里自定义日志类别的方法,以及介绍了在自定义过程中会遇到的一些问题的解答。
作者还在学习阶段,并且对UE4引擎的使用和理解还不是非常透彻,难免会在随笔内容里出现技术上或书写上的问题,如果出现了类似的问题欢迎在评论区或者私信讨论。
日志类别的声明
DECLARE_LOG_CATEGORY_EXTERN(CategoryName, DefaultVerbosity, CompileTimeVerbosity)
日志类别的声明是由上述宏来实现的,该宏需要三个参数:CategoryName
代表着这个类别的名字,该名字是一个关键字类型的变量[1],并不是一个字符串类型的变量,该名字并不需要按照特别格式来书写。DefaultVerbosity
代表着该类别的日志默认启用的详细状态(Veribosity)等级,CompileTimeVerbosity
代表着该类别的日志编译时候支持的最大详细状态等级。该宏只需要在头文件上调用即可。关于详细状态的定义可以通过查看源码了解到分为如下几个等级:
/**
* Enum that defines the verbosity levels of the logging system.
* Also defines some non-verbosity levels that are hacks that allow
* breaking on a given log line or setting the color.
**/
namespace ELogVerbosity
{
enum Type : uint8
{
/** Not used */
NoLogging = 0,
/** Always prints a fatal error to console (and log file) and crashes (even if logging is disabled) */
Fatal,
/**
* Prints an error to console (and log file).
* Commandlets and the editor collect and report errors. Error messages result in commandlet failure.
*/
Error,
/**
* Prints a warning to console (and log file).
* Commandlets and the editor collect and report warnings. Warnings can be treated as an error.
*/
Warning,
/** Prints a message to console (and log file) */
Display,
/** Prints a message to a log file (does not print to console) */
Log,
/**
* Prints a verbose message to a log file (if Verbose logging is enabled for the given category,
* usually used for detailed logging)
*/
Verbose,
/**
* Prints a verbose message to a log file (if VeryVerbose logging is enabled,
* usually used for detailed logging that would otherwise spam output)
*/
VeryVerbose,
// Log masks and special Enum values
All = VeryVerbose,
NumVerbosity,
VerbosityMask = 0xf,
SetColor = 0x40, // not actually a verbosity, used to set the color of an output device
BreakOnLog = 0x80
};
}
位置越往下的详细状态等级越高,例如等级Error
比等级Fatal
高,但是又比等级Log
低。常用的详细状态有Fatal
、Error
、Warning
、Log
和All
。不同的详细状态等级都有特殊的作用和表现形式,其详细介绍已经在代码的注释里面有了讲解。
日志类别的定义
DEFINE_LOG_CATEGOR(CategoryName)
只需要在源文件里调用该宏并传入在头文件里声明好的CategoryName
即可[2],这里的CategoryName
必须和头文件里定义的一致。
使用方法
当我们在头文件声明好了日志类别,以及在源文件里定义了日志类别之后,就能像普通的日志那样去使用调用我们定义好了的日志类别:UE_LOG(CategoryName, Verbosity, Format, __VA_ARGS__)
其中参数CategoryName
需要传入的是我们自定义的日志类别,参数Verbosity
则需要传入范围在我们定义的最大详细状态等级之内(包含)任意一个详细状态。这里就体现出了为什么我们在声明日志类别的时候,其参数CompileTimeVerbosity
代表的是最大详细状态等级,例如我们在声明的时候声明了Warning
等级的详细状态,那么我们在打印日志的时候可以选用的Verbosity
就为NoLogging
、Fatal
、Error
和Warning
,如果在打印日志的时候传入的详细状态等级大于我们声明的最大详细状态等级,那么将不会打印任何日志。
参数Format
和参数__VA_ARGS__
的使用方法并不在此随笔讲述范围内,故不过多介绍。
声明日志类别时参数DefaultVerbosity
的作用
UE4允许在编辑器内或者游戏运行时的控制台来启用或者关闭指定类别的日志,来确定是否要记录该类型的日志,使用方法为STAT命令:Log CategoryName
其中CategoryName
即为我们定义或者是由系统定义好的日志类别。每次使用该命令之后即会切换该日志类别的开关状态,每次项目启动之后该类别的日志默认都是开启状态,除非在声明日志类别的时候给参数DefaultVerbosit
传入了NoLogging
的值。所谓切换开关状态就是在详细状态NoLogging
和CompileTimeVerbosity
状态之间切换。这里隐藏了一个会影响实际输出的情况:如果声明时DefaultVerbosity
等级大于CompileTimeVerbosity
,默认状态下打印将会按照声明时CompileTimeVerbosity
指定的详细状态等级来打印。