Subversion Repositories Games.Rick Dangerous

Rev

Blame | Last modification | View Log | Download | RSS feed

  1. /*
  2.   Simple DirectMedia Layer
  3.   Copyright (C) 1997-2023 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 prior to SDL 2.0.24
  51.  *
  52.  *  As of 2.0.24 there is no limit to the length of SDL log messages.
  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: */
  405.