Simple log messages with priorities and categories. More...

Classes
class	SDL::LogCategory
	The predefined log categories. More...

Typedefs
using	SDL::LogOutputFunction = SDL_LogOutputFunction
	The prototype for the log output callback function.

using	SDL::LogOutputCB = std::function< void(LogCategory, LogPriority, const char *)>
	The prototype for the log output callback function.

Functions
void	SDL::SetLogPriorityPrefix (LogPriority priority, StringParam prefix)
	Set the text prepended to log messages of a given priority.

template<class... ARGS>
void	SDL::Log (std::string_view fmt, ARGS &&... args)
	Log a message with LOG_CATEGORY_APPLICATION and LOG_PRIORITY_INFO.

void	SDL::LogUnformatted (StringParam message)
	Log an unformatted message with LOG_CATEGORY_APPLICATION and LOG_PRIORITY_INFO.

LogOutputFunction	SDL::GetDefaultLogOutputFunction ()
	Get the default log output function.

void	SDL::GetLogOutputFunction (LogOutputFunction callback, void *userdata)
	Get the current log output function.

LogOutputCB	SDL::GetLogOutputFunction ()
	Get the current log output function.

void	SDL::SetLogOutputFunction (LogOutputFunction callback, void *userdata)
	Replace the default log output function with one of your own.

void	SDL::SetLogOutputFunction (LogOutputCB callback)
	Replace the default log output function with one of your own.

void	SDL::ResetLogOutputFunction ()
	Replace the current log output function with the default one.

LogPriorities
The priorities assignable for a LogCategory.
using	SDL::LogPriority = SDL_LogPriority
	The predefined log priorities.

constexpr LogPriority	SDL::LOG_PRIORITY_INVALID
	INVALID.

constexpr LogPriority	SDL::LOG_PRIORITY_TRACE = SDL_LOG_PRIORITY_TRACE
	TRACE.

constexpr LogPriority	SDL::LOG_PRIORITY_VERBOSE
	VERBOSE.

constexpr LogPriority	SDL::LOG_PRIORITY_DEBUG = SDL_LOG_PRIORITY_DEBUG
	DEBUG.

constexpr LogPriority	SDL::LOG_PRIORITY_INFO = SDL_LOG_PRIORITY_INFO
	INFO.

constexpr LogPriority	SDL::LOG_PRIORITY_WARN = SDL_LOG_PRIORITY_WARN
	WARN.

constexpr LogPriority	SDL::LOG_PRIORITY_ERROR = SDL_LOG_PRIORITY_ERROR
	ERROR.

constexpr LogPriority	SDL::LOG_PRIORITY_CRITICAL
	CRITICAL.

constexpr LogPriority	SDL::LOG_PRIORITY_COUNT = SDL_LOG_PRIORITY_COUNT
	COUNT.

LogCategories
The logging categories. see LogCategory for more info
constexpr LogCategory	SDL::LOG_CATEGORY_APPLICATION
	APPLICATION.

constexpr LogCategory	SDL::LOG_CATEGORY_ERROR = SDL_LOG_CATEGORY_ERROR
	ERROR.

constexpr LogCategory	SDL::LOG_CATEGORY_ASSERT = SDL_LOG_CATEGORY_ASSERT
	ASSERT.

constexpr LogCategory	SDL::LOG_CATEGORY_SYSTEM = SDL_LOG_CATEGORY_SYSTEM
	SYSTEM.

constexpr LogCategory	SDL::LOG_CATEGORY_AUDIO = SDL_LOG_CATEGORY_AUDIO
	AUDIO.

constexpr LogCategory	SDL::LOG_CATEGORY_VIDEO = SDL_LOG_CATEGORY_VIDEO
	VIDEO.

constexpr LogCategory	SDL::LOG_CATEGORY_RENDER = SDL_LOG_CATEGORY_RENDER
	RENDER.

constexpr LogCategory	SDL::LOG_CATEGORY_INPUT = SDL_LOG_CATEGORY_INPUT
	INPUT.

