include: More improved docs for the wikibridge!

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
+ * with SDL_GetAudioStreamData.
- * 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.
  *
  * 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);

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

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;
 

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);