Mercurial > foo_out_sdl

comparison SDL3/SDL_log.h @ 1:20d02a178406 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*: check in everything else yay
author Paper <paper@tflc.us>
date Mon, 05 Jan 2026 02:15:46 -0500
parents
children
comparison
equal deleted inserted replaced
0:e9bb126753e7 1:20d02a178406
1 /*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 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 "trace", "verbose", "debug",
45 * "info", "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 * You don't need to have a newline (`\n`) on the end of messages, the
61 * functions will do that for you. For consistent behavior cross-platform, you
62 * shouldn't have any newlines in messages, such as to log multiple lines in
63 * one call; unusual platform-specific behavior can be observed in such usage.
64 * Do one log call per line instead, with no newlines in messages.
65 *
66 * Each log call is atomic, so you won't see log messages cut off one another
67 * when logging from multiple threads.
68 */
69
70 #ifndef SDL_log_h_
71 #define SDL_log_h_
72
73 #include <SDL3/SDL_stdinc.h>
74
75 #include <SDL3/SDL_begin_code.h>
76 /* Set up for C function definitions, even when using C++ */
77 #ifdef __cplusplus
78 extern "C" {
79 #endif
80
81 /**
82 * The predefined log categories
83 *
84 * By default the application and gpu categories are enabled at the INFO
85 * level, the assert category is enabled at the WARN level, test is enabled at
86 * the VERBOSE level and all other categories are enabled at the ERROR level.
87 *
88 * \since This enum is available since SDL 3.2.0.
89 */
90 typedef enum SDL_LogCategory
91 {
92 SDL_LOG_CATEGORY_APPLICATION,
93 SDL_LOG_CATEGORY_ERROR,
94 SDL_LOG_CATEGORY_ASSERT,
95 SDL_LOG_CATEGORY_SYSTEM,
96 SDL_LOG_CATEGORY_AUDIO,
97 SDL_LOG_CATEGORY_VIDEO,
98 SDL_LOG_CATEGORY_RENDER,
99 SDL_LOG_CATEGORY_INPUT,
100 SDL_LOG_CATEGORY_TEST,
101 SDL_LOG_CATEGORY_GPU,
102
103 /* Reserved for future SDL library use */
104 SDL_LOG_CATEGORY_RESERVED2,
105 SDL_LOG_CATEGORY_RESERVED3,
106 SDL_LOG_CATEGORY_RESERVED4,
107 SDL_LOG_CATEGORY_RESERVED5,
108 SDL_LOG_CATEGORY_RESERVED6,
109 SDL_LOG_CATEGORY_RESERVED7,
110 SDL_LOG_CATEGORY_RESERVED8,
111 SDL_LOG_CATEGORY_RESERVED9,
112 SDL_LOG_CATEGORY_RESERVED10,
113
114 /* Beyond this point is reserved for application use, e.g.
115 enum {
116 MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
117 MYAPP_CATEGORY_AWESOME2,
118 MYAPP_CATEGORY_AWESOME3,
119 ...
120 };
121 */
122 SDL_LOG_CATEGORY_CUSTOM
123 } SDL_LogCategory;
124
125 /**
126 * The predefined log priorities
127 *
128 * \since This enum is available since SDL 3.2.0.
129 */
130 typedef enum SDL_LogPriority
131 {
132 SDL_LOG_PRIORITY_INVALID,
133 SDL_LOG_PRIORITY_TRACE,
134 SDL_LOG_PRIORITY_VERBOSE,
135 SDL_LOG_PRIORITY_DEBUG,
136 SDL_LOG_PRIORITY_INFO,
137 SDL_LOG_PRIORITY_WARN,
138 SDL_LOG_PRIORITY_ERROR,
139 SDL_LOG_PRIORITY_CRITICAL,
140 SDL_LOG_PRIORITY_COUNT
141 } SDL_LogPriority;
142
143
144 /**
145 * Set the priority of all log categories.
146 *
147 * \param priority the SDL_LogPriority to assign.
148 *
149 * \threadsafety It is safe to call this function from any thread.
150 *
151 * \since This function is available since SDL 3.2.0.
152 *
153 * \sa SDL_ResetLogPriorities
154 * \sa SDL_SetLogPriority
155 */
156 extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
157
158 /**
159 * Set the priority of a particular log category.
160 *
161 * \param category the category to assign a priority to.
162 * \param priority the SDL_LogPriority to assign.
163 *
164 * \threadsafety It is safe to call this function from any thread.
165 *
166 * \since This function is available since SDL 3.2.0.
167 *
168 * \sa SDL_GetLogPriority
169 * \sa SDL_ResetLogPriorities
170 * \sa SDL_SetLogPriorities
171 */
172 extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority);
173
174 /**
175 * Get the priority of a particular log category.
176 *
177 * \param category the category to query.
178 * \returns the SDL_LogPriority for the requested category.
179 *
180 * \threadsafety It is safe to call this function from any thread.
181 *
182 * \since This function is available since SDL 3.2.0.
183 *
184 * \sa SDL_SetLogPriority
185 */
186 extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category);
187
188 /**
189 * Reset all priorities to default.
190 *
191 * This is called by SDL_Quit().
192 *
193 * \threadsafety It is safe to call this function from any thread.
194 *
195 * \since This function is available since SDL 3.2.0.
196 *
197 * \sa SDL_SetLogPriorities
198 * \sa SDL_SetLogPriority
199 */
200 extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
201
202 /**
203 * Set the text prepended to log messages of a given priority.
204 *
205 * By default SDL_LOG_PRIORITY_INFO and below have no prefix, and
206 * SDL_LOG_PRIORITY_WARN and higher have a prefix showing their priority, e.g.
207 * "WARNING: ".
208 *
209 * This function makes a copy of its string argument, **prefix**, so it is not
210 * necessary to keep the value of **prefix** alive after the call returns.
211 *
212 * \param priority the SDL_LogPriority to modify.
213 * \param prefix the prefix to use for that log priority, or NULL to use no
214 * prefix.
215 * \returns true on success or false on failure; call SDL_GetError() for more
216 * information.
217 *
218 * \threadsafety It is safe to call this function from any thread.
219 *
220 * \since This function is available since SDL 3.2.0.
221 *
222 * \sa SDL_SetLogPriorities
223 * \sa SDL_SetLogPriority
224 */
225 extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix);
226
227 /**
228 * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
229 *
230 * \param fmt a printf() style message format string.
231 * \param ... additional parameters matching % tokens in the `fmt` string, if
232 * any.
233 *
234 * \threadsafety It is safe to call this function from any thread.
235 *
236 * \since This function is available since SDL 3.2.0.
237 *
238 * \sa SDL_LogCritical
239 * \sa SDL_LogDebug
240 * \sa SDL_LogError
241 * \sa SDL_LogInfo
242 * \sa SDL_LogMessage
243 * \sa SDL_LogMessageV
244 * \sa SDL_LogTrace
245 * \sa SDL_LogVerbose
246 * \sa SDL_LogWarn
247 */
248 extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
249
250 /**
251 * Log a message with SDL_LOG_PRIORITY_TRACE.
252 *
253 * \param category the category of the message.
254 * \param fmt a printf() style message format string.
255 * \param ... additional parameters matching % tokens in the **fmt** string,
256 * if any.
257 *
258 * \threadsafety It is safe to call this function from any thread.
259 *
260 * \since This function is available since SDL 3.2.0.
261 *
262 * \sa SDL_Log
263 * \sa SDL_LogCritical
264 * \sa SDL_LogDebug
265 * \sa SDL_LogError
266 * \sa SDL_LogInfo
267 * \sa SDL_LogMessage
268 * \sa SDL_LogMessageV
269 * \sa SDL_LogVerbose
270 * \sa SDL_LogWarn
271 */
272 extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
273
274 /**
275 * Log a message with SDL_LOG_PRIORITY_VERBOSE.
276 *
277 * \param category the category of the message.
278 * \param fmt a printf() style message format string.
279 * \param ... additional parameters matching % tokens in the **fmt** string,
280 * if any.
281 *
282 * \threadsafety It is safe to call this function from any thread.
283 *
284 * \since This function is available since SDL 3.2.0.
285 *
286 * \sa SDL_Log
287 * \sa SDL_LogCritical
288 * \sa SDL_LogDebug
289 * \sa SDL_LogError
290 * \sa SDL_LogInfo
291 * \sa SDL_LogMessage
292 * \sa SDL_LogMessageV
293 * \sa SDL_LogWarn
294 */
295 extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
296
297 /**
298 * Log a message with SDL_LOG_PRIORITY_DEBUG.
299 *
300 * \param category the category of the message.
301 * \param fmt a printf() style message format string.
302 * \param ... additional parameters matching % tokens in the **fmt** string,
303 * if any.
304 *
305 * \threadsafety It is safe to call this function from any thread.
306 *
307 * \since This function is available since SDL 3.2.0.
308 *
309 * \sa SDL_Log
310 * \sa SDL_LogCritical
311 * \sa SDL_LogError
312 * \sa SDL_LogInfo
313 * \sa SDL_LogMessage
314 * \sa SDL_LogMessageV
315 * \sa SDL_LogTrace
316 * \sa SDL_LogVerbose
317 * \sa SDL_LogWarn
318 */
319 extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
320
321 /**
322 * Log a message with SDL_LOG_PRIORITY_INFO.
323 *
324 * \param category the category of the message.
325 * \param fmt a printf() style message format string.
326 * \param ... additional parameters matching % tokens in the **fmt** string,
327 * if any.
328 *
329 * \threadsafety It is safe to call this function from any thread.
330 *
331 * \since This function is available since SDL 3.2.0.
332 *
333 * \sa SDL_Log
334 * \sa SDL_LogCritical
335 * \sa SDL_LogDebug
336 * \sa SDL_LogError
337 * \sa SDL_LogMessage
338 * \sa SDL_LogMessageV
339 * \sa SDL_LogTrace
340 * \sa SDL_LogVerbose
341 * \sa SDL_LogWarn
342 */
343 extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
344
345 /**
346 * Log a message with SDL_LOG_PRIORITY_WARN.
347 *
348 * \param category the category of the message.
349 * \param fmt a printf() style message format string.
350 * \param ... additional parameters matching % tokens in the **fmt** string,
351 * if any.
352 *
353 * \threadsafety It is safe to call this function from any thread.
354 *
355 * \since This function is available since SDL 3.2.0.
356 *
357 * \sa SDL_Log
358 * \sa SDL_LogCritical
359 * \sa SDL_LogDebug
360 * \sa SDL_LogError
361 * \sa SDL_LogInfo
362 * \sa SDL_LogMessage
363 * \sa SDL_LogMessageV
364 * \sa SDL_LogTrace
365 * \sa SDL_LogVerbose
366 */
367 extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
368
369 /**
370 * Log a message with SDL_LOG_PRIORITY_ERROR.
371 *
372 * \param category the category of the message.
373 * \param fmt a printf() style message format string.
374 * \param ... additional parameters matching % tokens in the **fmt** string,
375 * if any.
376 *
377 * \threadsafety It is safe to call this function from any thread.
378 *
379 * \since This function is available since SDL 3.2.0.
380 *
381 * \sa SDL_Log
382 * \sa SDL_LogCritical
383 * \sa SDL_LogDebug
384 * \sa SDL_LogInfo
385 * \sa SDL_LogMessage
386 * \sa SDL_LogMessageV
387 * \sa SDL_LogTrace
388 * \sa SDL_LogVerbose
389 * \sa SDL_LogWarn
390 */
391 extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
392
393 /**
394 * Log a message with SDL_LOG_PRIORITY_CRITICAL.
395 *
396 * \param category the category of the message.
397 * \param fmt a printf() style message format string.
398 * \param ... additional parameters matching % tokens in the **fmt** string,
399 * if any.
400 *
401 * \threadsafety It is safe to call this function from any thread.
402 *
403 * \since This function is available since SDL 3.2.0.
404 *
405 * \sa SDL_Log
406 * \sa SDL_LogDebug
407 * \sa SDL_LogError
408 * \sa SDL_LogInfo
409 * \sa SDL_LogMessage
410 * \sa SDL_LogMessageV
411 * \sa SDL_LogTrace
412 * \sa SDL_LogVerbose
413 * \sa SDL_LogWarn
414 */
415 extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
416
417 /**
418 * Log a message with the specified category and priority.
419 *
420 * \param category the category of the message.
421 * \param priority the priority of the message.
422 * \param fmt a printf() style message format string.
423 * \param ... additional parameters matching % tokens in the **fmt** string,
424 * if any.
425 *
426 * \threadsafety It is safe to call this function from any thread.
427 *
428 * \since This function is available since SDL 3.2.0.
429 *
430 * \sa SDL_Log
431 * \sa SDL_LogCritical
432 * \sa SDL_LogDebug
433 * \sa SDL_LogError
434 * \sa SDL_LogInfo
435 * \sa SDL_LogMessageV
436 * \sa SDL_LogTrace
437 * \sa SDL_LogVerbose
438 * \sa SDL_LogWarn
439 */
440 extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category,
441 SDL_LogPriority priority,
442 SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
443
444 /**
445 * Log a message with the specified category and priority.
446 *
447 * \param category the category of the message.
448 * \param priority the priority of the message.
449 * \param fmt a printf() style message format string.
450 * \param ap a variable argument list.
451 *
452 * \threadsafety It is safe to call this function from any thread.
453 *
454 * \since This function is available since SDL 3.2.0.
455 *
456 * \sa SDL_Log
457 * \sa SDL_LogCritical
458 * \sa SDL_LogDebug
459 * \sa SDL_LogError
460 * \sa SDL_LogInfo
461 * \sa SDL_LogMessage
462 * \sa SDL_LogTrace
463 * \sa SDL_LogVerbose
464 * \sa SDL_LogWarn
465 */
466 extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category,
467 SDL_LogPriority priority,
468 SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
469
470 /**
471 * The prototype for the log output callback function.
472 *
473 * This function is called by SDL when there is new text to be logged. A mutex
474 * is held so that this function is never called by more than one thread at
475 * once.
476 *
477 * \param userdata what was passed as `userdata` to
478 * SDL_SetLogOutputFunction().
479 * \param category the category of the message.
480 * \param priority the priority of the message.
481 * \param message the message being output.
482 *
483 * \since This datatype is available since SDL 3.2.0.
484 */
485 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
486
487 /**
488 * Get the default log output function.
489 *
490 * \returns the default log output callback.
491 *
492 * \threadsafety It is safe to call this function from any thread.
493 *
494 * \since This function is available since SDL 3.2.0.
495 *
496 * \sa SDL_SetLogOutputFunction
497 * \sa SDL_GetLogOutputFunction
498 */
499 extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void);
500
501 /**
502 * Get the current log output function.
503 *
504 * \param callback an SDL_LogOutputFunction filled in with the current log
505 * callback.
506 * \param userdata a pointer filled in with the pointer that is passed to
507 * `callback`.
508 *
509 * \threadsafety It is safe to call this function from any thread.
510 *
511 * \since This function is available since SDL 3.2.0.
512 *
513 * \sa SDL_GetDefaultLogOutputFunction
514 * \sa SDL_SetLogOutputFunction
515 */
516 extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
517
518 /**
519 * Replace the default log output function with one of your own.
520 *
521 * \param callback an SDL_LogOutputFunction to call instead of the default.
522 * \param userdata a pointer that is passed to `callback`.
523 *
524 * \threadsafety It is safe to call this function from any thread.
525 *
526 * \since This function is available since SDL 3.2.0.
527 *
528 * \sa SDL_GetDefaultLogOutputFunction
529 * \sa SDL_GetLogOutputFunction
530 */
531 extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata);
532
533
534 /* Ends C function definitions when using C++ */
535 #ifdef __cplusplus
536 }
537 #endif
538 #include <SDL3/SDL_close_code.h>
539
540 #endif /* SDL_log_h_ */