SDL 3.0
SDL_log.h File Reference
+ Include dependency graph for SDL_log.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef void(* SDL_LogOutputFunction) (void *userdata, int category, SDL_LogPriority priority, const char *message)
 

Enumerations

enum  SDL_LogCategory {
  SDL_LOG_CATEGORY_APPLICATION ,
  SDL_LOG_CATEGORY_ERROR ,
  SDL_LOG_CATEGORY_ASSERT ,
  SDL_LOG_CATEGORY_SYSTEM ,
  SDL_LOG_CATEGORY_AUDIO ,
  SDL_LOG_CATEGORY_VIDEO ,
  SDL_LOG_CATEGORY_RENDER ,
  SDL_LOG_CATEGORY_INPUT ,
  SDL_LOG_CATEGORY_TEST ,
  SDL_LOG_CATEGORY_GPU ,
  SDL_LOG_CATEGORY_RESERVED2 ,
  SDL_LOG_CATEGORY_RESERVED3 ,
  SDL_LOG_CATEGORY_RESERVED4 ,
  SDL_LOG_CATEGORY_RESERVED5 ,
  SDL_LOG_CATEGORY_RESERVED6 ,
  SDL_LOG_CATEGORY_RESERVED7 ,
  SDL_LOG_CATEGORY_RESERVED8 ,
  SDL_LOG_CATEGORY_RESERVED9 ,
  SDL_LOG_CATEGORY_RESERVED10 ,
  SDL_LOG_CATEGORY_CUSTOM
}
 
enum  SDL_LogPriority {
  SDL_LOG_PRIORITY_INVALID ,
  SDL_LOG_PRIORITY_TRACE ,
  SDL_LOG_PRIORITY_VERBOSE ,
  SDL_LOG_PRIORITY_DEBUG ,
  SDL_LOG_PRIORITY_INFO ,
  SDL_LOG_PRIORITY_WARN ,
  SDL_LOG_PRIORITY_ERROR ,
  SDL_LOG_PRIORITY_CRITICAL ,
  SDL_LOG_PRIORITY_COUNT
}
 

Functions

void SDL_SetLogPriorities (SDL_LogPriority priority)
 
void SDL_SetLogPriority (int category, SDL_LogPriority priority)
 
SDL_LogPriority SDL_GetLogPriority (int category)
 
void SDL_ResetLogPriorities (void)
 
SDL_bool SDL_SetLogPriorityPrefix (SDL_LogPriority priority, const char *prefix)
 
