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 46 extern "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 */ 64 typedef 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 */ 102 typedef 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 */ 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 SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); 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 363 * SDL_LogSetOutputFunction(). 364 * \param category the category of the message. 365 * \param priority the priority of the message. 366 * \param message the message being output. 367 */ 368 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); 369 370 /** 371 * Get the current log output function. 372 * 373 * \param callback an SDL_LogOutputFunction filled in with the current log 374 * callback. 375 * \param userdata a pointer filled in with the pointer that is passed to 376 * `callback`. 377 * 378 * \since This function is available since SDL 2.0.0. 379 * 380 * \sa SDL_LogSetOutputFunction 381 */ 382 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata); 383 384 /** 385 * Replace the default log output function with one of your own. 386 * 387 * \param callback an SDL_LogOutputFunction to call instead of the default. 388 * \param userdata a pointer that is passed to `callback`. 389 * 390 * \since This function is available since SDL 2.0.0. 391 * 392 * \sa SDL_LogGetOutputFunction 393 */ 394 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata); 395 396 397 /* Ends C function definitions when using C++ */ 398 #ifdef __cplusplus 399 } 400 #endif 401 #include "close_code.h" 402 403 #endif /* SDL_log_h_ */ 404 405 /* vi: set ts=4 sw=4 expandtab: */