Sync SDL3 header -> wiki

SDL3/README/migration.md

@@ -86,11 +86,14 @@ The following structures have been renamed:
 - SDL_atomic_t => SDL_AtomicInt
 
 The following functions have been renamed:
-* SDL_AtomicCAS() => SDL_AtomicCompareAndSwap()
-* SDL_AtomicCASPtr() => SDL_AtomicCompareAndSwapPointer()
-* SDL_AtomicGetPtr() => SDL_AtomicGetPointer()
+* SDL_AtomicAdd() => SDL_AddAtomicInt()
+* SDL_AtomicCAS() => SDL_CompareAndSwapAtomicInt()
+* SDL_AtomicCASPtr() => SDL_CompareAndSwapAtomicPointer()
+* SDL_AtomicGet() => SDL_GetAtomicInt()
+* SDL_AtomicGetPtr() => SDL_GetAtomicPointer()
 * SDL_AtomicLock() => SDL_LockSpinlock()
-* SDL_AtomicSetPtr() => SDL_AtomicSetPointer()
+* SDL_AtomicSet() => SDL_SetAtomicInt()
+* SDL_AtomicSetPtr() => SDL_SetAtomicPointer()
 * SDL_AtomicTryLock() => SDL_TryLockSpinlock()
 * SDL_AtomicUnlock() => SDL_UnlockSpinlock()
 
@@ -895,6 +898,7 @@ The following symbols have been renamed:
 The following symbols have been removed:
 * SDL_INIT_NOPARACHUTE
 * SDL_INIT_EVERYTHING - you should only initialize the subsystems you are using
+* SDL_INIT_TIMER - no longer needed before calling SDL_AddTimer()
 
 ## SDL_joystick.h
 

SDL3/SDL_AddAtomicInt.md

@@ -0,0 +1,49 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_AddAtomicInt
+
+Add to an atomic variable.
+
+## Header File
+
+Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_atomic.h)
+
+## Syntax
+
+```c
+int SDL_AddAtomicInt(SDL_AtomicInt *a, int v);
+```
+
+## Function Parameters
+
+|                                  |       |                                                                         |
+| -------------------------------- | ----- | ----------------------------------------------------------------------- |
+| [SDL_AtomicInt](SDL_AtomicInt) * | **a** | a pointer to an [SDL_AtomicInt](SDL_AtomicInt) variable to be modified. |
+| int                              | **v** | the desired value to add.                                               |
+
+## Return Value
+
+(int) Returns the previous value of the atomic variable.
+
+## Remarks
+
+This function also acts as a full memory barrier.
+
+***Note: If you don't know what this function is for, you shouldn't use
+it!***
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_AtomicDecRef](SDL_AtomicDecRef)
+- [SDL_AtomicIncRef](SDL_AtomicIncRef)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryAtomic](CategoryAtomic)
+

SDL3/SDL_AddTimer.md

