Convert ticks to 64-bit, added nanosecond precision to the API

Fixes #5512 Fixes #6731
libsdl-org · Dec 2, 2022 · 8121bbd · 8121bbd
1 parent 764b899
commit 8121bbd
Show file tree

Hide file tree

Showing 96 changed files with 937 additions and 1,242 deletions.
diff --git a/WhatsNew.txt b/WhatsNew.txt
@@ -32,4 +32,10 @@ General:
 * Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which replace the SDL_CreateRGBSurface*()
 * Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat
 * Removed 'SDL_GL_CONTEXT_EGL' from OpenGL configuration attributes
-
+* SDL_GetTicks() now returns a 64-bit value and the tick values should be directly compared instead of using the SDL_TICKS_PASSED macro
+* Added SDL_GetTicksNS() to return the number of nanoseconds since the SDL library initialized
+* Added SDL_DelayNS() to specify a delay in nanoseconds, to the highest precision the system will support
+* Added SDL_WaitEventTimeoutNS() to wait for events with the highest possible precision
+* Added SDL_SemWaitTimeoutNS() to wait for a semaphore with the highest possible precision
+* Added SDL_CondWaitTimeoutNS() to wait for a condition variable the highest possible precision
+* The timestamp member of the SDL_Event structure is now in nanoseconds, filled in with SDL_GetTicksNS()
diff --git a/docs/README-migration.md b/docs/README-migration.md
@@ -31,6 +31,10 @@ LDFLAGS += $(shell pkg-config sdl3 --libs)
 The SDL3main and SDL3test libraries have been renamed SDL3_main and SDL3_test, respectively.
 
 
+## SDL_events.h
+
+The `timestamp` member of the SDL_Event structure now represents nanoseconds, and is populated with `SDL_GetTicksNS()`
+
 ## SDL_platform.h
 
 The preprocessor symbol __MACOSX__ has been renamed __MACOS__, and __IPHONEOS__ has been renamed __IOS__
@@ -223,6 +227,30 @@ The structures in this file are versioned separately from the rest of SDL, allow
 This function now returns a standard int result instead of SDL_bool, returning 0 if the function succeeds or a negative error code if there was an error. You should also pass `SDL_SYSWM_CURRENT_VERSION` as the new third version parameter. The version member of the info structure will be filled in with the version of data that is returned, the minimum of the version you requested and the version supported by the runtime SDL library.
 
 
+## SDL_timer.h
+
+SDL_GetTicks() now returns a 64-bit value. Instead of using the `SDL_TICKS_PASSED` macro, you can directly compare tick values, e.g.
+```c
+Uint32 deadline = SDL_GetTicks() + 1000;
+...
+if (SDL_TICKS_PASSED(SDL_GetTicks(), deadline)) {
+    ...
+}
+```
+becomes:
+```c
+Uint64 deadline = SDL_GetTicks() + 1000
+...
+if (SDL_GetTicks() >= deadline) {
+    ...
+}
+```
+
+If you were using this macro for other things besides SDL ticks values, you can define it in your own code as:
+```c
+#define SDL_TICKS_PASSED(A, B)  ((Sint32)((B) - (A)) <= 0)
+```
+
 ## SDL_version.h
 
 SDL_GetRevisionNumber() has been removed from the API, it always returned 0 in SDL 2.0

diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
@@ -46,7 +46,7 @@ extern "C" {
 /**
  *  This is the timeout value which corresponds to never time out.
  */
-#define SDL_MUTEX_MAXWAIT   (~(Uint32)0)
+#define SDL_MUTEX_MAXWAIT   -1
 
 
 /**
@@ -194,6 +194,7 @@ typedef struct SDL_semaphore SDL_sem;
  * \sa SDL_SemValue
  * \sa SDL_SemWait
  * \sa SDL_SemWaitTimeout
+ * \sa SDL_SemWaitTimeoutNS
  */
 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
 
@@ -213,8 +214,9 @@ extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
  * \sa SDL_SemValue
  * \sa SDL_SemWait
  * \sa SDL_SemWaitTimeout
+ * \sa SDL_SemWaitTimeoutNS
  */
-extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
+extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
 
 /**
  * Wait until a semaphore has a positive value and then decrements it.
@@ -240,8 +242,9 @@ extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
  * \sa SDL_SemValue
  * \sa SDL_SemWait
  * \sa SDL_SemWaitTimeout
+ * \sa SDL_SemWaitTimeoutNS
  */
-extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
+extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
 
 /**
  * See if a semaphore has a positive value and decrement it if it does.
@@ -264,8 +267,9 @@ extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
  * \sa SDL_SemValue
  * \sa SDL_SemWait
  * \sa SDL_SemWaitTimeout
+ * \sa SDL_SemWaitTimeoutNS
  */
-extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
+extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
 
 /**
  * Wait until a semaphore has a positive value and then decrements it.
@@ -276,7 +280,7 @@ extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
  * successful it will atomically decrement the semaphore value.
  *
  * \param sem the semaphore to wait on
- * \param timeout the length of the timeout, in milliseconds
+ * \param timeoutMS the length of the timeout, in milliseconds
  * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
  *          succeed in the allotted time, or a negative error code on failure;
  *          call SDL_GetError() for more information.
@@ -289,8 +293,35 @@ extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
  * \sa SDL_SemTryWait
  * \sa SDL_SemValue
  * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeoutNS
  */
-extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout);
+extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Sint32 timeoutMS);
+
+/**
+ * Wait until a semaphore has a positive value and then decrements it.
+ *
+ * This function suspends the calling thread until either the semaphore
+ * pointed to by `sem` has a positive value, the call is interrupted by a
+ * signal or error, or the specified time has elapsed. If the call is
+ * successful it will atomically decrement the semaphore value.
+ *
+ * \param sem the semaphore to wait on
+ * \param timeoutNS the length of the timeout, in nanoseconds
+ * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
+ *          succeed in the allotted time, or a negative error code on failure;
+ *          call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
+ */
+extern DECLSPEC int SDLCALL SDL_SemWaitTimeoutNS(SDL_sem *sem, Sint64 timeoutNS);
 
 /**
  * Atomically increment a semaphore's value and wake waiting threads.
@@ -308,7 +339,7 @@ extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout);
  * \sa SDL_SemWait
  * \sa SDL_SemWaitTimeout
  */
-extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
+extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem);
 
 /**
  * Get the current value of a semaphore.
@@ -320,7 +351,7 @@ extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
  *
  * \sa SDL_CreateSemaphore
  */
-extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
+extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem);
 
 /* @} *//* Semaphore functions */
 
@@ -346,6 +377,7 @@ typedef struct SDL_cond SDL_cond;
  * \sa SDL_CondSignal
  * \sa SDL_CondWait
  * \sa SDL_CondWaitTimeout
+ * \sa SDL_CondWaitTimeoutNS
  * \sa SDL_DestroyCond
  */
 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
@@ -361,9 +393,10 @@ extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
  * \sa SDL_CondSignal
  * \sa SDL_CondWait
  * \sa SDL_CondWaitTimeout
+ * \sa SDL_CondWaitTimeoutNS
  * \sa SDL_CreateCond
  */
-extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
+extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
 
 /**
  * Restart one of the threads that are waiting on the condition variable.
@@ -377,10 +410,11 @@ extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
  * \sa SDL_CondBroadcast
  * \sa SDL_CondWait
  * \sa SDL_CondWaitTimeout
+ * \sa SDL_CondWaitTimeoutNS
  * \sa SDL_CreateCond
  * \sa SDL_DestroyCond
  */
-extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
+extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
 
 /**
  * Restart all threads that are waiting on the condition variable.
@@ -394,10 +428,11 @@ extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
  * \sa SDL_CondSignal
  * \sa SDL_CondWait
  * \sa SDL_CondWaitTimeout
+ * \sa SDL_CondWaitTimeoutNS
  * \sa SDL_CreateCond
  * \sa SDL_DestroyCond
  */
-extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
+extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
 
 /**
  * Wait until a condition variable is signaled.
@@ -422,10 +457,11 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
  * \sa SDL_CondBroadcast
  * \sa SDL_CondSignal
  * \sa SDL_CondWaitTimeout
+ * \sa SDL_CondWaitTimeoutNS
  * \sa SDL_CreateCond
  * \sa SDL_DestroyCond
  */
-extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
+extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mutex);
 
 /**
  * Wait until a condition variable is signaled or a certain time has passed.
@@ -440,7 +476,7 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
  *
  * \param cond the condition variable to wait on
  * \param mutex the mutex used to coordinate thread access
- * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
+ * \param timeoutMS the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
  *           to wait indefinitely
  * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
  *          the condition is not signaled in the allotted time, or a negative
@@ -451,11 +487,42 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
  * \sa SDL_CondBroadcast
  * \sa SDL_CondSignal
  * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeoutNS
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
+ */
+extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond,
+                                                SDL_mutex *mutex, Sint32 timeoutMS);
+
+/**
+ * Wait until a condition variable is signaled or a certain time has passed.
+ *
+ * This function unlocks the specified `mutex` and waits for another thread to
+ * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
+ * `cond`, or for the specified time to elapse. Once the condition variable is
+ * signaled or the time elapsed, the mutex is re-locked and the function
+ * returns.
+ *
+ * The mutex must be locked before calling this function.
+ *
+ * \param cond the condition variable to wait on
+ * \param mutex the mutex used to coordinate thread access
+ * \param timeoutNS the maximum time to wait, in nanoseconds, or `SDL_MUTEX_MAXWAIT` to wait indefinitely
+ * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
+ *          the condition is not signaled in the allotted time, or a negative
+ *          error code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
  * \sa SDL_CreateCond
  * \sa SDL_DestroyCond
  */
-extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
-                                                SDL_mutex * mutex, Uint32 ms);
+extern DECLSPEC int SDLCALL SDL_CondWaitTimeoutNS(SDL_cond *cond,
+                                                  SDL_mutex *mutex, Sint64 timeoutNS);
 
 /* @} *//* Condition variable functions */