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  * \sa SDL_LogSetPriority
120  */
121 extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
122 
123 /**
124  * Set the priority of a particular log category.
125  *
126  * \param category the category to assign a priority to
127  * \param priority the SDL_LogPriority to assign
128  *
129  * \sa SDL_LogGetPriority
130  * \sa SDL_LogSetAllPriority
131  */
132 extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
133  SDL_LogPriority priority);
134 
135 /**
136  * Get the priority of a particular log category.
137  *
138  * \param category the category to query
139  * \returns the SDL_LogPriority for the requested category
140  *
141  * \sa SDL_LogSetPriority
142  */
143 extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
144 
145 /**
146  * Reset all priorities to default.
147  *
148  * This is called by SDL_Quit().
149  *
150  * \sa SDL_LogSetAllPriority
151  * \sa SDL_LogSetPriority
152  */
153 extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
154 
155 /**
156  * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
157  *
158  * = * \param fmt a printf() style message format string
159  *
160  * \param ... additional parameters matching % tokens in the `fmt` string, if
161  * any
162  *
163  * \sa SDL_LogCritical
164  * \sa SDL_LogDebug
165  * \sa SDL_LogError
166  * \sa SDL_LogInfo
167  * \sa SDL_LogMessage
168  * \sa SDL_LogMessageV
169  * \sa SDL_LogVerbose
170  * \sa SDL_LogWarn
171  */
172 extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
173 
174 /**
175  * Log a message with SDL_LOG_PRIORITY_VERBOSE.
176  *
177  * \param category the category of the message
178  * \param fmt a printf() style message format string
179  * \param ... additional parameters matching % tokens in the **fmt** string,
180  * if any
181  *
182  * \sa SDL_Log
183  * \sa SDL_LogCritical
184  * \sa SDL_LogDebug
185  * \sa SDL_LogError
186  * \sa SDL_LogInfo
187  * \sa SDL_LogMessage
188  * \sa SDL_LogMessageV
189  * \sa SDL_LogWarn
190  */
191 extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
192 
193 /**
194  * Log a message with SDL_LOG_PRIORITY_DEBUG.
195  *
196  * \param category the category of the message
197  * \param fmt a printf() style message format string
198  * \param ... additional parameters matching % tokens in the **fmt** string,
199  * if any
200  *
201  * \sa SDL_Log
202  * \sa SDL_LogCritical
203  * \sa SDL_LogError
204  * \sa SDL_LogInfo
205  * \sa SDL_LogMessage
206  * \sa SDL_LogMessageV
207  * \sa SDL_LogVerbose
208  * \sa SDL_LogWarn
209  */
210 extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
211 
212 /**
213  * Log a message with SDL_LOG_PRIORITY_INFO.
214  *
215  * \param category the category of the message
216  * \param fmt a printf() style message format string
217  * \param ... additional parameters matching % tokens in the **fmt** string,
218  * if any
219  *
220  * \sa SDL_Log
221  * \sa SDL_LogCritical
222  * \sa SDL_LogDebug
223  * \sa SDL_LogError
224  * \sa SDL_LogMessage
225  * \sa SDL_LogMessageV
226  * \sa SDL_LogVerbose
227  * \sa SDL_LogWarn
228  */
229 extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
230 
231 /**
232  * Log a message with SDL_LOG_PRIORITY_WARN.
233  *
234  * \param category the category of the message
235  * \param fmt a printf() style message format string
236  * \param ... additional parameters matching % tokens in the **fmt** string,
237  * if any
238  *
239  * \sa SDL_Log
240  * \sa SDL_LogCritical
241  * \sa SDL_LogDebug
242  * \sa SDL_LogError
243  * \sa SDL_LogInfo
244  * \sa SDL_LogMessage
245  * \sa SDL_LogMessageV
246  * \sa SDL_LogVerbose
247  */
248 extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
249 
250 /**
251  * Log a message with SDL_LOG_PRIORITY_ERROR.
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  * \sa SDL_Log
259  * \sa SDL_LogCritical
260  * \sa SDL_LogDebug
261  * \sa SDL_LogInfo
262  * \sa SDL_LogMessage
263  * \sa SDL_LogMessageV
264  * \sa SDL_LogVerbose
265  * \sa SDL_LogWarn
266  */
267 extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
268 
269 /**
270  * Log a message with SDL_LOG_PRIORITY_CRITICAL.
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  * \sa SDL_Log
278  * \sa SDL_LogDebug
279  * \sa SDL_LogError
280  * \sa SDL_LogInfo
281  * \sa SDL_LogMessage
282  * \sa SDL_LogMessageV
283  * \sa SDL_LogVerbose
284  * \sa SDL_LogWarn
285  */
286 extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
287 
288 /**
289  * Log a message with the specified category and priority.
290  *
291  * \param category the category of the message
292  * \param priority the priority 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  * \sa SDL_Log
298  * \sa SDL_LogCritical
299  * \sa SDL_LogDebug
300  * \sa SDL_LogError
301  * \sa SDL_LogInfo
302  * \sa SDL_LogMessageV
303  * \sa SDL_LogVerbose
304  * \sa SDL_LogWarn
305  */
306 extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
307  SDL_LogPriority priority,
308  SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
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 ap a variable argument list
317  *
318  * \since This function is available since SDL 2.0.0.
319  *
320  * \sa SDL_Log
321  * \sa SDL_LogCritical
322  * \sa SDL_LogDebug
323  * \sa SDL_LogError
324  * \sa SDL_LogInfo
325  * \sa SDL_LogMessage
326  * \sa SDL_LogVerbose
327  * \sa SDL_LogWarn
328  */
329 extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
330  SDL_LogPriority priority,
331  const char *fmt, va_list ap);
332 
333 /**
334  * The prototype for the log output callback function.
335  *
336  * This function is called by SDL when there is new text to be logged.
337  *
338  * \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
339  * \param category the category of the message
340  * \param priority the priority of the message
341  * \param message the message being output
342  */
343 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
344 
345 /**
346  * Get the current log output function.
347  *
348  * \param callback an SDL_LogOutputFunction filled in with the current log
349  * callback
350  * \param userdata a pointer filled in with the pointer that is passed to
351  * `callback`
352  *
353  * \sa SDL_LogSetOutputFunction
354  */
355 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
356 
357 /**
358  * Replace the default log output function with one of your own.
359  *
360  * \param callback an SDL_LogOutputFunction to call instead of the default
361  * \param userdata a pointer that is passed to `callback`
362  *
363  * \sa SDL_LogGetOutputFunction
364  */
365 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
366 
367 
368 /* Ends C function definitions when using C++ */
369 #ifdef __cplusplus
370 }
371 #endif
372 #include "close_code.h"
373 
374 #endif /* SDL_log_h_ */
375 
376 /* vi: set ts=4 sw=4 expandtab: */
void SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata)
SDL_LogPriority SDL_LogGetPriority(int category)
void SDL_LogSetAllPriority(SDL_LogPriority priority)
void SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(1)
void SDL_LogMessageV(int category, SDL_LogPriority priority, const char *fmt, va_list ap)
void SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata)
void SDL_LogResetPriorities(void)
SDL_LogPriority
The predefined log priorities.
Definition: SDL_log.h:102
void SDL_LogCritical(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:343
void SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
void SDL_LogSetPriority(int category, SDL_LogPriority priority)
SDL_LogCategory
The predefined log categories.
Definition: SDL_log.h:64
void SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
#define SDL_PRINTF_FORMAT_STRING
Definition: SDL_stdinc.h:334
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_FUNC(fmtargnumber)
Definition: SDL_stdinc.h:341