@@ -28,9 +28,6 @@ SDL_TimerID SDL_AddTimer(Uint32 interval, SDL_TimerCallback callback, void *user
 
 ## Remarks
 
-If you use this function, you must pass [`SDL_INIT_TIMER`](SDL_INIT_TIMER)
-to [SDL_Init](SDL_Init)().
-
 The callback function is passed the current timer interval and the user
 supplied parameter from the [SDL_AddTimer](SDL_AddTimer)() call and should
 return the next timer interval. If the value returned from the callback is

SDL3/SDL_AddTimerNS.md

@@ -28,9 +28,6 @@ SDL_TimerID SDL_AddTimerNS(Uint64 interval, SDL_NSTimerCallback callback, void *
 
 ## Remarks
 
-If you use this function, you must pass [`SDL_INIT_TIMER`](SDL_INIT_TIMER)
-to [SDL_Init](SDL_Init)().
-
 The callback function is passed the current timer interval and the user
 supplied parameter from the [SDL_AddTimerNS](SDL_AddTimerNS)() call and
 should return the next timer interval. If the value returned from the

SDL3/SDL_AtomicDecRef.md

@@ -10,7 +10,7 @@ Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/inc
 ## Syntax
 
 ```c
-#define SDL_AtomicDecRef(a)    (SDL_AtomicAdd(a, -1) == 1)
+#define SDL_AtomicDecRef(a)    (SDL_AddAtomicInt(a, -1) == 1)
 ```
 
 ## Macro Parameters

SDL3/SDL_AtomicIncRef.md

@@ -10,7 +10,7 @@ Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/inc
 ## Syntax
 
 ```c
-#define SDL_AtomicIncRef(a)    SDL_AtomicAdd(a, 1)
+#define SDL_AtomicIncRef(a)    SDL_AddAtomicInt(a, 1)
 ```
 
 ## Macro Parameters

SDL3/SDL_AtomicInt.md

@@ -17,9 +17,9 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt;
 
 This can be used to manage a value that is synchronized across multiple
 CPUs without a race condition; when an app sets a value with
-[SDL_AtomicSet](SDL_AtomicSet) all other threads, regardless of the CPU it
-is running on, will see that value when retrieved with
-[SDL_AtomicGet](SDL_AtomicGet), regardless of CPU caches, etc.
+[SDL_SetAtomicInt](SDL_SetAtomicInt) all other threads, regardless of the
+CPU it is running on, will see that value when retrieved with
+[SDL_GetAtomicInt](SDL_GetAtomicInt), regardless of CPU caches, etc.
 
 This is also useful for atomic compare-and-swap operations: a thread can
 change the value as long as its current value matches expectations. When
@@ -30,18 +30,18 @@ disasters with this, so in most cases, you _should_ use a mutex instead of
 this!).
 
 This is a struct so people don't accidentally use numeric operations on it
-directly. You have to use [SDL_Atomic](SDL_Atomic)* functions.
+directly. You have to use SDL atomic functions.
 
 ## Version
 
 This struct is available since SDL 3.0.0.
 
 ## See Also
 
-- [SDL_AtomicCompareAndSwap](SDL_AtomicCompareAndSwap)
-- [SDL_AtomicGet](SDL_AtomicGet)
-- [SDL_AtomicSet](SDL_AtomicSet)
-- [SDL_AtomicAdd](SDL_AtomicAdd)
+- [SDL_CompareAndSwapAtomicInt](SDL_CompareAndSwapAtomicInt)
+- [SDL_GetAtomicInt](SDL_GetAtomicInt)
+- [SDL_SetAtomicInt](SDL_SetAtomicInt)
+- [SDL_AddAtomicInt](SDL_AddAtomicInt)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryAtomic](CategoryAtomic)

SDL3/SDL_AtomicU32.md

@@ -0,0 +1,48 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_AtomicU32
+
+A type representing an atomic unsigned 32-bit value.
+
+## Header File
+
+Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_atomic.h)
+
+## Syntax
+
+```c
+typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32;
+```
+
+## Remarks
+
+This can be used to manage a value that is synchronized across multiple
+CPUs without a race condition; when an app sets a value with
+[SDL_SetAtomicU32](SDL_SetAtomicU32) all other threads, regardless of the
+CPU it is running on, will see that value when retrieved with
+[SDL_GetAtomicU32](SDL_GetAtomicU32), regardless of CPU caches, etc.
+
+This is also useful for atomic compare-and-swap operations: a thread can
+change the value as long as its current value matches expectations. When
+done in a loop, one can guarantee data consistency across threads without a
+lock (but the usual warnings apply: if you don't know what you're doing, or
+you don't do it carefully, you can confidently cause any number of
+disasters with this, so in most cases, you _should_ use a mutex instead of
+this!).
+
+This is a struct so people don't accidentally use numeric operations on it
+directly. You have to use SDL atomic functions.
+
+## Version
+
+This struct is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_CompareAndSwapAtomicU32](SDL_CompareAndSwapAtomicU32)
+- [SDL_GetAtomicU32](SDL_GetAtomicU32)
+- [SDL_SetAtomicU32](SDL_SetAtomicU32)
+- [SDL_AddAtomicU32](SDL_AddAtomicU32)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIStruct](CategoryAPIStruct), [CategoryAtomic](CategoryAtomic)
+

SDL3/SDL_CompareAndSwapAtomicInt.md

