UE4学习笔记:如何自定义日志类别及其相关的注意事项

本随笔介绍如何在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低。常用的详细状态有FatalErrorWarningLogAll。不同的详细状态等级都有特殊的作用和表现形式,其详细介绍已经在代码的注释里面有了讲解。

日志类别的定义

DEFINE_LOG_CATEGOR(CategoryName)
只需要在源文件里调用该宏并传入在头文件里声明好的CategoryName即可[2],这里的CategoryName必须和头文件里定义的一致。

使用方法

当我们在头文件声明好了日志类别,以及在源文件里定义了日志类别之后,就能像普通的日志那样去使用调用我们定义好了的日志类别:
UE_LOG(CategoryName, Verbosity, Format, __VA_ARGS__)
其中参数CategoryName需要传入的是我们自定义的日志类别,参数Verbosity则需要传入范围在我们定义的最大详细状态等级之内(包含)任意一个详细状态。这里就体现出了为什么我们在声明日志类别的时候,其参数CompileTimeVerbosity代表的是最大详细状态等级,例如我们在声明的时候声明了Warning等级的详细状态,那么我们在打印日志的时候可以选用的Verbosity就为NoLoggingFatalErrorWarning如果在打印日志的时候传入的详细状态等级大于我们声明的最大详细状态等级,那么将不会打印任何日志
参数Format和参数__VA_ARGS__的使用方法并不在此随笔讲述范围内,故不过多介绍。

声明日志类别时参数DefaultVerbosity的作用

UE4允许在编辑器内或者游戏运行时的控制台来启用或者关闭指定类别的日志,来确定是否要记录该类型的日志,使用方法为STAT命令:
Log CategoryName
其中CategoryName即为我们定义或者是由系统定义好的日志类别。每次使用该命令之后即会切换该日志类别的开关状态,每次项目启动之后该类别的日志默认都是开启状态,除非在声明日志类别的时候给参数DefaultVerbosit传入了NoLogging的值。所谓切换开关状态就是在详细状态NoLoggingCompileTimeVerbosity状态之间切换。这里隐藏了一个会影响实际输出的情况:如果声明时DefaultVerbosity等级大于CompileTimeVerbosity,默认状态下打印将会按照声明时CompileTimeVerbosity指定的详细状态等级来打印。


  1. 随笔作者并不确定这种类型的变量该怎样去描述,很像是枚举类型的变量但是并不确定,故用关键字变量来代替这种变量的类型,如果有读者知道这种变量的正确描述形式,欢迎在评论区或者私信告知随笔作者。 ↩︎

  2. 这里源文件必须包含声明了该日志类别的头文件。 ↩︎

上一篇:UE4、MySQL预处理插入语句


下一篇:用python创建editor蓝图widget