2 Simple DirectMedia Layer
3 Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
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.
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:
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.
25 * Simple log messages with categories and priorities.
27 * By default logs are quiet, but if you're debugging SDL you might want:
29 * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
31 * Here's where the messages go on different platforms:
32 * Windows: debug output stream
34 * Others: standard error output (stderr)
40 #include "SDL_stdinc.h"
42 #include "begin_code.h"
43 /* Set up for C function definitions, even when using C++ */
50 * \brief The maximum size of a log message
52 * Messages longer than the maximum size will be truncated
54 #define SDL_MAX_LOG_MESSAGE 4096
57 * \brief The predefined log categories
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
66 SDL_LOG_CATEGORY_APPLICATION,
67 SDL_LOG_CATEGORY_ERROR,
68 SDL_LOG_CATEGORY_ASSERT,
69 SDL_LOG_CATEGORY_SYSTEM,
70 SDL_LOG_CATEGORY_AUDIO,
71 SDL_LOG_CATEGORY_VIDEO,
72 SDL_LOG_CATEGORY_RENDER,
73 SDL_LOG_CATEGORY_INPUT,
74 SDL_LOG_CATEGORY_TEST,
76 /* Reserved for future SDL library use */
77 SDL_LOG_CATEGORY_RESERVED1,
78 SDL_LOG_CATEGORY_RESERVED2,
79 SDL_LOG_CATEGORY_RESERVED3,
80 SDL_LOG_CATEGORY_RESERVED4,
81 SDL_LOG_CATEGORY_RESERVED5,
82 SDL_LOG_CATEGORY_RESERVED6,
83 SDL_LOG_CATEGORY_RESERVED7,
84 SDL_LOG_CATEGORY_RESERVED8,
85 SDL_LOG_CATEGORY_RESERVED9,
86 SDL_LOG_CATEGORY_RESERVED10,
88 /* Beyond this point is reserved for application use, e.g.
90 MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
91 MYAPP_CATEGORY_AWESOME2,
92 MYAPP_CATEGORY_AWESOME3,
96 SDL_LOG_CATEGORY_CUSTOM
100 * \brief The predefined log priorities
104 SDL_LOG_PRIORITY_VERBOSE = 1,
105 SDL_LOG_PRIORITY_DEBUG,
106 SDL_LOG_PRIORITY_INFO,
107 SDL_LOG_PRIORITY_WARN,
108 SDL_LOG_PRIORITY_ERROR,
109 SDL_LOG_PRIORITY_CRITICAL,
110 SDL_NUM_LOG_PRIORITIES
115 * Set the priority of all log categories.
117 * \param priority the SDL_LogPriority to assign
119 * \since This function is available since SDL 2.0.0.
121 * \sa SDL_LogSetPriority
123 extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
126 * Set the priority of a particular log category.
128 * \param category the category to assign a priority to
129 * \param priority the SDL_LogPriority to assign
131 * \since This function is available since SDL 2.0.0.
133 * \sa SDL_LogGetPriority
134 * \sa SDL_LogSetAllPriority
136 extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
137 SDL_LogPriority priority);
140 * Get the priority of a particular log category.
142 * \param category the category to query
143 * \returns the SDL_LogPriority for the requested category
145 * \since This function is available since SDL 2.0.0.
147 * \sa SDL_LogSetPriority
149 extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
152 * Reset all priorities to default.
154 * This is called by SDL_Quit().
156 * \since This function is available since SDL 2.0.0.
158 * \sa SDL_LogSetAllPriority
159 * \sa SDL_LogSetPriority
161 extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
164 * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
166 * = * \param fmt a printf() style message format string
168 * \param ... additional parameters matching % tokens in the `fmt` string, if
171 * \since This function is available since SDL 2.0.0.
173 * \sa SDL_LogCritical
178 * \sa SDL_LogMessageV
182 extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
185 * Log a message with SDL_LOG_PRIORITY_VERBOSE.
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,
192 * \since This function is available since SDL 2.0.0.
195 * \sa SDL_LogCritical
200 * \sa SDL_LogMessageV
203 extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
206 * Log a message with SDL_LOG_PRIORITY_DEBUG.
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,
213 * \since This function is available since SDL 2.0.0.
216 * \sa SDL_LogCritical
220 * \sa SDL_LogMessageV
224 extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
227 * Log a message with SDL_LOG_PRIORITY_INFO.
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,
234 * \since This function is available since SDL 2.0.0.
237 * \sa SDL_LogCritical
241 * \sa SDL_LogMessageV
245 extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
248 * Log a message with SDL_LOG_PRIORITY_WARN.
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,
255 * \since This function is available since SDL 2.0.0.
258 * \sa SDL_LogCritical
263 * \sa SDL_LogMessageV
266 extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
269 * Log a message with SDL_LOG_PRIORITY_ERROR.
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,
276 * \since This function is available since SDL 2.0.0.
279 * \sa SDL_LogCritical
283 * \sa SDL_LogMessageV
287 extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
290 * Log a message with SDL_LOG_PRIORITY_CRITICAL.
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,
297 * \since This function is available since SDL 2.0.0.
304 * \sa SDL_LogMessageV
308 extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
311 * Log a message with the specified category and priority.
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,
319 * \since This function is available since SDL 2.0.0.
322 * \sa SDL_LogCritical
326 * \sa SDL_LogMessageV
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);
335 * Log a message with the specified category and priority.
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
342 * \since This function is available since SDL 2.0.0.
345 * \sa SDL_LogCritical
353 extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
354 SDL_LogPriority priority,
355 const char *fmt, va_list ap);
358 * The prototype for the log output callback function.
360 * This function is called by SDL when there is new text to be logged.
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
367 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
370 * Get the current log output function.
372 * \param callback an SDL_LogOutputFunction filled in with the current log
374 * \param userdata a pointer filled in with the pointer that is passed to
377 * \since This function is available since SDL 2.0.0.
379 * \sa SDL_LogSetOutputFunction
381 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
384 * Replace the default log output function with one of your own.
386 * \param callback an SDL_LogOutputFunction to call instead of the default
387 * \param userdata a pointer that is passed to `callback`
389 * \since This function is available since SDL 2.0.0.
391 * \sa SDL_LogGetOutputFunction
393 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
396 /* Ends C function definitions when using C++ */
400 #include "close_code.h"
402 #endif /* SDL_log_h_ */
404 /* vi: set ts=4 sw=4 expandtab: */