SDL 3.0
SDL_log.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryLog
24 *
25 * Simple log messages with priorities and categories. A message’s
26 * SDL_LogPriority signifies how important the message is. A message's
27 * SDL_LogCategory signifies from what domain it belongs to. Every category
28 * has a minimum priority specified: when a message belongs to that category,
29 * it will only be sent out if it has that minimum priority or higher.
30 *
31 * SDL's own logs are sent below the default priority threshold, so they are
32 * quiet by default.
33 *
34 * You can change the log verbosity programmatically using
35 * SDL_SetLogPriority() or with SDL_SetHint(SDL_HINT_LOGGING, ...), or with
36 * the "SDL_LOGGING" environment variable. This variable is a comma separated
37 * set of category=level tokens that define the default logging levels for SDL
38 * applications.
39 *
40 * The category can be a numeric category, one of "app", "error", "assert",
41 * "system", "audio", "video", "render", "input", "test", or `*` for any
42 * unspecified category.
43 *
44 * The level can be a numeric level, one of "verbose", "debug", "info",
45 * "warn", "error", "critical", or "quiet" to disable that category.
46 *
47 * You can omit the category if you want to set the logging level for all
48 * categories.
49 *
50 * If this hint isn't set, the default log levels are equivalent to:
51 *
52 * `app=info,assert=warn,test=verbose,*=error`
53 *
54 * Here's where the messages go on different platforms:
55 *
56 * - Windows: debug output stream
57 * - Android: log output
58 * - Others: standard error output (stderr)
59 */
60
61#ifndef SDL_log_h_
62#define SDL_log_h_
63
64#include <SDL3/SDL_stdinc.h>
65
66#include <SDL3/SDL_begin_code.h>
67/* Set up for C function definitions, even when using C++ */
68#ifdef __cplusplus
69extern "C" {
70#endif
71
72/**
73 * The predefined log categories
74 *
75 * By default the application and gpu categories are enabled at the INFO
76 * level, the assert category is enabled at the WARN level, test is enabled at
77 * the VERBOSE level and all other categories are enabled at the ERROR level.
78 *
79 * \since This enum is available since SDL 3.0.0.
80 */
116
117/**
118 * The predefined log priorities
119 *
120 * \since This enum is available since SDL 3.0.0.
121 */
132
133
134/**
135 * Set the priority of all log categories.
136 *
137 * \param priority the SDL_LogPriority to assign.
138 *
139 * \since This function is available since SDL 3.0.0.
140 *
141 * \sa SDL_ResetLogPriorities
142 * \sa SDL_SetLogPriority
143 */
144extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
145
146/**
147 * Set the priority of a particular log category.
148 *
149 * \param category the category to assign a priority to.
150 * \param priority the SDL_LogPriority to assign.
151 *
152 * \since This function is available since SDL 3.0.0.
153 *
154 * \sa SDL_GetLogPriority
155 * \sa SDL_ResetLogPriorities
156 * \sa SDL_SetLogPriorities
157 */
158extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category,
159 SDL_LogPriority priority);
160
161/**
162 * Get the priority of a particular log category.
163 *
164 * \param category the category to query.
165 * \returns the SDL_LogPriority for the requested category.
166 *
167 * \since This function is available since SDL 3.0.0.
168 *
169 * \sa SDL_SetLogPriority
170 */
171extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category);
172
173/**
174 * Reset all priorities to default.
175 *
176 * This is called by SDL_Quit().
177 *
178 * \since This function is available since SDL 3.0.0.
179 *
180 * \sa SDL_SetLogPriorities
181 * \sa SDL_SetLogPriority
182 */
183extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
184
185/**
186 * Set the text prepended to log messages of a given priority.
187 *
188 * By default SDL_LOG_PRIORITY_INFO and below have no prefix, and
189 * SDL_LOG_PRIORITY_WARN and higher have a prefix showing their priority, e.g.
190 * "WARNING: ".
191 *
192 * \param priority the SDL_LogPriority to modify.
193 * \param prefix the prefix to use for that log priority, or NULL to use no
194 * prefix.
195 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
196 * for more information.
197 *
198 * \since This function is available since SDL 3.0.0.
199 *
200 * \sa SDL_SetLogPriorities
201 * \sa SDL_SetLogPriority
202 */
203extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix);
204
205/**
206 * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
207 *
208 * \param fmt a printf() style message format string.
209 * \param ... additional parameters matching % tokens in the `fmt` string, if
210 * any.
211 *
212 * \since This function is available since SDL 3.0.0.
213 *
214 * \sa SDL_LogCritical
215 * \sa SDL_LogDebug
216 * \sa SDL_LogError
217 * \sa SDL_LogInfo
218 * \sa SDL_LogMessage
219 * \sa SDL_LogMessageV
220 * \sa SDL_LogVerbose
221 * \sa SDL_LogWarn
222 */
223extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
224
225/**
226 * Log a message with SDL_LOG_PRIORITY_VERBOSE.
227 *
228 * \param category the category of the message.
229 * \param fmt a printf() style message format string.
230 * \param ... additional parameters matching % tokens in the **fmt** string,
231 * if any.
232 *
233 * \since This function is available since SDL 3.0.0.
234 *
235 * \sa SDL_Log
236 * \sa SDL_LogCritical
237 * \sa SDL_LogDebug
238 * \sa SDL_LogError
239 * \sa SDL_LogInfo
240 * \sa SDL_LogMessage
241 * \sa SDL_LogMessageV
242 * \sa SDL_LogWarn
243 */
244extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
245
246/**
247 * Log a message with SDL_LOG_PRIORITY_DEBUG.
248 *
249 * \param category the category of the message.
250 * \param fmt a printf() style message format string.
251 * \param ... additional parameters matching % tokens in the **fmt** string,
252 * if any.
253 *
254 * \since This function is available since SDL 3.0.0.
255 *
256 * \sa SDL_Log
257 * \sa SDL_LogCritical
258 * \sa SDL_LogError
259 * \sa SDL_LogInfo
260 * \sa SDL_LogMessage
261 * \sa SDL_LogMessageV
262 * \sa SDL_LogVerbose
263 * \sa SDL_LogWarn
264 */
265extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
266
267/**
268 * Log a message with SDL_LOG_PRIORITY_INFO.
269 *
270 * \param category the category of the message.
271 * \param fmt a printf() style message format string.
272 * \param ... additional parameters matching % tokens in the **fmt** string,
273 * if any.
274 *
275 * \since This function is available since SDL 3.0.0.
276 *
277 * \sa SDL_Log
278 * \sa SDL_LogCritical
279 * \sa SDL_LogDebug
280 * \sa SDL_LogError
281 * \sa SDL_LogMessage
282 * \sa SDL_LogMessageV
283 * \sa SDL_LogVerbose
284 * \sa SDL_LogWarn
285 */
286extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
287
288/**
289 * Log a message with SDL_LOG_PRIORITY_WARN.
290 *
291 * \param category the category of the message.
292 * \param fmt a printf() style message format string.
293 * \param ... additional parameters matching % tokens in the **fmt** string,
294 * if any.
295 *
296 * \since This function is available since SDL 3.0.0.
297 *
298 * \sa SDL_Log
299 * \sa SDL_LogCritical
300 * \sa SDL_LogDebug
301 * \sa SDL_LogError
302 * \sa SDL_LogInfo
303 * \sa SDL_LogMessage
304 * \sa SDL_LogMessageV
305 * \sa SDL_LogVerbose
306 */
307extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
308
309/**
310 * Log a message with SDL_LOG_PRIORITY_ERROR.
311 *
312 * \param category the category of the message.
313 * \param fmt a printf() style message format string.
314 * \param ... additional parameters matching % tokens in the **fmt** string,
315 * if any.
316 *
317 * \since This function is available since SDL 3.0.0.
318 *
319 * \sa SDL_Log
320 * \sa SDL_LogCritical
321 * \sa SDL_LogDebug
322 * \sa SDL_LogInfo
323 * \sa SDL_LogMessage
324 * \sa SDL_LogMessageV
325 * \sa SDL_LogVerbose
326 * \sa SDL_LogWarn
327 */
328extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
329
330/**
331 * Log a message with SDL_LOG_PRIORITY_CRITICAL.
332 *
333 * \param category the category of the message.
334 * \param fmt a printf() style message format string.
335 * \param ... additional parameters matching % tokens in the **fmt** string,
336 * if any.
337 *
338 * \since This function is available since SDL 3.0.0.
339 *
340 * \sa SDL_Log
341 * \sa SDL_LogDebug
342 * \sa SDL_LogError
343 * \sa SDL_LogInfo
344 * \sa SDL_LogMessage
345 * \sa SDL_LogMessageV
346 * \sa SDL_LogVerbose
347 * \sa SDL_LogWarn
348 */
349extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
350
351/**
352 * Log a message with the specified category and priority.
353 *
354 * \param category the category of the message.
355 * \param priority the priority of the message.
356 * \param fmt a printf() style message format string.
357 * \param ... additional parameters matching % tokens in the **fmt** string,
358 * if any.
359 *
360 * \since This function is available since SDL 3.0.0.
361 *
362 * \sa SDL_Log
363 * \sa SDL_LogCritical
364 * \sa SDL_LogDebug
365 * \sa SDL_LogError
366 * \sa SDL_LogInfo
367 * \sa SDL_LogMessageV
368 * \sa SDL_LogVerbose
369 * \sa SDL_LogWarn
370 */
371extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category,
372 SDL_LogPriority priority,
373 SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
374
375/**
376 * Log a message with the specified category and priority.
377 *
378 * \param category the category of the message.
379 * \param priority the priority of the message.
380 * \param fmt a printf() style message format string.
381 * \param ap a variable argument list.
382 *
383 * \since This function is available since SDL 3.0.0.
384 *
385 * \sa SDL_Log
386 * \sa SDL_LogCritical
387 * \sa SDL_LogDebug
388 * \sa SDL_LogError
389 * \sa SDL_LogInfo
390 * \sa SDL_LogMessage
391 * \sa SDL_LogVerbose
392 * \sa SDL_LogWarn
393 */
394extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category,
395 SDL_LogPriority priority,
396 SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
397
398/**
399 * The prototype for the log output callback function.
400 *
401 * This function is called by SDL when there is new text to be logged.
402 *
403 * \param userdata what was passed as `userdata` to
404 * SDL_SetLogOutputFunction().
405 * \param category the category of the message.
406 * \param priority the priority of the message.
407 * \param message the message being output.
408 *
409 * \since This datatype is available since SDL 3.0.0.
410 */
411typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
412
413/**
414 * Get the current log output function.
415 *
416 * \param callback an SDL_LogOutputFunction filled in with the current log
417 * callback.
418 * \param userdata a pointer filled in with the pointer that is passed to
419 * `callback`.
420 *
421 * \since This function is available since SDL 3.0.0.
422 *
423 * \sa SDL_SetLogOutputFunction
424 */
425extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
426
427/**
428 * Replace the default log output function with one of your own.
429 *
430 * \param callback an SDL_LogOutputFunction to call instead of the default.
431 * \param userdata a pointer that is passed to `callback`.
432 *
433 * \since This function is available since SDL 3.0.0.
434 *
435 * \sa SDL_GetLogOutputFunction
436 */
437extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata);
438
439
440/* Ends C function definitions when using C++ */
441#ifdef __cplusplus
442}
443#endif
444#include <SDL3/SDL_close_code.h>
445
446#endif /* SDL_log_h_ */
void SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata)
SDL_LogPriority
Definition SDL_log.h:123
@ SDL_NUM_LOG_PRIORITIES
Definition SDL_log.h:130
@ SDL_LOG_PRIORITY_INFO
Definition SDL_log.h:126
@ SDL_LOG_PRIORITY_CRITICAL
Definition SDL_log.h:129
@ SDL_LOG_PRIORITY_VERBOSE
Definition SDL_log.h:124
@ SDL_LOG_PRIORITY_DEBUG
Definition SDL_log.h:125
@ SDL_LOG_PRIORITY_ERROR
Definition SDL_log.h:128
@ SDL_LOG_PRIORITY_WARN
Definition SDL_log.h:127
void SDL_LogWarn(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_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
SDL_bool SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix)
void SDL_ResetLogPriorities(void)
void(* SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message)
Definition SDL_log.h:411
SDL_LogPriority SDL_GetLogPriority(int category)
void SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(1)
void SDL_SetLogPriority(int category, SDL_LogPriority priority)
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_SetLogPriorities(SDL_LogPriority priority)
void SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
SDL_LogCategory
Definition SDL_log.h:82
@ SDL_LOG_CATEGORY_CUSTOM
Definition SDL_log.h:114
@ SDL_LOG_CATEGORY_RESERVED1
Definition SDL_log.h:95
@ SDL_LOG_CATEGORY_GPU
Definition SDL_log.h:90
@ SDL_LOG_CATEGORY_RESERVED8
Definition SDL_log.h:102
@ SDL_LOG_CATEGORY_RESERVED6
Definition SDL_log.h:100
@ 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:99
@ SDL_LOG_CATEGORY_RESERVED3
Definition SDL_log.h:97
@ SDL_LOG_CATEGORY_INPUT
Definition SDL_log.h:91
@ SDL_LOG_CATEGORY_TEST
Definition SDL_log.h:92
@ SDL_LOG_CATEGORY_RESERVED9
Definition SDL_log.h:103
@ SDL_LOG_CATEGORY_SYSTEM
Definition SDL_log.h:86
@ SDL_LOG_CATEGORY_RESERVED10
Definition SDL_log.h:104
@ SDL_LOG_CATEGORY_RESERVED4
Definition SDL_log.h:98
@ 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:101
@ 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:96
void SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata)
void SDL_LogInfo(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)
#define SDL_PRINTF_VARARG_FUNCV(fmtargnumber)
Definition SDL_stdinc.h:459
#define SDL_PRINTF_FORMAT_STRING
Definition SDL_stdinc.h:447
#define SDL_PRINTF_VARARG_FUNC(fmtargnumber)
Definition SDL_stdinc.h:458
bool SDL_bool
Definition SDL_stdinc.h:216