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