SDL_log.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538
  1. /*
  2. Simple DirectMedia Layer
  3. Copyright (C) 1997-2025 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. * # CategoryLog
  20. *
  21. * Simple log messages with priorities and categories. A message's
  22. * SDL_LogPriority signifies how important the message is. A message's
  23. * SDL_LogCategory signifies from what domain it belongs to. Every category
  24. * has a minimum priority specified: when a message belongs to that category,
  25. * it will only be sent out if it has that minimum priority or higher.
  26. *
  27. * SDL's own logs are sent below the default priority threshold, so they are
  28. * quiet by default.
  29. *
  30. * You can change the log verbosity programmatically using
  31. * SDL_SetLogPriority() or with SDL_SetHint(SDL_HINT_LOGGING, ...), or with
  32. * the "SDL_LOGGING" environment variable. This variable is a comma separated
  33. * set of category=level tokens that define the default logging levels for SDL
  34. * applications.
  35. *
  36. * The category can be a numeric category, one of "app", "error", "assert",
  37. * "system", "audio", "video", "render", "input", "test", or `*` for any
  38. * unspecified category.
  39. *
  40. * The level can be a numeric level, one of "trace", "verbose", "debug",
  41. * "info", "warn", "error", "critical", or "quiet" to disable that category.
  42. *
  43. * You can omit the category if you want to set the logging level for all
  44. * categories.
  45. *
  46. * If this hint isn't set, the default log levels are equivalent to:
  47. *
  48. * `app=info,assert=warn,test=verbose,*=error`
  49. *
  50. * Here's where the messages go on different platforms:
  51. *
  52. * - Windows: debug output stream
  53. * - Android: log output
  54. * - Others: standard error output (stderr)
  55. *
  56. * You don't need to have a newline (`\n`) on the end of messages, the
  57. * functions will do that for you. For consistent behavior cross-platform, you
  58. * shouldn't have any newlines in messages, such as to log multiple lines in
  59. * one call; unusual platform-specific behavior can be observed in such usage.
  60. * Do one log call per line instead, with no newlines in messages.
  61. *
  62. * Each log call is atomic, so you won't see log messages cut off one another
  63. * when logging from multiple threads.
  64. */
  65. #ifndef SDL_log_h_
  66. #define SDL_log_h_
  67. #include <SDL3/SDL_stdinc.h>
  68. #include <SDL3/SDL_begin_code.h>
  69. /* Set up for C function definitions, even when using C++ */
  70. #ifdef __cplusplus
  71. extern "C" {
  72. #endif
  73. /**
  74. * The predefined log categories
  75. *
  76. * By default the application and gpu categories are enabled at the INFO
  77. * level, the assert category is enabled at the WARN level, test is enabled at
  78. * the VERBOSE level and all other categories are enabled at the ERROR level.
  79. *
  80. * \since This enum is available since SDL 3.2.0.
  81. */
  82. typedef enum SDL_LogCategory
  83. {
  84. SDL_LOG_CATEGORY_APPLICATION,
  85. SDL_LOG_CATEGORY_ERROR,
  86. SDL_LOG_CATEGORY_ASSERT,
  87. SDL_LOG_CATEGORY_SYSTEM,
  88. SDL_LOG_CATEGORY_AUDIO,
  89. SDL_LOG_CATEGORY_VIDEO,
  90. SDL_LOG_CATEGORY_RENDER,
  91. SDL_LOG_CATEGORY_INPUT,
  92. SDL_LOG_CATEGORY_TEST,
  93. SDL_LOG_CATEGORY_GPU,
  94. /* Reserved for future SDL library use */
  95. SDL_LOG_CATEGORY_RESERVED2,
  96. SDL_LOG_CATEGORY_RESERVED3,
  97. SDL_LOG_CATEGORY_RESERVED4,
  98. SDL_LOG_CATEGORY_RESERVED5,
  99. SDL_LOG_CATEGORY_RESERVED6,
  100. SDL_LOG_CATEGORY_RESERVED7,
  101. SDL_LOG_CATEGORY_RESERVED8,
  102. SDL_LOG_CATEGORY_RESERVED9,
  103. SDL_LOG_CATEGORY_RESERVED10,
  104. /* Beyond this point is reserved for application use, e.g.
  105. enum {
  106. MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
  107. MYAPP_CATEGORY_AWESOME2,
  108. MYAPP_CATEGORY_AWESOME3,
  109. ...
  110. };
  111. */
  112. SDL_LOG_CATEGORY_CUSTOM
  113. } SDL_LogCategory;
  114. /**
  115. * The predefined log priorities
  116. *
  117. * \since This enum is available since SDL 3.2.0.
  118. */
  119. typedef enum SDL_LogPriority
  120. {
  121. SDL_LOG_PRIORITY_INVALID,
  122. SDL_LOG_PRIORITY_TRACE,
  123. SDL_LOG_PRIORITY_VERBOSE,
  124. SDL_LOG_PRIORITY_DEBUG,
  125. SDL_LOG_PRIORITY_INFO,
  126. SDL_LOG_PRIORITY_WARN,
  127. SDL_LOG_PRIORITY_ERROR,
  128. SDL_LOG_PRIORITY_CRITICAL,
  129. SDL_LOG_PRIORITY_COUNT
  130. } SDL_LogPriority;
  131. /**
  132. * Set the priority of all log categories.
  133. *
  134. * \param priority the SDL_LogPriority to assign.
  135. *
  136. * \threadsafety It is safe to call this function from any thread.
  137. *
  138. * \since This function is available since SDL 3.2.0.
  139. *
  140. * \sa SDL_ResetLogPriorities
  141. * \sa SDL_SetLogPriority
  142. */
  143. extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
  144. /**
  145. * Set the priority of a particular log category.
  146. *
  147. * \param category the category to assign a priority to.
  148. * \param priority the SDL_LogPriority to assign.
  149. *
  150. * \threadsafety It is safe to call this function from any thread.
  151. *
  152. * \since This function is available since SDL 3.2.0.
  153. *
  154. * \sa SDL_GetLogPriority
  155. * \sa SDL_ResetLogPriorities
  156. * \sa SDL_SetLogPriorities
  157. */
  158. extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority);
  159. /**
  160. * Get the priority of a particular log category.
  161. *
  162. * \param category the category to query.
  163. * \returns the SDL_LogPriority for the requested category.
  164. *
  165. * \threadsafety It is safe to call this function from any thread.
  166. *
  167. * \since This function is available since SDL 3.2.0.
  168. *
  169. * \sa SDL_SetLogPriority
  170. */
  171. extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category);
  172. /**
  173. * Reset all priorities to default.
  174. *
  175. * This is called by SDL_Quit().
  176. *
  177. * \threadsafety It is safe to call this function from any thread.
  178. *
  179. * \since This function is available since SDL 3.2.0.
  180. *
  181. * \sa SDL_SetLogPriorities
  182. * \sa SDL_SetLogPriority
  183. */
  184. extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
  185. /**
  186. * Set the text prepended to log messages of a given priority.
  187. *
  188. * By default SDL_LOG_PRIORITY_INFO and below have no prefix, and
  189. * SDL_LOG_PRIORITY_WARN and higher have a prefix showing their priority, e.g.
  190. * "WARNING: ".
  191. *
  192. * \param priority the SDL_LogPriority to modify.
  193. * \param prefix the prefix to use for that log priority, or NULL to use no
  194. * prefix.
  195. * \returns true on success or false on failure; call SDL_GetError() for more
  196. * information.
  197. *
  198. * \threadsafety It is safe to call this function from any thread.
  199. *
  200. * \since This function is available since SDL 3.2.0.
  201. *
  202. * \sa SDL_SetLogPriorities
  203. * \sa SDL_SetLogPriority
  204. */
  205. extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix);
  206. /**
  207. * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
  208. *
  209. * \param fmt a printf() style message format string.
  210. * \param ... additional parameters matching % tokens in the `fmt` string, if
  211. * any.
  212. *
  213. * \threadsafety It is safe to call this function from any thread.
  214. *
  215. * \since This function is available since SDL 3.2.0.
  216. *
  217. * \sa SDL_LogCritical
  218. * \sa SDL_LogDebug
  219. * \sa SDL_LogError
  220. * \sa SDL_LogInfo
  221. * \sa SDL_LogMessage
  222. * \sa SDL_LogMessageV
  223. * \sa SDL_LogTrace
  224. * \sa SDL_LogVerbose
  225. * \sa SDL_LogWarn
  226. */
  227. extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
  228. /**
  229. * Log a message with SDL_LOG_PRIORITY_TRACE.
  230. *
  231. * \param category the category of the message.
  232. * \param fmt a printf() style message format string.
  233. * \param ... additional parameters matching % tokens in the **fmt** string,
  234. * if any.
  235. *
  236. * \threadsafety It is safe to call this function from any thread.
  237. *
  238. * \since This function is available since SDL 3.2.0.
  239. *
  240. * \sa SDL_Log
  241. * \sa SDL_LogCritical
  242. * \sa SDL_LogDebug
  243. * \sa SDL_LogError
  244. * \sa SDL_LogInfo
  245. * \sa SDL_LogMessage
  246. * \sa SDL_LogMessageV
  247. * \sa SDL_LogTrace
  248. * \sa SDL_LogVerbose
  249. * \sa SDL_LogWarn
  250. */
  251. extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  252. /**
  253. * Log a message with SDL_LOG_PRIORITY_VERBOSE.
  254. *
  255. * \param category the category of the message.
  256. * \param fmt a printf() style message format string.
  257. * \param ... additional parameters matching % tokens in the **fmt** string,
  258. * if any.
  259. *
  260. * \threadsafety It is safe to call this function from any thread.
  261. *
  262. * \since This function is available since SDL 3.2.0.
  263. *
  264. * \sa SDL_Log
  265. * \sa SDL_LogCritical
  266. * \sa SDL_LogDebug
  267. * \sa SDL_LogError
  268. * \sa SDL_LogInfo
  269. * \sa SDL_LogMessage
  270. * \sa SDL_LogMessageV
  271. * \sa SDL_LogWarn
  272. */
  273. extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  274. /**
  275. * Log a message with SDL_LOG_PRIORITY_DEBUG.
  276. *
  277. * \param category the category of the message.
  278. * \param fmt a printf() style message format string.
  279. * \param ... additional parameters matching % tokens in the **fmt** string,
  280. * if any.
  281. *
  282. * \threadsafety It is safe to call this function from any thread.
  283. *
  284. * \since This function is available since SDL 3.2.0.
  285. *
  286. * \sa SDL_Log
  287. * \sa SDL_LogCritical
  288. * \sa SDL_LogError
  289. * \sa SDL_LogInfo
  290. * \sa SDL_LogMessage
  291. * \sa SDL_LogMessageV
  292. * \sa SDL_LogTrace
  293. * \sa SDL_LogVerbose
  294. * \sa SDL_LogWarn
  295. */
  296. extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  297. /**
  298. * Log a message with SDL_LOG_PRIORITY_INFO.
  299. *
  300. * \param category the category of the message.
  301. * \param fmt a printf() style message format string.
  302. * \param ... additional parameters matching % tokens in the **fmt** string,
  303. * if any.
  304. *
  305. * \threadsafety It is safe to call this function from any thread.
  306. *
  307. * \since This function is available since SDL 3.2.0.
  308. *
  309. * \sa SDL_Log
  310. * \sa SDL_LogCritical
  311. * \sa SDL_LogDebug
  312. * \sa SDL_LogError
  313. * \sa SDL_LogMessage
  314. * \sa SDL_LogMessageV
  315. * \sa SDL_LogTrace
  316. * \sa SDL_LogVerbose
  317. * \sa SDL_LogWarn
  318. */
  319. extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  320. /**
  321. * Log a message with SDL_LOG_PRIORITY_WARN.
  322. *
  323. * \param category the category of the message.
  324. * \param fmt a printf() style message format string.
  325. * \param ... additional parameters matching % tokens in the **fmt** string,
  326. * if any.
  327. *
  328. * \threadsafety It is safe to call this function from any thread.
  329. *
  330. * \since This function is available since SDL 3.2.0.
  331. *
  332. * \sa SDL_Log
  333. * \sa SDL_LogCritical
  334. * \sa SDL_LogDebug
  335. * \sa SDL_LogError
  336. * \sa SDL_LogInfo
  337. * \sa SDL_LogMessage
  338. * \sa SDL_LogMessageV
  339. * \sa SDL_LogTrace
  340. * \sa SDL_LogVerbose
  341. */
  342. extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  343. /**
  344. * Log a message with SDL_LOG_PRIORITY_ERROR.
  345. *
  346. * \param category the category of the message.
  347. * \param fmt a printf() style message format string.
  348. * \param ... additional parameters matching % tokens in the **fmt** string,
  349. * if any.
  350. *
  351. * \threadsafety It is safe to call this function from any thread.
  352. *
  353. * \since This function is available since SDL 3.2.0.
  354. *
  355. * \sa SDL_Log
  356. * \sa SDL_LogCritical
  357. * \sa SDL_LogDebug
  358. * \sa SDL_LogInfo
  359. * \sa SDL_LogMessage
  360. * \sa SDL_LogMessageV
  361. * \sa SDL_LogTrace
  362. * \sa SDL_LogVerbose
  363. * \sa SDL_LogWarn
  364. */
  365. extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  366. /**
  367. * Log a message with SDL_LOG_PRIORITY_CRITICAL.
  368. *
  369. * \param category the category of the message.
  370. * \param fmt a printf() style message format string.
  371. * \param ... additional parameters matching % tokens in the **fmt** string,
  372. * if any.
  373. *
  374. * \threadsafety It is safe to call this function from any thread.
  375. *
  376. * \since This function is available since SDL 3.2.0.
  377. *
  378. * \sa SDL_Log
  379. * \sa SDL_LogDebug
  380. * \sa SDL_LogError
  381. * \sa SDL_LogInfo
  382. * \sa SDL_LogMessage
  383. * \sa SDL_LogMessageV
  384. * \sa SDL_LogTrace
  385. * \sa SDL_LogVerbose
  386. * \sa SDL_LogWarn
  387. */
  388. extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
  389. /**
  390. * Log a message with the specified category and priority.
  391. *
  392. * \param category the category of the message.
  393. * \param priority the priority of the message.
  394. * \param fmt a printf() style message format string.
  395. * \param ... additional parameters matching % tokens in the **fmt** string,
  396. * if any.
  397. *
  398. * \threadsafety It is safe to call this function from any thread.
  399. *
  400. * \since This function is available since SDL 3.2.0.
  401. *
  402. * \sa SDL_Log
  403. * \sa SDL_LogCritical
  404. * \sa SDL_LogDebug
  405. * \sa SDL_LogError
  406. * \sa SDL_LogInfo
  407. * \sa SDL_LogMessageV
  408. * \sa SDL_LogTrace
  409. * \sa SDL_LogVerbose
  410. * \sa SDL_LogWarn
  411. */
  412. extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category,
  413. SDL_LogPriority priority,
  414. SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
  415. /**
  416. * Log a message with the specified category and priority.
  417. *
  418. * \param category the category of the message.
  419. * \param priority the priority of the message.
  420. * \param fmt a printf() style message format string.
  421. * \param ap a variable argument list.
  422. *
  423. * \threadsafety It is safe to call this function from any thread.
  424. *
  425. * \since This function is available since SDL 3.2.0.
  426. *
  427. * \sa SDL_Log
  428. * \sa SDL_LogCritical
  429. * \sa SDL_LogDebug
  430. * \sa SDL_LogError
  431. * \sa SDL_LogInfo
  432. * \sa SDL_LogMessage
  433. * \sa SDL_LogTrace
  434. * \sa SDL_LogVerbose
  435. * \sa SDL_LogWarn
  436. */
  437. extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category,
  438. SDL_LogPriority priority,
  439. SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
  440. /**
  441. * The prototype for the log output callback function.
  442. *
  443. * This function is called by SDL when there is new text to be logged. A mutex
  444. * is held so that this function is never called by more than one thread at
  445. * once.
  446. *
  447. * \param userdata what was passed as `userdata` to
  448. * SDL_SetLogOutputFunction().
  449. * \param category the category of the message.
  450. * \param priority the priority of the message.
  451. * \param message the message being output.
  452. *
  453. * \since This datatype is available since SDL 3.2.0.
  454. */
  455. typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
  456. /**
  457. * Get the default log output function.
  458. *
  459. * \returns the default log output callback.
  460. *
  461. * \threadsafety It is safe to call this function from any thread.
  462. *
  463. * \since This function is available since SDL 3.2.0.
  464. *
  465. * \sa SDL_SetLogOutputFunction
  466. * \sa SDL_GetLogOutputFunction
  467. */
  468. extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void);
  469. /**
  470. * Get the current log output function.
  471. *
  472. * \param callback an SDL_LogOutputFunction filled in with the current log
  473. * callback.
  474. * \param userdata a pointer filled in with the pointer that is passed to
  475. * `callback`.
  476. *
  477. * \threadsafety It is safe to call this function from any thread.
  478. *
  479. * \since This function is available since SDL 3.2.0.
  480. *
  481. * \sa SDL_GetDefaultLogOutputFunction
  482. * \sa SDL_SetLogOutputFunction
  483. */
  484. extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
  485. /**
  486. * Replace the default log output function with one of your own.
  487. *
  488. * \param callback an SDL_LogOutputFunction to call instead of the default.
  489. * \param userdata a pointer that is passed to `callback`.
  490. *
  491. * \threadsafety It is safe to call this function from any thread.
  492. *
  493. * \since This function is available since SDL 3.2.0.
  494. *
  495. * \sa SDL_GetDefaultLogOutputFunction
  496. * \sa SDL_GetLogOutputFunction
  497. */
  498. extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata);
  499. /* Ends C function definitions when using C++ */
  500. #ifdef __cplusplus
  501. }
  502. #endif
  503. #include <SDL3/SDL_close_code.h>
  504. #endif /* SDL_log_h_ */