packages/sdl2.nuget.2.0.22/build/native/include/SDL_log.h

   1 /*
   2   Simple DirectMedia Layer
   3   Copyright (C) 1997-2022 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 {
  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  */
 102 typedef 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  * \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                                              const char *fmt, va_list ap);
 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 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  */
 367 typedef 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  */
 381 extern 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  */
 393 extern 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: */