From 407e54e188c8e30f486e87635989d77810be0b1c Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 11 Apr 2024 00:36:48 -0400
Subject: [PATCH] include: More improved docs for the wikibridge!
---
include/SDL3/SDL_audio.h | 40 +++++++++++++++++++++++++++++++++-----
include/SDL3/SDL_events.h | 10 ++++++++++
include/SDL3/SDL_keycode.h | 9 ++++++++-
include/SDL3/SDL_timer.h | 12 ++++++++++++
4 files changed, 65 insertions(+), 6 deletions(-)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index da00483dadb4b..ae0b2fb3800e7 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -991,11 +991,7 @@ extern DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
*
* Apps can (optionally) register a callback with an audio stream that
* is called when data is added with SDL_PutAudioStreamData, or requested
- * with SDL_GetAudioStreamData. These callbacks may run from any
- * thread, so if you need to protect shared data, you should use
- * SDL_LockAudioStream to serialize access; this lock will be held by
- * before your callback is called, so your callback does not need to
- * manage the lock explicitly.
+ * with SDL_GetAudioStreamData.
*
* Two values are offered here: one is the amount of additional data needed
* to satisfy the immediate request (which might be zero if the stream
@@ -1011,6 +1007,17 @@ extern DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
* \param additional_amount The amount of data, in bytes, that is needed right now.
* \param total_amount The total amount of data requested, in bytes, that is requested or available.
* \param userdata An opaque pointer provided by the app for their personal use.
+ *
+ * \threadsafety This callbacks may run from any thread, so if you need
+ * to protect shared data, you should use SDL_LockAudioStream to
+ * serialize access; this lock will be held before your callback
+ * is called, so your callback does not need to manage the lock
+ * explicitly.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetAudioStreamGetCallback
+ * \sa SDL_SetAudioStreamPutCallback
*/
typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount);
@@ -1185,6 +1192,29 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDevi
* This is useful for accessing the final mix, perhaps for writing a
* visualizer or applying a final effect to the audio data before playback.
*
+ * This callback should run as quickly as possible and not block for any
+ * significant time, as this callback delays submission of data to the audio
+ * device, which can cause audio playback problems.
+ *
+ * The postmix callback _must_ be able to handle any audio data format
+ * specified in `spec`, which can change between callbacks if the audio
+ * device changed. However, this only covers frequency and channel count;
+ * data is always provided here in SDL_AUDIO_F32 format.
+ *
+ * \param userdata a pointer provided by the app through
+ * SDL_SetAudioDevicePostmixCallback, for its own use.
+ * \param spec the current format of audio that is to be submitted to the
+ * audio device.
+ * \param buffer the buffer of audio samples to be submitted. The callback
+ * can inspect and/or modify this data.
+ * \param buflen the size of `buffer` in bytes.
+ *
+ * \threadsafety This will run from a background thread owned by SDL.
+ * The application is responsible for locking resources the
+ * callback touches that need to be protected.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ *
* \sa SDL_SetAudioDevicePostmixCallback
*/
typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen);
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 11267cf45b472..7176d2ef4eecc 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -1106,6 +1106,12 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
* \returns 1 to permit event to be added to the queue, and 0 to disallow
* it. When used with SDL_AddEventWatch, the return value is ignored.
*
+ * \threadsafety SDL may call this callback at any time from any thread; the
+ * application is responsible for locking resources the callback
+ * touches that need to be protected.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ *
* \sa SDL_SetEventFilter
* \sa SDL_AddEventWatch
*/
@@ -1145,6 +1151,10 @@ typedef int (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
* \param filter An SDL_EventFilter function to call when an event happens
* \param userdata a pointer that is passed to `filter`
*
+ * \threadsafety SDL may call the filter callback at any time from any thread;
+ * the application is responsible for locking resources the
+ * callback touches that need to be protected.
+ *
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AddEventWatch
diff --git a/include/SDL3/SDL_keycode.h b/include/SDL3/SDL_keycode.h
index 8aa40854a1e3d..14da234a92a17 100644
--- a/include/SDL3/SDL_keycode.h
+++ b/include/SDL3/SDL_keycode.h
@@ -37,10 +37,17 @@
* Values of this type are used to represent keyboard keys using the current
* layout of the keyboard. These values include Unicode values representing
* the unmodified character that would be generated by pressing the key, or
- * an SDLK_* constant for those keys that do not generate characters.
+ * an `SDLK_*` constant for those keys that do not generate characters.
*
* A special exception is the number keys at the top of the keyboard which
* map to SDLK_0...SDLK_9 on AZERTY layouts.
+ *
+ * The list of `SDLK_*` values are in SDL_KeyCode, which is an enum, while
+ * SDL_Keycode is an integer.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ *
+ * \sa SDL_KeyCode
*/
typedef Sint32 SDL_Keycode;
diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h
index a4ab5977745e9..2b03e089be8e8 100644
--- a/include/SDL3/SDL_timer.h
+++ b/include/SDL3/SDL_timer.h
@@ -131,6 +131,18 @@ extern DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns);
* the next timer interval, in milliseconds. If the returned value is the same as the one
* passed in, the periodic alarm continues, otherwise a new alarm is
* scheduled. If the callback returns 0, the periodic alarm is cancelled.
+ *
+ * \param interval the current callback time interval.
+ * \param param an arbitrary pointer provided by the app through SDL_AddTimer, for its own use.
+ * \returns the new callback time interval, or 0 to disable further runs of the callback.
+ *
+ * \threadsafety SDL may call this callback at any time from a background
+ * thread; the application is responsible for locking resources
+ * the callback touches that need to be protected.
+ *
+ * \since This datatype is available since SDL 3.0.0.
+ *
+ * \sa SDL_AddTimer
*/
typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval, void *param);