🛠️🐜 Antkeeper superbuild with dependencies included https://antkeeper.com
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

404 lines
11 KiB

  1. /*
  2. Simple DirectMedia Layer
  3. Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
  4. This software is provided 'as-is', without any express or implied
  5. warranty. In no event will the authors be held liable for any damages
  6. arising from the use of this software.
  7. Permission is granted to anyone to use this software for any purpose,
  8. including commercial applications, and to alter it and redistribute it
  9. freely, subject to the following restrictions:
  10. 1. The origin of this software must not be misrepresented; you must not
  11. claim that you wrote the original software. If you use this software
  12. in a product, an acknowledgment in the product documentation would be
  13. appreciated but is not required.
  14. 2. Altered source versions must be plainly marked as such, and must not be
  15. misrepresented as being the original software.
  16. 3. This notice may not be removed or altered from any source distribution.
  17. */
  18. /**
  19. * \file SDL_log.h
  20. *
  21. * Simple log messages with categories and priorities.
  22. *
  23. * By default logs are quiet, but if you're debugging SDL you might want:
  24. *
  25. * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
  26. *
  27. * Here's where the messages go on different platforms:
  28. * Windows: debug output stream
  29. * Android: log output
  30. * Others: standard error output (stderr)
  31. */
  32. #ifndef SDL_log_h_
  33. #define SDL_log_h_
  34. #include "SDL_stdinc.h"
  35. #include "begin_code.h"
  36. /* Set up for C function definitions, even when using C++ */
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40. /**
  41. * \brief The maximum size of a log message prior to SDL 2.0.24
  42. *
  43. * As of 2.0.24 there is no limit to the length of SDL log messages.
  44. */
  45. #define SDL_MAX_LOG_MESSAGE 4096
  46. /**
  47. * \brief The predefined log categories
  48. *
  49. * By default the application category is enabled at the INFO level,
  50. * the assert category is enabled at the WARN level, test is enabled
  51. * at the VERBOSE level and all other categories are enabled at the
  52. * CRITICAL level.
  53. */
  54. typedef enum
  55. {
  56. SDL_LOG_CATEGORY_APPLICATION,
  57. SDL_LOG_CATEGORY_ERROR,
  58. SDL_LOG_CATEGORY_ASSERT,
  59. SDL_LOG_CATEGORY_SYSTEM,
  60. SDL_LOG_CATEGORY_AUDIO,
  61. SDL_LOG_CATEGORY_VIDEO,
  62. SDL_LOG_CATEGORY_RENDER,
  63. SDL_LOG_CATEGORY_INPUT,
  64. SDL_LOG_CATEGORY_TEST,
  65. /* Reserved for future SDL library use */
  66. SDL_LOG_CATEGORY_RESERVED1,
  67. SDL_LOG_CATEGORY_RESERVED2,
  68. SDL_LOG_CATEGORY_RESERVED3,
  69. SDL_LOG_CATEGORY_RESERVED4,
  70. SDL_LOG_CATEGORY_RESERVED5,
  71. SDL_LOG_CATEGORY_RESERVED6,
  72. SDL_LOG_CATEGORY_RESERVED7,
  73. SDL_LOG_CATEGORY_RESERVED8,
  74. SDL_LOG_CATEGORY_RESERVED9,
  75. SDL_LOG_CATEGORY_RESERVED10,
  76. /* Beyond this point is reserved for application use, e.g.
  77. enum {
  78. MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
  79. MYAPP_CATEGORY_AWESOME2,
  80. MYAPP_CATEGORY_AWESOME3,
  81. ...
  82. };
  83. */
  84. SDL_LOG_CATEGORY_CUSTOM
  85. } SDL_LogCategory;
  86. /**
  87. * \brief The predefined log priorities
  88. */
  89. typedef enum
  90. {
  91. SDL_LOG_PRIORITY_VERBOSE = 1,
  92. SDL_LOG_PRIORITY_DEBUG,
  93. SDL_LOG_PRIORITY_INFO,
  94. SDL_LOG_PRIORITY_WARN,
  95. SDL_LOG_PRIORITY_ERROR,
  96. SDL_LOG_PRIORITY_CRITICAL,
  97. SDL_NUM_LOG_PRIORITIES
  98. } SDL_LogPriority;
  99. /**
  100. * Set the priority of all log categories.
  101. *
  102. * \param priority the SDL_LogPriority to assign
  103. *
  104. * \since This function is available since SDL 2.0.0.
  105. *
  106. * \sa SDL_LogSetPriority
  107. */
  108. extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
  109. /**
  110. * Set the priority of a particular log category.
  111. *
  112. * \param category the category to assign a priority to
  113. * \param priority the SDL_LogPriority to assign
  114. *
  115. * \since This function is available since SDL 2.0.0.
  116. *
  117. * \sa SDL_LogGetPriority
  118. * \sa SDL_LogSetAllPriority
  119. */
  120. extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
  121. SDL_LogPriority priority);
  122. /**
  123. * Get the priority of a particular log category.
  124. *
  125. * \param category the category to query
  126. * \returns the SDL_LogPriority for the requested category
  127. *
  128. * \since This function is available since SDL 2.0.0.
  129. *
  130. * \sa SDL_LogSetPriority
  131. */
  132. extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
  133. /**
  134. * Reset all priorities to default.
  135. *
  136. * This is called by SDL_Quit().
  137. *
  138. * \since This function is available since SDL 2.0.0.
  139. *
  140. * \sa SDL_LogSetAllPriority
  141. * \sa SDL_LogSetPriority
  142. */
  143. extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
  144. /**
  145. * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
  146. *
  147. * = * \param fmt a printf() style message format string
  148. *
  149. * \param ... additional parameters matching % tokens in the `fmt` string, if
  150. * any
  151. *
  152. * \since This function is available since SDL 2.0.0.
  153. *
  154. * \sa SDL_LogCritical
  155. * \sa SDL_LogDebug
  156. * \sa SDL_LogError
  157. * \sa SDL_LogInfo
  158. * \sa SDL_LogMessage
  159. * \sa SDL_LogMessageV
  160. * \sa SDL_LogVerbose
  161. * \sa SDL_LogWarn
  162. */
  163. extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
  164. /**
  165. * Log a message with SDL_LOG_PRIORITY_VERBOSE.
  166. *
  167. * \param category the category of the message
  168. * \param fmt a printf() style message format string
  169. * \param ... additional parameters matching % tokens in the **fmt** string,
  170. * if any
  171. *
  172. * \since This function is available since SDL 2.0.0.
  173. *
  174. * \sa SDL_Log
  175. * \sa SDL_LogCritical
  176. * \sa SDL_LogDebug
  177. * \sa SDL_LogError
  178. * \sa SDL_LogInfo
  179. * \sa SDL_LogMessage
  180. * \sa SDL_LogMessageV
  181. * \sa SDL_LogWarn
  182. */
  183. extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  184. /**
  185. * Log a message with SDL_LOG_PRIORITY_DEBUG.
  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_LogError
  197. * \sa SDL_LogInfo
  198. * \sa SDL_LogMessage
  199. * \sa SDL_LogMessageV
  200. * \sa SDL_LogVerbose
  201. * \sa SDL_LogWarn
  202. */
  203. extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  204. /**
  205. * Log a message with SDL_LOG_PRIORITY_INFO.
  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_LogDebug
  217. * \sa SDL_LogError
  218. * \sa SDL_LogMessage
  219. * \sa SDL_LogMessageV
  220. * \sa SDL_LogVerbose
  221. * \sa SDL_LogWarn
  222. */
  223. extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  224. /**
  225. * Log a message with SDL_LOG_PRIORITY_WARN.
  226. *
  227. * \param category the category of the message
  228. * \param fmt a printf() style message format string
  229. * \param ... additional parameters matching % tokens in the **fmt** string,
  230. * if any
  231. *
  232. * \since This function is available since SDL 2.0.0.
  233. *
  234. * \sa SDL_Log
  235. * \sa SDL_LogCritical
  236. * \sa SDL_LogDebug
  237. * \sa SDL_LogError
  238. * \sa SDL_LogInfo
  239. * \sa SDL_LogMessage
  240. * \sa SDL_LogMessageV
  241. * \sa SDL_LogVerbose
  242. */
  243. extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  244. /**
  245. * Log a message with SDL_LOG_PRIORITY_ERROR.
  246. *
  247. * \param category the category of the message
  248. * \param fmt a printf() style message format string
  249. * \param ... additional parameters matching % tokens in the **fmt** string,
  250. * if any
  251. *
  252. * \since This function is available since SDL 2.0.0.
  253. *
  254. * \sa SDL_Log
  255. * \sa SDL_LogCritical
  256. * \sa SDL_LogDebug
  257. * \sa SDL_LogInfo
  258. * \sa SDL_LogMessage
  259. * \sa SDL_LogMessageV
  260. * \sa SDL_LogVerbose
  261. * \sa SDL_LogWarn
  262. */
  263. extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  264. /**
  265. * Log a message with SDL_LOG_PRIORITY_CRITICAL.
  266. *
  267. * \param category the category of the message
  268. * \param fmt a printf() style message format string
  269. * \param ... additional parameters matching % tokens in the **fmt** string,
  270. * if any
  271. *
  272. * \since This function is available since SDL 2.0.0.
  273. *
  274. * \sa SDL_Log
  275. * \sa SDL_LogDebug
  276. * \sa SDL_LogError
  277. * \sa SDL_LogInfo
  278. * \sa SDL_LogMessage
  279. * \sa SDL_LogMessageV
  280. * \sa SDL_LogVerbose
  281. * \sa SDL_LogWarn
  282. */
  283. extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  284. /**
  285. * Log a message with the specified category and priority.
  286. *
  287. * \param category the category of the message
  288. * \param priority the priority of the message
  289. * \param fmt a printf() style message format string
  290. * \param ... additional parameters matching % tokens in the **fmt** string,
  291. * if any
  292. *
  293. * \since This function is available since SDL 2.0.0.
  294. *
  295. * \sa SDL_Log
  296. * \sa SDL_LogCritical
  297. * \sa SDL_LogDebug
  298. * \sa SDL_LogError
  299. * \sa SDL_LogInfo
  300. * \sa SDL_LogMessageV
  301. * \sa SDL_LogVerbose
  302. * \sa SDL_LogWarn
  303. */
  304. extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
  305. SDL_LogPriority priority,
  306. SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
  307. /**
  308. * Log a message with the specified category and priority.
  309. *
  310. * \param category the category of the message
  311. * \param priority the priority of the message
  312. * \param fmt a printf() style message format string
  313. * \param ap a variable argument list
  314. *
  315. * \since This function is available since SDL 2.0.0.
  316. *
  317. * \sa SDL_Log
  318. * \sa SDL_LogCritical
  319. * \sa SDL_LogDebug
  320. * \sa SDL_LogError
  321. * \sa SDL_LogInfo
  322. * \sa SDL_LogMessage
  323. * \sa SDL_LogVerbose
  324. * \sa SDL_LogWarn
  325. */
  326. extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
  327. SDL_LogPriority priority,
  328. const char *fmt, va_list ap);
  329. /**
  330. * The prototype for the log output callback function.
  331. *
  332. * This function is called by SDL when there is new text to be logged.
  333. *
  334. * \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
  335. * \param category the category of the message
  336. * \param priority the priority of the message
  337. * \param message the message being output
  338. */
  339. typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
  340. /**
  341. * Get the current log output function.
  342. *
  343. * \param callback an SDL_LogOutputFunction filled in with the current log
  344. * callback
  345. * \param userdata a pointer filled in with the pointer that is passed to
  346. * `callback`
  347. *
  348. * \since This function is available since SDL 2.0.0.
  349. *
  350. * \sa SDL_LogSetOutputFunction
  351. */
  352. extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
  353. /**
  354. * Replace the default log output function with one of your own.
  355. *
  356. * \param callback an SDL_LogOutputFunction to call instead of the default
  357. * \param userdata a pointer that is passed to `callback`
  358. *
  359. * \since This function is available since SDL 2.0.0.
  360. *
  361. * \sa SDL_LogGetOutputFunction
  362. */
  363. extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
  364. /* Ends C function definitions when using C++ */
  365. #ifdef __cplusplus
  366. }
  367. #endif
  368. #include "close_code.h"
  369. #endif /* SDL_log_h_ */
  370. /* vi: set ts=4 sw=4 expandtab: */