From 228219dcd4523ff38ee312e852fb50820fe4654f Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Sat, 23 Oct 2021 15:30:45 -0400 Subject: [PATCH] include: Improved SDL_GetTicks*() documentation a little. --- include/SDL_timer.h | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/include/SDL_timer.h b/include/SDL_timer.h index ed6be78c4..791f3b4c4 100644 --- a/include/SDL_timer.h +++ b/include/SDL_timer.h @@ -42,9 +42,11 @@ extern "C" { * * This value wraps if the program runs for more than ~49 days. * - * \deprecated This function is deprecated as of SDL 2.0.18; use - * SDL_GetTicks64() instead, where the value doesn't wrap - * every ~49 days. + * This function is not recommended as of SDL 2.0.18; use SDL_GetTicks64() + * instead, where the value doesn't wrap every ~49 days. There are places in + * SDL where we provide a 32-bit timestamp that can not change without + * breaking binary compatibility, though, so this function isn't officially + * deprecated. * * \returns an unsigned 32-bit value representing the number of milliseconds * since the SDL library initialized. @@ -53,15 +55,15 @@ extern "C" { * * \sa SDL_TICKS_PASSED */ -extern SDL_DEPRECATED DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); +extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); /** * Get the number of milliseconds since SDL library initialization. * * Note that you should not use the SDL_TICKS_PASSED macro with values * returned by this function, as that macro does clever math to compensate - * for the 32-bit overflow every ~49 days. 64-bit values can just be safely - * compared directly. + * for the 32-bit overflow every ~49 days that SDL_GetTicks() suffers from. + * 64-bit values from this function can be safely compared directly. * * For example, if you want to wait 100 ms, you could do this: * @@ -85,7 +87,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void); * days, but should _not_ be used with SDL_GetTicks64(), which does not have * that problem. * - * For example, if you want to wait 100 ms, you could do this: + * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could + * do this: * * ```c * const Uint32 timeout = SDL_GetTicks() + 100;