SDL  2.0
SDL_log.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2021 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 "SDL_stdinc.h"
41 
42 #include "begin_code.h"
43 /* Set up for C function definitions, even when using C++ */
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47 
48 
49 /**
50  * \brief The maximum size of a log message
51  *
52  * Messages longer than the maximum size will be truncated
53  */
54 #define SDL_MAX_LOG_MESSAGE 4096
55 
56 /**
57  * \brief 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  * CRITICAL level.
63  */
64 typedef enum
65 {
75 
76  /* Reserved for future SDL library use */
87 
88  /* Beyond this point is reserved for application use, e.g.
89  enum {
90  MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
91  MYAPP_CATEGORY_AWESOME2,
92  MYAPP_CATEGORY_AWESOME3,
93  ...
94  };
95  */
98 
99 /**
100  * \brief The predefined log priorities
101  */
102 typedef enum
103 {
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 2.0.0.
120  *
121  * \sa SDL_LogSetPriority
122  */
123 extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
124 
125 /**
126  * Set the priority of a particular log category.
127  *
128  * \param category the category to assign a priority to
129  * \param priority the SDL_LogPriority to assign
130  *
131  * \since This function is available since SDL 2.0.0.
132  *
133  * \sa SDL_LogGetPriority
134  * \sa SDL_LogSetAllPriority
135  */
136 extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
137  SDL_LogPriority priority);
138 
139 /**
140  * Get the priority of a particular log category.
141  *
142  * \param category the category to query
143  * \returns the SDL_LogPriority for the requested category
144  *
145  * \since This function is available since SDL 2.0.0.
146  *
147  * \sa SDL_LogSetPriority
148  */
149 extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
150 
151 /**
152  * Reset all priorities to default.
153  *
154  * This is called by SDL_Quit().
155  *
156  * \since This function is available since SDL 2.0.0.
157  *
158  * \sa SDL_LogSetAllPriority
159  * \sa SDL_LogSetPriority
160  */
161 extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
162 
163 /**
164  * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
165  *
166  * = * \param fmt a printf() style message format string
167  *
168  * \param ... additional parameters matching % tokens in the `fmt` string, if
169  * any
170  *
171  * \since This function is available since SDL 2.0.0.
172  *
173  * \sa SDL_LogCritical
174  * \sa SDL_LogDebug
175  * \sa SDL_LogError
176  * \sa SDL_LogInfo
177  * \sa SDL_LogMessage
178  * \sa SDL_LogMessageV
179  * \sa SDL_LogVerbose
180  * \sa SDL_LogWarn
181  */
182 extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
183 
184 /**
185  * Log a message with SDL_LOG_PRIORITY_VERBOSE.
186  *
187  * \param category the category of the message
188  * \param fmt a printf() style message format string
189  * \param ... additional parameters matching % tokens in the **fmt** string,
190  * if any
191  *
192  * \since This function is available since SDL 2.0.0.
193  *
194  * \sa SDL_Log
195  * \sa SDL_LogCritical
196  * \sa SDL_LogDebug
197  * \sa SDL_LogError
198  * \sa SDL_LogInfo
199  * \sa SDL_LogMessage
200  * \sa SDL_LogMessageV
201  * \sa SDL_LogWarn
202  */
203 extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
204 
205 /**
206  * Log a message with SDL_LOG_PRIORITY_DEBUG.
207  *
208  * \param category the category of the message
209  * \param fmt a printf() style message format string
210  * \param ... additional parameters matching % tokens in the **fmt** string,
211  * if any
212  *
213  * \since This function is available since SDL 2.0.0.
214  *
215  * \sa SDL_Log
216  * \sa SDL_LogCritical
217  * \sa SDL_LogError
218  * \sa SDL_LogInfo
219  * \sa SDL_LogMessage
220  * \sa SDL_LogMessageV
221  * \sa SDL_LogVerbose
222  * \sa SDL_LogWarn
223  */
224 extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
225 
226 /**
227  * Log a message with SDL_LOG_PRIORITY_INFO.
228  *
229  * \param category the category of the message
230  * \param fmt a printf() style message format string
231  * \param ... additional parameters matching % tokens in the **fmt** string,
232  * if any
233  *
234  * \since This function is available since SDL 2.0.0.
235  *
236  * \sa SDL_Log
237  * \sa SDL_LogCritical
238  * \sa SDL_LogDebug
239  * \sa SDL_LogError
240  * \sa SDL_LogMessage
241  * \sa SDL_LogMessageV
242  * \sa SDL_LogVerbose
243  * \sa SDL_LogWarn
244  */
245 extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
246 
247 /**
248  * Log a message with SDL_LOG_PRIORITY_WARN.
249  *
250  * \param category the category of the message
251  * \param fmt a printf() style message format string
252  * \param ... additional parameters matching % tokens in the **fmt** string,
253  * if any
254  *
255  * \since This function is available since SDL 2.0.0.
256  *
257  * \sa SDL_Log
258  * \sa SDL_LogCritical
259  * \sa SDL_LogDebug
260  * \sa SDL_LogError
261  * \sa SDL_LogInfo
262  * \sa SDL_LogMessage
263  * \sa SDL_LogMessageV
264  * \sa SDL_LogVerbose
265  */
266 extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
267 
268 /**
269  * Log a message with SDL_LOG_PRIORITY_ERROR.
270  *
271  * \param category the category of the message
272  * \param fmt a printf() style message format string
273  * \param ... additional parameters matching % tokens in the **fmt** string,
274  * if any
275  *
276  * \since This function is available since SDL 2.0.0.
277  *
278  * \sa SDL_Log
279  * \sa SDL_LogCritical
280  * \sa SDL_LogDebug
281  * \sa SDL_LogInfo
282  * \sa SDL_LogMessage
283  * \sa SDL_LogMessageV
284  * \sa SDL_LogVerbose
285  * \sa SDL_LogWarn
286  */
287 extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
288 
289 /**
290  * Log a message with SDL_LOG_PRIORITY_CRITICAL.
291  *
292  * \param category the category of the message
293  * \param fmt a printf() style message format string
294  * \param ... additional parameters matching % tokens in the **fmt** string,
295  * if any
296  *
297  * \since This function is available since SDL 2.0.0.
298  *
299  * \sa SDL_Log
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  * \sa SDL_LogWarn
307  */
308 extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
309 
310 /**
311  * Log a message with the specified category and priority.
312  *
313  * \param category the category of the message
314  * \param priority the priority of the message
315  * \param fmt a printf() style message format string
316  * \param ... additional parameters matching % tokens in the **fmt** string,
317  * if any
318  *
319  * \since This function is available since SDL 2.0.0.
320  *
321  * \sa SDL_Log
322  * \sa SDL_LogCritical
323  * \sa SDL_LogDebug
324  * \sa SDL_LogError
325  * \sa SDL_LogInfo
326  * \sa SDL_LogMessageV
327  * \sa SDL_LogVerbose
328  * \sa SDL_LogWarn
329  */
330 extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
331  SDL_LogPriority priority,
332  SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
333 
334 /**
335  * Log a message with the specified category and priority.
336  *
337  * \param category the category of the message
338  * \param priority the priority of the message
339  * \param fmt a printf() style message format string
340  * \param ap a variable argument list
341  *
342  * \since This function is available since SDL 2.0.0.
343  *
344  * \sa SDL_Log
345  * \sa SDL_LogCritical
346  * \sa SDL_LogDebug
347  * \sa SDL_LogError
348  * \sa SDL_LogInfo
349  * \sa SDL_LogMessage
350  * \sa SDL_LogVerbose
351  * \sa SDL_LogWarn
352  */
353 extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
354  SDL_LogPriority priority,
355  const char *fmt, va_list ap);
356 
357 /**
358  * The prototype for the log output callback function.
359  *
360  * This function is called by SDL when there is new text to be logged.
361  *
362  * \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
363  * \param category the category of the message
364  * \param priority the priority of the message
365  * \param message the message being output
366  */
367 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
368 
369 /**
370  * Get the current log output function.
371  *
372  * \param callback an SDL_LogOutputFunction filled in with the current log
373  * callback
374  * \param userdata a pointer filled in with the pointer that is passed to
375  * `callback`
376  *
377  * \since This function is available since SDL 2.0.0.
378  *
379  * \sa SDL_LogSetOutputFunction
380  */
381 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
382 
383 /**
384  * Replace the default log output function with one of your own.
385  *
386  * \param callback an SDL_LogOutputFunction to call instead of the default
387  * \param userdata a pointer that is passed to `callback`
388  *
389  * \since This function is available since SDL 2.0.0.
390  *
391  * \sa SDL_LogGetOutputFunction
392  */
393 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
394 
395 
396 /* Ends C function definitions when using C++ */
397 #ifdef __cplusplus
398 }
399 #endif
400 #include "close_code.h"
401 
402 #endif /* SDL_log_h_ */
403 
404 /* vi: set ts=4 sw=4 expandtab: */
void SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata)
SDL_LogPriority
The predefined log priorities.
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_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata)
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:367
void SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_LogMessageV(int category, SDL_LogPriority priority, const char *fmt, va_list ap)
void SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(1)
void SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
SDL_LogCategory
The predefined log categories.
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_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_FORMAT_STRING
Definition: SDL_stdinc.h:345
#define SDL_PRINTF_VARARG_FUNC(fmtargnumber)
Definition: SDL_stdinc.h:352