early-access version 2281

externals/SDL/include/SDL_timer.h

@@ -42,24 +42,66 @@ extern "C" {
  *
  * This value wraps if the program runs for more than ~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.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_TICKS_PASSED
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
 
 /**
- * Compare SDL ticks values, and return true if `A` has passed `B`.
+ * 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 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:
  *
- * ```c++
- * Uint32 timeout = SDL_GetTicks() + 100;
+ * ```c
+ * const Uint64 timeout = SDL_GetTicks64() + 100;
+ * while (SDL_GetTicks64() < timeout) {
+ *     // ... do work until timeout has elapsed
+ * }
+ * ```
+ *
+ * \returns an unsigned 64-bit value representing the number of milliseconds
+ *          since the SDL library initialized.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void);
+
+/**
+ * Compare 32-bit SDL ticks values, and return true if `A` has passed `B`.
+ *
+ * This should be used with results from SDL_GetTicks(), as this macro
+ * attempts to deal with the 32-bit counter wrapping back to zero every ~49
+ * days, but should _not_ be used with SDL_GetTicks64(), which does not have
+ * that problem.
+ *
+ * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could
+ * do this:
+ *
+ * ```c
+ * const Uint32 timeout = SDL_GetTicks() + 100;
  * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
  *     // ... do work until timeout has elapsed
  * }
  * ```
+ *
+ * Note that this does not handle tick differences greater
+ * than 2^31 so take care when using the above kind of code
+ * with large timeout delays (tens of days).
  */
 #define SDL_TICKS_PASSED(A, B)  ((Sint32)((B) - (A)) <= 0)
 
@@ -74,6 +116,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
  *
  * \returns the current counter value.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_GetPerformanceFrequency
  */
 extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
@@ -97,6 +141,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
  * scheduling.
  *
  * \param ms the number of milliseconds to delay
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
 
@@ -143,6 +189,8 @@ typedef int SDL_TimerID;
  * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
  *          information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_RemoveTimer
  */
 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
@@ -156,6 +204,8 @@ extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
  * \returns SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't
  *          found.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
  * \sa SDL_AddTimer
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id);