- * 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;
- * }
- *
+ * ```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;
+ * }
+ * ```
*
- * \return List of all assertions.
- * \sa SDL_ResetAssertionReport
+ * \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.
+ *
+ * \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.
*
- * \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!***
+ *
+ * \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.
*
- * \param lock Points to the lock.
+ * 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.
+ *
+ * \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.
*
- * \return The previous value of the atomic variable.
+ * 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.
+ *
+ * \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.
*
- * \return The previous value of the atomic variable.
+ * This function also acts as a full memory barrier.
*
- * \note This same style can be used for any number operation
+ * ***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 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.
*
- * \return The previous value of the pointer.
+ * ***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.
+ *
+ * \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.
+ * This function is a legacy means of opening the audio device.
*
- * 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.
+ * 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().
*
- * 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 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.
*
- * 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 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()).
+ *
+ * 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.
+ * Get the human-readable name of a specific audio device.
*
- * 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.
+ * 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 will be
+ * invalid next time any of several other SDL functions are called.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ * SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ * query the list of output devices.
+ * \returns the name of the audio device at the requested index, or NULL on
+ * error.
+ *
+ * \sa SDL_GetNumAudioDevices
*/
extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
int iscapture);
/**
- * Get the audio format 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.
+ * Get the preferred audio format of a specific audio device.
*
- * The spec will be filled with the sample rate, sample format, and channel
- * count. All other values in the structure are filled with 0. When the
- * supported struct members are 0, SDL was unable to get the property from the
- * backend.
+ * This function is only valid after a 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.
*
- * \return 0 on success, nonzero on error
+ * `spec` will be filled with the sample rate, sample format, and channel
+ * count. All other values in the structure are filled with 0. When the
+ * supported struct members are 0, SDL was unable to get the property from the
+ * backend.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ * SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ * query the list of output devices.
+ * \param spec The SDL_AudioSpec to be initialized by this function.
+ * \returns 0 on success, nonzero on error
+ *
+ * \sa SDL_GetNumAudioDevices
*/
extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
int iscapture,
@@ -380,17 +444,116 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
/**
- * Open a specific audio device. Passing in a device name of NULL requests
- * the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
+ * Open a specific audio device.
*
- * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
- * some drivers allow arbitrary and driver-specific strings, such as a
- * hostname/IP address for a remote audio server, or a filename in the
- * diskaudio driver.
+ * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such,
+ * this function will never return a 1 so as not to conflict with the legacy
+ * function.
*
- * \return 0 on error, a valid device ID that is >= 2 on success.
+ * Please note that SDL 2.0 before 2.0.5 did not support recording; as such,
+ * this function would fail if `iscapture` was not zero. Starting with SDL
+ * 2.0.5, recording is implemented and this value can be non-zero.
*
- * SDL_OpenAudio(), unlike this function, always acts on device ID 1.
+ * Passing in a `device` name of NULL requests the most reasonable default
+ * (and is equivalent to what SDL_OpenAudio() does to choose a device). The
+ * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
+ * some drivers allow arbitrary and driver-specific strings, such as a
+ * hostname/IP address for a remote audio server, or a filename in the
+ * diskaudio driver.
+ *
+ * When filling in the desired audio spec structure:
+ *
+ * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
+ *
+ * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
+ *
+ * - `desired->samples` is the desired size of the audio buffer, in
+ * _sample frames_ (with stereo output, two samples--left and right--would
+ * make a single sample frame). 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 reduce
+ * latency, but can lead to underflow if the application is doing heavy
+ * processing and cannot fill the audio buffer in time. Note that the
+ * number of sample frames is directly related to time by the following
+ * formula: `ms = (sampleframes*1000)/freq`
+ *
+ * - `desired->size` is the size in _bytes_ of the audio buffer, and is
+ * calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ *
+ * - `desired->silence` is the value used to set the buffer to silence,
+ * and is calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ *
+ * - `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_LockAudioDevice()
+ * and SDL_UnlockAudioDevice() 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).
+ *
+ * - `desired->userdata` is passed as the first parameter to your callback
+ * function. If you passed a NULL callback, this value is ignored.
+ *
+ * `allowed_changes` can have the following flags OR'd together:
+ *
+ * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
+ * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
+ * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
+ * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
+ *
+ * These flags specify how SDL should behave when a device cannot offer a
+ * specific feature. If the application requests a feature that the hardware
+ * doesn't offer, SDL will always try to get the closest equivalent.
+ *
+ * For example, if you ask for float32 audio format, but the sound card only
+ * supports int16, SDL will set the hardware to int16. If you had set
+ * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the
+ * `obtained` structure. If that flag was *not* set, SDL will prepare to
+ * convert your callback's float32 audio to int16 before feeding it to the
+ * hardware and will keep the originally requested format in the `obtained`
+ * structure.
+ *
+ * If your application can only handle one specific data format, pass a zero
+ * for `allowed_changes` and let SDL transparently handle any differences.
+ *
+ * An opened audio device starts out paused, and should be enabled for playing
+ * by calling SDL_PauseAudioDevice(devid, 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.
+ *
+ * The audio callback runs in a separate thread in most cases; you can prevent
+ * race conditions between your callback and other threads without fully
+ * pausing playback with SDL_LockAudioDevice(). For more information about the
+ * callback, see SDL_AudioSpec.
+ *
+ * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
+ * driver-specific name as appropriate. NULL requests the most
+ * reasonable default device.
+ * \param iscapture non-zero to specify a device should be opened for
+ * recording, not playback
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ * format; see SDL_OpenAudio() for more information
+ * \param obtained an SDL_AudioSpec structure filled in with the actual output
+ * format; see SDL_OpenAudio() for more information
+ * \param allowed_changes 0, or one or more flags OR'd together
+ * \returns a valid device ID that is > 0 on success or 0 on failure; call
+ * SDL_GetError() for more information.
+ *
+ * For compatibility with SDL 1.2, this will never return 1, since
+ * SDL reserves that ID for the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CloseAudioDevice
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_LockAudioDevice
+ * \sa SDL_OpenAudio
+ * \sa SDL_PauseAudioDevice
+ * \sa SDL_UnlockAudioDevice
*/
extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
*device,
@@ -418,9 +581,7 @@ typedef enum
SDL_AUDIO_PAUSED
} SDL_AudioStatus;
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
-
-extern DECLSPEC SDL_AudioStatus SDLCALL
-SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
+extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
/* @} *//* Audio State */
/**
@@ -439,56 +600,79 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
/* @} *//* Pause audio functions */
/**
- * \brief Load the audio data of a WAVE file into memory
+ * Load the audio data of a WAVE file into memory.
*
- * Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len
- * to be valid pointers. The entire data portion of the file is then loaded
- * into memory and decoded if necessary.
+ * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len`
+ * to be valid pointers. The entire data portion of the file is then loaded
+ * into memory and decoded if necessary.
*
- * If \c freesrc is non-zero, the data source gets automatically closed and
- * freed before the function returns.
+ * If `freesrc` is non-zero, the data source gets automatically closed and
+ * freed before the function returns.
*
- * Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits),
- * IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and
- * ยต-law (8 bits). Other formats are currently unsupported and cause an error.
+ * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
+ * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits),
+ * and A-law and mu-law (8 bits). Other formats are currently unsupported and
+ * cause an error.
*
- * If this function succeeds, the pointer returned by it is equal to \c spec
- * and the pointer to the audio data allocated by the function is written to
- * \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec
- * members \c freq, \c channels, and \c format are set to the values of the
- * audio data in the buffer. The \c samples member is set to a sane default and
- * all others are set to zero.
+ * If this function succeeds, the pointer returned by it is equal to `spec`
+ * and the pointer to the audio data allocated by the function is written to
+ * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
+ * members `freq`, `channels`, and `format` are set to the values of the
+ * audio data in the buffer. The `samples` member is set to a sane default
+ * and all others are set to zero.
*
- * It's necessary to use SDL_FreeWAV() to free the audio data returned in
- * \c audio_buf when it is no longer used.
+ * It's necessary to use SDL_FreeWAV() to free the audio data returned in
+ * `audio_buf` when it is no longer used.
*
- * Because of the underspecification of the Waveform format, there are many
- * problematic files in the wild that cause issues with strict decoders. To
- * provide compatibility with these files, this decoder is lenient in regards
- * to the truncation of the file, the fact chunk, and the size of the RIFF
- * chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION,
- * and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the
- * loading process.
+ * Because of the underspecification of the .WAV format, there are many
+ * problematic files in the wild that cause issues with strict decoders. To
+ * provide compatibility with these files, this decoder is lenient in regards
+ * to the truncation of the file, the fact chunk, and the size of the RIFF
+ * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, `SDL_HINT_WAVE_TRUNCATION`,
+ * and `SDL_HINT_WAVE_FACT_CHUNK` can be used to tune the behavior of the
+ * loading process.
*
- * Any file that is invalid (due to truncation, corruption, or wrong values in
- * the headers), too big, or unsupported causes an error. Additionally, any
- * critical I/O error from the data source will terminate the loading process
- * with an error. The function returns NULL on error and in all cases (with the
- * exception of \c src being NULL), an appropriate error message will be set.
+ * Any file that is invalid (due to truncation, corruption, or wrong values in
+ * the headers), too big, or unsupported causes an error. Additionally, any
+ * critical I/O error from the data source will terminate the loading process
+ * with an error. The function returns NULL on error and in all cases (with the
+ * exception of `src` being NULL), an appropriate error message will be set.
*
- * It is required that the data source supports seeking.
+ * It is required that the data source supports seeking.
*
- * Example:
- * \code
- * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
- * \endcode
+ * Example:
+ * ```c++
+ * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
+ * ```
*
- * \param src The data source with the WAVE data
- * \param freesrc A integer value that makes the function close the data source if non-zero
- * \param spec A pointer filled with the audio format of the audio data
- * \param audio_buf A pointer filled with the audio data allocated by the function
- * \param audio_len A pointer filled with the length of the audio data buffer in bytes
- * \return NULL on error, or non-NULL on success.
+ * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
+ * messy way:
+ *
+ * ```c++
+ * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
+ * ```
+ *
+ * \param src The data source for the WAVE data
+ * \param freesrc If non-zero, SDL will _always_ free the data source
+ * \param spec An SDL_AudioSpec that will be filled in with the wave file's
+ * format details
+ * \param audio_buf A pointer filled with the audio data, allocated by the function.
+ * \param audio_len A pointer filled with the length of the audio data buffer in bytes
+ * \returns This function, if successfully called, returns `spec`, which will
+ * be filled with the audio data format of the wave source data.
+ * `audio_buf` will be filled with a pointer to an allocated buffer
+ * containing the audio data, and `audio_len` is filled with the
+ * length of that audio buffer in bytes.
+ *
+ * This function returns NULL if the .WAV file cannot be opened, uses
+ * an unknown data format, or is corrupt; call SDL_GetError() for
+ * more information.
+ *
+ * When the application is done with the data returned in
+ * `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
+ *
+ * \sa SDL_FreeWAV
+ * \sa SDL_LoadWAV
*/
extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
int freesrc,
@@ -504,18 +688,50 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
/**
- * This function frees data previously allocated with SDL_LoadWAV_RW()
+ * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().
+ *
+ * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW()
+ * its data can eventually be freed with SDL_FreeWAV(). It is safe to call
+ * this function with a NULL pointer.
+ *
+ * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
+ * SDL_LoadWAV_RW()
+ *
+ * \sa SDL_LoadWAV
+ * \sa SDL_LoadWAV_RW
*/
extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
/**
- * This function takes a source format and rate and a destination format
- * and rate, and initializes the \c cvt structure with information needed
- * by SDL_ConvertAudio() to convert a buffer of audio data from one format
- * to the other. An unsupported format causes an error and -1 will be returned.
+ * Initialize an SDL_AudioCVT structure for conversion.
*
- * \return 0 if no conversion is needed, 1 if the audio filter is set up,
- * or -1 on error.
+ * Before an SDL_AudioCVT structure can be used to convert audio data it must
+ * be initialized with source and destination information.
+ *
+ * This function will zero out every field of the SDL_AudioCVT, so it must be
+ * called before the application fills in the final buffer information.
+ *
+ * Once this function has returned successfully, and reported that a
+ * conversion is necessary, the application fills in the rest of the fields in
+ * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate,
+ * and then can call SDL_ConvertAudio() to complete the conversion.
+ *
+ * \param cvt an SDL_AudioCVT structure filled in with audio conversion
+ * information
+ * \param src_format the source format of the audio data; for more info see
+ * SDL_AudioFormat
+ * \param src_channels the number of channels in the source
+ * \param src_rate the frequency (sample-frames-per-second) of the source
+ * \param dst_format the destination format of the audio data; for more info
+ * see SDL_AudioFormat
+ * \param dst_channels the number of channels in the destination
+ * \param dst_rate the frequency (sample-frames-per-second) of the
+ * destination
+ * \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
+ * or a negative error code on failure; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_ConvertAudio
*/
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
SDL_AudioFormat src_format,
@@ -526,16 +742,40 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
int dst_rate);
/**
- * Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
- * created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
- * audio data in the source format, this function will convert it in-place
- * to the desired format.
+ * Convert audio data to a desired audio format.
*
- * The data conversion may expand the size of the audio data, so the buffer
- * \c cvt->buf should be allocated after the \c cvt structure is initialized by
- * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
+ * This function does the actual audio data conversion, after the application
+ * has called SDL_BuildAudioCVT() to prepare the conversion information and
+ * then filled in the buffer details.
*
- * \return 0 on success or -1 if \c cvt->buf is NULL.
+ * Once the application has initialized the `cvt` structure using
+ * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio
+ * data in the source format, this function will convert the buffer, in-place,
+ * to the desired format.
+ *
+ * The data conversion may go through several passes; any given pass may
+ * possibly temporarily increase the size of the data. For example, SDL might
+ * expand 16-bit data to 32 bits before resampling to a lower frequency,
+ * shrinking the data size after having grown it briefly. Since the supplied
+ * buffer will be both the source and destination, converting as necessary
+ * in-place, the application must allocate a buffer that will fully contain
+ * the data during its largest conversion pass. After SDL_BuildAudioCVT()
+ * returns, the application should set the `cvt->len` field to the size, in
+ * bytes, of the source data, and allocate a buffer that is
+ * `cvt->len * cvt->len_mult` bytes long for the `buf` field.
+ *
+ * The source data should be copied into this buffer before the call to
+ * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
+ * converted audio, and `cvt->len_cvt` will be the size of the converted data,
+ * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once
+ * this function returns.
+ *
+ * \param cvt an SDL_AudioCVT structure that was previously set up by
+ * SDL_BuildAudioCVT().
+ * \returns 0 if the conversion was completed successfully or a negative error
+ * code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_BuildAudioCVT
*/
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
@@ -551,7 +791,7 @@ struct _SDL_AudioStream;
typedef struct _SDL_AudioStream SDL_AudioStream;
/**
- * Create a new audio stream
+ * Create a new audio stream.
*
* \param src_format The format of the source audio
* \param src_channels The number of channels of the source audio
@@ -559,7 +799,7 @@ typedef struct _SDL_AudioStream SDL_AudioStream;
* \param dst_format The format of the desired audio output
* \param dst_channels The number of channels of the desired audio output
* \param dst_rate The sampling rate of the desired audio output
- * \return 0 on success, or -1 on error.
+ * \returns 0 on success, or -1 on error.
*
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
@@ -576,12 +816,12 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
const int dst_rate);
/**
- * Add data to be converted/resampled to the stream
+ * Add data to be converted/resampled to the stream.
*
* \param stream The stream the audio data is being added to
* \param buf A pointer to the audio data to add
* \param len The number of bytes to write to the stream
- * \return 0 on success, or -1 on error.
+ * \returns 0 on success, or -1 on error.
*
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamGet
@@ -598,7 +838,7 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo
* \param stream The stream the audio is being requested from
* \param buf A buffer to fill with audio data
* \param len The maximum number of bytes to fill
- * \return The number of bytes read from the stream, or -1 on error
+ * \returns the number of bytes read from the stream, or -1 on error
*
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
@@ -667,19 +907,55 @@ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
#define SDL_MIX_MAXVOLUME 128
/**
- * This takes two audio buffers of the playing audio format and mixes
- * them, performing addition, volume adjustment, and overflow clipping.
- * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
- * for full audio volume. Note this does not change hardware volume.
- * This is provided for convenience -- you can mix your own audio data.
+ * This function is a legacy means of mixing audio.
+ *
+ * This function is equivalent to calling
+ *
+ * ```c++
+ * SDL_MixAudioFormat(dst, src, format, len, volume);
+ * ```
+ *
+ * where `format` is the obtained format of the audio device from the legacy
+ * SDL_OpenAudio() function.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ * for full audio volume
+ *
+ * \sa SDL_MixAudioFormat
*/
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
Uint32 len, int volume);
/**
- * This works like SDL_MixAudio(), but you specify the audio format instead of
- * using the format of audio device 1. Thus it can be used when no audio
- * device is open at all.
+ * Mix audio data in a specified format.
+ *
+ * This takes an audio buffer `src` of `len` bytes of `format` data and
+ * mixes it into `dst`, performing addition, volume adjustment, and overflow
+ * clipping. The buffer pointed to by `dst` must also be `len` bytes of
+ * `format` data.
+ *
+ * This is provided for convenience -- you can mix your own audio data.
+ *
+ * Do not use this function for mixing together more than two streams of
+ * sample data. The output from repeated application of this function may be
+ * distorted by clipping, because there is no accumulator with greater range
+ * than the input (not to mention this being an inefficient way of doing it).
+ *
+ * It is a common misconception that this function is required to write audio
+ * data to an output stream in an audio callback. While you can do that,
+ * SDL_MixAudioFormat() is really only needed when you're mixing a single
+ * audio stream with a volume adjustment.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param format the SDL_AudioFormat structure representing the desired audio
+ * format
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ * for full audio volume
*/
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
const Uint8 * src,
@@ -687,161 +963,163 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
Uint32 len, int volume);
/**
- * Queue more audio on non-callback devices.
+ * Queue more audio on non-callback devices.
*
- * (If you are looking to retrieve queued audio from a non-callback capture
- * device, you want SDL_DequeueAudio() instead. This will return -1 to
- * signify an error if you use it with capture devices.)
+ * If you are looking to retrieve queued audio from a non-callback capture
+ * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return
+ * -1 to signify an error if you use it with capture devices.
*
- * SDL offers two ways to feed audio to the device: you can either supply a
- * callback that SDL triggers with some frequency to obtain more audio
- * (pull method), or you can supply no callback, and then SDL will expect
- * you to supply data at regular intervals (push method) with this function.
+ * SDL offers two ways to feed audio to the device: you can either supply a
+ * callback that SDL triggers with some frequency to obtain more audio (pull
+ * method), or you can supply no callback, and then SDL will expect you to
+ * supply data at regular intervals (push method) with this function.
*
- * There are no limits on the amount of data you can queue, short of
- * exhaustion of address space. Queued data will drain to the device as
- * necessary without further intervention from you. If the device needs
- * audio but there is not enough queued, it will play silence to make up
- * the difference. This means you will have skips in your audio playback
- * if you aren't routinely queueing sufficient data.
+ * There are no limits on the amount of data you can queue, short of
+ * exhaustion of address space. Queued data will drain to the device as
+ * necessary without further intervention from you. If the device needs audio
+ * but there is not enough queued, it will play silence to make up the
+ * difference. This means you will have skips in your audio playback if you
+ * aren't routinely queueing sufficient data.
*
- * This function copies the supplied data, so you are safe to free it when
- * the function returns. This function is thread-safe, but queueing to the
- * same device from two threads at once does not promise which buffer will
- * be queued first.
+ * This function copies the supplied data, so you are safe to free it when the
+ * function returns. This function is thread-safe, but queueing to the same
+ * device from two threads at once does not promise which buffer will be
+ * queued first.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; doing so returns an error. You have to use the audio callback
- * or queue audio with this function, but not both.
+ * You may not queue audio on a device that is using an application-supplied
+ * callback; doing so returns an error. You have to use the audio callback or
+ * queue audio with this function, but not both.
*
- * You should not call SDL_LockAudio() on the device before queueing; SDL
- * handles locking internally for this function.
+ * You should not call SDL_LockAudio() on the device before queueing; SDL
+ * handles locking internally for this function.
*
- * \param dev The device ID to which we will queue audio.
- * \param data The data to queue to the device for later playback.
- * \param len The number of bytes (not samples!) to which (data) points.
- * \return 0 on success, or -1 on error.
+ * \param dev the device ID to which we will queue audio
+ * \param data the data to queue to the device for later playback
+ * \param len the number of bytes (not samples!) to which `data` points
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetQueuedAudioSize
- * \sa SDL_ClearQueuedAudio
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
/**
- * Dequeue more audio on non-callback devices.
+ * Dequeue more audio on non-callback devices.
*
- * (If you are looking to queue audio for output on a non-callback playback
- * device, you want SDL_QueueAudio() instead. This will always return 0
- * if you use it with playback devices.)
+ * If you are looking to queue audio for output on a non-callback playback
+ * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always
+ * return 0 if you use it with playback devices.
*
- * SDL offers two ways to retrieve audio from a capture device: you can
- * either supply a callback that SDL triggers with some frequency as the
- * device records more audio data, (push method), or you can supply no
- * callback, and then SDL will expect you to retrieve data at regular
- * intervals (pull method) with this function.
+ * SDL offers two ways to retrieve audio from a capture device: you can either
+ * supply a callback that SDL triggers with some frequency as the device
+ * records more audio data, (push method), or you can supply no callback, and
+ * then SDL will expect you to retrieve data at regular intervals (pull
+ * method) with this function.
*
- * There are no limits on the amount of data you can queue, short of
- * exhaustion of address space. Data from the device will keep queuing as
- * necessary without further intervention from you. This means you will
- * eventually run out of memory if you aren't routinely dequeueing data.
+ * There are no limits on the amount of data you can queue, short of
+ * exhaustion of address space. Data from the device will keep queuing as
+ * necessary without further intervention from you. This means you will
+ * eventually run out of memory if you aren't routinely dequeueing data.
*
- * Capture devices will not queue data when paused; if you are expecting
- * to not need captured audio for some length of time, use
- * SDL_PauseAudioDevice() to stop the capture device from queueing more
- * data. This can be useful during, say, level loading times. When
- * unpaused, capture devices will start queueing data from that point,
- * having flushed any capturable data available while paused.
+ * Capture devices will not queue data when paused; if you are expecting to
+ * not need captured audio for some length of time, use SDL_PauseAudioDevice()
+ * to stop the capture device from queueing more data. This can be useful
+ * during, say, level loading times. When unpaused, capture devices will start
+ * queueing data from that point, having flushed any capturable data available
+ * while paused.
*
- * This function is thread-safe, but dequeueing from the same device from
- * two threads at once does not promise which thread will dequeued data
- * first.
+ * This function is thread-safe, but dequeueing from the same device from two
+ * threads at once does not promise which thread will dequeue data first.
*
- * You may not dequeue audio from a device that is using an
- * application-supplied callback; doing so returns an error. You have to use
- * the audio callback, or dequeue audio with this function, but not both.
+ * You may not dequeue audio from a device that is using an
+ * application-supplied callback; doing so returns an error. You have to use
+ * the audio callback, or dequeue audio with this function, but not both.
*
- * You should not call SDL_LockAudio() on the device before queueing; SDL
- * handles locking internally for this function.
+ * You should not call SDL_LockAudio() on the device before dequeueing; SDL
+ * handles locking internally for this function.
*
- * \param dev The device ID from which we will dequeue audio.
- * \param data A pointer into where audio data should be copied.
- * \param len The number of bytes (not samples!) to which (data) points.
- * \return number of bytes dequeued, which could be less than requested.
+ * \param dev the device ID from which we will dequeue audio
+ * \param data a pointer into where audio data should be copied
+ * \param len the number of bytes (not samples!) to which (data) points
+ * \returns number of bytes dequeued, which could be less than requested; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetQueuedAudioSize
- * \sa SDL_ClearQueuedAudio
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
/**
- * Get the number of bytes of still-queued audio.
+ * Get the number of bytes of still-queued audio.
*
- * For playback device:
+ * For playback devices: this is the number of bytes that have been queued
+ * for playback with SDL_QueueAudio(), but have not yet been sent to the
+ * hardware.
*
- * This is the number of bytes that have been queued for playback with
- * SDL_QueueAudio(), but have not yet been sent to the hardware. This
- * number may shrink at any time, so this only informs of pending data.
+ * Once we've sent it to the hardware, this function can not decide the exact
+ * byte boundary of what has been played. It's possible that we just gave the
+ * hardware several kilobytes right before you called this function, but it
+ * hasn't played any of it yet, or maybe half of it, etc.
*
- * Once we've sent it to the hardware, this function can not decide the
- * exact byte boundary of what has been played. It's possible that we just
- * gave the hardware several kilobytes right before you called this
- * function, but it hasn't played any of it yet, or maybe half of it, etc.
+ * For capture devices, this is the number of bytes that have been captured by
+ * the device and are waiting for you to dequeue. This number may grow at any
+ * time, so this only informs of the lower-bound of available data.
*
- * For capture devices:
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
*
- * This is the number of bytes that have been captured by the device and
- * are waiting for you to dequeue. This number may grow at any time, so
- * this only informs of the lower-bound of available data.
+ * You should not call SDL_LockAudio() on the device before querying; SDL
+ * handles locking internally for this function.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; calling this function on such a device always returns 0.
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
- * the audio callback, but not both.
+ * \param dev the device ID of which we will query queued audio size
+ * \returns the number of bytes (not samples!) of queued audio.
*
- * You should not call SDL_LockAudio() on the device before querying; SDL
- * handles locking internally for this function.
+ * \since This function is available since SDL 2.0.4.
*
- * \param dev The device ID of which we will query queued audio size.
- * \return Number of bytes (not samples!) of queued audio.
- *
- * \sa SDL_QueueAudio
- * \sa SDL_ClearQueuedAudio
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
/**
- * Drop any queued audio data. For playback devices, this is any queued data
- * still waiting to be submitted to the hardware. For capture devices, this
- * is any data that was queued by the device that hasn't yet been dequeued by
- * the application.
+ * Drop any queued audio data waiting to be sent to the hardware.
*
- * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
- * playback devices, the hardware will start playing silence if more audio
- * isn't queued. Unpaused capture devices will start filling the queue again
- * as soon as they have more data available (which, depending on the state
- * of the hardware and the thread, could be before this function call
- * returns!).
+ * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
+ * output devices, the hardware will start playing silence if more audio isn't
+ * queued. For capture devices, the hardware will start filling the empty
+ * queue with new data if the capture device isn't paused.
*
- * This will not prevent playback of queued audio that's already been sent
- * to the hardware, as we can not undo that, so expect there to be some
- * fraction of a second of audio that might still be heard. This can be
- * useful if you want to, say, drop any pending music during a level change
- * in your game.
+ * This will not prevent playback of queued audio that's already been sent to
+ * the hardware, as we can not undo that, so expect there to be some fraction
+ * of a second of audio that might still be heard. This can be useful if you
+ * want to, say, drop any pending music or any unprocessed microphone input
+ * during a level change in your game.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; calling this function on such a device is always a no-op.
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
- * the audio callback, but not both.
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
*
- * You should not call SDL_LockAudio() on the device before clearing the
- * queue; SDL handles locking internally for this function.
+ * You should not call SDL_LockAudio() on the device before clearing the
+ * queue; SDL handles locking internally for this function.
*
- * This function always succeeds and thus returns void.
+ * This function always succeeds and thus returns void.
*
- * \param dev The device ID of which to clear the audio queue.
+ * \param dev the device ID of which to clear the audio queue
*
- * \sa SDL_QueueAudio
- * \sa SDL_GetQueuedAudioSize
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_GetQueuedAudioSize
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
*/
extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
@@ -862,7 +1140,17 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
/* @} *//* Audio lock functions */
/**
- * This function shuts down audio processing and closes the audio device.
+ * This function is a legacy means of closing the audio device.
+ *
+ * This function is equivalent to calling
+ *
+ * ```c++
+ * SDL_CloseAudioDevice(1);
+ * ```
+ *
+ * and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \sa SDL_OpenAudio
*/
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h
index 4c45cad66..919588a70 100644
--- a/include/SDL_blendmode.h
+++ b/include/SDL_blendmode.h
@@ -91,19 +91,106 @@ typedef enum
} SDL_BlendFactor;
/**
- * \brief Create a custom blend mode, which may or may not be supported by a given renderer
+ * Compose a custom blend mode for renderers.
*
- * \param srcColorFactor source color factor
- * \param dstColorFactor destination color factor
- * \param colorOperation color operation
- * \param srcAlphaFactor source alpha factor
- * \param dstAlphaFactor destination alpha factor
- * \param alphaOperation alpha operation
+ * The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept
+ * the SDL_BlendMode returned by this function if the renderer supports it.
*
- * The result of the blend mode operation will be:
- * dstRGB = dstRGB * dstColorFactor colorOperation srcRGB * srcColorFactor
- * and
- * dstA = dstA * dstAlphaFactor alphaOperation srcA * srcAlphaFactor
+ * A blend mode controls how the pixels from a drawing operation (source) get
+ * combined with the pixels from the render target (destination). First, the
+ * components of the source and destination pixels get multiplied with their
+ * blend factors. Then, the blend operation takes the two products and
+ * calculates the result that will get stored in the render target.
+ *
+ * Expressed in pseudocode, it would look like this:
+ *
+ * ```c
+ * dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor);
+ * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
+ * ```
+ *
+ * Where the functions `colorOperation(src, dst)` and
+ * `alphaOperation(src, dst)` can return one of the following:
+ *
+ * - `src + dst`
+ *
+ * - `src - dst`
+ *
+ * - `dst - src`
+ *
+ * - `min(src, dst)`
+ *
+ * - `max(src, dst)`
+ *
+ * The red, green, and blue components are always multiplied with the first,
+ * second, and third components of the SDL_BlendFactor, respectively. The
+ * fourth component is not used.
+ *
+ * The alpha component is always multiplied with the fourth component of the
+ * SDL_BlendFactor. The other components are not used in the alpha
+ * calculation.
+ *
+ * Support for these blend modes varies for each renderer. To check if a
+ * specific SDL_BlendMode is supported, create a renderer and pass it to
+ * either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will
+ * return with an error if the blend mode is not supported.
+ *
+ * This list describes the support of custom blend modes for each renderer in
+ * SDL 2.0.6. All renderers support the four blend modes listed in the
+ * SDL_BlendMode enumeration.
+ *
+ * - **direct3d**: Supports `SDL_BLENDOPERATION_ADD` with all factors.
+ *
+ * - **direct3d11**: Supports all operations with all factors. However, some
+ * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
+ * `SDL_BLENDOPERATION_MAXIMUM`.
+ *
+ * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
+ * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with
+ * SDL 2.0.6.
+ *
+ * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
+ * factors. Color and alpha factors need to be the same. OpenGL ES 1
+ * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
+ * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
+ * operations being different from each other. May support color and alpha
+ * factors being different from each other.
+ *
+ * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
+ * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations
+ * with all factors.
+ *
+ * - **psp**: No custom blend mode support.
+ *
+ * - **software**: No custom blend mode support.
+ *
+ * Some renderers do not provide an alpha component for the default render
+ * target. The `SDL_BLENDFACTOR_DST_ALPHA` and
+ * `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this
+ * case.
+ *
+ * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
+ * blue components of the source pixels
+ * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
+ * blue components of the destination pixels
+ * \param colorOperation the SDL_BlendOperation used to combine the red,
+ * green, and blue components of the source and
+ * destination pixels
+ * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ * the source pixels
+ * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ * the destination pixels
+ * \param alphaOperation the SDL_BlendOperation used to combine the alpha
+ * component of the source and destination pixels
+ * \returns an SDL_BlendMode that represents the chosen factors and
+ * operations.
+ *
+ * \since This function is available in SDL 2.0.6.
+ *
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_GetRenderDrawBlendMode
+ * \sa SDL_SetTextureBlendMode
+ * \sa SDL_GetTextureBlendMode
*/
extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor,
SDL_BlendFactor dstColorFactor,
diff --git a/include/SDL_clipboard.h b/include/SDL_clipboard.h
index 1455348fd..79e4dcc33 100644
--- a/include/SDL_clipboard.h
+++ b/include/SDL_clipboard.h
@@ -39,23 +39,41 @@ extern "C" {
/* Function prototypes */
/**
- * \brief Put UTF-8 text into the clipboard
+ * Put UTF-8 text into the clipboard.
*
- * \sa SDL_GetClipboardText()
+ * \param text the text to store in the clipboard
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetClipboardText
+ * \sa SDL_HasClipboardText
*/
extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
/**
- * \brief Get UTF-8 text from the clipboard, which must be freed with SDL_free()
+ * Get UTF-8 text from the clipboard, which must be freed with SDL_free().
*
- * \sa SDL_SetClipboardText()
+ * This functions returns NULL if there was not enough memory left for a copy
+ * of the clipboard's content.
+ *
+ * \returns the clipboard text on success or NULL on failure; call
+ * SDL_GetError() for more information. Caller must call SDL_free()
+ * on the returned pointer when done with it.
+ *
+ * \sa SDL_HasClipboardText
+ * \sa SDL_SetClipboardText
*/
extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
/**
- * \brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty
+ * Query whether the clipboard exists and contains a non-empty text string.
*
- * \sa SDL_GetClipboardText()
+ * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetClipboardText
+ * \sa SDL_SetClipboardText
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h
index d3984be34..d5273113c 100644
--- a/include/SDL_cpuinfo.h
+++ b/include/SDL_cpuinfo.h
@@ -117,136 +117,340 @@ extern "C" {
#define SDL_CACHELINE_SIZE 128
/**
- * This function returns the number of CPU cores available.
+ * Get the number of CPU cores available.
+ *
+ * \returns the total number of logical CPU cores. On CPUs that include
+ * technologies such as hyperthreading, the number of logical cores
+ * may be more than the number of physical cores.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCount(void);
/**
- * This function returns the L1 cache line size of the CPU
+ * Determine the L1 cache line size of the CPU.
*
- * This is useful for determining multi-threaded structure padding
- * or SIMD prefetch sizes.
+ * This is useful for determining multi-threaded structure padding or SIMD
+ * prefetch sizes.
+ *
+ * \returns the L1 cache line size of the CPU, in bytes.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void);
/**
- * This function returns true if the CPU has the RDTSC instruction.
+ * Determine whether the CPU has the RDTSC instruction.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
/**
- * This function returns true if the CPU has AltiVec features.
+ * Determine whether the CPU has AltiVec features.
+ *
+ * This always returns false on CPUs that aren't using PowerPC instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
/**
- * This function returns true if the CPU has MMX features.
+ * Determine whether the CPU has MMX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
/**
- * This function returns true if the CPU has 3DNow! features.
+ * Determine whether the CPU has 3DNow! features.
+ *
+ * This always returns false on CPUs that aren't using AMD instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
/**
- * This function returns true if the CPU has SSE features.
+ * Determine whether the CPU has SSE features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
/**
- * This function returns true if the CPU has SSE2 features.
+ * Determine whether the CPU has SSE2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
/**
- * This function returns true if the CPU has SSE3 features.
+ * Determine whether the CPU has SSE3 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void);
/**
- * This function returns true if the CPU has SSE4.1 features.
+ * Determine whether the CPU has SSE4.1 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void);
/**
- * This function returns true if the CPU has SSE4.2 features.
+ * Determine whether the CPU has SSE4.2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void);
/**
- * This function returns true if the CPU has AVX features.
+ * Determine whether the CPU has AVX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void);
/**
- * This function returns true if the CPU has AVX2 features.
+ * Determine whether the CPU has AVX2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void);
/**
- * This function returns true if the CPU has AVX-512F (foundation) features.
+ * Determine whether the CPU has AVX-512F (foundation) features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasAVX
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
/**
- * This function returns true if the CPU has ARM SIMD (ARMv6) features.
+ * Determine whether the CPU has ARM SIMD (ARMv6) features.
+ *
+ * This is different from ARM NEON, which is a different instruction set.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasNEON
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
/**
- * This function returns true if the CPU has NEON (ARM SIMD) features.
+ * Determine whether the CPU has NEON (ARM SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
/**
- * This function returns the amount of RAM configured in the system, in MB.
+ * Get the amount of RAM configured in the system.
+ *
+ * \returns the amount of RAM configured in the system in MB.
+ *
+ * \since This function is available since SDL 2.0.1.
*/
extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
/**
- * \brief Report the alignment this system needs for SIMD allocations.
+ * Report the alignment this system needs for SIMD allocations.
*
* This will return the minimum number of bytes to which a pointer must be
- * aligned to be compatible with SIMD instructions on the current machine.
- * For example, if the machine supports SSE only, it will return 16, but if
- * it supports AVX-512F, it'll return 64 (etc). This only reports values for
- * instruction sets SDL knows about, so if your SDL build doesn't have
- * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
- * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
- * Plan accordingly.
+ * aligned to be compatible with SIMD instructions on the current machine.
+ * For example, if the machine supports SSE only, it will return 16, but if
+ * it supports AVX-512F, it'll return 64 (etc). This only reports values for
+ * instruction sets SDL knows about, so if your SDL build doesn't have
+ * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
+ * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
+ * Plan accordingly.
+ *
+ * \returns Alignment in bytes needed for available, known SIMD instructions.
*/
extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
/**
- * \brief Allocate memory in a SIMD-friendly way.
+ * Allocate memory in a SIMD-friendly way.
*
* This will allocate a block of memory that is suitable for use with SIMD
- * instructions. Specifically, it will be properly aligned and padded for
- * the system's supported vector instructions.
+ * instructions. Specifically, it will be properly aligned and padded for
+ * the system's supported vector instructions.
*
* The memory returned will be padded such that it is safe to read or write
- * an incomplete vector at the end of the memory block. This can be useful
- * so you don't have to drop back to a scalar fallback at the end of your
- * SIMD processing loop to deal with the final elements without overflowing
- * the allocated buffer.
+ * an incomplete vector at the end of the memory block. This can be useful
+ * so you don't have to drop back to a scalar fallback at the end of your
+ * SIMD processing loop to deal with the final elements without overflowing
+ * the allocated buffer.
*
* You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
- * or delete[], etc.
+ * or delete[], etc.
*
* Note that SDL will only deal with SIMD instruction sets it is aware of;
- * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
- * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
- * know that AVX-512 wants 64. To be clear: if you can't decide to use an
- * instruction set with an SDL_Has*() function, don't use that instruction
- * set with memory allocated through here.
+ * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
+ * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
+ * know that AVX-512 wants 64. To be clear: if you can't decide to use an
+ * instruction set with an SDL_Has*() function, don't use that instruction
+ * set with memory allocated through here.
*
* SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
- * out of memory.
+ * out of memory, but you are not allowed to dereference it (because you only
+ * own zero bytes of that buffer).
*
- * \param len The length, in bytes, of the block to allocated. The actual
- * allocated block might be larger due to padding, etc.
- * \return Pointer to newly-allocated block, NULL if out of memory.
+ * \param len The length, in bytes, of the block to allocate. The actual
+ * allocated block might be larger due to padding, etc.
+ * \returns Pointer to newly-allocated block, NULL if out of memory.
*
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDRealloc
@@ -255,20 +459,20 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
/**
- * \brief Reallocate memory obtained from SDL_SIMDAlloc
+ * Reallocate memory obtained from SDL_SIMDAlloc
*
* It is not valid to use this function on a pointer from anything but
- * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
- * SDL_malloc, memalign, new[], etc.
+ * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
+ * SDL_malloc, memalign, new[], etc.
*
- * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
- * accepts NULL, at which point this function is the same as
- * calling SDL_realloc with a NULL pointer.
- * \param len The length, in bytes, of the block to allocated. The actual
- * allocated block might be larger due to padding, etc. Passing 0
- * will return a non-NULL pointer, assuming the system isn't out of
- * memory.
- * \return Pointer to newly-reallocated block, NULL if out of memory.
+ * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
+ * accepts NULL, at which point this function is the same as
+ * calling SDL_SIMDAlloc with a NULL pointer.
+ * \param len The length, in bytes, of the block to allocated. The actual
+ * allocated block might be larger due to padding, etc. Passing 0
+ * will return a non-NULL pointer, assuming the system isn't out of
+ * memory.
+ * \returns Pointer to newly-reallocated block, NULL if out of memory.
*
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDAlloc
@@ -277,20 +481,27 @@ extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
/**
- * \brief Deallocate memory obtained from SDL_SIMDAlloc
+ * Deallocate memory obtained from SDL_SIMDAlloc
*
* It is not valid to use this function on a pointer from anything but
- * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
- * SDL_malloc, memalign, new[], etc.
+ * SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from
+ * malloc, realloc, SDL_malloc, memalign, new[], etc.
*
* However, SDL_SIMDFree(NULL) is a legal no-op.
*
+ * The memory pointed to by `ptr` is no longer valid for access upon return,
+ * and may be returned to the system or reused by a future allocation.
+ * The pointer passed to this function is no longer safe to dereference once
+ * this function returns, and should be discarded.
+ *
+ * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc,
+ * to deallocate. NULL is a legal no-op.
+ *
* \sa SDL_SIMDAlloc
* \sa SDL_SIMDRealloc
*/
extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr);
-/* vi: set ts=4 sw=4 expandtab: */
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
diff --git a/include/SDL_error.h b/include/SDL_error.h
index 144a17070..bb200c5fb 100644
--- a/include/SDL_error.h
+++ b/include/SDL_error.h
@@ -40,41 +40,83 @@ extern "C" {
/**
- * \brief Set the error message for the current thread
+ * Set the SDL error message for the current thread.
*
- * \return -1, there is no error handling for this function
+ * Calling this function will replace any previous error message that was set.
+ *
+ * This function always returns -1, since SDL frequently uses -1 to signify
+ * an failing result, leading to this idiom:
+ *
+ * ```c
+ * if (error_code) {
+ * return SDL_SetError("This operation has failed: %d", error_code);
+ * }
+ * ```
+ *
+ * \param fmt a printf()-style message format string
+ * \param ... additional parameters matching % tokens in the `fmt` string,
+ * if any
+ * \returns always -1.
+ *
+ * \sa SDL_ClearError
+ * \sa SDL_GetError
*/
extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/**
- * \brief Get the last error message that was set
+ * Retrieve a message about the last error that occurred on the current thread.
*
- * SDL API functions may set error messages and then succeed, so you should
- * only use the error value if a function fails.
- *
- * This returns a pointer to a static buffer for convenience and should not
- * be called by multiple threads simultaneously.
+ * It is possible for multiple errors to occur before calling SDL_GetError().
+ * Only the last error is returned.
*
- * \return a pointer to the last error message that was set
+ * The message is only applicable when an SDL function has signaled an error.
+ * You must check the return values of SDL function calls to determine when
+ * to appropriately call SDL_GetError(). You should _not_ use the results
+ * of SDL_GetError() to decide if an error has occurred! Sometimes SDL will
+ * set an error string even when reporting success.
+ *
+ * SDL will _not_ clear the error string for successful API calls. You _must_
+ * check return values for failure cases before you can assume the error
+ * string applies.
+ *
+ * Error strings are set per-thread, so an error set in a different thread
+ * will not interfere with the current thread's operation.
+ *
+ * The returned string is internally allocated and must not be freed by the
+ * application.
+ *
+ * \returns a message with information about the specific error that occurred,
+ * or an empty string if there hasn't been an error message set since
+ * the last call to SDL_ClearError(). The message is only applicable when an
+ * SDL function has signaled an error. You must check the return
+ * values of SDL function calls to determine when to appropriately
+ * call SDL_GetError().
+ *
+ * \sa SDL_ClearError
+ * \sa SDL_SetError
*/
extern DECLSPEC const char *SDLCALL SDL_GetError(void);
/**
- * \brief Get the last error message that was set for the current thread
+ * Get the last error message that was set for the current thread.
*
- * SDL API functions may set error messages and then succeed, so you should
- * only use the error value if a function fails.
- *
- * \param errstr A buffer to fill with the last error message that was set
+ * This allows the caller to copy the error string into a provided buffer,
+ * but otherwise operates exactly the same as SDL_GetError().
+ *
+ * \param errstr A buffer to fill with the last error message that was set
* for the current thread
- * \param maxlen The size of the buffer pointed to by the errstr parameter
+ * \param maxlen The size of the buffer pointed to by the errstr parameter
+ * \returns The pointer passed in as the `errstr` parameter.
*
- * \return errstr
+ * \sa SDL_GetError
*/
extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
/**
- * \brief Clear the error message for the current thread
+ * Clear any previous error message for this thread.
+ *
+ * \sa SDL_GetError
+ * \sa SDL_SetError
*/
extern DECLSPEC void SDLCALL SDL_ClearError(void);
diff --git a/include/SDL_events.h b/include/SDL_events.h
index c775b1047..a2f3e3c8e 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -50,7 +50,7 @@ extern "C" {
#define SDL_PRESSED 1
/**
- * \brief The types of events that can be delivered.
+ * The types of events that can be delivered.
*/
typedef enum
{
@@ -637,11 +637,24 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == 56);
/* Function prototypes */
/**
- * Pumps the event loop, gathering events from the input devices.
+ * Pump the event loop, gathering events from the input devices.
*
- * This function updates the event queue and internal input device state.
+ * This function updates the event queue and internal input device state.
*
- * This should only be run in the thread that sets the video mode.
+ * **WARNING**: This should only be run in the thread that initialized the
+ * video subsystem, and for extra safety, you should consider only doing those
+ * things on the main thread in any case.
+ *
+ * SDL_PumpEvents() gathers all the pending input information from devices and
+ * places it in the event queue. Without calls to SDL_PumpEvents() no events
+ * would ever be placed on the queue. Often the need for calls to
+ * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
+ * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
+ * polling or waiting for events (e.g. you are filtering them), then you must
+ * call SDL_PumpEvents() to force an event queue update.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_WaitEvent
*/
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
@@ -654,22 +667,42 @@ typedef enum
} SDL_eventaction;
/**
- * Checks the event queue for messages and optionally returns them.
+ * Check the event queue for messages and optionally return them.
*
- * If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
- * the back of the event queue.
+ * `action` may be any of the following:
*
- * If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
- * of the event queue, within the specified minimum and maximum type,
- * will be returned and will not be removed from the queue.
+ * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of
+ * the event queue.
*
- * If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
- * of the event queue, within the specified minimum and maximum type,
- * will be returned and will be removed from the queue.
+ * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will _not_ be removed from the queue.
*
- * \return The number of events actually stored, or -1 if there was an error.
+ * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will be removed from the queue.
*
- * This function is thread-safe.
+ * You may have to call SDL_PumpEvents() before calling this function.
+ * Otherwise, the events may not be ready to be filtered when you call
+ * SDL_PeepEvents().
+ *
+ * This function is thread-safe.
+ *
+ * \param events destination buffer for the retrieved events
+ * \param numevents if action is SDL_ADDEVENT, the number of events to add
+ * back to the event queue; if action is SDL_PEEKEVENT or
+ * SDL_GETEVENT, the maximum number of events to retrieve
+ * \param action action to take; see [[#action|Remarks]] for details
+ * \param minType minimum value of the event type to be considered;
+ * SDL_FIRSTEVENT is a safe choice
+ * \param maxType maximum value of the event type to be considered;
+ * SDL_LASTEVENT is a safe choice
+ * \returns the number of events actually stored or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_PushEvent
*/
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
@@ -677,113 +710,330 @@ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
/* @} */
/**
- * Checks to see if certain event types are in the event queue.
+ * Check for the existence of a certain event type in the event queue.
+ *
+ * If you need to check for a range of event types, use SDL_HasEvents()
+ * instead.
+ *
+ * \param type the type of event to be queried; see SDL_EventType for details
+ * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
+ * events matching `type` are not present.
+ *
+ * \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
+
+
+/**
+ * Check for the existence of certain event types in the event queue.
+ *
+ * If you need to check for a single event type, use SDL_HasEvent() instead.
+ *
+ * \param minType the low end of event type to be queried, inclusive; see
+ * SDL_EventType for details
+ * \param maxType the high end of event type to be queried, inclusive; see
+ * SDL_EventType for details
+ * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
+ * present, or SDL_FALSE if not.
+ *
+ * \sa SDL_HasEvents
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
/**
- * This function clears events from the event queue
- * This function only affects currently queued events. If you want to make
- * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
- * on the main thread immediately before the flush call.
+ * Clear events of a specific type from the event queue.
+ *
+ * This will unconditionally remove any events from the queue that match
+ * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
+ * instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param type the type of event to be cleared; see SDL_EventType for details
+ *
+ * \sa SDL_FlushEvents
*/
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
+
+/**
+ * Clear events of a range of types from the event queue.
+ *
+ * This will unconditionally remove any events from the queue that are in the
+ * range of `minType` to `maxType`, inclusive. If you need to remove a single
+ * event type, use SDL_FlushEvent() instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param minType the low end of event type to be cleared, inclusive; see
+ * SDL_EventType for details
+ * \param maxType the high end of event type to be cleared, inclusive; see
+ * SDL_EventType for details
+ *
+ * \sa SDL_FlushEvent
+ */
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
/**
- * \brief Polls for currently pending events.
+ * Poll for currently pending events.
*
- * \return 1 if there are any pending events, or 0 if there are none available.
+ * If `event` is not NULL, the next event is removed from the queue and
+ * stored in the SDL_Event structure pointed to by `event`. The 1 returned
+ * refers to this event, immediately stored in the SDL Event structure -- not
+ * an event to follow.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
+ * If `event` is NULL, it simply returns 1 if there is an event in the queue,
+ * but will not remove it from the queue.
+ *
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that set the video mode.
+ *
+ * SDL_PollEvent() is the favored way of receiving system events since it can
+ * be done from the main loop and does not suspend the main loop while waiting
+ * on an event to be posted.
+ *
+ * The common practice is to fully process the event queue once every frame,
+ * usually as a first step before updating the game's state:
+ *
+ * ```c
+ * while (game_is_still_running) {
+ * SDL_Event event;
+ * while (SDL_PollEvent(&event)) { // poll until all events are handled!
+ * // decide what to do with this event.
+ * }
+ *
+ * // update game state, draw the current frame
+ * }
+ * ```
+ *
+ * \param event the SDL_Event structure to be filled with the next event from
+ * the queue, or NULL
+ * \returns 1 if there is a pending event or 0 if there are none available.
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
+ * \sa SDL_SetEventFilter
+ * \sa SDL_WaitEvent
+ * \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
/**
- * \brief Waits indefinitely for the next available event.
+ * Wait indefinitely for the next available event.
*
- * \return 1, or 0 if there was an error while waiting for events.
+ * If `event` is not NULL, the next event is removed from the queue and
+ * stored in the SDL_Event structure pointed to by `event`.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that initialized the video subsystem.
+ *
+ * \param event the SDL_Event structure to be filled in with the next event
+ * from the queue, or NULL
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
/**
- * \brief Waits until the specified timeout (in milliseconds) for the next
- * available event.
+ * Wait until the specified timeout (in milliseconds) for
+ * the next available event.
*
- * \return 1, or 0 if there was an error while waiting for events.
+ * If `event` is not NULL, the next event is removed from the queue and
+ * stored in the SDL_Event structure pointed to by `event`.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
- * \param timeout The timeout (in milliseconds) to wait for next event.
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that initialized the video subsystem.
+ *
+ * \param event the SDL_Event structure to be filled in with the next event
+ * from the queue, or NULL
+ * \param timeout the maximum number of milliseconds to wait for the next
+ * available event
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ * call SDL_GetError() for more information. This also returns 0 if
+ * the timeout elapsed without an event arriving.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEvent
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
int timeout);
/**
- * \brief Add an event to the event queue.
+ * Add an event to the event queue.
*
- * \return 1 on success, 0 if the event was filtered, or -1 if the event queue
- * was full or there was some other error.
+ * The event queue can actually be used as a two way communication channel.
+ * Not only can events be read from the queue, but the user can also push
+ * their own events onto it. `event` is a pointer to the event structure you
+ * wish to push onto the queue. The event is copied into the queue, and the
+ * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
+ *
+ * Note: Pushing device input events onto the queue doesn't modify the state
+ * of the device within SDL.
+ *
+ * This function is thread-safe, and can be called from other threads safely.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter but events added with SDL_PeepEvents() do not.
+ *
+ * For pushing application-specific events, please use SDL_RegisterEvents() to
+ * get an event type that does not conflict with other code that also wants
+ * its own custom event types.
+ *
+ * \param event the SDL_Event to be added to the queue
+ * \returns 1 on success, 0 if the event was filtered, or a negative error
+ * code on failure; call SDL_GetError() for more information. A
+ * common reason for error is the event queue being full.
+ *
+ * \sa SDL_PeepEvents
+ * \sa SDL_PollEvent
+ * \sa SDL_RegisterEvents
*/
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
+/**
+ * A function pointer used for callbacks that watch the event queue.
+ *
+ * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
+ * or SDL_AddEventWatch, etc
+ * \param event the event that triggered the callback
+ * \returns Filters return 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.
+ *
+ * \sa SDL_SetEventFilter
+ * \sa SDL_AddEventWatch
+ */
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
/**
- * Sets up a filter to process all events before they change internal state and
- * are posted to the internal event queue.
+ * Set up a filter to process all events before they change internal state and
+ * are posted to the internal event queue.
*
- * The filter is prototyped as:
- * \code
- * int SDL_EventFilter(void *userdata, SDL_Event * event);
- * \endcode
+ * If the filter function returns 1 when called, then the event will be added
+ * to the internal queue. If it returns 0, then the event will be dropped from
+ * the queue, but the internal state will still be updated. This allows
+ * selective filtering of dynamically arriving events.
*
- * If the filter returns 1, then the event will be added to the internal queue.
- * If it returns 0, then the event will be dropped from the queue, but the
- * internal state will still be updated. This allows selective filtering of
- * dynamically arriving events.
+ * **WARNING**: Be very careful of what you do in the event filter function,
+ * as it may run in a different thread!
*
- * \warning Be very careful of what you do in the event filter function, as
- * it may run in a different thread!
+ * On platforms that support it, if the quit event is generated by an
+ * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
+ * application at the next event poll.
*
- * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
- * event filter is only called when the window manager desires to close the
- * application window. If the event filter returns 1, then the window will
- * be closed, otherwise the window will remain open if possible.
+ * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
+ * event filter is only called when the window manager desires to close the
+ * application window. If the event filter returns 1, then the window will
+ * be closed, otherwise the window will remain open if possible.
*
- * If the quit event is generated by an interrupt signal, it will bypass the
- * internal queue and be delivered to the application at the next event poll.
+ * Note: Disabled events never make it to the event filter function; see
+ * SDL_EventState().
+ *
+ * Note: If you just want to inspect events without filtering, you should use
+ * SDL_AddEventWatch() instead.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
+ * not.
+ *
+ * \param filter An SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_AddEventWatch
+ * \sa SDL_EventState
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
*/
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
void *userdata);
/**
- * Return the current event filter - can be used to "chain" filters.
- * If there is no event filter set, this function returns SDL_FALSE.
+ * Query the current event filter.
+ *
+ * This function can be used to "chain" filters, by saving the existing filter
+ * before replacing it with a function that will call that saved filter.
+ *
+ * \param filter the current callback function will be stored here
+ * \param userdata the pointer that is passed to the current event filter will
+ * be stored here
+ * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
+ *
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
void **userdata);
/**
- * Add a function which is called when an event is added to the queue.
+ * Add a callback to be triggered when an event is added to the event queue.
+ *
+ * `filter` will be called when an event happens, and its return value is
+ * ignored.
+ *
+ * **WARNING**: Be very careful of what you do in the event filter function,
+ * as it may run in a different thread!
+ *
+ * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
+ * the internal queue and be delivered to the watch callback immediately, and
+ * arrive at the next event poll.
+ *
+ * Note: the callback is called for events posted by the user through
+ * SDL_PushEvent(), but not for disabled events, nor for events by a filter
+ * callback set with SDL_SetEventFilter(), nor for events posted by the user
+ * through SDL_PeepEvents().
+ *
+ * \param filter an SDL_EventFilter function to call when an event happens.
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_DelEventWatch
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata);
/**
- * Remove an event watch function added with SDL_AddEventWatch()
+ * Remove an event watch callback added with
+ * SDL_AddEventWatch().
+ *
+ * This function takes the same input as SDL_AddEventWatch() to identify and
+ * delete the corresponding callback.
+ *
+ * \param filter the function originally passed to SDL_AddEventWatch()
+ * \param userdata the pointer originally passed to SDL_AddEventWatch()
+ *
+ * \sa SDL_AddEventWatch
*/
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata);
/**
- * Run the filter function on the current event queue, removing any
- * events for which the filter returns 0.
+ * Run a specific filter function on the current event
+ * queue, removing any events for which the filter returns 0.
+ *
+ * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
+ * this function does not change the filter permanently, it only uses the
+ * supplied filter until this function returns.
+ *
+ * \param filter the SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
void *userdata);
@@ -795,24 +1045,45 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
#define SDL_ENABLE 1
/**
- * This function allows you to set the state of processing certain events.
- * - If \c state is set to ::SDL_IGNORE, that event will be automatically
- * dropped from the event queue and will not be filtered.
- * - If \c state is set to ::SDL_ENABLE, that event will be processed
- * normally.
- * - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
- * current processing state of the specified event.
+ * Set the state of processing events by type.
+ *
+ * `state` may be any of the following:
+ *
+ * - `SDL_QUERY`: returns the current processing state of the specified event
+ *
+ * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
+ * from the event queue and will not be filtered
+ *
+ * - `SDL_ENABLE`: the event will be processed normally
+ *
+ * \param type the type of event; see SDL_EventType for details
+ * \param state how to process the event
+ * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
+ * of the event before this function makes any changes to it.
+ *
+ * \sa SDL_GetEventState
*/
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
/* @} */
#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
/**
- * This function allocates a set of user-defined events, and returns
- * the beginning event number for that set of events.
+ * Allocate a set of user-defined events, and return the beginning event
+ * number for that set of events.
*
- * If there aren't enough user-defined events left, this function
- * returns (Uint32)-1
+ * Calling this function with `numevents` <= 0 is an error and will return
+ * (Uint32)-1.
+ *
+ * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
+ * 0xFFFFFFFF), but is clearer to write.
+ *
+ * \param numevents the number of events to be allocated
+ * \returns The beginning event number, or (Uint32)-1 if there are not enough
+ * user-defined events left.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PushEvent
*/
extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h
index c3b6602b8..55c93eee9 100644
--- a/include/SDL_filesystem.h
+++ b/include/SDL_filesystem.h
@@ -38,88 +38,102 @@ extern "C" {
#endif
/**
- * \brief Get the path where the application resides.
+ * Get the directory where the application was run from.
*
- * Get the "base path". This is the directory where the application was run
- * from, which is probably the installation directory, and may or may not
- * be the process's current working directory.
+ * This is not necessarily a fast call, so you should call this once near
+ * startup and save the string if you need it.
*
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
- * end with a path separator ('\\' on Windows, '/' most other places).
+ * **Mac OS X and iOS Specific Functionality**: If the application is in a
+ * ".app" bundle, this function returns the Resource directory (e.g.
+ * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding
+ * a property to the Info.plist file. Adding a string key with the name
+ * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the
+ * behaviour.
*
- * The pointer returned by this function is owned by you. Please call
- * SDL_free() on the pointer when you are done with it, or it will be a
- * memory leak. This is not necessarily a fast call, though, so you should
- * call this once near startup and save the string if you need it.
+ * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an
+ * application in /Applications/SDLApp/MyApp.app):
*
- * Some platforms can't determine the application's path, and on other
- * platforms, this might be meaningless. In such cases, this function will
- * return NULL.
+ * - `resource`: bundle resource directory (the default). For example:
+ * `/Applications/SDLApp/MyApp.app/Contents/Resources`
*
- * \return String of base dir in UTF-8 encoding, or NULL on error.
+ * - `bundle`: the Bundle directory. Fpr example:
+ * `/Applications/SDLApp/MyApp.app/`
+ *
+ * - `parent`: the containing directory of the bundle. For example:
+ * `/Applications/SDLApp/`
+ *
+ * The returned path is guaranteed to end with a path separator ('\' on
+ * Windows, '/' on most other platforms).
+ *
+ * The pointer returned is owned by the caller. Please call SDL_free() on
+ * the pointer when done with it.
+ *
+ * \returns an absolute path in UTF-8 encoding to the application data
+ * directory. NULL will be returned on error or when the platform
+ * doesn't implement this functionality, call SDL_GetError() for more
+ * information.
+ *
+ * \since This function is available since SDL 2.0.1.
*
* \sa SDL_GetPrefPath
*/
extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
/**
- * \brief Get the user-and-app-specific path where files can be written.
+ * Get the user-and-app-specific path where files can be written.
*
* Get the "pref dir". This is meant to be where users can write personal
- * files (preferences and save games, etc) that are specific to your
- * application. This directory is unique per user, per application.
+ * files (preferences and save games, etc) that are specific to your
+ * application. This directory is unique per user, per application.
*
* This function will decide the appropriate location in the native filesystem,
- * create the directory if necessary, and return a string of the absolute
- * path to the directory in UTF-8 encoding.
+ * create the directory if necessary, and return a string of the absolute
+ * path to the directory in UTF-8 encoding.
*
* On Windows, the string might look like:
- * "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\"
*
- * On Linux, the string might look like:
- * "/home/bob/.local/share/My Program Name/"
+ * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\`
+ *
+ * On Linux, the string might look like"
+ *
+ * `/home/bob/.local/share/My Program Name/`
*
* On Mac OS X, the string might look like:
- * "/Users/bob/Library/Application Support/My Program Name/"
*
- * (etc.)
+ * `/Users/bob/Library/Application Support/My Program Name/`
*
- * You specify the name of your organization (if it's not a real organization,
- * your name or an Internet domain you own might do) and the name of your
- * application. These should be untranslated proper names.
+ * You should assume the path returned by this function is the only safe place
+ * to write files (and that SDL_GetBasePath(), while it might be writable, or
+ * even the parent of the returned path, isn't where you should be writing
+ * things).
*
- * Both the org and app strings may become part of a directory name, so
- * please follow these rules:
+ * Both the org and app strings may become part of a directory name, so please
+ * follow these rules:
*
- * - Try to use the same org string (including case-sensitivity) for
- * all your applications that use this function.
- * - Always use a unique app string for each one, and make sure it never
- * changes for an app once you've decided on it.
- * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
- * - ...only use letters, numbers, and spaces. Avoid punctuation like
- * "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
+ * - Try to use the same org string (_including case-sensitivity_) for all
+ * your applications that use this function.
*
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
- * end with a path separator ('\\' on Windows, '/' most other places).
+ * - Always use a unique app string for each one, and make sure it never
+ * changes for an app once you've decided on it.
*
- * The pointer returned by this function is owned by you. Please call
- * SDL_free() on the pointer when you are done with it, or it will be a
- * memory leak. This is not necessarily a fast call, though, so you should
- * call this once near startup and save the string if you need it.
+ * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
*
- * You should assume the path returned by this function is the only safe
- * place to write files (and that SDL_GetBasePath(), while it might be
- * writable, or even the parent of the returned path, aren't where you
- * should be writing things).
+ * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
+ * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
*
- * Some platforms can't determine the pref path, and on other
- * platforms, this might be meaningless. In such cases, this function will
- * return NULL.
+ * The returned path is guaranteed to end with a path separator ('\' on
+ * Windows, '/' on most other platforms).
*
- * \param org The name of your organization.
- * \param app The name of your application.
- * \return UTF-8 string of user dir in platform-dependent notation. NULL
- * if there's a problem (creating directory failed, etc).
+ * The pointer returned is owned by the caller. Please call SDL_free() on
+ * the pointer when done with it.
+ *
+ * \param org the name of your organization
+ * \param app the name of your application
+ * \returns a UTF-8 string of the user directory in platform-dependent
+ * notation. NULL if there's a problem (creating directory failed,
+ * etc.).
+ *
+ * \since This function is available since SDL 2.0.1.
*
* \sa SDL_GetBasePath
*/
diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index aa4b47983..5b6461ed2 100644
--- a/include/SDL_gamecontroller.h
+++ b/include/SDL_gamecontroller.h
@@ -124,12 +124,32 @@ typedef struct SDL_GameControllerButtonBind
*/
/**
- * Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform()
- * A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt
+ * Load a set of Game Controller mappings from a seekable SDL data stream.
*
- * If \c freerw is non-zero, the stream will be closed after being read.
- *
- * \return number of mappings added, -1 on error
+ * You can call this function several times, if needed, to load different
+ * database files.
+ *
+ * If a new mapping is loaded for an already known controller GUID, the later
+ * version will overwrite the one currently loaded.
+ *
+ * Mappings not belonging to the current platform or with no platform field
+ * specified will be ignored (i.e. mappings for Linux will be ignored in
+ * Windows, etc).
+ *
+ * This function will load the text database entirely in memory before
+ * processing it, so take this into consideration if you are in a memory
+ * constrained environment.
+ *
+ * \param rw the data stream for the mappings to be added
+ * \param freerw non-zero to close the stream after being read
+ * \returns the number of mappings added or -1 on error; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerAddMappingsFromFile
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
@@ -141,161 +161,338 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
#define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
/**
- * Add or update an existing mapping configuration
+ * Add support for controllers that SDL is unaware of or
+ * to cause an existing controller to have a different binding.
*
- * \return 1 if mapping is added, 0 if updated, -1 on error
+ * The mapping string has the format "GUID,name,mapping", where GUID is the
+ * string value from SDL_JoystickGetGUIDString(), name is the human readable
+ * string for the device and mappings are controller mappings to joystick
+ * ones. Under Windows there is a reserved GUID of "xinput" that covers all
+ * XInput devices. The mapping format for joystick is: {| |bX |a joystick
+ * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
+ * |} Buttons can be used as a controller axes and vice versa.
+ *
+ * This string shows an example of a valid mapping for a controller:
+ *
+ * ```
+ * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
+ * ```
+ *
+ * \param mappingString the mapping string
+ * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
+ * -1 on error; call SDL_GetError() for more information.
+ *
+ * \sa SDL_GameControllerMapping
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
/**
- * Get the number of mappings installed
+ * Get the number of mappings installed.
*
- * \return the number of mappings
+ * \returns the number of mappings.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
/**
- * Get the mapping at a particular index.
+ * Get the mapping at a particular index.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if the index is out of range.
+ * \returns the mapping string. Must be freed with SDL_free().
+ * Returns NULL if the index is out of range.
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
/**
- * Get a mapping string for a GUID
+ * Get the game controller mapping string for a given GUID.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * The returned string must be freed with SDL_free().
+ *
+ * \param guid a structure containing the GUID for which a mapping is desired
+ * \returns a mapping string or NULL on error; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid);
/**
- * Get a mapping string for an open GameController
+ * Get the current mapping of a Game Controller.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * The returned string must be freed with SDL_free().
+ *
+ * Details about mappings are discussed with SDL_GameControllerAddMapping().
+ *
+ * \param gamecontroller the game controller you want to get the current
+ * mapping for
+ * \returns a string that has the controller's mapping or NULL if no mapping
+ * is available; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller);
/**
- * Is the joystick on this index supported by the game controller interface?
+ * Check if the given joystick is supported by the game controller interface.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, up to
+ * SDL_NumJoysticks()
+ * \returns SDL_TRUE if the given joystick is supported by the game controller
+ * interface, SDL_FALSE if it isn't or it's an invalid index.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
/**
- * Get the implementation dependent name of a game controller.
- * This can be called before any controllers are opened.
- * If no name can be found, this function returns NULL.
+ * Get the implementation dependent name for the game
+ * controller.
+ *
+ * This function can be called before any controllers are opened.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the implementation-dependent name for the game controller, or NULL
+ * if there is no name or the index is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerName
+ * \sa SDL_GameControllerOpen
+ * \sa SDL_IsGameController
*/
extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
/**
- * Get the type of a game controller.
- * This can be called before any controllers are opened.
+ * Get the type of a game controller.
+ *
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the controller type.
*/
extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index);
/**
- * Get the mapping of a game controller.
- * This can be called before any controllers are opened.
+ * Get the mapping of a game controller.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL
+ * if no mapping is available.
*/
extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
/**
- * Open a game controller for use.
- * The index passed as an argument refers to the N'th game controller on the system.
- * This index is not the value which will identify this controller in future
- * controller events. The joystick's instance id (::SDL_JoystickID) will be
- * used there instead.
+ * Open a game controller for use.
*
- * \return A controller identifier, or NULL if an error occurred.
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * The index passed as an argument refers to the N'th game controller on the
+ * system. This index is not the value which will identify this controller in
+ * future controller events. The joystick's instance id (SDL_JoystickID) will
+ * be used there instead.
+ *
+ * \param joystick_index the device_index of a device, up to
+ * SDL_NumJoysticks()
+ * \returns a gamecontroller identifier or NULL if an error occurred; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_IsGameController
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
/**
- * Return the SDL_GameController associated with an instance id.
+ * Get the SDL_GameController associated with an instance id.
+ *
+ * \param joyid the instance id to get the SDL_GameController for
+ * \returns an SDL_GameController on success or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid);
/**
- * Return the SDL_GameController associated with a player index.
+ * Get the SDL_GameController associated with a player index.
+ *
+ * Please note that the player index is _not_ the device index, nor is it
+ * the instance id!
+ *
+ * \param player_index the player index, which is not the device index or
+ * the instance id!
+ * \returns the SDL_GameController associated with a player index.
+ *
+ * \sa SDL_GameControllerGetPlayerIndex
+ * \sa SDL_GameControllerSetPlayerIndex
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index);
/**
- * Return the name for this currently opened controller
+ * Get the implementation-dependent name for an opened game controller.
+ *
+ * This is the same name as returned by SDL_GameControllerNameForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ * \returns the implementation dependent name for the game controller, or NULL
+ * if there is no name or the identifier passed is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller);
/**
- * Return the type of this currently opened controller
+ * Get the type of this currently opened controller
+ *
+ * This is the same name as returned by SDL_GameControllerTypeForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the controller type.
*/
extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
/**
- * Get the player index of an opened game controller, or -1 if it's not available
+ * Get the player index of an opened game controller.
*
* For XInput controllers this returns the XInput user index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns player index for controller, or -1 if it's not available.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
/**
- * Set the player index of an opened game controller
+ * Set the player index of an opened game controller.
+ *
+ * \param gamecontroller the game controller object to adjust.
+ * \param player_index Player index to assign to this controller.
*/
extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index);
/**
- * Get the USB vendor ID of an opened controller, if available.
- * If the vendor ID isn't available this function returns 0.
+ * Get the USB vendor ID of an opened controller, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return USB vendor ID, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
/**
- * Get the USB product ID of an opened controller, if available.
- * If the product ID isn't available this function returns 0.
+ * Get the USB product ID of an opened controller, if available.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return USB product ID, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
/**
- * Get the product version of an opened controller, if available.
- * If the product version isn't available this function returns 0.
+ * Get the product version of an opened controller, if available.
+ *
+ * If the product version isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return USB product version, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
/**
- * Get the serial number of an opened controller, if available.
+ * Get the serial number of an opened controller, if available.
*
- * Returns the serial number of the controller, or NULL if it is not available.
+ * Returns the serial number of the controller, or NULL if it is not available.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return Serial number, or NULL if unavailable.
*/
extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
/**
- * Returns SDL_TRUE if the controller has been opened and currently connected,
- * or SDL_FALSE if it has not.
+ * Check if a controller has been opened and is currently connected.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ * \returns SDL_TRUE if the controller has been opened and is currently
+ * connected, or SDL_FALSE if not.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller);
/**
- * Get the underlying joystick object used by a controller
+ * Get the Joystick ID from a Game Controller.
+ *
+ * This function will give you a SDL_Joystick object, which allows you to use
+ * the SDL_Joystick functions with a SDL_GameController object. This would be
+ * useful for getting a joystick's position at any given time, even if it
+ * hasn't moved (moving it would produce an event, which would have the axis'
+ * value).
+ *
+ * The pointer returned is owned by the SDL_GameController. You should not
+ * call SDL_JoystickClose() on it, for example, since doing so will likely
+ * cause SDL to crash.
+ *
+ * \param gamecontroller the game controller object that you want to get a
+ * joystick from
+ * \returns a SDL_Joystick object; call SDL_GetError() for more information.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller);
/**
- * Enable/disable controller event polling.
+ * Query or change current state of Game Controller events.
*
- * If controller events are disabled, you must call SDL_GameControllerUpdate()
- * yourself and check the state of the controller when you want controller
- * information.
+ * If controller events are disabled, you must call SDL_GameControllerUpdate()
+ * yourself and check the state of the controller when you want controller
+ * information.
*
- * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
+ * and 1 will have any effect. Other numbers will just be returned.
+ *
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns the same value passed to the function, with exception to -1
+ * (SDL_QUERY), which will return the current state.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickEventState
*/
extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
/**
- * Update the current state of the open game controllers.
+ * Manually pump game controller updates if not using the loop.
*
- * This is called automatically by the event loop if any game controller
- * events are enabled.
+ * This function is called automatically by the event loop if events are
+ * enabled. Under such circumstances, it will not be necessary to call this
+ * function.
*/
extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
@@ -322,35 +519,81 @@ typedef enum
} SDL_GameControllerAxis;
/**
- * turn this string into a axis mapping
+ * Convert a string into SDL_GameControllerAxis enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerAxis enum corresponding to the input string,
+ * or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
+ * \sa SDL_GameControllerGetStringForAxis
*/
-extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str);
/**
- * turn this axis enum into a string mapping
+ * Convert from an SDL_GameControllerAxis enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param axis an enum value for a given SDL_GameControllerAxis
+ * \returns a string for the given axis, or NULL if an invalid axis is
+ * specified. The string returned is of the format used by
+ * SDL_GameController mapping strings.
+ *
+ * \sa SDL_GameControllerGetAxisFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis);
/**
- * Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller axis mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On
+ * failure (like the given Controller axis doesn't exist on the
+ * device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForButton
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
SDL_GameControllerAxis axis);
/**
- * Return whether a game controller has a given axis
+ * Query whether a game controller has a given axis.
+ *
+ * This merely reports whether the controller's mapping defined this axis, as
+ * that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (an SDL_GameControllerAxis value)
+ * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL
SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
/**
- * Get the current state of an axis control on a game controller.
+ * Get the current state of an axis control on a game controller.
*
- * The state is a value ranging from -32768 to 32767 (except for the triggers,
- * which range from 0 to 32767).
+ * The axis indices start at index 0.
*
- * The axis indices start at index 0.
+ * The state is a value ranging from -32768 to 32767. Triggers, however, range
+ * from 0 to 32767 (they never return a negative value).
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis index (one of the SDL_GameControllerAxis values)
+ * \returns axis state (including 0) on success or 0 (also) on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButton
*/
extern DECLSPEC Sint16 SDLCALL
SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
@@ -386,150 +629,207 @@ typedef enum
} SDL_GameControllerButton;
/**
- * turn this string into a button mapping
+ * Convert a string into an SDL_GameControllerButton enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerButton enum corresponding to the input
+ * string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
*/
-extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
/**
- * turn this button enum into a string mapping
+ * Convert from an SDL_GameControllerButton enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param button an enum value for a given SDL_GameControllerButton
+ * \returns a string for the given button, or NULL if an invalid axis is
+ * specified. The string returned is of the format used by
+ * SDL_GameController mapping strings.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButtonFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button);
/**
- * Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller button mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param button an button enum value (an SDL_GameControllerButton value)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On
+ * failure (like the given Controller button doesn't exist on the
+ * device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForAxis
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
- * Return whether a game controller has a given button
+ * Query whether a game controller has a given button.
+ *
+ * This merely reports whether the controller's mapping defined this button,
+ * as that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button enum value (an SDL_GameControllerButton value)
+ * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
- * Get the current state of a button on a game controller.
+ * Get the current state of a button on a game controller.
*
- * The button indices start at index 0.
+ * \param gamecontroller a game controller
+ * \param button a button index (one of the SDL_GameControllerButton values)
+ * \returns 1 for pressed state or 0 for not pressed state or error; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetAxis
*/
extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
- * Get the number of touchpads on a game controller.
+ * Get the number of touchpads on a game controller.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
/**
- * Get the number of supported simultaneous fingers on a touchpad on a game controller.
+ * Get the number of supported simultaneous fingers on a touchpad on a game controller.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
/**
- * Get the current state of a finger on a touchpad on a game controller.
+ * Get the current state of a finger on a touchpad on a game controller.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);
/**
- * Return whether a game controller has a particular sensor.
+ * Return whether a game controller has a particular sensor.
*
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
*
- * \return SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
/**
- * Set whether data reporting for a game controller sensor is enabled
+ * Set whether data reporting for a game controller sensor is enabled.
*
- * \param gamecontroller The controller to update
- * \param type The type of sensor to enable/disable
- * \param enabled Whether data reporting should be enabled
+ * \param gamecontroller The controller to update
+ * \param type The type of sensor to enable/disable
+ * \param enabled Whether data reporting should be enabled
*
- * \return 0 or -1 if an error occurred.
+ * \returns 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
/**
- * Query whether sensor data reporting is enabled for a game controller
+ * Query whether sensor data reporting is enabled for a game controller.
*
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
*
- * \return SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
/**
- * Get the current state of a game controller sensor.
+ * Get the current state of a game controller sensor.
*
- * The number of values and interpretation of the data is sensor dependent.
- * See SDL_sensor.h for the details for each type of sensor.
+ * The number of values and interpretation of the data is sensor dependent.
+ * See SDL_sensor.h for the details for each type of sensor.
*
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
- *
- * \return 0 or -1 if an error occurred.
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \return 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values);
/**
- * Start a rumble effect
- * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect on a game controller.
*
- * \param gamecontroller The controller to vibrate
- * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
- * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
*
- * \return 0, or -1 if rumble isn't supported on this controller
+ * \param gamecontroller The controller to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ * rumble motor, from 0 to 0xFFFF
+ * \param high_frequency_rumble The intensity of the high frequency (right)
+ * rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if rumble isn't supported on this controller
*/
extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
/**
- * Start a rumble effect in the game controller's triggers
- * Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect in the game controller's triggers.
*
- * \param gamecontroller The controller to vibrate
- * \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
- * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Each call to this function cancels any previous trigger rumble effect, and
+ * calling it with 0 intensity stops any rumbling.
*
- * \return 0, or -1 if rumble isn't supported on this controller
+ * Note that this is rumbling of the _triggers_ and not the game controller as
+ * a whole. The first controller to offer this feature was the PlayStation 5's
+ * DualShock 5.
+ *
+ * \param gamecontroller The controller to vibrate
+ * \param left_rumble The intensity of the left trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ *
+ * \returns 0, or -1 if trigger rumble isn't supported on this controller
*/
extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
/**
- * Return whether a controller has an LED
+ * Query whether a game controller has an LED.
*
- * \param gamecontroller The controller to query
- *
- * \return SDL_TRUE, or SDL_FALSE if this controller does not have a modifiable LED
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
+ * modifiable LED
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller);
/**
- * Update a controller's LED color.
+ * Update a game controller's LED color.
*
- * \param gamecontroller The controller to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
- *
- * \return 0, or -1 if this controller does not have a modifiable LED
+ * \param gamecontroller The controller to update
+ * \param red The intensity of the red LED
+ * \param green The intensity of the green LED
+ * \param blue The intensity of the blue LED
+ * \returns 0, or -1 if this controller does not have a modifiable LED
*/
extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue);
/**
- * Close a controller previously opened with SDL_GameControllerOpen().
+ * Close a game controller previously opened with SDL_GameControllerOpen().
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ *
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
-
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
diff --git a/include/SDL_gesture.h b/include/SDL_gesture.h
index a7382bc68..530b3d577 100644
--- a/include/SDL_gesture.h
+++ b/include/SDL_gesture.h
@@ -46,36 +46,66 @@ typedef Sint64 SDL_GestureID;
/* Function prototypes */
/**
- * \brief Begin Recording a gesture on the specified touch, or all touches (-1)
+ * Begin recording a gesture on a specified touch device or all touch devices.
*
+ * If the parameter `touchId` is -1 (i.e., all devices), this function will
+ * always return 1, regardless of whether there actually are any devices.
*
+ * \param touchId the touch device id, or -1 for all touch devices
+ * \returns 1 on success or 0 if the specified device could not be found.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchDevice
*/
extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId);
/**
- * \brief Save all currently loaded Dollar Gesture templates
+ * Save all currently loaded Dollar Gesture templates.
*
+ * \param dst a SDL_RWops to save to
+ * \returns the number of saved templates on success or 0 on failure; call
+ * SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst);
/**
- * \brief Save a currently loaded Dollar Gesture template
+ * Save a currently loaded Dollar Gesture template.
*
+ * \param gestureId a gesture id
+ * \param dst a SDL_RWops to save to
+ * \returns 1 on success or 0 on failure; call SDL_GetError() for more
+ * information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveAllDollarTemplates
*/
extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst);
/**
- * \brief Load Dollar Gesture templates from a file
+ * Load Dollar Gesture templates from a file.
*
+ * \param touchId a touch id
+ * \param src a SDL_RWops to load from
+ * \returns the number of loaded templates on success or a negative error code
+ * (or 0) on failure; call SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SaveAllDollarTemplates
+ * \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src);
-
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h
index 29f45066a..424cbd111 100644
--- a/include/SDL_haptic.h
+++ b/include/SDL_haptic.h
@@ -821,418 +821,492 @@ typedef union SDL_HapticEffect
/* Function prototypes */
/**
- * \brief Count the number of haptic devices attached to the system.
+ * Count the number of haptic devices attached to the system.
*
- * \return Number of haptic devices detected on the system.
+ * \returns the number of haptic devices detected on the system or a negative
+ * error code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticName
*/
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
/**
- * \brief Get the implementation dependent name of a haptic device.
+ * Get the implementation dependent name of a haptic device.
*
- * This can be called before any joysticks are opened.
- * If no name can be found, this function returns NULL.
+ * This can be called before any joysticks are opened. If no name can be
+ * found, this function returns NULL.
*
- * \param device_index Index of the device to get its name.
- * \return Name of the device or NULL on error.
+ * \param device_index index of the device to query.
+ * \returns the name of the device or NULL on failure; call SDL_GetError() for
+ * more information.
*
- * \sa SDL_NumHaptics
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_NumHaptics
*/
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
/**
- * \brief Opens a haptic device for use.
+ * Open a haptic device for use.
*
- * The index passed as an argument refers to the N'th haptic device on this
- * system.
+ * The index passed as an argument refers to the N'th haptic device on this
+ * system.
*
- * When opening a haptic device, its gain will be set to maximum and
- * autocenter will be disabled. To modify these values use
- * SDL_HapticSetGain() and SDL_HapticSetAutocenter().
+ * When opening a haptic device, its gain will be set to maximum and
+ * autocenter will be disabled. To modify these values use SDL_HapticSetGain()
+ * and SDL_HapticSetAutocenter().
*
- * \param device_index Index of the device to open.
- * \return Device identifier or NULL on error.
+ * \param device_index index of the device to open
+ * \returns the device identifier or NULL on failure; call SDL_GetError() for
+ * more information.
*
- * \sa SDL_HapticIndex
- * \sa SDL_HapticOpenFromMouse
- * \sa SDL_HapticOpenFromJoystick
- * \sa SDL_HapticClose
- * \sa SDL_HapticSetGain
- * \sa SDL_HapticSetAutocenter
- * \sa SDL_HapticPause
- * \sa SDL_HapticStopAll
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpenFromJoystick
+ * \sa SDL_HapticOpenFromMouse
+ * \sa SDL_HapticPause
+ * \sa SDL_HapticSetAutocenter
+ * \sa SDL_HapticSetGain
+ * \sa SDL_HapticStopAll
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
/**
- * \brief Checks if the haptic device at index has been opened.
+ * Check if the haptic device at the designated index has been opened.
*
- * \param device_index Index to check to see if it has been opened.
- * \return 1 if it has been opened or 0 if it hasn't.
+ * \param device_index the index of the device to query
+ * \returns 1 if it has been opened, 0 if it hasn't or on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticIndex
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpen
*/
extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
/**
- * \brief Gets the index of a haptic device.
+ * Get the index of a haptic device.
*
- * \param haptic Haptic device to get the index of.
- * \return The index of the haptic device or -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \returns the index of the specified haptic device or a negative error code
+ * on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticOpened
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticOpened
*/
extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
/**
- * \brief Gets whether or not the current mouse has haptic capabilities.
+ * Query whether or not the current mouse has haptic capabilities.
*
- * \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
+ * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
*
- * \sa SDL_HapticOpenFromMouse
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpenFromMouse
*/
extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
/**
- * \brief Tries to open a haptic device from the current mouse.
+ * Try to open a haptic device from the current mouse.
*
- * \return The haptic device identifier or NULL on error.
+ * \returns the haptic device identifier or NULL on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_MouseIsHaptic
- * \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_MouseIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
/**
- * \brief Checks to see if a joystick has haptic features.
+ * Query if a joystick has haptic features.
*
- * \param joystick Joystick to test for haptic capabilities.
- * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
- * or -1 if an error occurred.
+ * \param joystick the SDL_Joystick to test for haptic capabilities
+ * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticOpenFromJoystick
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpenFromJoystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
/**
- * \brief Opens a haptic device for use from a joystick device.
+ * Open a haptic device for use from a joystick device.
*
- * You must still close the haptic device separately. It will not be closed
- * with the joystick.
+ * You must still close the haptic device separately. It will not be closed
+ * with the joystick.
*
- * When opening from a joystick you should first close the haptic device before
- * closing the joystick device. If not, on some implementations the haptic
- * device will also get unallocated and you'll be unable to use force feedback
- * on that device.
+ * When opened from a joystick you should first close the haptic device before
+ * closing the joystick device. If not, on some implementations the haptic
+ * device will also get unallocated and you'll be unable to use force feedback
+ * on that device.
*
- * \param joystick Joystick to create a haptic device from.
- * \return A valid haptic device identifier on success or NULL on error.
+ * \param joystick the SDL_Joystick to create a haptic device from
+ * \returns a valid haptic device identifier on success or NULL on failure;
+ * call SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticClose
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticOpen
+ * \sa SDL_JoystickIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
joystick);
/**
- * \brief Closes a haptic device previously opened with SDL_HapticOpen().
+ * Close a haptic device previously opened with SDL_HapticOpen().
*
- * \param haptic Haptic device to close.
+ * \param haptic the SDL_Haptic device to close
+ *
+ * \sa SDL_HapticOpen
*/
extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
/**
- * \brief Returns the number of effects a haptic device can store.
+ * Get the number of effects a haptic device can store.
*
- * On some platforms this isn't fully supported, and therefore is an
- * approximation. Always check to see if your created effect was actually
- * created and do not rely solely on SDL_HapticNumEffects().
+ * On some platforms this isn't fully supported, and therefore is an
+ * approximation. Always check to see if your created effect was actually
+ * created and do not rely solely on SDL_HapticNumEffects().
*
- * \param haptic The haptic device to query effect max.
- * \return The number of effects the haptic device can store or
- * -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of effects the haptic device can store or a negative
+ * error code on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticNumEffectsPlaying
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNumEffectsPlaying
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
/**
- * \brief Returns the number of effects a haptic device can play at the same
- * time.
+ * Get the number of effects a haptic device can play at
+ * the same time.
*
- * This is not supported on all platforms, but will always return a value.
- * Added here for the sake of completeness.
+ * This is not supported on all platforms, but will always return a value.
*
- * \param haptic The haptic device to query maximum playing effects.
- * \return The number of effects the haptic device can play at the same time
- * or -1 on error.
+ * \param haptic the SDL_Haptic device to query maximum playing effects
+ * \returns the number of effects the haptic device can play at the same time
+ * or a negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticNumEffects
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNumEffects
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
/**
- * \brief Gets the haptic device's supported features in bitwise manner.
+ * Get the haptic device's supported features in bitwise manner.
*
- * Example:
- * \code
- * if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
- * printf("We have constant haptic effect!\n");
- * }
- * \endcode
+ * \param haptic the SDL_Haptic device to query
+ * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
+ * on failure; call SDL_GetError() for more information.
*
- * \param haptic The haptic device to query.
- * \return Haptic features in bitwise manner (OR'd).
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticNumEffects
- * \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticNumEffects
*/
extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
/**
- * \brief Gets the number of haptic axes the device has.
+ * Get the number of haptic axes the device has.
*
- * \sa SDL_HapticDirection
+ * The number of haptic axes might be useful if working with the
+ * SDL_HapticDirection effect.
+ *
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of axes on success or a negative error code on failure;
+ * call SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
/**
- * \brief Checks to see if effect is supported by haptic.
+ * Check to see if an effect is supported by a haptic
+ * device.
*
- * \param haptic Haptic device to check on.
- * \param effect Effect to check to see if it is supported.
- * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \param effect the desired effect to query
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticQuery
- * \sa SDL_HapticNewEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
SDL_HapticEffect *
effect);
/**
- * \brief Creates a new haptic effect on the device.
+ * Create a new haptic effect on a specified device.
*
- * \param haptic Haptic device to create the effect on.
- * \param effect Properties of the effect to create.
- * \return The identifier of the effect on success or -1 on error.
+ * \param haptic an SDL_Haptic device to create the effect on
+ * \param effect an SDL_HapticEffect structure containing the properties of
+ * the effect to create
+ * \returns the ID of the effect on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticUpdateEffect
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticUpdateEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
SDL_HapticEffect * effect);
/**
- * \brief Updates the properties of an effect.
+ * Update the properties of an effect.
*
- * Can be used dynamically, although behavior when dynamically changing
- * direction may be strange. Specifically the effect may reupload itself
- * and start playing from the start. You cannot change the type either when
- * running SDL_HapticUpdateEffect().
+ * Can be used dynamically, although behavior when dynamically changing
+ * direction may be strange. Specifically the effect may re-upload itself and
+ * start playing from the start. You also cannot change the type either when
+ * running SDL_HapticUpdateEffect().
*
- * \param haptic Haptic device that has the effect.
- * \param effect Identifier of the effect to update.
- * \param data New effect properties to use.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device that has the effect
+ * \param effect the identifier of the effect to update
+ * \param data an SDL_HapticEffect structure containing the new effect
+ * properties to use
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticNewEffect
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticRunEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
int effect,
SDL_HapticEffect * data);
/**
- * \brief Runs the haptic effect on its associated haptic device.
+ * Run the haptic effect on its associated haptic device.
*
- * If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
- * repeating the envelope (attack and fade) every time. If you only want the
- * effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
- * parameter.
+ * To repeat the effect over and over indefinitely, set `iterations` to
+ * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
+ * one instance of the effect last indefinitely (so the effect does not fade),
+ * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
+ * instead.
*
- * \param haptic Haptic device to run the effect on.
- * \param effect Identifier of the haptic effect to run.
- * \param iterations Number of iterations to run the effect. Use
- * ::SDL_HAPTIC_INFINITY for infinity.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to run the effect on
+ * \param effect the ID of the haptic effect to run
+ * \param iterations the number of iterations to run the effect; use
+ * `SDL_HAPTIC_INFINITY` to repeat forever
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticStopEffect
- * \sa SDL_HapticDestroyEffect
- * \sa SDL_HapticGetEffectStatus
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticGetEffectStatus
+ * \sa SDL_HapticStopEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
int effect,
Uint32 iterations);
/**
- * \brief Stops the haptic effect on its associated haptic device.
+ * Stop the haptic effect on its associated haptic device.
+ * *
+ * \param haptic the SDL_Haptic device to stop the effect on
+ * \param effect the ID of the haptic effect to stop
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \param haptic Haptic device to stop the effect on.
- * \param effect Identifier of the effect to stop.
- * \return 0 on success or -1 on error.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
int effect);
/**
- * \brief Destroys a haptic effect on the device.
+ * Destroy a haptic effect on the device.
*
- * This will stop the effect if it's running. Effects are automatically
- * destroyed when the device is closed.
+ * This will stop the effect if it's running. Effects are automatically
+ * destroyed when the device is closed.
*
- * \param haptic Device to destroy the effect on.
- * \param effect Identifier of the effect to destroy.
+ * \param haptic the SDL_Haptic device to destroy the effect on
+ * \param effect the ID of the haptic effect to destroy
*
- * \sa SDL_HapticNewEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNewEffect
*/
extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
int effect);
/**
- * \brief Gets the status of the current effect on the haptic device.
+ * Get the status of the current effect on the specified
+ * haptic device.
*
- * Device must support the ::SDL_HAPTIC_STATUS feature.
+ * Device must support the SDL_HAPTIC_STATUS feature.
*
- * \param haptic Haptic device to query the effect status on.
- * \param effect Identifier of the effect to query its status.
- * \return 0 if it isn't playing, 1 if it is playing or -1 on error.
+ * \param haptic the SDL_Haptic device to query for the effect status on
+ * \param effect the ID of the haptic effect to query its status
+ * \returns 0 if it isn't playing, 1 if it is playing, or a negative error
+ * code on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticStopEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticStopEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
int effect);
/**
- * \brief Sets the global gain of the device.
+ * Set the global gain of the specified haptic device.
*
- * Device must support the ::SDL_HAPTIC_GAIN feature.
+ * Device must support the SDL_HAPTIC_GAIN feature.
*
- * The user may specify the maximum gain by setting the environment variable
- * SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to
- * SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
- * maximum.
+ * The user may specify the maximum gain by setting the environment variable
+ * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
+ * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
+ * maximum.
*
- * \param haptic Haptic device to set the gain on.
- * \param gain Value to set the gain to, should be between 0 and 100.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to set the gain on
+ * \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
/**
- * \brief Sets the global autocenter of the device.
+ * Set the global autocenter of the device.
*
- * Autocenter should be between 0 and 100. Setting it to 0 will disable
- * autocentering.
+ * Autocenter should be between 0 and 100. Setting it to 0 will disable
+ * autocentering.
*
- * Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
+ * Device must support the SDL_HAPTIC_AUTOCENTER feature.
*
- * \param haptic Haptic device to set autocentering on.
- * \param autocenter Value to set autocenter to, 0 disables autocentering.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to set autocentering on
+ * \param autocenter value to set autocenter to (0-100)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticQuery
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
int autocenter);
/**
- * \brief Pauses a haptic device.
+ * Pause a haptic device.
*
- * Device must support the ::SDL_HAPTIC_PAUSE feature. Call
- * SDL_HapticUnpause() to resume playback.
+ * Device must support the `SDL_HAPTIC_PAUSE` feature. Call
+ * SDL_HapticUnpause() to resume playback.
*
- * Do not modify the effects nor add new ones while the device is paused.
- * That can cause all sorts of weird errors.
+ * Do not modify the effects nor add new ones while the device is paused. That
+ * can cause all sorts of weird errors.
*
- * \param haptic Haptic device to pause.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to pause
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticUnpause
+ * \sa SDL_HapticUnpause
*/
extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
/**
- * \brief Unpauses a haptic device.
+ * Unpause a haptic device.
*
- * Call to unpause after SDL_HapticPause().
+ * Call to unpause after SDL_HapticPause().
*
- * \param haptic Haptic device to unpause.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to unpause
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticPause
+ * \sa SDL_HapticPause
*/
extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
/**
- * \brief Stops all the currently playing effects on a haptic device.
+ * Stop all the currently playing effects on a haptic device.
*
- * \param haptic Haptic device to stop.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to stop
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
/**
- * \brief Checks to see if rumble is supported on a haptic device.
+ * Check whether rumble is supported on a haptic device.
*
- * \param haptic Haptic device to check to see if it supports rumble.
- * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \param haptic haptic device to check for rumble support
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumblePlay
- * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
/**
- * \brief Initializes the haptic device for simple rumble playback.
+ * Initialize a haptic device for simple rumble playback.
*
- * \param haptic Haptic device to initialize for simple rumble playback.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to initialize for simple rumble playback
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumblePlay
- * \sa SDL_HapticRumbleStop
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
/**
- * \brief Runs simple rumble on a haptic device
+ * Run a simple rumble effect on a haptic device.
*
- * \param haptic Haptic device to play rumble effect on.
- * \param strength Strength of the rumble to play as a 0-1 float value.
- * \param length Length of the rumble to play in milliseconds.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to play the rumble effect on
+ * \param strength strength of the rumble to play as a 0-1 float value
+ * \param length length of the rumble to play in milliseconds
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
/**
- * \brief Stops the simple rumble on a haptic device.
+ * Stop the simple rumble on a haptic device.
*
- * \param haptic Haptic to stop the rumble on.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to stop the rumble effect on
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
diff --git a/include/SDL_hints.h b/include/SDL_hints.h
index 097e78699..90e45de98 100644
--- a/include/SDL_hints.h
+++ b/include/SDL_hints.h
@@ -1671,71 +1671,113 @@ typedef enum
/**
- * \brief Set a hint with a specific priority
+ * Set a hint with a specific priority.
*
- * The priority controls the behavior when setting a hint that already
- * has a value. Hints will replace existing hints of their priority and
- * lower. Environment variables are considered to have override priority.
+ * The priority controls the behavior when setting a hint that already has a
+ * value. Hints will replace existing hints of their priority and lower.
+ * Environment variables are considered to have override priority.
*
- * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
+ * \param name the hint to set
+ * \param value the value of the hint variable
+ * \param priority the SDL_HintPriority level for the hint
+ * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
+ *
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
const char *value,
SDL_HintPriority priority);
/**
- * \brief Set a hint with normal priority
+ * Set a hint with normal priority.
*
- * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
+ * Hints will not be set if there is an existing override hint or environment
+ * variable that takes precedence. You can use SDL_SetHintWithPriority() to
+ * set the hint with override priority instead.
+ *
+ * \param name the hint to set
+ * \param value the value of the hint variable
+ * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
+ *
+ * \sa SDL_GetHint
+ * \sa SDL_SetHintWithPriority
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
const char *value);
/**
- * \brief Get a hint
+ * Get the value of a hint.
*
- * \return The string value of a hint variable.
+ * \param name the hint to query
+ * \returns the string value of a hint or NULL if the hint isn't set.
+ *
+ * \sa SDL_SetHint
+ * \sa SDL_SetHintWithPriority
*/
extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
/**
- * \brief Get a hint
+ * Get the boolean value of a hint variable.
*
- * \return The boolean value of a hint variable.
+ * \param name the name of the hint to get the boolean value from
+ * \param default_value the value to return if the hint does not exist
+ * \returns the boolean value of a hint or the provided default value if the
+ * hint does not exist.
+ *
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value);
/**
- * \brief type definition of the hint callback function.
+ * Type definition of the hint callback function.
+ *
+ * \param userdata what was passed as `userdata` to SDL_AddHintCallback()
+ * \param name what was passed as `name` to SDL_AddHintCallback()
+ * \param oldValue the previous hint value
+ * \param newValue the new value hint is to be set to
*/
typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue);
/**
- * \brief Add a function to watch a particular hint
+ * Add a function to watch a particular hint.
*
- * \param name The hint to watch
- * \param callback The function to call when the hint value changes
- * \param userdata A pointer to pass to the callback function
+ * \param name the hint to watch
+ * \param callback An SDL_HintCallback function that will be called when the
+ * hint value changes
+ * \param userdata a pointer to pass to the callback function
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_DelHintCallback
*/
extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
SDL_HintCallback callback,
void *userdata);
/**
- * \brief Remove a function watching a particular hint
+ * Remove a function watching a particular hint.
*
- * \param name The hint being watched
- * \param callback The function being called when the hint value changes
- * \param userdata A pointer being passed to the callback function
+ * \param name the hint being watched
+ * \param callback An SDL_HintCallback function that will be called when the
+ * hint value changes
+ * \param userdata a pointer being passed to the callback function
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AddHintCallback
*/
extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name,
SDL_HintCallback callback,
void *userdata);
/**
- * \brief Clear all hints
+ * Clear all hints.
*
- * This function is called during SDL_Quit() to free stored hints.
+ * This function is automatically called during SDL_Quit().
*/
extern DECLSPEC void SDLCALL SDL_ClearHints(void);
diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h
index 259204002..cfdbcd8db 100644
--- a/include/SDL_joystick.h
+++ b/include/SDL_joystick.h
@@ -30,10 +30,12 @@
* The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
* then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
*
+ * The term "player_index" is the number assigned to a player on a specific
+ * controller. For XInput controllers this returns the XInput user index.
+ * Many joysticks will not be able to supply this information.
+ *
* The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
* the device (a X360 wired controller for example). This identifier is platform dependent.
- *
- *
*/
#ifndef SDL_joystick_h_
@@ -124,17 +126,43 @@ typedef enum
* and game controller events will not be delivered.
*/
extern DECLSPEC void SDLCALL SDL_LockJoysticks(void);
+
+
+/**
+ * Unlocking for multi-threaded access to the joystick API
+ *
+ * If you are using the joystick API or handling events from multiple threads
+ * you should use these locking functions to protect access to the joysticks.
+ *
+ * In particular, you are guaranteed that the joystick list won't change, so
+ * the API functions that take a joystick index will be valid, and joystick
+ * and game controller events will not be delivered.
+ */
extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void);
/**
- * Count the number of joysticks attached to the system right now
+ * Count the number of joysticks attached to the system.
+ *
+ * \returns the number of attached joysticks on success or a negative error
+ * code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
/**
- * Get the implementation dependent name of a joystick.
- * This can be called before any joysticks are opened.
- * If no name can be found, this function returns NULL.
+ * Get the implementation dependent name of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system)
+ * \returns the name of the selected joystick. If no name can be found, this
+ * function returns NULL; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
@@ -145,69 +173,129 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
/**
- * Return the GUID for the joystick at this index
- * This can be called before any joysticks are opened.
+ * Get the implementation-dependent GUID for the joystick
+ * at a given device index.
+ *
+ * This function can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the GUID of the selected joystick. If called on an invalid index,
+ * this function returns a zero GUID
+ *
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index);
/**
- * Get the USB vendor ID of a joystick, if available.
- * This can be called before any joysticks are opened.
- * If the vendor ID isn't available this function returns 0.
+ * Get the USB vendor ID of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the USB vendor ID of the selected joystick. If called on an
+ * invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
/**
- * Get the USB product ID of a joystick, if available.
- * This can be called before any joysticks are opened.
- * If the product ID isn't available this function returns 0.
+ * Get the USB product ID of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the USB product ID of the selected joystick. If called on an
+ * invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
/**
- * Get the product version of a joystick, if available.
- * This can be called before any joysticks are opened.
- * If the product version isn't available this function returns 0.
+ * Get the product version of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ * If the product version isn't available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the product version of the selected joystick. If called on an
+ * invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index);
/**
- * Get the type of a joystick, if available.
- * This can be called before any joysticks are opened.
+ * Get the type of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the SDL_JoystickType of the selected joystick. If called on an
+ * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`
*/
extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index);
/**
- * Get the instance ID of a joystick.
- * This can be called before any joysticks are opened.
- * If the index is out of range, this function will return -1.
+ * Get the instance ID of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ * If the index is out of range, this function will return -1.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the instance id of the selected joystick. If called on an invalid
+ * index, this function returns zero
*/
extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index);
/**
- * Open a joystick for use.
- * The index passed as an argument refers to the N'th joystick on the system.
- * This index is not the value which will identify this joystick in future
- * joystick events. The joystick's instance id (::SDL_JoystickID) will be used
- * there instead.
+ * Open a joystick for use.
*
- * \return A joystick identifier, or NULL if an error occurred.
+ * The `device_index` argument refers to the N'th joystick presently
+ * recognized by SDL on the system. It is **NOT** the same as the instance ID
+ * used to identify the joystick in future events. See
+ * SDL_JoystickInstanceID() for more details about instance IDs.
+ *
+ * The joystick subsystem must be initialized before a joystick can be opened
+ * for use.
+ *
+ * \param device_index the index of the joystick to query
+ * \returns a joystick identifier or NULL if an error occurred; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickInstanceID
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
/**
- * Return the SDL_Joystick associated with an instance id.
+ * Get the SDL_Joystick associated with an instance id.
+ *
+ * \param joyid the instance id to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id);
/**
- * Return the SDL_Joystick associated with a player index.
+ * Get the SDL_Joystick associated with a player index.
+ *
+ * \param player_index the player index to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ * for more information.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index);
/**
- * Attaches a new virtual joystick.
- * Returns the joystick's device index, or -1 if an error occurred.
+ * Attach a new virtual joystick.
+ *
+ * \returns the joystick's device index, or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
int naxes,
@@ -215,166 +303,344 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
int nhats);
/**
- * Detaches a virtual joystick
- * Returns 0 on success, or -1 if an error occurred.
+ * Detach a virtual joystick.
+ *
+ * \param device_index a value previously returned from
+ * SDL_JoystickAttachVirtual()
+ * \returns 0 on success, or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index);
/**
- * Indicates whether or not a virtual-joystick is at a given device index.
+ * Query whether or not the joystick at a given device index is virtual.
+ *
+ * \param device_index a joystick device index.
+ * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);
/**
- * Set values on an opened, virtual-joystick's controls.
+ * Set values on an opened, virtual-joystick's axis.
+ *
* Please note that values set here will not be applied until the next
* call to SDL_JoystickUpdate, which can either be called directly,
- * or can be called indirectly through various other SDL APIS,
+ * or can be called indirectly through various other SDL APIs,
* including, but not limited to the following: SDL_PollEvent,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
*
- * Returns 0 on success, -1 on error.
+ * \param joystick the virtual joystick on which to set state.
+ * \param axis the specific axis on the virtual joystick to set.
+ * \param value the new value for the specified axis.
+ * \returns 0 on success, -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value);
+
+/**
+ * Set values on an opened, virtual-joystick's button.
+ *
+ * Please note that values set here will not be applied until the next
+ * call to SDL_JoystickUpdate, which can either be called directly,
+ * or can be called indirectly through various other SDL APIs,
+ * including, but not limited to the following: SDL_PollEvent,
+ * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
+ *
+ * \param joystick the virtual joystick on which to set state.
+ * \param button the specific button on the virtual joystick to set.
+ * \param value the new value for the specified button.
+ * \returns 0 on success, -1 on error.
+ */
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value);
+
+/**
+ * Set values on an opened, virtual-joystick's hat.
+ *
+ * Please note that values set here will not be applied until the next
+ * call to SDL_JoystickUpdate, which can either be called directly,
+ * or can be called indirectly through various other SDL APIs,
+ * including, but not limited to the following: SDL_PollEvent,
+ * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
+ *
+ * \param joystick the virtual joystick on which to set state.
+ * \param hat the specific hat on the virtual joystick to set.
+ * \param value the new value for the specified hat.
+ * \returns 0 on success, -1 on error.
+ */
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
/**
- * Return the name for this currently opened joystick.
- * If no name can be found, this function returns NULL.
+ * Get the implementation dependent name of a joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the name of the selected joystick. If no name can be found, this
+ * function returns NULL; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickNameForIndex
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick);
/**
- * Get the player index of an opened joystick, or -1 if it's not available
+ * Get the player index of an opened joystick.
*
- * For XInput controllers this returns the XInput user index.
+ * For XInput controllers this returns the XInput user index. Many joysticks
+ * will not be able to supply this information.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the player index, or -1 if it's not available.
*/
extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick);
/**
- * Set the player index of an opened joystick
+ * Set the player index of an opened joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \param player_index the player index to set.
*/
extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index);
/**
- * Return the GUID for this opened joystick
+ * Get the implementation-dependent GUID for the joystick.
+ *
+ * This function requires an open joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the GUID of the given joystick. If called on an invalid index,
+ * this function returns a zero GUID; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick);
/**
- * Get the USB vendor ID of an opened joystick, if available.
- * If the vendor ID isn't available this function returns 0.
+ * Get the USB vendor ID of an opened joystick, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick);
/**
- * Get the USB product ID of an opened joystick, if available.
- * If the product ID isn't available this function returns 0.
+ * Get the USB product ID of an opened joystick, if available.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB product ID of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
/**
- * Get the product version of an opened joystick, if available.
- * If the product version isn't available this function returns 0.
+ * Get the product version of an opened joystick, if available.
+ * If the product version isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the product version of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick);
/**
- * Get the serial number of an opened joystick, if available.
+ * Get the serial number of an opened joystick, if available.
*
- * Returns the serial number of the joystick, or NULL if it is not available.
+ * Returns the serial number of the joystick, or NULL if it is not available.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the serial number of the selected joystick, or NULL if unavailable.
*/
extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
/**
- * Get the type of an opened joystick.
+ * Get the type of an opened joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the SDL_JoystickType of the selected joystick.
*/
extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick);
/**
- * Return a string representation for this guid. pszGUID must point to at least 33 bytes
- * (32 for the string plus a NULL terminator).
+ * Get an ASCII string representation for a given SDL_JoystickGUID.
+ *
+ * You should supply at least 33 bytes for pszGUID.
+ *
+ * \param guid the SDL_JoystickGUID you wish to convert to string
+ * \param pszGUID buffer in which to write the ASCII string
+ * \param cbGUID the size of pszGUID
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDFromString
*/
extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
/**
- * Convert a string into a joystick guid
+ * Convert a GUID string into a SDL_JoystickGUID structure.
+ *
+ * Performs no error checking. If this function is given a string containing
+ * an invalid GUID, the function will silently succeed, but the GUID generated
+ * will not be useful.
+ *
+ * \param pchGUID string containing an ASCII representation of a GUID
+ * \returns a SDL_JoystickGUID structure.
+ *
+ * \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID);
/**
- * Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not.
+ * Get the status of a specified joystick.
+ *
+ * \param joystick the joystick to query
+ * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick);
/**
- * Get the instance ID of an opened joystick or -1 if the joystick is invalid.
+ * Get the instance ID of an opened joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the instance ID of the specified joystick on success or a negative
+ * error code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick);
/**
- * Get the number of general axis controls on a joystick.
+ * Get the number of general axis controls on a joystick.
+ *
+ * Often, the directional pad on a game controller will either look like 4
+ * separate buttons or a POV hat, and not axes, but all of this is up to the
+ * device and platform.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of axis controls/number of axes on success or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_JoystickGetAxis
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
/**
- * Get the number of trackballs on a joystick.
+ * Get the number of trackballs on a joystick.
*
- * Joystick trackballs have only relative motion events associated
- * with them and their state cannot be polled.
+ * Joystick trackballs have only relative motion events associated with them
+ * and their state cannot be polled.
+ *
+ * Most joysticks do not have trackballs.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of trackballs on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetBall
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
/**
- * Get the number of POV hats on a joystick.
+ * Get the number of POV hats on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of POV hats on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetHat
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
/**
- * Get the number of buttons on a joystick.
+ * Get the number of buttons on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of buttons on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetButton
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
/**
- * Update the current state of the open joysticks.
+ * Update the current state of the open joysticks.
*
- * This is called automatically by the event loop if any joystick
- * events are enabled.
+ * This is called automatically by the event loop if any joystick events are
+ * enabled.
+ *
+ * \sa SDL_JoystickEventState
*/
extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
/**
- * Enable/disable joystick event polling.
+ * Enable/disable joystick event polling.
*
- * If joystick events are disabled, you must call SDL_JoystickUpdate()
- * yourself and check the state of the joystick when you want joystick
- * information.
+ * If joystick events are disabled, you must call SDL_JoystickUpdate()
+ * yourself and manually check the state of the joystick when you want
+ * joystick information.
*
- * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * It is recommended that you leave joystick event handling enabled.
+ *
+ * **WARNING**: Calling this function may delete all events currently in SDL's
+ * event queue.
+ *
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
+ * call SDL_GetError() for more information.
+ *
+ * If `state` is `SDL_QUERY` then the current state is returned,
+ * otherwise the new processing state is returned.
+ *
+ * \sa SDL_GameControllerEventState
*/
extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
#define SDL_JOYSTICK_AXIS_MAX 32767
#define SDL_JOYSTICK_AXIS_MIN -32768
/**
- * Get the current state of an axis control on a joystick.
+ * Get the current state of an axis control on a joystick.
*
- * The state is a value ranging from -32768 to 32767.
+ * SDL makes no promises about what part of the joystick any given axis
+ * refers to. Your game should have some sort of configuration UI to let
+ * users specify what each axis should be bound to. Alternately, SDL's
+ * higher-level Game Controller API makes a great effort to apply order
+ * to this lower-level interface, so you know that a specific axis is the
+ * "left thumb stick," etc.
*
- * The axis indices start at index 0.
+ * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
+ * 32767) representing the current position of the axis. It may be necessary
+ * to impose certain tolerances on these values to account for jitter.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \returns a 16-bit signed integer representing the current position of the
+ * axis or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickNumAxes
*/
extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick,
int axis);
/**
- * Get the initial state of an axis control on a joystick.
+ * Get the initial state of an axis control on a joystick.
*
- * The state is a value ranging from -32768 to 32767.
+ * The state is a value ranging from -32768 to 32767.
*
- * The axis indices start at index 0.
+ * The axis indices start at index 0.
*
- * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \param state Upon return, the initial value is supplied here.
+ * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick,
int axis, Sint16 *state);
@@ -395,96 +661,153 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j
/* @} */
/**
- * Get the current state of a POV hat on a joystick.
+ * Get the current state of a POV hat on a joystick.
*
- * The hat indices start at index 0.
+ * The returned value will be one of the following positions:
*
- * \return The return value is one of the following positions:
- * - ::SDL_HAT_CENTERED
- * - ::SDL_HAT_UP
- * - ::SDL_HAT_RIGHT
- * - ::SDL_HAT_DOWN
- * - ::SDL_HAT_LEFT
- * - ::SDL_HAT_RIGHTUP
- * - ::SDL_HAT_RIGHTDOWN
- * - ::SDL_HAT_LEFTUP
- * - ::SDL_HAT_LEFTDOWN
+ * - `SDL_HAT_CENTERED`
+ *
+ * - `SDL_HAT_UP`
+ *
+ * - `SDL_HAT_RIGHT`
+ *
+ * - `SDL_HAT_DOWN`
+ *
+ * - `SDL_HAT_LEFT`
+ *
+ * - `SDL_HAT_RIGHTUP`
+ *
+ * - `SDL_HAT_RIGHTDOWN`
+ *
+ * - `SDL_HAT_LEFTUP`
+ *
+ * - `SDL_HAT_LEFTDOWN`
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param hat the hat index to get the state from; hat indices start at index
+ * 0
+ * \returns the current hat position.
+ *
+ * \sa SDL_JoystickNumHats
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
int hat);
/**
- * Get the ball axis change since the last poll.
+ * Get the ball axis change since the last poll.
*
- * \return 0, or -1 if you passed it invalid parameters.
+ * Trackballs can only return relative motion since the last call to
+ * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and
+ * `dy`.
*
- * The ball indices start at index 0.
+ * Most joysticks do not have trackballs.
+ *
+ * \param joystick the SDL_Joystick to query
+ * \param ball the ball index to query; ball indices start at index 0
+ * \param dx stores the difference in the x axis position since the last poll
+ * \param dy stores the difference in the y axis position since the last poll
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickNumBalls
*/
extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick,
int ball, int *dx, int *dy);
/**
- * Get the current state of a button on a joystick.
+ * Get the current state of a button on a joystick.
*
- * The button indices start at index 0.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param button the button index to get the state from; indices start at
+ * index 0
+ * \returns 1 if the specified button is pressed, 0 otherwise.
+ *
+ * \sa SDL_JoystickNumButtons
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
int button);
/**
- * Start a rumble effect
- * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect.
*
- * \param joystick The joystick to vibrate
- * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
- * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
*
- * \return 0, or -1 if rumble isn't supported on this joystick
+ * \param joystick The joystick to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ * rumble motor, from 0 to 0xFFFF
+ * \param high_frequency_rumble The intensity of the high frequency (right)
+ * rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ *
+ * \returns 0, or -1 if rumble isn't supported on this joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
/**
- * Start a rumble effect in the joystick's triggers
- * Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect in the joystick's triggers
*
- * \param joystick The joystick to vibrate
- * \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
- * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Each call to this function cancels any previous trigger rumble effect,
+ * and calling it with 0 intensity stops any rumbling.
*
- * \return 0, or -1 if trigger rumble isn't supported on this joystick
+ * Note that this function is for _trigger_ rumble; the first joystick to
+ * support this was the PlayStation 5's DualShock 5 controller. If you want
+ * the (more common) whole-controller rumble, use SDL_JoystickRumble() instead.
+ *
+ * \param joystick The joystick to vibrate
+ * \param left_rumble The intensity of the left trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ *
+ * \returns 0, or -1 if trigger rumble isn't supported on this joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
/**
- * Return whether a joystick has an LED
+ * Query whether a joystick has an LED.
*
- * \param joystick The joystick to query
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
*
- * \return SDL_TRUE, or SDL_FALSE if this joystick does not have a modifiable LED
+ * \param joystick The joystick to query
+ * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
/**
- * Update a joystick's LED color.
+ * Update a joystick's LED color.
*
- * \param joystick The joystick to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
*
- * \return 0, or -1 if this joystick does not have a modifiable LED
+ * \param joystick The joystick to update
+ * \param red The intensity of the red LED
+ * \param green The intensity of the green LED
+ * \param blue The intensity of the blue LED
+ *
+ * \returns 0 on success, -1 if this joystick does not have a modifiable LED
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
/**
- * Close a joystick previously opened with SDL_JoystickOpen().
+ * Close a joystick previously opened with SDL_JoystickOpen().
+ *
+ * \param joystick The joystick device to close
+ *
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
/**
- * Return the battery level of this joystick
+ * Get the battery level of a joystick as SDL_JoystickPowerLevel.
+ *
+ * \param joystick the SDL_Joystick to query
+ * \returns the current battery level as SDL_JoystickPowerLevel on success or
+ * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick);
diff --git a/include/SDL_keyboard.h b/include/SDL_keyboard.h
index 9eaeb2838..3b14acbf2 100644
--- a/include/SDL_keyboard.h
+++ b/include/SDL_keyboard.h
@@ -55,154 +55,231 @@ typedef struct SDL_Keysym
/* Function prototypes */
/**
- * \brief Get the window which currently has keyboard focus.
+ * Query the window which currently has keyboard focus.
+ *
+ * \returns the window with keyboard focus.
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
/**
- * \brief Get a snapshot of the current state of the keyboard.
+ * Get a snapshot of the current state of the keyboard.
*
- * \param numkeys if non-NULL, receives the length of the returned array.
+ * The pointer returned is a pointer to an internal SDL array. It will be
+ * valid for the whole lifetime of the application and should not be freed
+ * by the caller.
*
- * \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
+ * A array element with a value of 1 means that the key is pressed and a value
+ * of 0 means that it is not. Indexes into this array are obtained by using
+ * SDL_Scancode values.
*
- * \b Example:
- * \code
- * const Uint8 *state = SDL_GetKeyboardState(NULL);
- * if ( state[SDL_SCANCODE_RETURN] ) {
- * printf("| data | mask | resulting pixel on screen |
| 0 | 1 | White |
| 1 | 1 | Black |
| 0 | 0 | Transparent |
| 1 | 0 | Inverted color if possible, black - * if not. |