constexpr LogCategory	SDL::LOG_CATEGORY_TEST = SDL_LOG_CATEGORY_TEST
	TEST.

constexpr LogCategory	SDL::LOG_CATEGORY_GPU = SDL_LOG_CATEGORY_GPU
	GPU.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED2
	RESERVED2.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED3
	RESERVED3.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED4
	RESERVED4.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED5
	RESERVED5.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED6
	RESERVED6.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED7
	RESERVED7.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED8
	RESERVED8.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED9
	RESERVED9.

constexpr LogCategory	SDL::LOG_CATEGORY_RESERVED10
	RESERVED10.

constexpr LogCategory	SDL::LOG_CATEGORY_CUSTOM = SDL_LOG_CATEGORY_CUSTOM
	CUSTOM.

Detailed Description

A message's LogPriority signifies how important the message is. A message's LogCategory signifies from what domain it belongs to. Every category has a minimum priority specified: when a message belongs to that category, it will only be sent out if it has that minimum priority or higher.

SDL's own logs are sent below the default priority threshold, so they are quiet by default.

You can change the log verbosity programmatically using LogCategory.SetLogPriority() or with SDL_SetHint(SDL_HINT_LOGGING, ...), or with the "SDL_LOGGING" environment variable. This variable is a comma separated set of category=level tokens that define the default logging levels for SDL applications.

The category can be a numeric category, one of "app", "error", "assert", "system", "audio", "video", "render", "input", "test", or * for any unspecified category.

The level can be a numeric level, one of "trace", "verbose", "debug", "info", "warn", "error", "critical", or "quiet" to disable that category.

You can omit the category if you want to set the logging level for all categories.

If this hint isn't set, the default log levels are equivalent to:

app=info,assert=warn,test=verbose,*=error

Here's where the messages go on different platforms:

Windows: debug output stream
Android: log output
Others: standard error output (stderr)

You don't need to have a newline (@n) on the end of messages, the functions will do that for you. For consistent behavior cross-platform, you shouldn't have any newlines in messages, such as to log multiple lines in one call; unusual platform-specific behavior can be observed in such usage. Do one log call per line instead, with no newlines in messages.

Each log call is atomic, so you won't see log messages cut off one another when logging from multiple threads.

Typedef Documentation

◆ LogOutputCB

using SDL::LogOutputCB = typedef std::function<void(LogCategory, LogPriority, const char*)>

This function is called by SDL when there is new text to be logged. A mutex is held so that this function is never called by more than one thread at once.

Parameters

category	the category of the message.
priority	the priority of the message.
message	the message being output.

Since: This datatype is available since SDL 3.2.0.

Category:: Listener callback

See also: LogOutputFunction

◆ LogOutputFunction

using SDL::LogOutputFunction = typedef SDL_LogOutputFunction

This function is called by SDL when there is new text to be logged. A mutex is held so that this function is never called by more than one thread at once.

Parameters

userdata	what was passed as `userdata` to SetLogOutputFunction().
category	the category of the message.
priority	the priority of the message.
message	the message being output.

Since: This datatype is available since SDL 3.2.0.

◆ LogPriority

using SDL::LogPriority = typedef SDL_LogPriority

Since: This enum is available since SDL 3.2.0.

Function Documentation

◆ GetDefaultLogOutputFunction()

LogOutputFunction SDL::GetDefaultLogOutputFunction ( )

inline

Returns: the default log output callback.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetLogOutputFunction(); GetLogOutputFunction()

◆ GetLogOutputFunction() [1/2]

LogOutputCB SDL::GetLogOutputFunction ( )

inline

Returns: the LogOutputCB currently set

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; GetDefaultLogOutputFunction(); SetLogOutputFunction()

◆ GetLogOutputFunction() [2/2]

void SDL::GetLogOutputFunction	(	LogOutputFunction *	callback,
		void **	userdata
	)

inline

