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