From 3f40396d33df64326756648c3b8e1e6c922efe5a Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sun, 21 Mar 2021 14:18:39 -0400
Subject: [PATCH] First shot at merging the wiki documentation into the
headers.
---
include/SDL.h | 110 ++-
include/SDL_assert.h | 127 +--
include/SDL_atomic.h | 134 ++-
include/SDL_audio.h | 892 +++++++++++++-------
include/SDL_blendmode.h | 113 ++-
include/SDL_clipboard.h | 30 +-
include/SDL_cpuinfo.h | 331 ++++++--
include/SDL_error.h | 76 +-
include/SDL_events.h | 415 ++++++++--
include/SDL_filesystem.h | 138 ++--
include/SDL_gamecontroller.h | 546 ++++++++++---
include/SDL_gesture.h | 40 +-
include/SDL_haptic.h | 490 ++++++-----
include/SDL_hints.h | 86 +-
include/SDL_joystick.h | 565 ++++++++++---
include/SDL_keyboard.h | 201 +++--
include/SDL_loadso.h | 42 +-
include/SDL_log.h | 200 ++++-
include/SDL_main.h | 33 +-
include/SDL_messagebox.h | 91 ++-
include/SDL_misc.h | 32 +-
include/SDL_mouse.h | 342 +++++---
include/SDL_mutex.h | 317 +++++--
include/SDL_pixels.h | 200 ++++-
include/SDL_platform.h | 17 +-
include/SDL_power.h | 29 +-
include/SDL_rect.h | 98 ++-
include/SDL_render.h | 1441 ++++++++++++++++++++------------
include/SDL_rwops.h | 183 ++++-
include/SDL_sensor.h | 94 ++-
include/SDL_surface.h | 605 ++++++++++----
include/SDL_system.h | 384 ++++++---
include/SDL_syswm.h | 26 +-
include/SDL_thread.h | 309 ++++---
include/SDL_timer.h | 99 ++-
include/SDL_touch.h | 50 +-
include/SDL_version.h | 100 +--
include/SDL_video.h | 1499 +++++++++++++++++++++++-----------
include/SDL_vulkan.h | 261 +++---
39 files changed, 7580 insertions(+), 3166 deletions(-)
diff --git a/include/SDL.h b/include/SDL.h
index 02203f29a..a69541679 100644
--- a/include/SDL.h
+++ b/include/SDL.h
@@ -93,37 +93,121 @@ extern "C" {
/* @} */
/**
- * This function initializes the subsystems specified by \c flags
+ * Initialize the SDL library.
+ *
+ * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
+ * two may be used interchangeably. Though for readability of your code
+ * SDL_InitSubSystem() might be preferred.
+ *
+ * The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread)
+ * subsystems are initialized by default. Message boxes
+ * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
+ * video subsystem, in hopes of being useful in showing an error dialog when
+ * SDL_Init fails. You must specifically initialize other subsystems if you
+ * use them in your application.
+ *
+ * Logging (such as SDL_Log) works without initialization, too.
+ *
+ * `flags` may be any of the following OR'd together:
+ *
+ * - `SDL_INIT_TIMER`: timer subsystem
+ * - `SDL_INIT_AUDIO`: audio subsystem
+ * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
+ * subsystem
+ * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
+ * events subsystem
+ * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
+ * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
+ * initializes the joystick subsystem
+ * - `SDL_INIT_EVENTS`: events subsystem
+ * - `SDL_INIT_EVERYTHING`: all of the above subsystems
+ * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
+ *
+ * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
+ * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
+ * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
+ * this call will increase the ref-count and return.
+ *
+ * \param flags subsystem initialization flags
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
+ * \sa SDL_SetMainReady
+ * \sa SDL_WasInit
*/
extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
/**
- * This function initializes specific SDL subsystems
+ * Compatibility function to initialize the SDL library.
+ *
+ * In SDL2, this function and SDL_Init() are interchangeable.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * Subsystem initialization is ref-counted, you must call
- * SDL_QuitSubSystem() for each SDL_InitSubSystem() to correctly
- * shutdown a subsystem manually (or call SDL_Quit() to force shutdown).
- * If a subsystem is already loaded then this call will
- * increase the ref-count and return.
+ * \sa SDL_Init
+ * \sa SDL_Quit
+ * \sa SDL_QuitSubSystem
*/
extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
/**
- * This function cleans up specific SDL subsystems
+ * Shut down specific SDL subsystems.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use
+ * that subsystem's quit function (SDL_VideoQuit()) directly instead. But
+ * generally, you should not be using those functions directly anyhow; use
+ * SDL_Init() instead.
+ *
+ * You still need to call SDL_Quit() even if you close all open subsystems
+ * with SDL_QuitSubSystem().
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
*/
extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
/**
- * This function returns a mask of the specified subsystems which have
- * previously been initialized.
+ * Get a mask of the specified subsystems which are currently initialized.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns If `flags` is 0 it returns a mask of all initialized subsystems,
+ * otherwise it returns the initialization status of the specified
+ * subsystems.
*
- * If \c flags is 0, it returns a mask of all initialized subsystems.
+ * The return value does not include SDL_INIT_NOPARACHUTE.
+ *
+ * \sa SDL_Init
+ * \sa SDL_InitSubSystem
*/
extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
/**
- * This function cleans up all initialized subsystems. You should
- * call it upon all exit conditions.
+ * Clean up all initialized subsystems.
+ *
+ * You should call this function even if you have already shutdown each
+ * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
+ * function even in the case of errors in initialization.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * then you must use that subsystem's quit function (SDL_VideoQuit()) to shut
+ * it down before calling SDL_Quit(). But generally, you should not be using
+ * those functions directly anyhow; use SDL_Init() instead.
+ *
+ * You can use this function with atexit() to ensure that it is run when your
+ * application is shutdown, but it is not wise to do this from a library or
+ * other dynamically loaded code.
+ *
+ * \sa SDL_Init
+ * \sa SDL_QuitSubSystem
*/
extern DECLSPEC void SDLCALL SDL_Quit(void);
diff --git a/include/SDL_assert.h b/include/SDL_assert.h
index b1355b31b..6a5bc0006 100644
--- a/include/SDL_assert.h
+++ b/include/SDL_assert.h
@@ -193,88 +193,119 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
const SDL_AssertData* data, void* userdata);
/**
- * \brief Set an application-defined assertion handler.
+ * Set an application-defined assertion handler.
*
- * This allows an app to show its own assertion UI and/or force the
- * response to an assertion failure. If the app doesn't provide this, SDL
- * will try to do the right thing, popping up a system-specific GUI dialog,
- * and probably minimizing any fullscreen windows.
+ * This function allows an application to show its own assertion UI and/or
+ * force the response to an assertion failure. If the application doesn't
+ * provide this, SDL will try to do the right thing, popping up a
+ * system-specific GUI dialog, and probably minimizing any fullscreen windows.
*
- * This callback may fire from any thread, but it runs wrapped in a mutex, so
- * it will only fire from one thread at a time.
+ * The function prototype for `handler` is:
*
- * Setting the callback to NULL restores SDL's original internal handler.
+ * ```c
+ * SDL_AssertState YourAssertionHandler(const SDL_AssertData* data, void* userdata)
+ * ```
*
- * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
+ * where `YourAssertionHandler` is the name of your function and its
+ * parameters are:
*
- * Return SDL_AssertState value of how to handle the assertion failure.
+ * - `data`: a pointer to the SDL_AssertData structure corresponding to the
+ * current assertion
+ * - `userdata`: what was passed as `userdata` to SDL_SetAssertionHandler()
*
- * \param handler Callback function, called when an assertion fails.
- * \param userdata A pointer passed to the callback as-is.
+ * This callback should return an SDL_AssertState value indicating how to
+ * handle the assertion failure.
+ *
+ * This callback may fire from any thread, but it runs wrapped in a mutex, so
+ * it will only fire from one thread at a time.
+ *
+ * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
+ *
+ * \param handler the function to call when an assertion fails or NULL for the
+ * default handler
+ * \param userdata a pointer that is passed to `handler`
+ *
+ * \sa SDL_GetAssertionHandler
*/
extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
SDL_AssertionHandler handler,
void *userdata);
/**
- * \brief Get the default assertion handler.
+ * Get the default assertion handler.
+ *
+ * This returns the function pointer that is called by default when an
+ * assertion is triggered. This is an internal function provided by SDL, that
+ * is used for assertions when SDL_SetAssertionHandler() hasn't been used to
+ * provide a different function.
*
- * This returns the function pointer that is called by default when an
- * assertion is triggered. This is an internal function provided by SDL,
- * that is used for assertions when SDL_SetAssertionHandler() hasn't been
- * used to provide a different function.
+ * \returns the default SDL_AssertionHandler that is called when an assert
+ * triggers.
*
- * \return The default SDL_AssertionHandler that is called when an assert triggers.
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void);
/**
- * \brief Get the current assertion handler.
+ * Get the current assertion handler.
+ *
+ * This returns the function pointer that is called when an assertion is
+ * triggered. This is either the value last passed to
+ * SDL_SetAssertionHandler(), or if no application-specified function is set,
+ * is equivalent to calling SDL_GetDefaultAssertionHandler().
+ *
+ * The parameter `puserdata` is a pointer to a void*, which will store the
+ * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value
+ * will always be NULL for the default handler. If you don't care about this
+ * data, it is safe to pass a NULL pointer to this function to ignore it.
*
- * This returns the function pointer that is called when an assertion is
- * triggered. This is either the value last passed to
- * SDL_SetAssertionHandler(), or if no application-specified function is
- * set, is equivalent to calling SDL_GetDefaultAssertionHandler().
+ * \param puserdata pointer which is filled with the "userdata" pointer that
+ * was passed to SDL_SetAssertionHandler()
+ * \returns the SDL_AssertionHandler that is called when an assert triggers.
*
- * \param puserdata Pointer to a void*, which will store the "userdata"
- * pointer that was passed to SDL_SetAssertionHandler().
- * This value will always be NULL for the default handler.
- * If you don't care about this data, it is safe to pass
- * a NULL pointer to this function to ignore it.
- * \return The SDL_AssertionHandler that is called when an assert triggers.
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_SetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
/**
- * \brief Get a list of all assertion failures.
+ * Get a list of all assertion failures.
+ *
+ * This function gets all assertions triggered since the last call to
+ * SDL_ResetAssertionReport(), or the start of the program.
*
- * Get all assertions triggered since last call to SDL_ResetAssertionReport(),
- * or the start of the program.
+ * The proper way to examine this data looks something like this:
*
- * The proper way to examine this data looks something like this:
+ * ```c
+ * const SDL_AssertData *item = SDL_GetAssertionReport();
+ * while (item) {
+ * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
+ * item->condition, item->function, item->filename,
+ * item->linenum, item->trigger_count,
+ * item->always_ignore ? "yes" : "no");
+ * item = item->next;
+ * }
+ * ```
*
- * <code>
- * const SDL_AssertData *item = SDL_GetAssertionReport();
- * while (item) {
- * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
- * item->condition, item->function, item->filename,
- * item->linenum, item->trigger_count,
- * item->always_ignore ? "yes" : "no");
- * item = item->next;
- * }
- * </code>
+ * \returns a list of all failed assertions or NULL if the list is empty. This
+ * memory should not be modified or freed by the application.
*
- * \return List of all assertions.
- * \sa SDL_ResetAssertionReport
+ * \sa SDL_ResetAssertionReport
*/
extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
/**
- * \brief Reset the list of all assertion failures.
+ * Clear the list of all assertion failures.
*
- * Reset list of all assertions triggered.
+ * This function will clear the list of all assertions triggered up to that
+ * point. Immediately following this call, SDL_GetAssertionReport will return
+ * no items. In addition, any previously-triggered assertions will be reset to
+ * a trigger_count of zero, and their always_ignore state will be false.
*
- * \sa SDL_GetAssertionReport
+ * \sa SDL_GetAssertionReport
*/
extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h
index 5f62bd736..df2974bbb 100644
--- a/include/SDL_atomic.h
+++ b/include/SDL_atomic.h
@@ -89,25 +89,47 @@ extern "C" {
typedef int SDL_SpinLock;
/**
- * \brief Try to lock a spin lock by setting it to a non-zero value.
+ * Try to lock a spin lock by setting it to a non-zero value.
*
- * \param lock Points to the lock.
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
*
- * \return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
+ * \param lock a pointer to a lock variable
+ * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
+ * held.
+ *
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicUnlock
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
/**
- * \brief Lock a spin lock by setting it to a non-zero value.
+ * Lock a spin lock by setting it to a non-zero value.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
*
- * \param lock Points to the lock.
+ * \param lock a pointer to a lock variable
+ *
+ * \sa SDL_AtomicTryLock
+ * \sa SDL_AtomicUnlock
*/
extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
/**
- * \brief Unlock a spin lock by setting it to 0. Always returns immediately
+ * Unlock a spin lock by setting it to 0.
+ *
+ * Always returns immediately.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \param lock Points to the lock.
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicTryLock
*/
extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
@@ -216,32 +238,68 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
typedef struct { int value; } SDL_atomic_t;
/**
- * \brief Set an atomic variable to a new value if it is currently an old value.
+ * Set an atomic variable to a new value if it is
+ * currently an old value.
*
- * \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param oldval the old value
+ * \param newval the new value
+ * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGet
+ * \sa SDL_AtomicSet
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval);
/**
- * \brief Set an atomic variable to a value.
+ * Set an atomic variable to a value.
+ *
+ * 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!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value
+ * \returns the previous value of the atomic variable.
*
- * \return The previous value of the atomic variable.
+ * \sa SDL_AtomicGet
*/
extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
/**
- * \brief Get the value of an atomic variable
+ * Get the value of an atomic variable.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable
+ * \returns the current value of an atomic variable.
+ *
+ * \sa SDL_AtomicSet
*/
extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
/**
- * \brief Add to an atomic variable.
+ * Add to an atomic variable.
+ *
+ * This function also acts as a full memory barrier.
*
- * \return The previous value of the atomic variable.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note This same style can be used for any number operation
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value to add
+ * \returns the previous value of the atomic variable.
+ *
+ * \sa SDL_AtomicDecRef
+ * \sa SDL_AtomicIncRef
*/
extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
@@ -263,23 +321,51 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
#endif
/**
- * \brief Set a pointer to a new value if it is currently an old value.
+ * Set a pointer to a new value if it is currently an old
+ * value.
*
- * \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to a pointer
+ * \param oldval the old pointer value
+ * \param newval the new pointer value
+ * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCAS
+ * \sa SDL_AtomicGetPtr
+ * \sa SDL_AtomicSetPtr
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval);
/**
- * \brief Set a pointer to a value atomically.
+ * Set a pointer to a value atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \param v the desired pointer value
+ * \returns the previous value of the pointer.
*
- * \return The previous value of the pointer.
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
/**
- * \brief Get the value of a pointer atomically.
+ * Get the value of a pointer atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \returns the current value of a pointer.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicSetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 46fefe2e2..99d8a2b8b 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -19,6 +19,8 @@
3. This notice may not be removed or altered from any source distribution.
*/
+/* !!! FIXME: several functions in here need Doxygen comments. */
+
/**
* \file SDL_audio.h
*
@@ -265,55 +267,69 @@ extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
/* @} */
/**
- * This function returns the name of the current audio driver, or NULL
- * if no driver has been initialized.
+ * Get the name of the current audio driver.
+ *
+ * The returned string points to internal static memory and thus never becomes
+ * invalid, even if you quit the audio subsystem and initialize a new driver
+ * (although such a case would return a different static string from another
+ * call to this function, of course). As such, you should not modify or free
+ * the returned string.
+ *
+ * \returns the name of the current audio driver or NULL if no driver has been
+ * initialized.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AudioInit
*/
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
/**
- * This function opens the audio device with the desired parameters, and
- * returns 0 if successful, placing the actual hardware parameters in the
- * structure pointed to by \c obtained. If \c obtained is NULL, the audio
- * data passed to the callback function will be guaranteed to be in the
- * requested format, and will be automatically converted to the hardware
- * audio format if necessary. This function returns -1 if it failed
- * to open the audio device, or couldn't set up the audio thread.
- *
- * When filling in the desired audio spec structure,
- * - \c desired->freq should be the desired audio frequency in samples-per-
- * second.
- * - \c desired->format should be the desired audio format.
- * - \c desired->samples is the desired size of the audio buffer, in
- * samples. This number should be a power of two, and may be adjusted by
- * the audio driver to a value more suitable for the hardware. Good values
- * seem to range between 512 and 8096 inclusive, depending on the
- * application and CPU speed. Smaller values yield faster response time,
- * but can lead to underflow if the application is doing heavy processing
- * and cannot fill the audio buffer in time. A stereo sample consists of
- * both right and left channels in LR ordering.
- * Note that the number of samples is directly related to time by the
- * following formula: \code ms = (samples*1000)/freq \endcode
- * - \c desired->size is the size in bytes of the audio buffer, and is
- * calculated by SDL_OpenAudio().
- * - \c desired->silence is the value used to set the buffer to silence,
- * and is calculated by SDL_OpenAudio().
- * - \c desired->callback should be set to a function that will be called
- * when the audio device is ready for more data. It is passed a pointer
- * to the audio buffer, and the length in bytes of the audio buffer.
- * This function usually runs in a separate thread, and so you should
- * protect data structures that it accesses by calling SDL_LockAudio()
- * and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
- * pointer here, and call SDL_QueueAudio() with some frequency, to queue
- * more audio samples to be played (or for capture devices, call
- * SDL_DequeueAudio() with some frequency, to obtain audio samples).
- * - \c desired->userdata is passed as the first parameter to your callback
- * function. If you passed a NULL callback, this value is ignored.
- *
- * The audio device starts out playing silence when it's opened, and should
- * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
- * for your audio callback function to be called. Since the audio driver
- * may modify the requested size of the audio buffer, you should allocate
- * any local mixing buffers after you open the audio device.
+ * This function is a legacy means of opening the audio device.
+ *
+ * This function remains for compatibility with SDL 1.2, but also because it's
+ * slightly easier to use than the new functions in SDL 2.0. The new, more
+ * powerful, and preferred way to do this is SDL_OpenAudioDevice().
+ *
+ * This function is roughly equivalent to:
+ *
+ * ```c++
+ * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
+ * ```
+ *
+ * With two notable exceptions:
+ *
+ * - If `obtained` is NULL, we use `desired` (and allow no changes), which
+ * means desired will be modified to have the correct values for silence, etc,
+ * and SDL will convert any differences between your app's specific request
+ * and the hardware behind the scenes.
+ *
+ * - The return value is always success or failure, and not a device ID, which
+ * means you can only have one device open at a time with this function.
+ *
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ * format. Please refer to the SDL_OpenAudioDevice documentation
+ * for details on how to prepare this structure.
+ * \param obtained an SDL_AudioSpec structure filled in with the actual
+ * parameters, or NULL.
+ * \returns This function opens the audio device with the desired parameters,
+ * and returns 0 if successful, placing the actual hardware
+ * parameters in the structure pointed to by `obtained`.
+ *
+ * If `obtained` is NULL, the audio data passed to the callback
+ * function will be guaranteed to be in the requested format, and
+ * will be automatically converted to the actual hardware audio
+ * format if necessary. If `obtained` is NULL, `desired` will
+ * have fields modified.
+ *
+ * This function returns a negative error code on failure to open the
+ * audio device or failure to set up the audio thread; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_CloseAudio
+ * \sa SDL_LockAudio
+ * \sa SDL_PauseAudio
+ * \sa SDL_UnlockAudio
*/
extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
SDL_AudioSpec * obtained);
@@ -330,49 +346,97 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
typedef Uint32 SDL_AudioDeviceID;
/**
- * Get the number of available devices exposed by the current driver.
- * Only valid after a successfully initializing the audio subsystem.
- * Returns -1 if an explicit list of devices can't be determined; this is
- * not an error. For example, if SDL is set up to talk to a remote audio
- * server, it can't list every one available on the Internet, but it will
- * still allow a specific host to be specified to SDL_OpenAudioDevice().
+ * Get the number of built-in audio devices.
+ *
+ * This function is only valid after successfully initializing the audio
+ * subsystem.
+ *
+ * Note that audio capture support is not implemented as of SDL 2.0.4, so the
+ * `iscapture` parameter is for future expansion and should always be zero
+ * for now.
+ *
+ * This function will return -1 if an explicit list of devices can't be
+ * determined. Returning -1 is not an error. For example, if SDL is set up to
+ * talk to a remote audio server, it can't list every one available on the
+ * Internet, but it will still allow a specific host to be specified in
+ * SDL_OpenAudioDevice().
+ *
+ * In many common cases, when this function returns a value <= 0, it can still
+ * successfully open the default device (NULL for first argument of
+ * SDL_OpenAudioDevice()).
*
- * In many common cases, when this function returns a value <= 0, it can still
- * successfully open the default device (NULL for first argument of
- * SDL_OpenAudioDevice()).
+ * This function may trigger a complete redetect of available hardware. It
+ * should not be called for each iteration of a loop, but rather once at the
+ * start of a loop:
+ *
+ * ```c++
+ * // Don't do this:
+ * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
+ *
+ * // do this instead:
+ * const int count = SDL_GetNumAudioDevices(0);
+ * for (int i = 0; i < count; ++i) { do_something_here(); }
+ * ```
+ *
+ * \param iscapture zero to request playback devices, non-zero to request
+ * recording devices
+ * \returns the number of available devices exposed by the current driver or
+ * -1 if an explicit list of devices can't be determined. A return
+ * value of -1 does not necessarily mean an error condition.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_OpenAudioDevice
*/
extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
/**
- * Get the human-readable name of a specific audio device.
- * Must be a value between 0 and (number of audio devices-1).
- * Only valid after a successfully initializing the audio subsystem.
- * The values returned by this function reflect the latest call to
- * SDL_GetNumAudioDevices(); recall that function to redetect available
- * hardware.
- *
- * The string returned by this function is UTF-8 encoded, read-only, and
- * managed internally. You are not to free it. If you need to keep the
- * string for any length of time, you should make your own copy of it, as it
- * will be invalid next time any of several other SDL functions is called.
+ * Get the human-readable name of a specific audio device.
+ *
+ * This function is only valid after successfully initializing the audio
+ * subsystem. The values returned by this function reflect the latest call to
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
+ * hardware.
+ *
+ * The string returned by this function is UTF-8 encoded, read-only, and
+ * managed internally. You are not to free it. If you need to keep the string
+ * for any length of time, you should make your own copy of it, as it
(Patch may be truncated, please check the link at the top of this post.)