Parameters

callback	an LogOutputFunction filled in with the current log callback.
userdata	a pointer filled in with the pointer that is passed to `callback`.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetDefaultLogOutputFunction(); SetLogOutputFunction()

◆ Log()

template<class... ARGS>

void SDL::Log	(	std::string_view	fmt,
		ARGS &&...	args
	)

inline

Parameters

fmt	a std::format/fmt style message format string.
args	additional parameters matching the `{}` tokens in the format string, if any.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Formatted string

See also: formatted-string; LogUnformatted(); LogCategory.LogCritical(); LogCategory.LogDebug(); LogCategory.LogError(); LogCategory.LogInfo(); LogCategory.Log(); LogCategory.LogUnformatted(); LogCategory.LogTrace(); LogCategory.LogVerbose(); LogCategory.LogWarn()

◆ LogUnformatted()

void SDL::LogUnformatted ( StringParam message )

inline

Parameters

message string to output.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Log(); LogCategory.LogCritical(); LogCategory.LogDebug(); LogCategory.LogError(); LogCategory.LogInfo(); LogCategory.Log(); LogCategory.LogUnformatted(); LogCategory.LogTrace(); LogCategory.LogVerbose(); LogCategory.LogWarn()

◆ ResetLogOutputFunction()

void SDL::ResetLogOutputFunction ( )

inline

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetDefaultLogOutputFunction(); GetLogOutputFunction()

◆ SetLogOutputFunction() [1/2]

void SDL::SetLogOutputFunction ( LogOutputCB callback )

inline

Parameters

callback an LogOutputFunction to call instead of the default.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; GetDefaultLogOutputFunction(); GetLogOutputFunction(); ResetLogOutputFunction()

◆ SetLogOutputFunction() [2/2]

void SDL::SetLogOutputFunction	(	LogOutputFunction	callback,
		void *	userdata
	)

inline

Parameters

callback	an LogOutputFunction to call instead of the default.
userdata	a pointer that is passed to `callback`.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetDefaultLogOutputFunction(); GetLogOutputFunction(); ResetLogOutputFunction()

◆ SetLogPriorityPrefix()

void SDL::SetLogPriorityPrefix	(	LogPriority	priority,
		StringParam	prefix
	)

inline

By default LOG_PRIORITY_INFO and below have no prefix, and LOG_PRIORITY_WARN and higher have a prefix showing their priority, e.g. "WARNING: ".

Parameters

priority	the LogPriority to modify.
prefix	the prefix to use for that log priority, or nullptr to use no prefix.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: LogCategory.SetLogPriorities; LogCategory.SetLogPriority

SDL_LOG_PRIORITY_VERBOSE

Classes

Typedefs

Functions

LogPriorities

LogCategories

Detailed Description

Typedef Documentation

◆ LogOutputCB

◆ LogOutputFunction

◆ LogPriority

Function Documentation

◆ GetDefaultLogOutputFunction()

◆ GetLogOutputFunction() [1/2]

◆ GetLogOutputFunction() [2/2]

◆ Log()

◆ LogUnformatted()

◆ ResetLogOutputFunction()

◆ SetLogOutputFunction() [1/2]

◆ SetLogOutputFunction() [2/2]

◆ SetLogPriorityPrefix()

Variable Documentation

◆ LOG_CATEGORY_APPLICATION

◆ LOG_CATEGORY_RESERVED10

◆ LOG_CATEGORY_RESERVED2

◆ LOG_CATEGORY_RESERVED3

◆ LOG_CATEGORY_RESERVED4

◆ LOG_CATEGORY_RESERVED5

◆ LOG_CATEGORY_RESERVED6

◆ LOG_CATEGORY_RESERVED7

◆ LOG_CATEGORY_RESERVED8

◆ LOG_CATEGORY_RESERVED9

◆ LOG_PRIORITY_CRITICAL

◆ LOG_PRIORITY_INVALID

◆ LOG_PRIORITY_VERBOSE