void SDL_Log (SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(1)
 
void SDL_LogTrace (int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
 
void SDL_LogVerbose (int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
 
void SDL_LogDebug (int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
 
void SDL_LogInfo (int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
 
void SDL_LogWarn (int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
 
void SDL_LogError (int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
 
void SDL_LogCritical (int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
 
void SDL_LogMessage (int category, SDL_LogPriority priority, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(3)
 
void SDL_LogMessageV (int category, SDL_LogPriority priority, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3)
 
void SDL_GetLogOutputFunction (SDL_LogOutputFunction *callback, void **userdata)
 
void SDL_SetLogOutputFunction (SDL_LogOutputFunction callback, void *userdata)
 

Typedef Documentation

◆ SDL_LogOutputFunction

typedef void(* SDL_LogOutputFunction) (void *userdata, int category, SDL_LogPriority priority, const char *message)

The prototype for the log output callback function.

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
userdatawhat was passed as userdata to SDL_SetLogOutputFunction().
categorythe category of the message.
prioritythe priority of the message.
messagethe message being output.
Since
This datatype is available since SDL 3.0.0.

Definition at line 474 of file SDL_log.h.

Enumeration Type Documentation

◆ SDL_LogCategory

CategoryLog

Simple log messages with priorities and categories. A message's SDL_LogPriority signifies how important the message is. A message's SDL_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 SDL_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 "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) The predefined log categories

By default the application and gpu categories are enabled at the INFO level, the assert category is enabled at the WARN level, test is enabled at the VERBOSE level and all other categories are enabled at the ERROR level.

Since
This enum is available since SDL 3.0.0.
Enumerator
SDL_LOG_CATEGORY_APPLICATION 
SDL_LOG_CATEGORY_ERROR 
SDL_LOG_CATEGORY_ASSERT 
SDL_LOG_CATEGORY_SYSTEM 
SDL_LOG_CATEGORY_AUDIO 
SDL_LOG_CATEGORY_VIDEO 
SDL_LOG_CATEGORY_RENDER 
SDL_LOG_CATEGORY_INPUT 
SDL_LOG_CATEGORY_TEST 
SDL_LOG_CATEGORY_GPU 
SDL_LOG_CATEGORY_RESERVED2 
SDL_LOG_CATEGORY_RESERVED3 
SDL_LOG_CATEGORY_RESERVED4 
SDL_LOG_CATEGORY_RESERVED5 
SDL_LOG_CATEGORY_RESERVED6 
SDL_LOG_CATEGORY_RESERVED7 
SDL_LOG_CATEGORY_RESERVED8 
SDL_LOG_CATEGORY_RESERVED9 
SDL_LOG_CATEGORY_RESERVED10 
SDL_LOG_CATEGORY_CUSTOM 

Definition at line 81 of file SDL_log.h.

82{
93
94 /* Reserved for future SDL library use */
104
105 /* Beyond this point is reserved for application use, e.g.
106 enum {
107 MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
108 MYAPP_CATEGORY_AWESOME2,
109 MYAPP_CATEGORY_AWESOME3,
110 ...
111 };
112 */
SDL_LogCategory
Definition SDL_log.h:82
@ SDL_LOG_CATEGORY_CUSTOM
Definition SDL_log.h:113
@ SDL_LOG_CATEGORY_GPU
Definition SDL_log.h:92
@ SDL_LOG_CATEGORY_RESERVED8
Definition SDL_log.h:101
@ SDL_LOG_CATEGORY_RESERVED6
Definition SDL_log.h:99
@ SDL_LOG_CATEGORY_ERROR
Definition SDL_log.h:84
@ SDL_LOG_CATEGORY_RENDER
Definition SDL_log.h:89
@ SDL_LOG_CATEGORY_RESERVED5
Definition SDL_log.h:98
@ SDL_LOG_CATEGORY_RESERVED3
Definition SDL_log.h:96
@ SDL_LOG_CATEGORY_INPUT
Definition SDL_log.h:90
@ SDL_LOG_CATEGORY_TEST
Definition SDL_log.h:91
@ SDL_LOG_CATEGORY_RESERVED9
Definition SDL_log.h:102
@ SDL_LOG_CATEGORY_SYSTEM
Definition SDL_log.h:86
@ SDL_LOG_CATEGORY_RESERVED10
Definition SDL_log.h:103
@ SDL_LOG_CATEGORY_RESERVED4
Definition SDL_log.h:97
@ SDL_LOG_CATEGORY_APPLICATION
Definition SDL_log.h:83
@ SDL_LOG_CATEGORY_AUDIO
Definition SDL_log.h:87
@ SDL_LOG_CATEGORY_RESERVED7
Definition SDL_log.h:100
@ SDL_LOG_CATEGORY_ASSERT
Definition SDL_log.h:85
@ SDL_LOG_CATEGORY_VIDEO
Definition SDL_log.h:88
@ SDL_LOG_CATEGORY_RESERVED2
Definition SDL_log.h:95

◆ SDL_LogPriority

The predefined log priorities

Since
This enum is available since SDL 3.0.0.
Enumerator
SDL_LOG_PRIORITY_INVALID 
SDL_LOG_PRIORITY_TRACE 
SDL_LOG_PRIORITY_VERBOSE 
SDL_LOG_PRIORITY_DEBUG 
SDL_LOG_PRIORITY_INFO 
SDL_LOG_PRIORITY_WARN 
SDL_LOG_PRIORITY_ERROR 
SDL_LOG_PRIORITY_CRITICAL 
SDL_LOG_PRIORITY_COUNT 

Definition at line 121 of file SDL_log.h.

122{
SDL_LogPriority
Definition SDL_log.h:122
@ SDL_LOG_PRIORITY_TRACE
Definition SDL_log.h:124
@ SDL_LOG_PRIORITY_INFO
Definition SDL_log.h:127
@ SDL_LOG_PRIORITY_COUNT
Definition SDL_log.h:131
@ SDL_LOG_PRIORITY_CRITICAL
Definition SDL_log.h:130
@ SDL_LOG_PRIORITY_VERBOSE
Definition SDL_log.h:125
@ SDL_LOG_PRIORITY_DEBUG
Definition SDL_log.h:126
@ SDL_LOG_PRIORITY_ERROR
Definition SDL_log.h:129
@ SDL_LOG_PRIORITY_INVALID
Definition SDL_log.h:123
@ SDL_LOG_PRIORITY_WARN
Definition SDL_log.h:128

Function Documentation

◆ SDL_GetLogOutputFunction()

void SDL_GetLogOutputFunction ( SDL_LogOutputFunction callback,
void **  userdata 
)
extern

Get the current log output function.

Parameters
callbackan SDL_LogOutputFunction filled in with the current log callback.
userdataa pointer filled in with the pointer that is passed to callback.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_SetLogOutputFunction

◆ SDL_GetLogPriority()

SDL_LogPriority SDL_GetLogPriority ( int  category)
extern

Get the priority of a particular log category.

Parameters
categorythe category to query.
Returns
the SDL_LogPriority for the requested category.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_SetLogPriority

◆ SDL_Log()

void SDL_Log ( SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.

Parameters
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_LogCritical
SDL_LogDebug
SDL_LogError
SDL_LogInfo
SDL_LogMessage
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogCritical()

void SDL_LogCritical ( int  category,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_PRIORITY_CRITICAL.

Parameters
categorythe category of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogDebug
SDL_LogError
SDL_LogInfo
SDL_LogMessage
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogDebug()

void SDL_LogDebug ( int  category,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_PRIORITY_DEBUG.

Parameters
categorythe category of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogError
SDL_LogInfo
SDL_LogMessage
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogError()

void SDL_LogError ( int  category,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_PRIORITY_ERROR.

Parameters
categorythe category of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogDebug
SDL_LogInfo
SDL_LogMessage
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogInfo()

void SDL_LogInfo ( int  category,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_PRIORITY_INFO.

Parameters
categorythe category of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogDebug
SDL_LogError
SDL_LogMessage
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogMessage()

void SDL_LogMessage ( int  category,
SDL_LogPriority  priority,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with the specified category and priority.

Parameters
categorythe category of the message.
prioritythe priority of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogDebug
SDL_LogError
SDL_LogInfo
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogMessageV()

void SDL_LogMessageV ( int  category,
SDL_LogPriority  priority,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
va_list  ap 
)
extern

Log a message with the specified category and priority.

Parameters
categorythe category of the message.
prioritythe priority of the message.
fmta printf() style message format string.
apa variable argument list.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogDebug
SDL_LogError
SDL_LogInfo
SDL_LogMessage
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogTrace()

void SDL_LogTrace ( int  category,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_PRIORITY_TRACE.

Parameters
categorythe category of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogDebug
SDL_LogError
SDL_LogInfo
SDL_LogMessage
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose
SDL_LogWarn

◆ SDL_LogVerbose()

void SDL_LogVerbose ( int  category,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_PRIORITY_VERBOSE.

Parameters
categorythe category of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogDebug
SDL_LogError
SDL_LogInfo
SDL_LogMessage
SDL_LogMessageV
SDL_LogWarn

◆ SDL_LogWarn()

void SDL_LogWarn ( int  category,
SDL_PRINTF_FORMAT_STRING const char *  fmt,
  ... 
)
extern

Log a message with SDL_LOG_PRIORITY_WARN.

Parameters
categorythe category of the message.
fmta printf() style message format string.
...additional parameters matching % tokens in the fmt string, if any.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_Log
SDL_LogCritical
SDL_LogDebug
SDL_LogError
SDL_LogInfo
SDL_LogMessage
SDL_LogMessageV
SDL_LogTrace
SDL_LogVerbose

◆ SDL_ResetLogPriorities()

void SDL_ResetLogPriorities ( void  )
extern

Reset all priorities to default.

This is called by SDL_Quit().

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_SetLogPriorities
SDL_SetLogPriority

◆ SDL_SetLogOutputFunction()

void SDL_SetLogOutputFunction ( SDL_LogOutputFunction  callback,
void *  userdata 
)
extern

Replace the default log output function with one of your own.

Parameters
callbackan SDL_LogOutputFunction to call instead of the default.
userdataa pointer that is passed to callback.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetLogOutputFunction

◆ SDL_SetLogPriorities()

void SDL_SetLogPriorities ( SDL_LogPriority  priority)
extern

Set the priority of all log categories.

Parameters
prioritythe SDL_LogPriority to assign.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_ResetLogPriorities
SDL_SetLogPriority

◆ SDL_SetLogPriority()

void SDL_SetLogPriority ( int  category,
SDL_LogPriority  priority 
)
extern

Set the priority of a particular log category.

Parameters
categorythe category to assign a priority to.
prioritythe SDL_LogPriority to assign.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetLogPriority
SDL_ResetLogPriorities
SDL_SetLogPriorities

◆ SDL_SetLogPriorityPrefix()

SDL_bool SDL_SetLogPriorityPrefix ( SDL_LogPriority  priority,
const char *  prefix 
)
extern

Set the text prepended to log messages of a given priority.

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

Parameters
prioritythe SDL_LogPriority to modify.
prefixthe prefix to use for that log priority, or NULL to use no prefix.
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_SetLogPriorities
SDL_SetLogPriority