@@ -0,0 +1,49 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_CompareAndSwapAtomicInt
+
+Set an atomic variable to a new value if it is currently an old value.
+
+## Header File
+
+Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_atomic.h)
+
+## Syntax
+
+```c
+SDL_bool SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval);
+```
+
+## Function Parameters
+
+|                                  |            |                                                                         |
+| -------------------------------- | ---------- | ----------------------------------------------------------------------- |
+| [SDL_AtomicInt](SDL_AtomicInt) * | **a**      | a pointer to an [SDL_AtomicInt](SDL_AtomicInt) variable to be modified. |
+| int                              | **oldval** | the old value.                                                          |
+| int                              | **newval** | the new value.                                                          |
+
+## Return Value
+
+([SDL_bool](SDL_bool)) Returns [SDL_TRUE](SDL_TRUE) if the atomic variable
+was set, [SDL_FALSE](SDL_FALSE) otherwise.
+
+## Remarks
+
+***Note: If you don't know what this function is for, you shouldn't use
+it!***
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_GetAtomicInt](SDL_GetAtomicInt)
+- [SDL_SetAtomicInt](SDL_SetAtomicInt)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryAtomic](CategoryAtomic)
+

SDL3/SDL_CompareAndSwapAtomicPointer.md

@@ -0,0 +1,50 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_CompareAndSwapAtomicPointer
+
+Set a pointer to a new value if it is currently an old value.
+
+## Header File
+
+Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_atomic.h)
+
+## Syntax
+
+```c
+SDL_bool SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval);
+```
+
+## Function Parameters
+
+|         |            |                         |
+| ------- | ---------- | ----------------------- |
+| void ** | **a**      | a pointer to a pointer. |
+| void *  | **oldval** | the old pointer value.  |
+| void *  | **newval** | the new pointer value.  |
+
+## Return Value
+
+([SDL_bool](SDL_bool)) Returns [SDL_TRUE](SDL_TRUE) if the pointer was set,
+[SDL_FALSE](SDL_FALSE) otherwise.
+
+## Remarks
+
+***Note: If you don't know what this function is for, you shouldn't use
+it!***
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_CompareAndSwapAtomicInt](SDL_CompareAndSwapAtomicInt)
+- [SDL_GetAtomicPointer](SDL_GetAtomicPointer)
+- [SDL_SetAtomicPointer](SDL_SetAtomicPointer)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryAtomic](CategoryAtomic)
+

SDL3/SDL_CompareAndSwapAtomicU32.md

@@ -0,0 +1,49 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_CompareAndSwapAtomicU32
+
+Set an atomic variable to a new value if it is currently an old value.
+
+## Header File
+
+Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_atomic.h)
+
+## Syntax
+
+```c
+SDL_bool SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval);
+```
+
+## Function Parameters
+
+|                                  |            |                                                                         |
+| -------------------------------- | ---------- | ----------------------------------------------------------------------- |
+| [SDL_AtomicU32](SDL_AtomicU32) * | **a**      | a pointer to an [SDL_AtomicU32](SDL_AtomicU32) variable to be modified. |
+| Uint32                           | **oldval** | the old value.                                                          |
+| Uint32                           | **newval** | the new value.                                                          |
+
+## Return Value
+
+([SDL_bool](SDL_bool)) Returns [SDL_TRUE](SDL_TRUE) if the atomic variable
+was set, [SDL_FALSE](SDL_FALSE) otherwise.
+
+## Remarks
+
+***Note: If you don't know what this function is for, you shouldn't use
+it!***
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_GetAtomicU32](SDL_GetAtomicU32)
+- [SDL_SetAtomicU32](SDL_SetAtomicU32)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryAtomic](CategoryAtomic)
+

SDL3/SDL_GetAtomicInt.md

@@ -0,0 +1,45 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_GetAtomicInt
+
+Get the value of an atomic variable.
+
+## Header File
+
+Defined in [<SDL3/SDL_atomic.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_atomic.h)
+
+## Syntax
+
+```c
+int SDL_GetAtomicInt(SDL_AtomicInt *a);
+```
+
+## Function Parameters
+
+|                                  |       |                                                          |
+| -------------------------------- | ----- | -------------------------------------------------------- |
+| [SDL_AtomicInt](SDL_AtomicInt) * | **a** | a pointer to an [SDL_AtomicInt](SDL_AtomicInt) variable. |
+
+## Return Value
+
+(int) Returns the current value of an atomic variable.
+
+## Remarks
+
+***Note: If you don't know what this function is for, you shouldn't use
+it!***
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_SetAtomicInt](SDL_SetAtomicInt)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryAtomic](CategoryAtomic)
+