1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 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 * # CategoryLog
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 *
33 * - Windows: debug output stream
34 * - Android: log output
35 * - Others: standard error output (stderr)
36 */
37
38#ifndef SDL_log_h_
39#define SDL_log_h_
40
41#include "SDL_stdinc.h"
42
43#include "begin_code.h"
44/* Set up for C function definitions, even when using C++ */
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49
50/**
51 * The maximum size of a log message prior to SDL 2.0.24
52 *
53 * As of 2.0.24 there is no limit to the length of SDL log messages.
54 */
55#define SDL_MAX_LOG_MESSAGE 4096
56
57/**
58 * The predefined log categories
59 *
60 * By default the application category is enabled at the INFO level, the
61 * assert category is enabled at the WARN level, test is enabled at the
62 * VERBOSE level and all other categories are enabled at the ERROR level.
63 */
64typedef enum SDL_LogCategory
65{
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,
75
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,
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 */
96 SDL_LOG_CATEGORY_CUSTOM
97} SDL_LogCategory;
98
99/**
100 * The predefined log priorities
101 */
102typedef enum SDL_LogPriority
103{
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
111} SDL_LogPriority;
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 */
123extern 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 */
136extern 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 */
149extern 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 */
161extern 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 * \param ... additional parameters matching % tokens in the `fmt` string, if
168 * any.
169 *
170 * \since This function is available since SDL 2.0.0.
171 *
172 * \sa SDL_LogCritical
173 * \sa SDL_LogDebug
174 * \sa SDL_LogError
175 * \sa SDL_LogInfo
176 * \sa SDL_LogMessage
177 * \sa SDL_LogMessageV
178 * \sa SDL_LogVerbose
179 * \sa SDL_LogWarn
180 */
181extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
182
183/**
184 * Log a message with SDL_LOG_PRIORITY_VERBOSE.
185 *
186 * \param category the category of the message.
187 * \param fmt a printf() style message format string.
188 * \param ... additional parameters matching % tokens in the **fmt** string,
189 * if any.
190 *
191 * \since This function is available since SDL 2.0.0.
192 *
193 * \sa SDL_Log
194 * \sa SDL_LogCritical
195 * \sa SDL_LogDebug
196 * \sa SDL_LogError
197 * \sa SDL_LogInfo
198 * \sa SDL_LogMessage
199 * \sa SDL_LogMessageV
200 * \sa SDL_LogWarn
201 */
202extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
203
204/**
205 * Log a message with SDL_LOG_PRIORITY_DEBUG.
206 *
207 * \param category the category of the message.
208 * \param fmt a printf() style message format string.
209 * \param ... additional parameters matching % tokens in the **fmt** string,
210 * if any.
211 *
212 * \since This function is available since SDL 2.0.0.
213 *
214 * \sa SDL_Log
215 * \sa SDL_LogCritical
216 * \sa SDL_LogError
217 * \sa SDL_LogInfo
218 * \sa SDL_LogMessage
219 * \sa SDL_LogMessageV
220 * \sa SDL_LogVerbose
221 * \sa SDL_LogWarn
222 */
223extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
224
225/**
226 * Log a message with SDL_LOG_PRIORITY_INFO.
227 *
228 * \param category the category of the message.
229 * \param fmt a printf() style message format string.
230 * \param ... additional parameters matching % tokens in the **fmt** string,
231 * if any.
232 *
233 * \since This function is available since SDL 2.0.0.
234 *
235 * \sa SDL_Log
236 * \sa SDL_LogCritical
237 * \sa SDL_LogDebug
238 * \sa SDL_LogError
239 * \sa SDL_LogMessage
240 * \sa SDL_LogMessageV
241 * \sa SDL_LogVerbose
242 * \sa SDL_LogWarn
243 */
244extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
245
246/**
247 * Log a message with SDL_LOG_PRIORITY_WARN.
248 *
249 * \param category the category of the message.
250 * \param fmt a printf() style message format string.
251 * \param ... additional parameters matching % tokens in the **fmt** string,
252 * if any.
253 *
254 * \since This function is available since SDL 2.0.0.
255 *
256 * \sa SDL_Log
257 * \sa SDL_LogCritical
258 * \sa SDL_LogDebug
259 * \sa SDL_LogError
260 * \sa SDL_LogInfo
261 * \sa SDL_LogMessage
262 * \sa SDL_LogMessageV
263 * \sa SDL_LogVerbose
264 */
265extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
266
267/**
268 * Log a message with SDL_LOG_PRIORITY_ERROR.
269 *
270 * \param category the category of the message.
271 * \param fmt a printf() style message format string.
272 * \param ... additional parameters matching % tokens in the **fmt** string,
273 * if any.
274 *
275 * \since This function is available since SDL 2.0.0.
276 *
277 * \sa SDL_Log
278 * \sa SDL_LogCritical
279 * \sa SDL_LogDebug
280 * \sa SDL_LogInfo
281 * \sa SDL_LogMessage
282 * \sa SDL_LogMessageV
283 * \sa SDL_LogVerbose
284 * \sa SDL_LogWarn
285 */
286extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
287
288/**
289 * Log a message with SDL_LOG_PRIORITY_CRITICAL.
290 *
291 * \param category the category of the message.
292 * \param fmt a printf() style message format string.
293 * \param ... additional parameters matching % tokens in the **fmt** string,
294 * if any.
295 *
296 * \since This function is available since SDL 2.0.0.
297 *
298 * \sa SDL_Log
299 * \sa SDL_LogDebug
300 * \sa SDL_LogError
301 * \sa SDL_LogInfo
302 * \sa SDL_LogMessage
303 * \sa SDL_LogMessageV
304 * \sa SDL_LogVerbose
305 * \sa SDL_LogWarn
306 */
307extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
308
309/**
310 * Log a message with the specified category and priority.
311 *
312 * \param category the category of the message.
313 * \param priority the priority of the message.
314 * \param fmt a printf() style message format string.
315 * \param ... additional parameters matching % tokens in the **fmt** string,
316 * if any.
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_LogMessageV
326 * \sa SDL_LogVerbose
327 * \sa SDL_LogWarn
328 */
329extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
330 SDL_LogPriority priority,
331 SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
332
333/**
334 * Log a message with the specified category and priority.
335 *
336 * \param category the category of the message.
337 * \param priority the priority of the message.
338 * \param fmt a printf() style message format string.
339 * \param ap a variable argument list.
340 *
341 * \since This function is available since SDL 2.0.0.
342 *
343 * \sa SDL_Log
344 * \sa SDL_LogCritical
345 * \sa SDL_LogDebug
346 * \sa SDL_LogError
347 * \sa SDL_LogInfo
348 * \sa SDL_LogMessage
349 * \sa SDL_LogVerbose
350 * \sa SDL_LogWarn
351 */
352extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
353 SDL_LogPriority priority,
354 SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
355
356/**
357 * The prototype for the log output callback function.
358 *
359 * This function is called by SDL when there is new text to be logged.
360 *
361 * \param userdata what was passed as `userdata` to
362 * 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 */
367typedef 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 */
381extern 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 */
393extern 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: */
405