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. If you're debugging SDL you might want:
33 *
34 * SDL_SetLogPriorities(SDL_LOG_PRIORITY_WARN);
35 *
36 * Here's where the messages go on different platforms:
37 *
38 * - Windows: debug output stream
39 * - Android: log output
40 * - Others: standard error output (stderr)
41 */
42
43#ifndef SDL_log_h_
44#define SDL_log_h_
45
46#include <SDL3/SDL_stdinc.h>
47
48#include <SDL3/SDL_begin_code.h>
49/* Set up for C function definitions, even when using C++ */
50#ifdef __cplusplus
51extern "C" {
52#endif
53
54/**
55 * The predefined log categories
56 *
57 * By default the application category is enabled at the INFO level, the
58 * assert category is enabled at the WARN level, test is enabled at the
59 * VERBOSE level and all other categories are enabled at the ERROR level.
60 *
61 * \since This enum is available since SDL 3.0.0.
62 */
97
98/**
99 * The predefined log priorities
100 *
101 * \since This enum is available since SDL 3.0.0.
102 */
113
114
115/**
116 * Set the priority of all log categories.
117 *
118 * \param priority the SDL_LogPriority to assign.
119 *
120 * \since This function is available since SDL 3.0.0.
121 *
122 * \sa SDL_ResetLogPriorities
123 * \sa SDL_SetLogPriority
124 */
125extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
126
127/**
128 * Set the priority of a particular log category.
129 *
130 * \param category the category to assign a priority to.
131 * \param priority the SDL_LogPriority to assign.
132 *
133 * \since This function is available since SDL 3.0.0.
134 *
135 * \sa SDL_GetLogPriority
136 * \sa SDL_ResetLogPriorities
137 * \sa SDL_SetLogPriorities
138 */
139extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category,
140 SDL_LogPriority priority);
141
142/**
143 * Get the priority of a particular log category.
144 *
145 * \param category the category to query.
146 * \returns the SDL_LogPriority for the requested category.
147 *
148 * \since This function is available since SDL 3.0.0.
149 *
150 * \sa SDL_SetLogPriority
151 */
152extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category);
153
154/**
155 * Reset all priorities to default.
156 *
157 * This is called by SDL_Quit().
158 *
159 * \since This function is available since SDL 3.0.0.
160 *
161 * \sa SDL_SetLogPriorities
162 * \sa SDL_SetLogPriority
163 */
164extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
165
166/**
167 * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
168 *
169 * \param fmt a printf() style message format string.
170 * \param ... additional parameters matching % tokens in the `fmt` string, if
171 * any.
172 *
173 * \since This function is available since SDL 3.0.0.
174 *
175 * \sa SDL_LogCritical
176 * \sa SDL_LogDebug
177 * \sa SDL_LogError
178 * \sa SDL_LogInfo
179 * \sa SDL_LogMessage
180 * \sa SDL_LogMessageV
181 * \sa SDL_LogVerbose
182 * \sa SDL_LogWarn
183 */
184extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
185
186/**
187 * Log a message with SDL_LOG_PRIORITY_VERBOSE.
188 *
189 * \param category the category of the message.
190 * \param fmt a printf() style message format string.
191 * \param ... additional parameters matching % tokens in the **fmt** string,
192 * if any.
193 *
194 * \since This function is available since SDL 3.0.0.
195 *
196 * \sa SDL_Log
197 * \sa SDL_LogCritical
198 * \sa SDL_LogDebug
199 * \sa SDL_LogError
200 * \sa SDL_LogInfo
201 * \sa SDL_LogMessage
202 * \sa SDL_LogMessageV
203 * \sa SDL_LogWarn
204 */
205extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
206
207/**
208 * Log a message with SDL_LOG_PRIORITY_DEBUG.
209 *
210 * \param category the category of the message.
211 * \param fmt a printf() style message format string.
212 * \param ... additional parameters matching % tokens in the **fmt** string,
213 * if any.
214 *
215 * \since This function is available since SDL 3.0.0.
216 *
217 * \sa SDL_Log
218 * \sa SDL_LogCritical
219 * \sa SDL_LogError
220 * \sa SDL_LogInfo
221 * \sa SDL_LogMessage
222 * \sa SDL_LogMessageV
223 * \sa SDL_LogVerbose
224 * \sa SDL_LogWarn
225 */
226extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
227
228/**
229 * Log a message with SDL_LOG_PRIORITY_INFO.
230 *
231 * \param category the category of the message.
232 * \param fmt a printf() style message format string.
233 * \param ... additional parameters matching % tokens in the **fmt** string,
234 * if any.
235 *
236 * \since This function is available since SDL 3.0.0.
237 *
238 * \sa SDL_Log
239 * \sa SDL_LogCritical
240 * \sa SDL_LogDebug
241 * \sa SDL_LogError
242 * \sa SDL_LogMessage
243 * \sa SDL_LogMessageV
244 * \sa SDL_LogVerbose
245 * \sa SDL_LogWarn
246 */
247extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
248
249/**
250 * Log a message with SDL_LOG_PRIORITY_WARN.
251 *
252 * \param category the category of the message.
253 * \param fmt a printf() style message format string.
254 * \param ... additional parameters matching % tokens in the **fmt** string,
255 * if any.
256 *
257 * \since This function is available since SDL 3.0.0.
258 *
259 * \sa SDL_Log
260 * \sa SDL_LogCritical
261 * \sa SDL_LogDebug
262 * \sa SDL_LogError
263 * \sa SDL_LogInfo
264 * \sa SDL_LogMessage
265 * \sa SDL_LogMessageV
266 * \sa SDL_LogVerbose
267 */
268extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
269
270/**
271 * Log a message with SDL_LOG_PRIORITY_ERROR.
272 *
273 * \param category the category of the message.
274 * \param fmt a printf() style message format string.
275 * \param ... additional parameters matching % tokens in the **fmt** string,
276 * if any.
277 *
278 * \since This function is available since SDL 3.0.0.
279 *
280 * \sa SDL_Log
281 * \sa SDL_LogCritical
282 * \sa SDL_LogDebug
283 * \sa SDL_LogInfo
284 * \sa SDL_LogMessage
285 * \sa SDL_LogMessageV
286 * \sa SDL_LogVerbose
287 * \sa SDL_LogWarn
288 */
289extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
290
291/**
292 * Log a message with SDL_LOG_PRIORITY_CRITICAL.
293 *
294 * \param category the category of the message.
295 * \param fmt a printf() style message format string.
296 * \param ... additional parameters matching % tokens in the **fmt** string,
297 * if any.
298 *
299 * \since This function is available since SDL 3.0.0.
300 *
301 * \sa SDL_Log
302 * \sa SDL_LogDebug
303 * \sa SDL_LogError
304 * \sa SDL_LogInfo
305 * \sa SDL_LogMessage
306 * \sa SDL_LogMessageV
307 * \sa SDL_LogVerbose
308 * \sa SDL_LogWarn
309 */
310extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
311
312/**
313 * Log a message with the specified category and priority.
314 *
315 * \param category the category of the message.
316 * \param priority the priority of the message.
317 * \param fmt a printf() style message format string.
318 * \param ... additional parameters matching % tokens in the **fmt** string,
319 * if any.
320 *
321 * \since This function is available since SDL 3.0.0.
322 *
323 * \sa SDL_Log
324 * \sa SDL_LogCritical
325 * \sa SDL_LogDebug
326 * \sa SDL_LogError
327 * \sa SDL_LogInfo
328 * \sa SDL_LogMessageV
329 * \sa SDL_LogVerbose
330 * \sa SDL_LogWarn
331 */
332extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category,
333 SDL_LogPriority priority,
334 SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
335
336/**
337 * Log a message with the specified category and priority.
338 *
339 * \param category the category of the message.
340 * \param priority the priority of the message.
341 * \param fmt a printf() style message format string.
342 * \param ap a variable argument list.
343 *
344 * \since This function is available since SDL 3.0.0.
345 *
346 * \sa SDL_Log
347 * \sa SDL_LogCritical
348 * \sa SDL_LogDebug
349 * \sa SDL_LogError
350 * \sa SDL_LogInfo
351 * \sa SDL_LogMessage
352 * \sa SDL_LogVerbose
353 * \sa SDL_LogWarn
354 */
355extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category,
356 SDL_LogPriority priority,
357 SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
358
359/**
360 * The prototype for the log output callback function.
361 *
362 * This function is called by SDL when there is new text to be logged.
363 *
364 * \param userdata what was passed as `userdata` to
365 * SDL_SetLogOutputFunction().
366 * \param category the category of the message.
367 * \param priority the priority of the message.
368 * \param message the message being output.
369 *
370 * \since This datatype is available since SDL 3.0.0.
371 */
372typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
373
374/**
375 * Get the current log output function.
376 *
377 * \param callback an SDL_LogOutputFunction filled in with the current log
378 * callback.
379 * \param userdata a pointer filled in with the pointer that is passed to
380 * `callback`.
381 *
382 * \since This function is available since SDL 3.0.0.
383 *
384 * \sa SDL_SetLogOutputFunction
385 */
386extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
387
388/**
389 * Replace the default log output function with one of your own.
390 *
391 * \param callback an SDL_LogOutputFunction to call instead of the default.
392 * \param userdata a pointer that is passed to `callback`.
393 *
394 * \since This function is available since SDL 3.0.0.
395 *
396 * \sa SDL_GetLogOutputFunction
397 */
398extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata);
399
400
401/* Ends C function definitions when using C++ */
402#ifdef __cplusplus
403}
404#endif
405#include <SDL3/SDL_close_code.h>
406
407#endif /* SDL_log_h_ */
void SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata)
SDL_LogPriority
Definition SDL_log.h:104
@ SDL_NUM_LOG_PRIORITIES
Definition SDL_log.h:111
@ SDL_LOG_PRIORITY_INFO
Definition SDL_log.h:107
@ SDL_LOG_PRIORITY_CRITICAL
Definition SDL_log.h:110
@ SDL_LOG_PRIORITY_VERBOSE
Definition SDL_log.h:105
@ SDL_LOG_PRIORITY_DEBUG
Definition SDL_log.h:106
@ SDL_LOG_PRIORITY_ERROR
Definition SDL_log.h:109
@ SDL_LOG_PRIORITY_WARN
Definition SDL_log.h:108
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)
void SDL_ResetLogPriorities(void)
void(* SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message)
Definition SDL_log.h:372
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:64
@ SDL_LOG_CATEGORY_CUSTOM
Definition SDL_log.h:95
@ SDL_LOG_CATEGORY_RESERVED1
Definition SDL_log.h:76
@ SDL_LOG_CATEGORY_RESERVED8
Definition SDL_log.h:83
@ SDL_LOG_CATEGORY_RESERVED6
Definition SDL_log.h:81
@ SDL_LOG_CATEGORY_ERROR
Definition SDL_log.h:66
@ SDL_LOG_CATEGORY_RENDER
Definition SDL_log.h:71
@ SDL_LOG_CATEGORY_RESERVED5
Definition SDL_log.h:80
@ SDL_LOG_CATEGORY_RESERVED3
Definition SDL_log.h:78
@ SDL_LOG_CATEGORY_INPUT
Definition SDL_log.h:72
@ SDL_LOG_CATEGORY_TEST
Definition SDL_log.h:73
@ SDL_LOG_CATEGORY_RESERVED9
Definition SDL_log.h:84
@ SDL_LOG_CATEGORY_SYSTEM
Definition SDL_log.h:68
@ SDL_LOG_CATEGORY_RESERVED10
Definition SDL_log.h:85
@ SDL_LOG_CATEGORY_RESERVED4
Definition SDL_log.h:79
@ SDL_LOG_CATEGORY_APPLICATION
Definition SDL_log.h:65
@ SDL_LOG_CATEGORY_AUDIO
Definition SDL_log.h:69
@ SDL_LOG_CATEGORY_RESERVED7
Definition SDL_log.h:82
@ SDL_LOG_CATEGORY_ASSERT
Definition SDL_log.h:67
@ SDL_LOG_CATEGORY_VIDEO
Definition SDL_log.h:70
@ SDL_LOG_CATEGORY_RESERVED2
Definition SDL_log.h:77
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:456
#define SDL_PRINTF_FORMAT_STRING
Definition SDL_stdinc.h:444
#define SDL_PRINTF_VARARG_FUNC(fmtargnumber)
Definition SDL_stdinc.h:455