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