mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-09-07 11:58:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated headers with latest wikiheaders tweaks.

Browse Source
This commit is contained in:
Ryan C. Gordon
2024-06-14 02:09:55 -04:00
parent c0c0c64a1d
commit 51902d4ac5
44 changed files with 1699 additions and 1686 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
include/SDL3/SDL_assert.h
View File

@@ -234,11 +234,11 @@ typedef struct SDL_AssertData
* *
* Use the SDL_assert* macros instead. * Use the SDL_assert* macros instead.
* *
* \param data assert data structure * \param data assert data structure.
* \param func function name * \param func function name.
* \param file file name * \param file file name.
* \param line line number * \param line line number.
* \returns assert state * \returns assert state.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -306,7 +306,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
* Please refer to your platform's documentation for how to set it! * Please refer to your platform's documentation for how to set it!
* *
* \param condition boolean value to test * \param condition boolean value to test.
* *
* \since This macro is available since SDL 3.0.0. * \since This macro is available since SDL 3.0.0.
*/ */
@@ -339,7 +339,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
* Please refer to your platform's documentation for how to set it! * Please refer to your platform's documentation for how to set it!
* *
* \param condition boolean value to test * \param condition boolean value to test.
* *
* \since This macro is available since SDL 3.0.0. * \since This macro is available since SDL 3.0.0.
*/ */
@@ -369,7 +369,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
* Please refer to your platform's documentation for how to set it! * Please refer to your platform's documentation for how to set it!
* *
* \param condition boolean value to test * \param condition boolean value to test.
* *
* \since This macro is available since SDL 3.0.0. * \since This macro is available since SDL 3.0.0.
*/ */
@@ -415,7 +415,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
* Please refer to your platform's documentation for how to set it! * Please refer to your platform's documentation for how to set it!
* *
* \param condition boolean value to test * \param condition boolean value to test.
* *
* \since This macro is available since SDL 3.0.0. * \since This macro is available since SDL 3.0.0.
*/ */
@@ -426,8 +426,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* A callback that fires when an SDL assertion fails. * A callback that fires when an SDL assertion fails.
* *
* \param data a pointer to the SDL_AssertData structure corresponding to the * \param data a pointer to the SDL_AssertData structure corresponding to the
* current assertion * current assertion.
* \param userdata what was passed as `userdata` to SDL_SetAssertionHandler() * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler().
* \returns an SDL_AssertState value indicating how to handle the failure. * \returns an SDL_AssertState value indicating how to handle the failure.
* *
* \since This datatype is available since SDL 3.0.0. * \since This datatype is available since SDL 3.0.0.
@@ -449,8 +449,8 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
* This callback is NOT reset to SDL's internal handler upon SDL_Quit()! * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
* *
* \param handler the SDL_AssertionHandler function to call when an assertion * \param handler the SDL_AssertionHandler function to call when an assertion
* fails or NULL for the default handler * fails or NULL for the default handler.
* \param userdata a pointer that is passed to `handler` * \param userdata a pointer that is passed to `handler`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -491,7 +491,7 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(
* data, it is safe to pass a NULL pointer to this function to ignore it. * data, it is safe to pass a NULL pointer to this function to ignore it.
* *
* \param puserdata pointer which is filled with the "userdata" pointer that * \param puserdata pointer which is filled with the "userdata" pointer that
* was passed to SDL_SetAssertionHandler() * was passed to SDL_SetAssertionHandler().
* \returns the SDL_AssertionHandler that is called when an assert triggers. * \returns the SDL_AssertionHandler that is called when an assert triggers.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

36
include/SDL3/SDL_atomic.h
View File

@@ -87,7 +87,7 @@ typedef int SDL_SpinLock;
* ***Please note that spinlocks are dangerous if you don't know what you're * ***Please note that spinlocks are dangerous if you don't know what you're
* doing. Please be careful using any sort of spinlock!*** * doing. Please be careful using any sort of spinlock!***
* *
* \param lock a pointer to a lock variable * \param lock a pointer to a lock variable.
* \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
* held. * held.
* *
@@ -104,7 +104,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock);
* ***Please note that spinlocks are dangerous if you don't know what you're * ***Please note that spinlocks are dangerous if you don't know what you're
* doing. Please be careful using any sort of spinlock!*** * doing. Please be careful using any sort of spinlock!***
* *
* \param lock a pointer to a lock variable * \param lock a pointer to a lock variable.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -121,7 +121,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock);
* ***Please note that spinlocks are dangerous if you don't know what you're * ***Please note that spinlocks are dangerous if you don't know what you're
* doing. Please be careful using any sort of spinlock!*** * doing. Please be careful using any sort of spinlock!***
* *
* \param lock a pointer to a lock variable * \param lock a pointer to a lock variable.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -333,9 +333,9 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt;
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
* *
* \param a a pointer to an SDL_AtomicInt variable to be modified * \param a a pointer to an SDL_AtomicInt variable to be modified.
* \param oldval the old value * \param oldval the old value.
* \param newval the new value * \param newval the new value.
* \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -354,8 +354,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a,
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
* *
* \param a a pointer to an SDL_AtomicInt variable to be modified * \param a a pointer to an SDL_AtomicInt variable to be modified.
* \param v the desired value * \param v the desired value.
* \returns the previous value of the atomic variable. * \returns the previous value of the atomic variable.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -372,7 +372,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v);
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
* *
* \param a a pointer to an SDL_AtomicInt variable * \param a a pointer to an SDL_AtomicInt variable.
* \returns the current value of an atomic variable. * \returns the current value of an atomic variable.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -391,8 +391,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a);
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
* *
* \param a a pointer to an SDL_AtomicInt variable to be modified * \param a a pointer to an SDL_AtomicInt variable to be modified.
* \param v the desired value to add * \param v the desired value to add.
* \returns the previous value of the atomic variable. * \returns the previous value of the atomic variable.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -430,7 +430,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
* *
* \param a a pointer to an SDL_AtomicInt to increment. * \param a a pointer to an SDL_AtomicInt to increment.
* \returns SDL_TRUE if the variable reached zero after decrementing, * \returns SDL_TRUE if the variable reached zero after decrementing,
* SDL_FALSE otherwise * SDL_FALSE otherwise.
* *
* \since This macro is available since SDL 3.0.0. * \since This macro is available since SDL 3.0.0.
* *
@@ -445,9 +445,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
* *
* \param a a pointer to a pointer * \param a a pointer to a pointer.
* \param oldval the old pointer value * \param oldval the old pointer value.
* \param newval the new pointer value * \param newval the new pointer value.
* \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -466,8 +466,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
* *
* \param a a pointer to a pointer * \param a a pointer to a pointer.
* \param v the desired pointer value * \param v the desired pointer value.
* \returns the previous value of the pointer. * \returns the previous value of the pointer.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -485,7 +485,7 @@ extern SDL_DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
* *
* \param a a pointer to a pointer * \param a a pointer to a pointer.
* \returns the current value of a pointer. * \returns the current value of a pointer.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.

160
include/SDL3/SDL_audio.h
View File

@@ -141,8 +141,8 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16. * For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns data size in bits * \returns data size in bits.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
* *
@@ -155,8 +155,8 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2. * For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns data size in bytes * \returns data size in bytes.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
* *
@@ -169,7 +169,7 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0. * For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns non-zero if format is floating point, zero otherwise. * \returns non-zero if format is floating point, zero otherwise.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
@@ -183,7 +183,7 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0. * For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns non-zero if format is bigendian, zero otherwise. * \returns non-zero if format is bigendian, zero otherwise.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
@@ -197,7 +197,7 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0. * For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns non-zero if format is littleendian, zero otherwise. * \returns non-zero if format is littleendian, zero otherwise.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
@@ -211,7 +211,7 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0. * For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns non-zero if format is signed, zero otherwise. * \returns non-zero if format is signed, zero otherwise.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
@@ -225,7 +225,7 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0. * For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns non-zero if format is integer, zero otherwise. * \returns non-zero if format is integer, zero otherwise.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
@@ -239,7 +239,7 @@ typedef Uint16 SDL_AudioFormat;
* *
* For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0. * For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
* *
* \param x an SDL_AudioFormat value * \param x an SDL_AudioFormat value.
* \returns non-zero if format is unsigned, zero otherwise. * \returns non-zero if format is unsigned, zero otherwise.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
@@ -382,7 +382,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param index the index of the audio driver; the value ranges from 0 to * \param index the index of the audio driver; the value ranges from 0 to
* SDL_GetNumAudioDrivers() - 1 * SDL_GetNumAudioDrivers() - 1.
* \returns the name of the audio driver at the requested index, or NULL if an * \returns the name of the audio driver at the requested index, or NULL if an
* invalid index was specified. * invalid index was specified.
* *
@@ -512,8 +512,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID
* playback timing. Most apps do not need this. * playback timing. Most apps do not need this.
* *
* \param devid the instance ID of the device to query. * \param devid the instance ID of the device to query.
* \param spec On return, will be filled with device details. * \param spec on return, will be filled with device details.
* \param sample_frames Pointer to store device buffer size, in sample frames. * \param sample_frames pointer to store device buffer size, in sample frames.
* Can be NULL. * Can be NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@@ -618,7 +618,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic
* Physical devices can not be paused or unpaused, only logical devices * Physical devices can not be paused or unpaused, only logical devices
* created through SDL_OpenAudioDevice() can be. * created through SDL_OpenAudioDevice() can be.
* *
* \param dev a device opened by SDL_OpenAudioDevice() * \param dev a device opened by SDL_OpenAudioDevice().
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -646,7 +646,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
* Physical devices can not be paused or unpaused, only logical devices * Physical devices can not be paused or unpaused, only logical devices
* created through SDL_OpenAudioDevice() can be. * created through SDL_OpenAudioDevice() can be.
* *
* \param dev a device opened by SDL_OpenAudioDevice() * \param dev a device opened by SDL_OpenAudioDevice().
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -669,7 +669,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
* created through SDL_OpenAudioDevice() can be. Physical and invalid device * created through SDL_OpenAudioDevice() can be. Physical and invalid device
* IDs will report themselves as unpaused here. * IDs will report themselves as unpaused here.
* *
* \param dev a device opened by SDL_OpenAudioDevice() * \param dev a device opened by SDL_OpenAudioDevice().
* \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise. * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -692,7 +692,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev
* supplied if terminating immediately afterwards. * supplied if terminating immediately afterwards.
* *
* \param devid an audio device id previously returned by * \param devid an audio device id previously returned by
* SDL_OpenAudioDevice() * SDL_OpenAudioDevice().
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -725,7 +725,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
* *
* \param devid an audio device to bind a stream to. * \param devid an audio device to bind a stream to.
* \param streams an array of audio streams to unbind. * \param streams an array of audio streams to unbind.
* \param num_streams Number streams listed in the `streams` array. * \param num_streams number streams listed in the `streams` array.
* \returns 0 on success, -1 on error; call SDL_GetError() for more * \returns 0 on success, -1 on error; call SDL_GetError() for more
* information. * information.
* *
@@ -770,7 +770,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL
* Unbinding a stream that isn't bound to a device is a legal no-op. * Unbinding a stream that isn't bound to a device is a legal no-op.
* *
* \param streams an array of audio streams to unbind. * \param streams an array of audio streams to unbind.
* \param num_streams Number streams listed in the `streams` array. * \param num_streams number streams listed in the `streams` array.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -819,8 +819,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
/** /**
* Create a new audio stream. * Create a new audio stream.
* *
* \param src_spec The format details of the input audio * \param src_spec the format details of the input audio.
* \param dst_spec The format details of the output audio * \param dst_spec the format details of the output audio.
* \returns a new audio stream on success, or NULL on failure. * \returns a new audio stream on success, or NULL on failure.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -840,7 +840,7 @@ extern SDL_DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_Aud
/** /**
* Get the properties associated with an audio stream. * Get the properties associated with an audio stream.
* *
* \param stream the SDL_AudioStream to query * \param stream the SDL_AudioStream to query.
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -855,8 +855,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au
* Query the current format of an audio stream. * Query the current format of an audio stream.
* *
* \param stream the SDL_AudioStream to query. * \param stream the SDL_AudioStream to query.
* \param src_spec Where to store the input audio format; ignored if NULL. * \param src_spec where to store the input audio format; ignored if NULL.
* \param dst_spec Where to store the output audio format; ignored if NULL. * \param dst_spec where to store the output audio format; ignored if NULL.
* \returns 0 on success, or -1 on error. * \returns 0 on success, or -1 on error.
* *
* \threadsafety It is safe to call this function from any thread, as it holds * \threadsafety It is safe to call this function from any thread, as it holds
@@ -881,10 +881,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream
* next sound file, and start putting that new data while the previous sound * next sound file, and start putting that new data while the previous sound
* file is still queued, and everything will still play back correctly. * file is still queued, and everything will still play back correctly.
* *
* \param stream The stream the format is being changed * \param stream the stream the format is being changed.
* \param src_spec The new format of the audio input; if NULL, it is not * \param src_spec the new format of the audio input; if NULL, it is not
* changed. * changed.
* \param dst_spec The new format of the audio output; if NULL, it is not * \param dst_spec the new format of the audio output; if NULL, it is not
* changed. * changed.
* \returns 0 on success, or -1 on error. * \returns 0 on success, or -1 on error.
* *
@@ -904,7 +904,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream
* Get the frequency ratio of an audio stream. * Get the frequency ratio of an audio stream.
* *
* \param stream the SDL_AudioStream to query. * \param stream the SDL_AudioStream to query.
* \returns the frequency ratio of the stream, or 0.0 on error * \returns the frequency ratio of the stream, or 0.0 on error.
* *
* \threadsafety It is safe to call this function from any thread, as it holds * \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running. * a stream-specific mutex while running.
@@ -927,8 +927,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre
* This is applied during SDL_GetAudioStreamData, and can be continuously * This is applied during SDL_GetAudioStreamData, and can be continuously
* changed to create various effects. * changed to create various effects.
* *
* \param stream The stream the frequency ratio is being changed * \param stream the stream the frequency ratio is being changed.
* \param ratio The frequency ratio. 1.0 is normal speed. Must be between 0.01 * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
* and 100. * and 100.
* \returns 0 on success, or -1 on error. * \returns 0 on success, or -1 on error.
* *
@@ -953,9 +953,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream
* different than SDL2, where data was converted during the Put call and the * different than SDL2, where data was converted during the Put call and the
* Get call would just dequeue the previously-converted data. * Get call would just dequeue the previously-converted data.
* *
* \param stream The stream the audio data is being added to * \param stream the stream the audio data is being added to.
* \param buf A pointer to the audio data to add * \param buf a pointer to the audio data to add.
* \param len The number of bytes to write to the stream * \param len the number of bytes to write to the stream.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -984,10 +984,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream,
* is different than SDL2, where that work was done while inputting new data * is different than SDL2, where that work was done while inputting new data
* to the stream and requesting the output just copied the converted data. * to the stream and requesting the output just copied the converted data.
* *
* \param stream The stream the audio is being requested from * \param stream the stream the audio is being requested from.
* \param buf A buffer to fill with audio data * \param buf a buffer to fill with audio data.
* \param len The maximum number of bytes to fill * \param len the maximum number of bytes to fill.
* \returns 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.
* *
* \threadsafety It is safe to call this function from any thread, but if the * \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage * stream has a callback set, the caller might need to manage
@@ -1014,7 +1014,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream,
* SDL_GetAudioStreamData before this function's return value is no longer * SDL_GetAudioStreamData before this function's return value is no longer
* clamped. * clamped.
* *
* \param stream The audio stream to query * \param stream the audio stream to query.
* \returns the number of converted/resampled bytes available. * \returns the number of converted/resampled bytes available.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -1046,7 +1046,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str
* SDL_GetAudioStreamData before this function's return value is no longer * SDL_GetAudioStreamData before this function's return value is no longer
* clamped. * clamped.
* *
* \param stream The audio stream to query * \param stream the audio stream to query.
* \returns the number of bytes queued. * \returns the number of bytes queued.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -1067,7 +1067,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream
* audio gaps in the output. Generally this is intended to signal the end of * audio gaps in the output. Generally this is intended to signal the end of
* input, so the complete output becomes available. * input, so the complete output becomes available.
* *
* \param stream The audio stream to flush * \param stream the audio stream to flush.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1085,7 +1085,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
* This drops any queued data, so there will be nothing to read from the * This drops any queued data, so there will be nothing to read from the
* stream until more is added. * stream until more is added.
* *
* \param stream The audio stream to clear * \param stream the audio stream to clear.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1112,7 +1112,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
* audio streams. This might be useful while a game is paused, or a level is * audio streams. This might be useful while a game is paused, or a level is
* loading, etc. * loading, etc.
* *
* \param stream The audio stream associated with the audio device to pause * \param stream the audio stream associated with the audio device to pause.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1132,7 +1132,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stre
* previously been paused. Once unpaused, any bound audio streams will begin * previously been paused. Once unpaused, any bound audio streams will begin
* to progress again, and audio can be generated. * to progress again, and audio can be generated.
* *
* \param stream The audio stream associated with the audio device to resume * \param stream the audio stream associated with the audio device to resume.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1160,7 +1160,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *str
* As this is just a wrapper over SDL_LockMutex for an internal lock; it has * As this is just a wrapper over SDL_LockMutex for an internal lock; it has
* all the same attributes (recursive locks are allowed, etc). * all the same attributes (recursive locks are allowed, etc).
* *
* \param stream The audio stream to lock. * \param stream the audio stream to lock.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1178,7 +1178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
* *
* This unlocks an audio stream after a call to SDL_LockAudioStream. * This unlocks an audio stream after a call to SDL_LockAudioStream.
* *
* \param stream The audio stream to unlock. * \param stream the audio stream to unlock.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1212,12 +1212,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
* appropriate, but the system goes on with the data currently available to it * appropriate, but the system goes on with the data currently available to it
* if this callback does nothing. * if this callback does nothing.
* *
* \param stream The SDL audio stream associated with this callback. * \param stream the SDL audio stream associated with this callback.
* \param additional_amount The amount of data, in bytes, that is needed right * \param additional_amount the amount of data, in bytes, that is needed right
* now. * now.
* \param total_amount The total amount of data requested, in bytes, that is * \param total_amount the total amount of data requested, in bytes, that is
* requested or available. * requested or available.
* \param userdata An opaque pointer provided by the app for their personal * \param userdata an opaque pointer provided by the app for their personal
* use. * use.
* *
* \threadsafety This callbacks may run from any thread, so if you need to * \threadsafety This callbacks may run from any thread, so if you need to
@@ -1338,7 +1338,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *s
* device that was opened alongside this stream's creation will be closed, * device that was opened alongside this stream's creation will be closed,
* too. * too.
* *
* \param stream The audio stream to destroy. * \param stream the audio stream to destroy.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1390,11 +1390,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
* \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or * \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
* SDL_AUDIO_DEVICE_DEFAULT_CAPTURE. * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE.
* \param spec the audio stream's data format. Can be NULL. * \param spec the audio stream's data format. Can be NULL.
* \param callback A callback where the app will provide new data for * \param callback a callback where the app will provide new data for
* playback, or receive new data for capture. Can be NULL, in * playback, or receive new data for capture. Can be NULL, in
* which case the app will need to call SDL_PutAudioStreamData * which case the app will need to call SDL_PutAudioStreamData
* or SDL_GetAudioStreamData as necessary. * or SDL_GetAudioStreamData as necessary.
* \param userdata App-controlled pointer passed to callback. Can be NULL. * \param userdata app-controlled pointer passed to callback. Can be NULL.
* Ignored if callback is NULL. * Ignored if callback is NULL.
* \returns an audio stream on success, ready to use. NULL on error; call * \returns an audio stream on success, ready to use. NULL on error; call
* SDL_GetError() for more information. When done with this stream, * SDL_GetError() for more information. When done with this stream,
@@ -1485,9 +1485,9 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio
* *
* Setting a NULL callback function disables any previously-set callback. * Setting a NULL callback function disables any previously-set callback.
* *
* \param devid The ID of an opened audio device. * \param devid the ID of an opened audio device.
* \param callback A callback function to be called. Can be NULL. * \param callback a callback function to be called. Can be NULL.
* \param userdata App-controlled pointer passed to callback. Can be NULL. * \param userdata app-controlled pointer passed to callback. Can be NULL.
* \returns zero on success, -1 on error; call SDL_GetError() for more * \returns zero on success, -1 on error; call SDL_GetError() for more
* information. * information.
* *
@@ -1549,15 +1549,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID de
* SDL_LoadWAV("sample.wav", &spec, &buf, &len); * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
* ``` * ```
* *
* \param src The data source for the WAVE data * \param src the data source for the WAVE data.
* \param closeio If SDL_TRUE, calls SDL_CloseIO() on `src` before returning, * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error * even in the case of an error.
* \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
* data's format details on successful return * data's format details on successful return.
* \param audio_buf A pointer filled with the audio data, allocated by the * \param audio_buf a pointer filled with the audio data, allocated by the
* function * function.
* \param audio_len A pointer filled with the length of the audio data buffer * \param audio_len a pointer filled with the length of the audio data buffer
* in bytes * in bytes.
* \returns 0 on success. `audio_buf` will be filled with a pointer to an * \returns 0 on success. `audio_buf` will be filled with a pointer to an
* allocated buffer containing the audio data, and `audio_len` is * allocated buffer containing the audio data, and `audio_len` is
* filled with the length of that audio buffer in bytes. * filled with the length of that audio buffer in bytes.
@@ -1589,13 +1589,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool clos
* SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len); * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
* ``` * ```
* *
* \param path The file path of the WAV file to open. * \param path the file path of the WAV file to open.
* \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
* data's format details on successful return. * data's format details on successful return.
* \param audio_buf A pointer filled with the audio data, allocated by the * \param audio_buf a pointer filled with the audio data, allocated by the
* function. * function.
* \param audio_len A pointer filled with the length of the audio data buffer * \param audio_len a pointer filled with the length of the audio data buffer
* in bytes * in bytes.
* \returns 0 on success. `audio_buf` will be filled with a pointer to an * \returns 0 on success. `audio_buf` will be filled with a pointer to an
* allocated buffer containing the audio data, and `audio_len` is * allocated buffer containing the audio data, and `audio_len` is
* filled with the length of that audio buffer in bytes. * filled with the length of that audio buffer in bytes.
@@ -1637,13 +1637,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * sp
* SDL_MixAudio() is really only needed when you're mixing a single audio * SDL_MixAudio() is really only needed when you're mixing a single audio
* stream with a volume adjustment. * stream with a volume adjustment.
* *
* \param dst the destination for the mixed audio * \param dst the destination for the mixed audio.
* \param src the source audio buffer to be mixed * \param src the source audio buffer to be mixed.
* \param format the SDL_AudioFormat structure representing the desired audio * \param format the SDL_AudioFormat structure representing the desired audio
* format * format.
* \param len the length of the audio buffer in bytes * \param len the length of the audio buffer in bytes.
* \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full
* audio volume * audio volume.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1669,14 +1669,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_MixAudio(Uint8 * dst,
* use, so it's also less efficient than using one directly, if you need to * use, so it's also less efficient than using one directly, if you need to
* convert multiple times. * convert multiple times.
* *
* \param src_spec The format details of the input audio * \param src_spec the format details of the input audio.
* \param src_data The audio data to be converted * \param src_data the audio data to be converted.
* \param src_len The len of src_data * \param src_len the len of src_data.
* \param dst_spec The format details of the output audio * \param dst_spec the format details of the output audio.
* \param dst_data Will be filled with a pointer to converted audio data, * \param dst_data will be filled with a pointer to converted audio data,
* which should be freed with SDL_free(). On error, it will be * which should be freed with SDL_free(). On error, it will be
* NULL. * NULL.
* \param dst_len Will be filled with the len of dst_data * \param dst_len will be filled with the len of dst_data.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

4
include/SDL3/SDL_bits.h
View File

@@ -60,7 +60,7 @@ extern __inline int _SDL_bsr_watcom(Uint32);
* embedded in the calling program and the linker and dynamic loader will not * embedded in the calling program and the linker and dynamic loader will not
* be able to find this function inside SDL itself). * be able to find this function inside SDL itself).
* *
* \param x the 32-bit value to examine * \param x the 32-bit value to examine.
* \returns the index of the most significant bit, or -1 if the value is 0. * \returns the index of the most significant bit, or -1 if the value is 0.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -128,7 +128,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x)
* embedded in the calling program and the linker and dynamic loader will not * embedded in the calling program and the linker and dynamic loader will not
* be able to find this function inside SDL itself). * be able to find this function inside SDL itself).
* *
* \param x the 32-bit value to examine * \param x the 32-bit value to examine.
* \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.

12
include/SDL3/SDL_blendmode.h
View File

@@ -168,18 +168,18 @@ typedef enum SDL_BlendFactor
* case. * case.
* *
* \param srcColorFactor the SDL_BlendFactor applied to the red, green, and * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
* blue components of the source pixels * blue components of the source pixels.
* \param dstColorFactor the SDL_BlendFactor applied to the red, green, and * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
* blue components of the destination pixels * blue components of the destination pixels.
* \param colorOperation the SDL_BlendOperation used to combine the red, * \param colorOperation the SDL_BlendOperation used to combine the red,
* green, and blue components of the source and * green, and blue components of the source and
* destination pixels * destination pixels.
* \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
* the source pixels * the source pixels.
* \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
* the destination pixels * the destination pixels.
* \param alphaOperation the SDL_BlendOperation used to combine the alpha * \param alphaOperation the SDL_BlendOperation used to combine the alpha
* component of the source and destination pixels * component of the source and destination pixels.
* \returns an SDL_BlendMode that represents the chosen factors and * \returns an SDL_BlendMode that represents the chosen factors and
* operations. * operations.
* *

28
include/SDL3/SDL_camera.h
View File

@@ -137,7 +137,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param index the index of the camera driver; the value ranges from 0 to * \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1 * SDL_GetNumCameraDrivers() - 1.
* \returns the name of the camera driver at the requested index, or NULL if * \returns the name of the camera driver at the requested index, or NULL if
* an invalid index was specified. * an invalid index was specified.
* *
@@ -232,7 +232,7 @@ extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraDeviceSupportedFormats(
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the camera device instance ID * \param instance_id the camera device instance ID.
* \returns a human-readable device name, or NULL on error; call * \returns a human-readable device name, or NULL on error; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -252,7 +252,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDeviceName(SDL_CameraDevic
* points towards the user, for taking "selfies") and cameras on the back (for * points towards the user, for taking "selfies") and cameras on the back (for
* filming in the direction the user is facing). * filming in the direction the user is facing).
* *
* \param instance_id the camera device instance ID * \param instance_id the camera device instance ID.
* \returns the position of the camera on the system hardware. * \returns the position of the camera on the system hardware.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -294,8 +294,8 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraDevicePosition(SDL_C
* where the user previously permitted access), the approval event might come * where the user previously permitted access), the approval event might come
* immediately, but it might come seconds, minutes, or hours later! * immediately, but it might come seconds, minutes, or hours later!
* *
* \param instance_id the camera device instance ID * \param instance_id the camera device instance ID.
* \param spec The desired format for data the device will provide. Can be * \param spec the desired format for data the device will provide. Can be
* NULL. * NULL.
* \returns device, or NULL on failure; call SDL_GetError() for more * \returns device, or NULL on failure; call SDL_GetError() for more
* information. * information.
@@ -329,7 +329,7 @@ extern SDL_DECLSPEC SDL_Camera *SDLCALL SDL_OpenCameraDevice(SDL_CameraDeviceID
* If a camera is declined, there's nothing to be done but call * If a camera is declined, there's nothing to be done but call
* SDL_CloseCamera() to dispose of it. * SDL_CloseCamera() to dispose of it.
* *
* \param camera the opened camera device to query * \param camera the opened camera device to query.
* \returns -1 if user denied access to the camera, 1 if user approved access, * \returns -1 if user denied access to the camera, 1 if user approved access,
* 0 if no decision has been made yet. * 0 if no decision has been made yet.
* *
@@ -345,7 +345,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera)
/** /**
* Get the instance ID of an opened camera. * Get the instance ID of an opened camera.
* *
* \param camera an SDL_Camera to query * \param camera an SDL_Camera to query.
* \returns the instance ID of the specified camera on success or 0 on * \returns the instance ID of the specified camera on success or 0 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -360,7 +360,7 @@ extern SDL_DECLSPEC SDL_CameraDeviceID SDLCALL SDL_GetCameraInstanceID(SDL_Camer
/** /**
* Get the properties associated with an opened camera. * Get the properties associated with an opened camera.
* *
* \param camera the SDL_Camera obtained from SDL_OpenCameraDevice() * \param camera the SDL_Camera obtained from SDL_OpenCameraDevice().
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -385,8 +385,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera
* (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() * (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
* occasionally until it returns non-zero. * occasionally until it returns non-zero.
* *
* \param camera opened camera device * \param camera opened camera device.
* \param spec The SDL_CameraSpec to be initialized by this function. * \param spec the SDL_CameraSpec to be initialized by this function.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -427,7 +427,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_Came
* SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
* occasionally until it returns non-zero. * occasionally until it returns non-zero.
* *
* \param camera opened camera device * \param camera opened camera device.
* \param timestampNS a pointer filled in with the frame's timestamp, or 0 on * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
* error. Can be NULL. * error. Can be NULL.
* \returns a new frame of video on success, NULL if none is currently * \returns a new frame of video on success, NULL if none is currently
@@ -458,8 +458,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam
* The app should not use the surface again after calling this function; * The app should not use the surface again after calling this function;
* assume the surface is freed and the pointer is invalid. * assume the surface is freed and the pointer is invalid.
* *
* \param camera opened camera device * \param camera opened camera device.
* \param frame The video frame surface to release. * \param frame the video frame surface to release.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -475,7 +475,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_S
* Use this function to shut down camera processing and close the camera * Use this function to shut down camera processing and close the camera
* device. * device.
* *
* \param camera opened camera device * \param camera opened camera device.
* *
* \threadsafety It is safe to call this function from any thread, but no * \threadsafety It is safe to call this function from any thread, but no
* thread may reference `device` once this function is called. * thread may reference `device` once this function is called.

32
include/SDL3/SDL_clipboard.h
View File

@@ -45,7 +45,7 @@ extern "C" {
/** /**
* Put UTF-8 text into the clipboard. * Put UTF-8 text into the clipboard.
* *
* \param text the text to store in the clipboard * \param text the text to store in the clipboard.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -89,7 +89,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
/** /**
* Put UTF-8 text into the primary selection. * Put UTF-8 text into the primary selection.
* *
* \param text the text to store in the primary selection * \param text the text to store in the primary selection.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -141,9 +141,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
* clipboard is cleared or new data is set. The clipboard is automatically * clipboard is cleared or new data is set. The clipboard is automatically
* cleared in SDL_Quit(). * cleared in SDL_Quit().
* *
* \param userdata A pointer to provided user data * \param userdata a pointer to provided user data.
* \param mime_type The requested mime-type * \param mime_type the requested mime-type.
* \param size A pointer filled in with the length of the returned data * \param size a pointer filled in with the length of the returned data.
* \returns a pointer to the data for the provided mime-type. Returning NULL * \returns a pointer to the data for the provided mime-type. Returning NULL
* or setting length to 0 will cause no data to be sent to the * or setting length to 0 will cause no data to be sent to the
* "receiver". It is up to the receiver to handle this. Essentially * "receiver". It is up to the receiver to handle this. Essentially
@@ -161,7 +161,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c
* Callback function that will be called when the clipboard is cleared, or new * Callback function that will be called when the clipboard is cleared, or new
* data is set. * data is set.
* *
* \param userdata A pointer to provided user data * \param userdata a pointer to provided user data.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -181,13 +181,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
* not need to be null terminated (e.g. you can directly copy a portion of a * not need to be null terminated (e.g. you can directly copy a portion of a
* document) * document)
* *
* \param callback A function pointer to the function that provides the * \param callback a function pointer to the function that provides the
* clipboard data * clipboard data.
* \param cleanup A function pointer to the function that cleans up the * \param cleanup a function pointer to the function that cleans up the
* clipboard data * clipboard data.
* \param userdata An opaque pointer that will be forwarded to the callbacks * \param userdata an opaque pointer that will be forwarded to the callbacks.
* \param mime_types A list of mime-types that are being offered * \param mime_types a list of mime-types that are being offered.
* \param num_mime_types The number of mime-types in the mime_types list * \param num_mime_types the number of mime-types in the mime_types list.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -217,8 +217,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
* The size of text data does not include the terminator, but the text is * The size of text data does not include the terminator, but the text is
* guaranteed to be null terminated. * guaranteed to be null terminated.
* *
* \param mime_type The mime type to read from the clipboard * \param mime_type the mime type to read from the clipboard.
* \param size A pointer filled in with the length of the returned data * \param size a pointer filled in with the length of the returned data.
* \returns the retrieved data buffer or NULL on failure; call SDL_GetError() * \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
* for more information. Caller must call SDL_free() on the returned * for more information. Caller must call SDL_free() on the returned
* pointer when done with it. * pointer when done with it.
@@ -233,7 +233,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetClipboardData(const char *mime_type, si
/** /**
* Query whether there is data in the clipboard for the provided mime type. * Query whether there is data in the clipboard for the provided mime type.
* *
* \param mime_type The mime type to check for data for * \param mime_type the mime type to check for data for.
* \returns SDL_TRUE if there exists data in clipboard for the provided mime * \returns SDL_TRUE if there exists data in clipboard for the provided mime
* type, SDL_FALSE if it does not. * type, SDL_FALSE if it does not.
* *

42
include/SDL3/SDL_dialog.h
View File

@@ -82,9 +82,9 @@ typedef struct SDL_DialogFileFilter
* no filter was selected or if the platform or method doesn't support * no filter was selected or if the platform or method doesn't support
* fetching the selected filter. * fetching the selected filter.
* *
* \param userdata An app-provided pointer, for the callback's use. * \param userdata an app-provided pointer, for the callback's use.
* \param filelist The file(s) chosen by the user. * \param filelist the file(s) chosen by the user.
* \param filter Index of the selected filter. * \param filter index of the selected filter.
* *
* \since This datatype is available since SDL 3.0.0. * \since This datatype is available since SDL 3.0.0.
* *
@@ -117,7 +117,7 @@ typedef void(SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const
* requires an event-handling loop. Apps that do not use SDL to handle events * requires an event-handling loop. Apps that do not use SDL to handle events
* should add a call to SDL_PumpEvents in their main loop. * should add a call to SDL_PumpEvents in their main loop.
* *
* \param callback An SDL_DialogFileCallback to be invoked when the user * \param callback an SDL_DialogFileCallback to be invoked when the user
* selects a file and accepts, or cancels the dialog, or an * selects a file and accepts, or cancels the dialog, or an
* error occurs. The first argument is a null-terminated list * error occurs. The first argument is a null-terminated list
* of C strings, representing the paths chosen by the user. * of C strings, representing the paths chosen by the user.
@@ -130,17 +130,17 @@ typedef void(SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const
* index of the terminating NULL filter) if no filter was * index of the terminating NULL filter) if no filter was
* chosen, or -1 if the platform does not support detecting * chosen, or -1 if the platform does not support detecting
* the selected filter. * the selected filter.
* \param userdata An optional pointer to pass extra data to the callback when * \param userdata an optional pointer to pass extra data to the callback when
* it will be invoked. * it will be invoked.
* \param window The window that the dialog should be modal for. May be NULL. * \param window the window that the dialog should be modal for. May be NULL.
* Not all platforms support this option. * Not all platforms support this option.
* \param filters A list of SDL_DialogFileFilter's. May be NULL. Not all * \param filters a list of SDL_DialogFileFilter's. May be NULL. Not all
* platforms support this option, and platforms that do support * platforms support this option, and platforms that do support
* it may allow the user to ignore the filters. * it may allow the user to ignore the filters.
* \param nfilters The number of filters. Ignored if filters is NULL. * \param nfilters the number of filters. Ignored if filters is NULL.
* \param default_location The default folder or file to start the dialog at. * \param default_location the default folder or file to start the dialog at.
* May be NULL. Not all platforms support this option. * May be NULL. Not all platforms support this option.
* \param allow_many If non-zero, the user will be allowed to select multiple * \param allow_many if non-zero, the user will be allowed to select multiple
* entries. Not all platforms support this option. * entries. Not all platforms support this option.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -174,7 +174,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c
* requires an event-handling loop. Apps that do not use SDL to handle events * requires an event-handling loop. Apps that do not use SDL to handle events
* should add a call to SDL_PumpEvents in their main loop. * should add a call to SDL_PumpEvents in their main loop.
* *
* \param callback An SDL_DialogFileCallback to be invoked when the user * \param callback an SDL_DialogFileCallback to be invoked when the user
* selects a file and accepts, or cancels the dialog, or an * selects a file and accepts, or cancels the dialog, or an
* error occurs. The first argument is a null-terminated list * error occurs. The first argument is a null-terminated list
* of C strings, representing the paths chosen by the user. * of C strings, representing the paths chosen by the user.
@@ -187,15 +187,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c
* index of the terminating NULL filter) if no filter was * index of the terminating NULL filter) if no filter was
* chosen, or -1 if the platform does not support detecting * chosen, or -1 if the platform does not support detecting
* the selected filter. * the selected filter.
* \param userdata An optional pointer to pass extra data to the callback when * \param userdata an optional pointer to pass extra data to the callback when
* it will be invoked. * it will be invoked.
* \param window The window that the dialog should be modal for. May be NULL. * \param window the window that the dialog should be modal for. May be NULL.
* Not all platforms support this option. * Not all platforms support this option.
* \param filters A list of SDL_DialogFileFilter's. May be NULL. Not all * \param filters a list of SDL_DialogFileFilter's. May be NULL. Not all
* platforms support this option, and platforms that do support * platforms support this option, and platforms that do support
* it may allow the user to ignore the filters. * it may allow the user to ignore the filters.
* \param nfilters The number of filters. Ignored if filters is NULL. * \param nfilters the number of filters. Ignored if filters is NULL.
* \param default_location The default folder or file to start the dialog at. * \param default_location the default folder or file to start the dialog at.
* May be NULL. Not all platforms support this option. * May be NULL. Not all platforms support this option.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -229,7 +229,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c
* requires an event-handling loop. Apps that do not use SDL to handle events * requires an event-handling loop. Apps that do not use SDL to handle events
* should add a call to SDL_PumpEvents in their main loop. * should add a call to SDL_PumpEvents in their main loop.
* *
* \param callback An SDL_DialogFileCallback to be invoked when the user * \param callback an SDL_DialogFileCallback to be invoked when the user
* selects a file and accepts, or cancels the dialog, or an * selects a file and accepts, or cancels the dialog, or an
* error occurs. The first argument is a null-terminated list * error occurs. The first argument is a null-terminated list
* of C strings, representing the paths chosen by the user. * of C strings, representing the paths chosen by the user.
@@ -238,13 +238,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c
* it can be fetched with SDL_GetError(). The second argument * it can be fetched with SDL_GetError(). The second argument
* is the userdata pointer passed to the function. The third * is the userdata pointer passed to the function. The third
* argument is always -1 for SDL_ShowOpenFolderDialog. * argument is always -1 for SDL_ShowOpenFolderDialog.
* \param userdata An optional pointer to pass extra data to the callback when * \param userdata an optional pointer to pass extra data to the callback when
* it will be invoked. * it will be invoked.
* \param window The window that the dialog should be modal for. May be NULL. * \param window the window that the dialog should be modal for. May be NULL.
* Not all platforms support this option. * Not all platforms support this option.
* \param default_location The default folder or file to start the dialog at. * \param default_location the default folder or file to start the dialog at.
* May be NULL. Not all platforms support this option. * May be NULL. Not all platforms support this option.
* \param allow_many If non-zero, the user will be allowed to select multiple * \param allow_many if non-zero, the user will be allowed to select multiple
* entries. Not all platforms support this option. * entries. Not all platforms support this option.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

8
include/SDL3/SDL_error.h
View File

@@ -53,9 +53,9 @@ extern "C" {
* } * }
* ``` * ```
* *
* \param fmt a printf()-style message format string * \param fmt a printf()-style message format string.
* \param ... additional parameters matching % tokens in the `fmt` string, if * \param ... additional parameters matching % tokens in the `fmt` string, if
* any * any.
* \returns always -1. * \returns always -1.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -70,7 +70,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char
* *
* This function does not do any memory allocation. * This function does not do any memory allocation.
* *
* \returns -1 * \returns -1.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -115,7 +115,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetError(void);
/** /**
* Clear any previous error message for this thread. * Clear any previous error message for this thread.
* *
* \returns 0 * \returns 0.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

54
include/SDL3/SDL_events.h
View File

@@ -958,7 +958,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
* If you need to check for a range of event types, use SDL_HasEvents() * If you need to check for a range of event types, use SDL_HasEvents()
* instead. * instead.
* *
* \param type the type of event to be queried; see SDL_EventType for details * \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 * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
* events matching `type` are not present. * events matching `type` are not present.
* *
@@ -975,9 +975,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
* If you need to check for a single event type, use SDL_HasEvent() instead. * 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 * \param minType the low end of event type to be queried, inclusive; see
* SDL_EventType for details * SDL_EventType for details.
* \param maxType the high end of event type to be queried, inclusive; see * \param maxType the high end of event type to be queried, inclusive; see
* SDL_EventType for details * SDL_EventType for details.
* \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
* present, or SDL_FALSE if not. * present, or SDL_FALSE if not.
* *
@@ -1005,7 +1005,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxTyp
* use SDL_PeepEvents() to remove and clean up those events before calling * use SDL_PeepEvents() to remove and clean up those events before calling
* this function. * this function.
* *
* \param type the type of event to be cleared; see SDL_EventType for details * \param type the type of event to be cleared; see SDL_EventType for details.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1028,9 +1028,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
* on the main thread immediately before the flush call. * on the main thread immediately before the flush call.
* *
* \param minType the low end of event type to be cleared, inclusive; see * \param minType the low end of event type to be cleared, inclusive; see
* SDL_EventType for details * SDL_EventType for details.
* \param maxType the high end of event type to be cleared, inclusive; see * \param maxType the high end of event type to be cleared, inclusive; see
* SDL_EventType for details * SDL_EventType for details.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1071,7 +1071,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType)
* ``` * ```
* *
* \param event the SDL_Event structure to be filled with the next event from * \param event the SDL_Event structure to be filled with the next event from
* the queue, or NULL * the queue, or NULL.
* \returns SDL_TRUE if this got an event or SDL_FALSE if there are none * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none
* available. * available.
* *
@@ -1093,7 +1093,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event);
* this function in the thread that initialized the video subsystem. * this function in the thread that initialized the video subsystem.
* *
* \param event the SDL_Event structure to be filled in with the next event * \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL * from the queue, or NULL.
* \returns SDL_TRUE on success or SDL_FALSE if there was an error while * \returns SDL_TRUE on success or SDL_FALSE if there was an error while
* waiting for events; call SDL_GetError() for more information. * waiting for events; call SDL_GetError() for more information.
* *
@@ -1119,9 +1119,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event);
* system scheduling. * system scheduling.
* *
* \param event the SDL_Event structure to be filled in with the next event * \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL * from the queue, or NULL.
* \param timeoutMS the maximum number of milliseconds to wait for the next * \param timeoutMS the maximum number of milliseconds to wait for the next
* available event * available event.
* \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed
* without any events available. * without any events available.
* *
@@ -1154,7 +1154,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint
* get an event type that does not conflict with other code that also wants * get an event type that does not conflict with other code that also wants
* its own custom event types. * its own custom event types.
* *
* \param event the SDL_Event to be added to the queue * \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 * \returns 1 on success, 0 if the event was filtered, or a negative error
* code on failure; call SDL_GetError() for more information. A * code on failure; call SDL_GetError() for more information. A
* common reason for error is the event queue being full. * common reason for error is the event queue being full.
@@ -1171,8 +1171,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
* A function pointer used for callbacks that watch the event queue. * A function pointer used for callbacks that watch the event queue.
* *
* \param userdata what was passed as `userdata` to SDL_SetEventFilter() or * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
* SDL_AddEventWatch, etc * SDL_AddEventWatch, etc.
* \param event the event that triggered the callback * \param event the event that triggered the callback.
* \returns 1 to permit event to be added to the queue, and 0 to disallow it. * \returns 1 to permit event to be added to the queue, and 0 to disallow it.
* When used with SDL_AddEventWatch, the return value is ignored. * When used with SDL_AddEventWatch, the return value is ignored.
* *
@@ -1218,8 +1218,8 @@ typedef int (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
* the event filter, but events pushed onto the queue with SDL_PeepEvents() do * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
* not. * not.
* *
* \param filter An SDL_EventFilter function to call when an event happens * \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter` * \param userdata a pointer that is passed to `filter`.
* *
* \threadsafety SDL may call the filter callback at any time from any thread; * \threadsafety SDL may call the filter callback at any time from any thread;
* the application is responsible for locking resources the * the application is responsible for locking resources the
@@ -1241,9 +1241,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void
* This function can be used to "chain" filters, by saving the existing 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. * before replacing it with a function that will call that saved filter.
* *
* \param filter the current callback function will be stored here * \param filter the current callback function will be stored here.
* \param userdata the pointer that is passed to the current event filter will * \param userdata the pointer that is passed to the current event filter will
* be stored here * be stored here.
* \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1271,7 +1271,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter,
* through SDL_PeepEvents(). * through SDL_PeepEvents().
* *
* \param filter an SDL_EventFilter function to call when an event happens. * \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter` * \param userdata a pointer that is passed to `filter`.
* \returns 0 on success, or a negative error code on failure; call * \returns 0 on success, or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1290,8 +1290,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *
* This function takes the same input as SDL_AddEventWatch() to identify and * This function takes the same input as SDL_AddEventWatch() to identify and
* delete the corresponding callback. * delete the corresponding callback.
* *
* \param filter the function originally passed to SDL_AddEventWatch() * \param filter the function originally passed to SDL_AddEventWatch().
* \param userdata the pointer originally passed to SDL_AddEventWatch() * \param userdata the pointer originally passed to SDL_AddEventWatch().
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1307,8 +1307,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, void
* this function does not change the filter permanently, it only uses the * this function does not change the filter permanently, it only uses the
* supplied filter until this function returns. * supplied filter until this function returns.
* *
* \param filter the SDL_EventFilter function to call when an event happens * \param filter the SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter` * \param userdata a pointer that is passed to `filter`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1320,8 +1320,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *
/** /**
* Set the state of processing events by type. * Set the state of processing events by type.
* *
* \param type the type of event; see SDL_EventType for details * \param type the type of event; see SDL_EventType for details.
* \param enabled whether to process the event or not * \param enabled whether to process the event or not.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1332,7 +1332,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabl
/** /**
* Query the state of processing events by type. * Query the state of processing events by type.
* *
* \param type the type of event; see SDL_EventType for details * \param type the type of event; see SDL_EventType for details.
* \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise. * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1345,7 +1345,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type);
* Allocate a set of user-defined events, and return the beginning event * Allocate a set of user-defined events, and return the beginning event
* number for that set of events. * number for that set of events.
* *
* \param numevents the number of events to be allocated * \param numevents the number of events to be allocated.
* \returns the beginning event number, or 0 if numevents is invalid or if * \returns the beginning event number, or 0 if numevents is invalid or if
* there are not enough user-defined events left. * there are not enough user-defined events left.
* *
@@ -1361,7 +1361,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
* You can use this to allocate memory for user events that will be * You can use this to allocate memory for user events that will be
* automatically freed after the event is processed. * automatically freed after the event is processed.
* *
* \param size the amount of memory to allocate * \param size the amount of memory to allocate.
* \returns a pointer to the memory allocated or NULL on failure; call * \returns a pointer to the memory allocated or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

26
include/SDL3/SDL_filesystem.h
View File

@@ -127,8 +127,8 @@ extern SDL_DECLSPEC char *SDLCALL SDL_GetBasePath(void);
* The pointer returned is owned by the caller. Please call SDL_free() on the * The pointer returned is owned by the caller. Please call SDL_free() on the
* pointer when done with it. * pointer when done with it.
* *
* \param org the name of your organization * \param org the name of your organization.
* \param app the name of your application * \param app the name of your application.
* \returns a UTF-8 string of the user directory in platform-dependent * \returns a UTF-8 string of the user directory in platform-dependent
* notation. NULL if there's a problem (creating directory failed, * notation. NULL if there's a problem (creating directory failed,
* etc.). * etc.).
@@ -232,7 +232,7 @@ typedef enum SDL_Folder
* *
* If NULL is returned, the error may be obtained with SDL_GetError(). * If NULL is returned, the error may be obtained with SDL_GetError().
* *
* \param folder The type of folder to find * \param folder the type of folder to find.
* \returns either a null-terminated C string containing the full path to the * \returns either a null-terminated C string containing the full path to the
* folder, or NULL if an error happened. * folder, or NULL if an error happened.
* *
@@ -277,7 +277,7 @@ typedef Uint32 SDL_GlobFlags;
/** /**
* Create a directory. * Create a directory.
* *
* \param path the path of the directory to create * \param path the path of the directory to create.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -298,9 +298,9 @@ typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char
* callback, called once for each directory entry, until all results have been * callback, called once for each directory entry, until all results have been
* provided or the callback returns <= 0. * provided or the callback returns <= 0.
* *
* \param path the path of the directory to enumerate * \param path the path of the directory to enumerate.
* \param callback a function that is called for each entry in the directory * \param callback a function that is called for each entry in the directory.
* \param userdata a pointer that is passed to `callback` * \param userdata a pointer that is passed to `callback`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -311,7 +311,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnumerateDirectory(const char *path, SDL_Enu
/** /**
* Remove a file or an empty directory. * Remove a file or an empty directory.
* *
* \param path the path of the directory to enumerate * \param path the path of the directory to enumerate.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -322,8 +322,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RemovePath(const char *path);
/** /**
* Rename a file or directory. * Rename a file or directory.
* *
* \param oldpath the old path * \param oldpath the old path.
* \param newpath the new path * \param newpath the new path.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -334,9 +334,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenamePath(const char *oldpath, const char *
/** /**
* Get information about a filesystem path. * Get information about a filesystem path.
* *
* \param path the path to query * \param path the path to query.
* \param info a pointer filled in with information about the path, or NULL to * \param info a pointer filled in with information about the path, or NULL to
* check for the existence of a file * check for the existence of a file.
* \returns 0 on success or a negative error code if the file doesn't exist, * \returns 0 on success or a negative error code if the file doesn't exist,
* or another failure; call SDL_GetError() for more information. * or another failure; call SDL_GetError() for more information.
* *
@@ -363,7 +363,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *
* *
* You must free the returned pointer with SDL_free() when done with it. * You must free the returned pointer with SDL_free() when done with it.
* *
* \param path the path of the directory to enumerate * \param path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be * \param pattern the pattern that files in the directory must match. Can be
* NULL. * NULL.
* \param flags `SDL_GLOB_*` bitflags that affect this search. * \param flags `SDL_GLOB_*` bitflags that affect this search.

220
include/SDL3/SDL_gamepad.h
View File

@@ -299,7 +299,7 @@ typedef struct SDL_GamepadBinding
* "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" * "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 mapping the mapping string * \param mapping the mapping string.
* \returns 1 if a new mapping is added, 0 if an existing mapping is updated, * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
* -1 on error; call SDL_GetError() for more information. * -1 on error; call SDL_GetError() for more information.
* *
@@ -329,9 +329,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
* processing it, so take this into consideration if you are in a memory * processing it, so take this into consideration if you are in a memory
* constrained environment. * constrained environment.
* *
* \param src the data stream for the mappings to be added * \param src the data stream for the mappings to be added.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error * even in the case of an error.
* \returns the number of mappings added or -1 on error; call SDL_GetError() * \returns the number of mappings added or -1 on error; call SDL_GetError()
* for more information. * for more information.
* *
@@ -359,7 +359,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
* specified will be ignored (i.e. mappings for Linux will be ignored in * specified will be ignored (i.e. mappings for Linux will be ignored in
* Windows, etc). * Windows, etc).
* *
* \param file the mappings file to load * \param file the mappings file to load.
* \returns the number of mappings added or -1 on error; call SDL_GetError() * \returns the number of mappings added or -1 on error; call SDL_GetError()
* for more information. * for more information.
* *
@@ -406,7 +406,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count);
* *
* The returned string must be freed with SDL_free(). * The returned string must be freed with SDL_free().
* *
* \param guid a structure containing the GUID for which a mapping is desired * \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 * \returns a mapping string or NULL on error; call SDL_GetError() for more
* information. * information.
* *
@@ -424,7 +424,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID
* *
* Details about mappings are discussed with SDL_AddGamepadMapping(). * Details about mappings are discussed with SDL_AddGamepadMapping().
* *
* \param gamepad the gamepad you want to get the current mapping for * \param gamepad the gamepad you want to get the current mapping for.
* \returns a string that has the gamepad's mapping or NULL if no mapping is * \returns a string that has the gamepad's mapping or NULL if no mapping is
* available; call SDL_GetError() for more information. * available; call SDL_GetError() for more information.
* *
@@ -442,9 +442,9 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
* *
* Details about mappings are discussed with SDL_AddGamepadMapping(). * Details about mappings are discussed with SDL_AddGamepadMapping().
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \param mapping the mapping to use for this device, or NULL to clear the * \param mapping the mapping to use for this device, or NULL to clear the
* mapping * mapping.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -469,7 +469,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
/** /**
* Get a list of currently connected gamepads. * Get a list of currently connected gamepads.
* *
* \param count a pointer filled in with the number of gamepads returned * \param count a pointer filled in with the number of gamepads returned.
* \returns a 0 terminated array of joystick instance IDs which should be * \returns a 0 terminated array of joystick instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details. * more details.
@@ -484,7 +484,7 @@ extern SDL_DECLSPEC SDL_JoystickID *SDLCALL SDL_GetGamepads(int *count);
/** /**
* Check if the given joystick is supported by the gamepad interface. * Check if the given joystick is supported by the gamepad interface.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns SDL_TRUE if the given joystick is supported by the gamepad * \returns SDL_TRUE if the given joystick is supported by the gamepad
* interface, SDL_FALSE if it isn't or it's an invalid index. * interface, SDL_FALSE if it isn't or it's an invalid index.
* *
@@ -502,7 +502,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the name of the selected gamepad. If no name can be found, this * \returns the name of the selected gamepad. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
@@ -520,7 +520,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstanceName(SDL_JoystickI
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the path of the selected gamepad. If no path can be found, this * \returns the path of the selected gamepad. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
@@ -536,8 +536,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstancePath(SDL_JoystickI
* *
* This can be called before any gamepads are opened. * This can be called before any gamepads are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the player index of a gamepad, or -1 if it's not available * \returns the player index of a gamepad, or -1 if it's not available.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -551,9 +551,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadInstancePlayerIndex(SDL_JoystickID
* *
* This can be called before any gamepads are opened. * This can be called before any gamepads are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the GUID of the selected gamepad. If called on an invalid index, * \returns the GUID of the selected gamepad. If called on an invalid index,
* this function returns a zero GUID * this function returns a zero GUID.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -569,9 +569,9 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_Joys
* This can be called before any gamepads are opened. If the vendor ID isn't * This can be called before any gamepads are opened. If the vendor ID isn't
* available this function returns 0. * available this function returns 0.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the USB vendor ID of the selected gamepad. If called on an invalid * \returns the USB vendor ID of the selected gamepad. If called on an invalid
* index, this function returns zero * index, this function returns zero.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -586,9 +586,9 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceVendor(SDL_JoystickID i
* This can be called before any gamepads are opened. If the product ID isn't * This can be called before any gamepads are opened. If the product ID isn't
* available this function returns 0. * available this function returns 0.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the USB product ID of the selected gamepad. If called on an * \returns the USB product ID of the selected gamepad. If called on an
* invalid index, this function returns zero * invalid index, this function returns zero.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -603,9 +603,9 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProduct(SDL_JoystickID
* This can be called before any gamepads are opened. If the product version * This can be called before any gamepads are opened. If the product version
* isn't available this function returns 0. * isn't available this function returns 0.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the product version of the selected gamepad. If called on an * \returns the product version of the selected gamepad. If called on an
* invalid index, this function returns zero * invalid index, this function returns zero.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -619,7 +619,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProductVersion(SDL_Joys
* *
* This can be called before any gamepads are opened. * This can be called before any gamepads are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the gamepad type. * \returns the gamepad type.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -635,7 +635,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadInstanceType(SDL_Joyst
* *
* This can be called before any gamepads are opened. * This can be called before any gamepads are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the gamepad type. * \returns the gamepad type.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -651,7 +651,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadInstanceType(SDL_J
* *
* This can be called before any gamepads are opened. * This can be called before any gamepads are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL if * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* no mapping is available. * no mapping is available.
* *
@@ -665,7 +665,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_GetGamepadInstanceMapping(SDL_JoystickID i
/** /**
* Open a gamepad for use. * Open a gamepad for use.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns a gamepad identifier or NULL if an error occurred; call * \returns a gamepad identifier or NULL if an error occurred; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -680,7 +680,7 @@ extern SDL_DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(SDL_JoystickID instance
* Get the SDL_Gamepad associated with a joystick instance ID, if it has been * Get the SDL_Gamepad associated with a joystick instance ID, if it has been
* opened. * opened.
* *
* \param instance_id the joystick instance ID of the gamepad * \param instance_id the joystick instance ID of the gamepad.
* \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been
* opened yet; call SDL_GetError() for more information. * opened yet; call SDL_GetError() for more information.
* *
@@ -691,7 +691,7 @@ extern SDL_DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromInstanceID(SDL_Joysti
/** /**
* Get the SDL_Gamepad associated with a player index. * Get the SDL_Gamepad associated with a player index.
* *
* \param player_index the player index, which different from the instance ID * \param player_index the player index, which different from the instance ID.
* \returns the SDL_Gamepad associated with a player index. * \returns the SDL_Gamepad associated with a player index.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -720,7 +720,7 @@ extern SDL_DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromPlayerIndex(int playe
* simple trigger rumble * simple trigger rumble
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad().
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -741,7 +741,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa
* Get the instance ID of an opened gamepad. * Get the instance ID of an opened gamepad.
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad().
* \returns the instance ID of the specified gamepad on success or 0 on * \returns the instance ID of the specified gamepad on success or 0 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -755,7 +755,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadInstanceID(SDL_Gamepad
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad().
* \returns the implementation dependent name for the gamepad, or NULL if * \returns the implementation dependent name for the gamepad, or NULL if
* there is no name or the identifier passed is invalid. * there is no name or the identifier passed is invalid.
* *
@@ -771,7 +771,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad)
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad().
* \returns the implementation dependent path for the gamepad, or NULL if * \returns the implementation dependent path for the gamepad, or NULL if
* there is no path or the identifier passed is invalid. * there is no path or the identifier passed is invalid.
* *
@@ -825,7 +825,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad);
* Set the player index of an opened gamepad. * Set the player index of an opened gamepad.
* *
* \param gamepad the gamepad object to adjust. * \param gamepad the gamepad object to adjust.
* \param player_index Player index to assign to this gamepad, or -1 to clear * \param player_index player index to assign to this gamepad, or -1 to clear
* the player index and turn off player LEDs. * the player index and turn off player LEDs.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@@ -953,7 +953,7 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *
* Check if a gamepad has been opened and is currently connected. * Check if a gamepad has been opened and is currently connected.
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad().
* \returns SDL_TRUE if the gamepad has been opened and is currently * \returns SDL_TRUE if the gamepad has been opened and is currently
* connected, or SDL_FALSE if not. * connected, or SDL_FALSE if not.
* *
@@ -973,7 +973,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
* SDL_CloseJoystick() on it, for example, since doing so will likely cause * SDL_CloseJoystick() on it, for example, since doing so will likely cause
* SDL to crash. * SDL to crash.
* *
* \param gamepad the gamepad object that you want to get a joystick from * \param gamepad the gamepad object that you want to get a joystick from.
* \returns an SDL_Joystick object; call SDL_GetError() for more information. * \returns an SDL_Joystick object; call SDL_GetError() for more information.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -986,7 +986,7 @@ extern SDL_DECLSPEC SDL_Joystick *SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *ga
* If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
* and check the state of the gamepad when you want gamepad information. * and check the state of the gamepad when you want gamepad information.
* *
* \param enabled whether to process gamepad events or not * \param enabled whether to process gamepad events or not.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1013,8 +1013,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);
/** /**
* Get the SDL joystick layer bindings for a gamepad. * Get the SDL joystick layer bindings for a gamepad.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param count a pointer filled in with the number of bindings returned * \param count a pointer filled in with the number of bindings returned.
* \returns a NULL terminated array of pointers to bindings which should be * \returns a NULL terminated array of pointers to bindings which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details. * more details.
@@ -1042,7 +1042,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
* You do not normally need to call this function unless you are parsing * You do not normally need to call this function unless you are parsing
* SDL_Gamepad mappings in your own code. * SDL_Gamepad mappings in your own code.
* *
* \param str string representing a SDL_GamepadType type * \param str string representing a SDL_GamepadType type.
* \returns the SDL_GamepadType enum corresponding to the input string, or * \returns the SDL_GamepadType enum corresponding to the input string, or
* `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found.
* *
@@ -1057,7 +1057,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param type an enum value for a given SDL_GamepadType * \param type an enum value for a given SDL_GamepadType.
* \returns a string for the given type, or NULL if an invalid type is * \returns a string for the given type, or NULL if an invalid type is
* specified. The string returned is of the format used by * specified. The string returned is of the format used by
* SDL_Gamepad mapping strings. * SDL_Gamepad mapping strings.
@@ -1080,7 +1080,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadStringForType(SDL_GamepadT
* `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`, * `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`,
* respectively. * respectively.
* *
* \param str string representing a SDL_Gamepad axis * \param str string representing a SDL_Gamepad axis.
* \returns the SDL_GamepadAxis enum corresponding to the input string, or * \returns the SDL_GamepadAxis enum corresponding to the input string, or
* `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
* *
@@ -1095,7 +1095,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param axis an enum value for a given SDL_GamepadAxis * \param axis an enum value for a given SDL_GamepadAxis.
* \returns a string for the given axis, or NULL if an invalid axis is * \returns a string for the given axis, or NULL if an invalid axis is
* specified. The string returned is of the format used by * specified. The string returned is of the format used by
* SDL_Gamepad mapping strings. * SDL_Gamepad mapping strings.
@@ -1112,8 +1112,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad
* This merely reports whether the gamepad's mapping defined this axis, as * This merely reports whether the gamepad's mapping defined this axis, as
* that is all the information SDL has about the physical device. * that is all the information SDL has about the physical device.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param axis an axis enum value (an SDL_GamepadAxis value) * \param axis an axis enum value (an SDL_GamepadAxis value).
* \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise. * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1135,8 +1135,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SD
* return a negative value. Note that this differs from the value reported by * return a negative value. Note that this differs from the value reported by
* the lower-level SDL_GetJoystickAxis(), which normally uses the full range. * the lower-level SDL_GetJoystickAxis(), which normally uses the full range.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param axis an axis index (one of the SDL_GamepadAxis values) * \param axis an axis index (one of the SDL_GamepadAxis values).
* \returns axis state (including 0) on success or 0 (also) on failure; call * \returns axis state (including 0) on success or 0 (also) on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1155,7 +1155,7 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_
* You do not normally need to call this function unless you are parsing * You do not normally need to call this function unless you are parsing
* SDL_Gamepad mappings in your own code. * SDL_Gamepad mappings in your own code.
* *
* \param str string representing a SDL_Gamepad axis * \param str string representing a SDL_Gamepad axis.
* \returns the SDL_GamepadButton enum corresponding to the input string, or * \returns the SDL_GamepadButton enum corresponding to the input string, or
* `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found.
* *
@@ -1170,7 +1170,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param button an enum value for a given SDL_GamepadButton * \param button an enum value for a given SDL_GamepadButton.
* \returns a string for the given button, or NULL if an invalid button is * \returns a string for the given button, or NULL if an invalid button is
* specified. The string returned is of the format used by * specified. The string returned is of the format used by
* SDL_Gamepad mapping strings. * SDL_Gamepad mapping strings.
@@ -1187,8 +1187,8 @@ extern SDL_DECLSPEC const char* SDLCALL SDL_GetGamepadStringForButton(SDL_Gamepa
* This merely reports whether the gamepad's mapping defined this button, as * This merely reports whether the gamepad's mapping defined this button, as
* that is all the information SDL has about the physical device. * that is all the information SDL has about the physical device.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param button a button enum value (an SDL_GamepadButton value) * \param button a button enum value (an SDL_GamepadButton value).
* \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise. * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1200,8 +1200,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad,
/** /**
* Get the current state of a button on a gamepad. * Get the current state of a button on a gamepad.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param button a button index (one of the SDL_GamepadButton values) * \param button a button index (one of the SDL_GamepadButton values).
* \returns 1 for pressed state or 0 for not pressed state or error; call * \returns 1 for pressed state or 0 for not pressed state or error; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1215,9 +1215,9 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL
/** /**
* Get the label of a button on a gamepad. * Get the label of a button on a gamepad.
* *
* \param type the type of gamepad to check * \param type the type of gamepad to check.
* \param button a button index (one of the SDL_GamepadButton values) * \param button a button index (one of the SDL_GamepadButton values).
* \returns the SDL_GamepadButtonLabel enum corresponding to the button label * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1228,9 +1228,9 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT
/** /**
* Get the label of a button on a gamepad. * Get the label of a button on a gamepad.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param button a button index (one of the SDL_GamepadButton values) * \param button a button index (one of the SDL_GamepadButton values).
* \returns the SDL_GamepadButtonLabel enum corresponding to the button label * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1241,8 +1241,8 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL
/** /**
* Get the number of touchpads on a gamepad. * Get the number of touchpads on a gamepad.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \returns number of touchpads * \returns number of touchpads.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1254,9 +1254,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad)
* Get the number of supported simultaneous fingers on a touchpad on a game * Get the number of supported simultaneous fingers on a touchpad on a game
* gamepad. * gamepad.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param touchpad a touchpad * \param touchpad a touchpad.
* \returns number of supported simultaneous fingers * \returns number of supported simultaneous fingers.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1268,15 +1268,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga
/** /**
* Get the current state of a finger on a touchpad on a gamepad. * Get the current state of a finger on a touchpad on a gamepad.
* *
* \param gamepad a gamepad * \param gamepad a gamepad.
* \param touchpad a touchpad * \param touchpad a touchpad.
* \param finger a finger * \param finger a finger.
* \param state filled with state * \param state filled with state.
* \param x filled with x position, normalized 0 to 1, with the origin in the * \param x filled with x position, normalized 0 to 1, with the origin in the
* upper left * upper left.
* \param y filled with y position, normalized 0 to 1, with the origin in the * \param y filled with y position, normalized 0 to 1, with the origin in the
* upper left * upper left.
* \param pressure filled with pressure value * \param pressure filled with pressure value.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1289,8 +1289,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepa
/** /**
* Return whether a gamepad has a particular sensor. * Return whether a gamepad has a particular sensor.
* *
* \param gamepad The gamepad to query * \param gamepad the gamepad to query.
* \param type The type of sensor to query * \param type the type of sensor to query.
* \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1304,9 +1304,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad,
/** /**
* Set whether data reporting for a gamepad sensor is enabled. * Set whether data reporting for a gamepad sensor is enabled.
* *
* \param gamepad The gamepad to update * \param gamepad the gamepad to update.
* \param type The type of sensor to enable/disable * \param type the type of sensor to enable/disable.
* \param enabled Whether data reporting should be enabled * \param enabled whether data reporting should be enabled.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1320,8 +1320,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad
/** /**
* Query whether sensor data reporting is enabled for a gamepad. * Query whether sensor data reporting is enabled for a gamepad.
* *
* \param gamepad The gamepad to query * \param gamepad the gamepad to query.
* \param type The type of sensor to query * \param type the type of sensor to query.
* \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1333,8 +1333,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamep
/** /**
* Get the data rate (number of events per second) of a gamepad sensor. * Get the data rate (number of events per second) of a gamepad sensor.
* *
* \param gamepad The gamepad to query * \param gamepad the gamepad to query.
* \param type The type of sensor to query * \param type the type of sensor to query.
* \returns the data rate, or 0.0f if the data rate is not available. * \returns the data rate, or 0.0f if the data rate is not available.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1347,10 +1347,10 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game
* The number of values and interpretation of the data is sensor dependent. * The number of values and interpretation of the data is sensor dependent.
* See SDL_sensor.h for the details for each type of sensor. * See SDL_sensor.h for the details for each type of sensor.
* *
* \param gamepad The gamepad to query * \param gamepad the gamepad to query.
* \param type The type of sensor to query * \param type the type of sensor to query.
* \param data A pointer filled with the current sensor state * \param data a pointer filled with the current sensor state.
* \param num_values The number of values to write to data * \param num_values the number of values to write to data.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1367,13 +1367,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, S
* This function requires you to process SDL events or call * This function requires you to process SDL events or call
* SDL_UpdateJoysticks() to update rumble state. * SDL_UpdateJoysticks() to update rumble state.
* *
* \param gamepad The gamepad to vibrate * \param gamepad the gamepad to vibrate.
* \param low_frequency_rumble The intensity of the low frequency (left) * \param low_frequency_rumble the intensity of the low frequency (left)
* rumble motor, from 0 to 0xFFFF * rumble motor, from 0 to 0xFFFF.
* \param high_frequency_rumble The intensity of the high frequency (right) * \param high_frequency_rumble the intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF * rumble motor, from 0 to 0xFFFF.
* \param duration_ms The duration of the rumble effect, in milliseconds * \param duration_ms the duration of the rumble effect, in milliseconds.
* \returns 0, or -1 if rumble isn't supported on this gamepad * \returns 0, or -1 if rumble isn't supported on this gamepad.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -1392,12 +1392,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 l
* This function requires you to process SDL events or call * This function requires you to process SDL events or call
* SDL_UpdateJoysticks() to update rumble state. * SDL_UpdateJoysticks() to update rumble state.
* *
* \param gamepad The gamepad to vibrate * \param gamepad the gamepad to vibrate.
* \param left_rumble The intensity of the left trigger rumble motor, from 0 * \param left_rumble the intensity of the left trigger rumble motor, from 0
* to 0xFFFF * to 0xFFFF.
* \param right_rumble The intensity of the right trigger rumble motor, from 0 * \param right_rumble the intensity of the right trigger rumble motor, from 0
* to 0xFFFF * to 0xFFFF.
* \param duration_ms The duration of the rumble effect, in milliseconds * \param duration_ms the duration of the rumble effect, in milliseconds.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1416,10 +1416,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad,
* For gamepads with a single color LED, the maximum of the RGB values will be * For gamepads with a single color LED, the maximum of the RGB values will be
* used as the LED brightness. * used as the LED brightness.
* *
* \param gamepad The gamepad to update * \param gamepad the gamepad to update.
* \param red The intensity of the red LED * \param red the intensity of the red LED.
* \param green The intensity of the green LED * \param green the intensity of the green LED.
* \param blue The intensity of the blue LED * \param blue the intensity of the blue LED.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1430,9 +1430,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 re
/** /**
* Send a gamepad specific effect packet. * Send a gamepad specific effect packet.
* *
* \param gamepad The gamepad to affect * \param gamepad the gamepad to affect.
* \param data The data to send to the gamepad * \param data the data to send to the gamepad.
* \param size The size of the data to send to the gamepad * \param size the size of the data to send to the gamepad.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1444,7 +1444,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, cons
* Close a gamepad previously opened with SDL_OpenGamepad(). * Close a gamepad previously opened with SDL_OpenGamepad().
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad().
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1458,9 +1458,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param gamepad the gamepad to query * \param gamepad the gamepad to query.
* \param button a button on the gamepad * \param button a button on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found * \returns the sfSymbolsName or NULL if the name can't be found.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1473,9 +1473,9 @@ extern SDL_DECLSPEC const char* SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButto
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param gamepad the gamepad to query * \param gamepad the gamepad to query.
* \param axis an axis on the gamepad * \param axis an axis on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found * \returns the sfSymbolsName or NULL if the name can't be found.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

8
include/SDL3/SDL_guid.h
View File

@@ -68,9 +68,9 @@ typedef struct SDL_GUID {
* *
* You should supply at least 33 bytes for pszGUID. * You should supply at least 33 bytes for pszGUID.
* *
* \param guid the SDL_GUID you wish to convert to string * \param guid the SDL_GUID you wish to convert to string.
* \param pszGUID buffer in which to write the ASCII string * \param pszGUID buffer in which to write the ASCII string.
* \param cbGUID the size of pszGUID * \param cbGUID the size of pszGUID.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -87,7 +87,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, i
* an invalid GUID, the function will silently succeed, but the GUID generated * an invalid GUID, the function will silently succeed, but the GUID generated
* will not be useful. * will not be useful.
* *
* \param pchGUID string containing an ASCII representation of a GUID * \param pchGUID string containing an ASCII representation of a GUID.
* \returns a SDL_GUID structure. * \returns a SDL_GUID structure.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

86
include/SDL3/SDL_haptic.h
View File

@@ -932,7 +932,8 @@ typedef Uint32 SDL_HapticID;
/** /**
* Get a list of currently connected haptic devices. * Get a list of currently connected haptic devices.
* *
* \param count a pointer filled in with the number of haptic devices returned * \param count a pointer filled in with the number of haptic devices
* returned.
* \returns a 0 terminated array of haptic device instance IDs which should be * \returns a 0 terminated array of haptic device instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details. * more details.
@@ -950,7 +951,7 @@ extern SDL_DECLSPEC SDL_HapticID *SDLCALL SDL_GetHaptics(int *count);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the haptic device instance ID * \param instance_id the haptic device instance ID.
* \returns the name of the selected haptic device. If no name can be found, * \returns the name of the selected haptic device. If no name can be found,
* this function returns NULL; call SDL_GetError() for more * this function returns NULL; call SDL_GetError() for more
* information. * information.
@@ -972,7 +973,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetHapticInstanceName(SDL_HapticID i
* autocenter will be disabled. To modify these values use SDL_SetHapticGain() * autocenter will be disabled. To modify these values use SDL_SetHapticGain()
* and SDL_SetHapticAutocenter(). * and SDL_SetHapticAutocenter().
* *
* \param instance_id the haptic device instance ID * \param instance_id the haptic device instance ID.
* \returns the device identifier or NULL on failure; call SDL_GetError() for * \returns the device identifier or NULL on failure; call SDL_GetError() for
* more information. * more information.
* *
@@ -991,7 +992,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id)
/** /**
* Get the SDL_Haptic associated with an instance ID, if it has been opened. * Get the SDL_Haptic associated with an instance ID, if it has been opened.
* *
* \param instance_id the instance ID to get the SDL_Haptic for * \param instance_id the instance ID to get the SDL_Haptic for.
* \returns an SDL_Haptic on success or NULL on failure or if it hasn't been * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been
* opened yet; call SDL_GetError() for more information. * opened yet; call SDL_GetError() for more information.
* *
@@ -1002,7 +1003,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_GetHapticFromInstanceID(SDL_HapticID
/** /**
* Get the instance ID of an opened haptic device. * Get the instance ID of an opened haptic device.
* *
* \param haptic the SDL_Haptic device to query * \param haptic the SDL_Haptic device to query.
* \returns the instance ID of the specified haptic device on success or 0 on * \returns the instance ID of the specified haptic device on success or 0 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -1015,7 +1016,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticInstanceID(SDL_Haptic *hap
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param haptic the SDL_Haptic obtained from SDL_OpenJoystick() * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick().
* \returns the name of the selected haptic device. If no name can be found, * \returns the name of the selected haptic device. If no name can be found,
* this function returns NULL; call SDL_GetError() for more * this function returns NULL; call SDL_GetError() for more
* information. * information.
@@ -1053,7 +1054,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHapticFromMouse(void);
/** /**
* Query if a joystick has haptic features. * Query if a joystick has haptic features.
* *
* \param joystick the SDL_Joystick to test for haptic capabilities * \param joystick the SDL_Joystick to test for haptic capabilities.
* \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't. * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1073,7 +1074,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick
* device will also get unallocated and you'll be unable to use force feedback * device will also get unallocated and you'll be unable to use force feedback
* on that device. * on that device.
* *
* \param joystick the SDL_Joystick to create a haptic device from * \param joystick the SDL_Joystick to create a haptic device from.
* \returns a valid haptic device identifier on success or NULL on failure; * \returns a valid haptic device identifier on success or NULL on failure;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -1087,7 +1088,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick
/** /**
* Close a haptic device previously opened with SDL_OpenHaptic(). * Close a haptic device previously opened with SDL_OpenHaptic().
* *
* \param haptic the SDL_Haptic device to close * \param haptic the SDL_Haptic device to close.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1102,7 +1103,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic);
* approximation. Always check to see if your created effect was actually * approximation. Always check to see if your created effect was actually
* created and do not rely solely on SDL_GetMaxHapticEffects(). * created and do not rely solely on SDL_GetMaxHapticEffects().
* *
* \param haptic the SDL_Haptic device to query * \param haptic the SDL_Haptic device to query.
* \returns the number of effects the haptic device can store or a negative * \returns the number of effects the haptic device can store or a negative
* error code on failure; call SDL_GetError() for more information. * error code on failure; call SDL_GetError() for more information.
* *
@@ -1118,7 +1119,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic);
* *
* This is not supported on all platforms, but will always return a value. * This is not supported on all platforms, but will always return a value.
* *
* \param haptic the SDL_Haptic device to query maximum playing effects * \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 * \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 * or a negative error code on failure; call SDL_GetError() for more
* information. * information.
@@ -1133,7 +1134,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti
/** /**
* Get the haptic device's supported features in bitwise manner. * Get the haptic device's supported features in bitwise manner.
* *
* \param haptic the SDL_Haptic device to query * \param haptic the SDL_Haptic device to query.
* \returns a list of supported haptic features in bitwise manner (OR'd), or 0 * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
* on failure; call SDL_GetError() for more information. * on failure; call SDL_GetError() for more information.
* *
@@ -1150,7 +1151,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic);
* The number of haptic axes might be useful if working with the * The number of haptic axes might be useful if working with the
* SDL_HapticDirection effect. * SDL_HapticDirection effect.
* *
* \param haptic the SDL_Haptic device to query * \param haptic the SDL_Haptic device to query.
* \returns the number of axes on success or a negative error code on failure; * \returns the number of axes on success or a negative error code on failure;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -1161,8 +1162,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic);
/** /**
* Check to see if an effect is supported by a haptic device. * Check to see if an effect is supported by a haptic device.
* *
* \param haptic the SDL_Haptic device to query * \param haptic the SDL_Haptic device to query.
* \param effect the desired effect to query * \param effect the desired effect to query.
* \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1175,9 +1176,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti
/** /**
* Create a new haptic effect on a specified device. * Create a new haptic effect on a specified device.
* *
* \param haptic an SDL_Haptic device to create the effect on * \param haptic an SDL_Haptic device to create the effect on.
* \param effect an SDL_HapticEffect structure containing the properties of * \param effect an SDL_HapticEffect structure containing the properties of
* the effect to create * the effect to create.
* \returns the ID of the effect on success or a negative error code on * \returns the ID of the effect on success or a negative error code on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -1197,10 +1198,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const
* start playing from the start. You also cannot change the type either when * start playing from the start. You also cannot change the type either when
* running SDL_UpdateHapticEffect(). * running SDL_UpdateHapticEffect().
* *
* \param haptic the SDL_Haptic device that has the effect * \param haptic the SDL_Haptic device that has the effect.
* \param effect the identifier of the effect to update * \param effect the identifier of the effect to update.
* \param data an SDL_HapticEffect structure containing the new effect * \param data an SDL_HapticEffect structure containing the new effect
* properties to use * properties to use.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1220,10 +1221,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int e
* set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
* instead. * instead.
* *
* \param haptic the SDL_Haptic device to run the effect on * \param haptic the SDL_Haptic device to run the effect on.
* \param effect the ID of the haptic effect to run * \param effect the ID of the haptic effect to run.
* \param iterations the number of iterations to run the effect; use * \param iterations the number of iterations to run the effect; use
* `SDL_HAPTIC_INFINITY` to repeat forever * `SDL_HAPTIC_INFINITY` to repeat forever.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1238,8 +1239,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effe
/** /**
* Stop 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 haptic the SDL_Haptic device to stop the effect on.
* \param effect the ID of the haptic effect to stop * \param effect the ID of the haptic effect to stop.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1256,8 +1257,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int eff
* This will stop the effect if it's running. Effects are automatically * This will stop the effect if it's running. Effects are automatically
* destroyed when the device is closed. * destroyed when the device is closed.
* *
* \param haptic the SDL_Haptic device to destroy the effect on * \param haptic the SDL_Haptic device to destroy the effect on.
* \param effect the ID of the haptic effect to destroy * \param effect the ID of the haptic effect to destroy.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1270,8 +1271,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int
* *
* Device must support the SDL_HAPTIC_STATUS feature. * Device must support the SDL_HAPTIC_STATUS feature.
* *
* \param haptic the SDL_Haptic device to query for the effect status on * \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 * \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 * \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. * code on failure; call SDL_GetError() for more information.
* *
@@ -1289,8 +1290,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, in
* SDL_SetHapticGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the * SDL_SetHapticGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
* maximum. * maximum.
* *
* \param haptic the SDL_Haptic device to set the gain on * \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) * \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 * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1308,8 +1310,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain);
* *
* Device must support the SDL_HAPTIC_AUTOCENTER feature. * Device must support the SDL_HAPTIC_AUTOCENTER feature.
* *
* \param haptic the SDL_Haptic device to set autocentering on * \param haptic the SDL_Haptic device to set autocentering on.
* \param autocenter value to set autocenter to (0-100) * \param autocenter value to set autocenter to (0-100).
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1328,7 +1330,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int
* Do not modify the effects nor add new ones while the device is paused. That * Do not modify the effects nor add new ones while the device is paused. That
* can cause all sorts of weird errors. * can cause all sorts of weird errors.
* *
* \param haptic the SDL_Haptic device to pause * \param haptic the SDL_Haptic device to pause.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1343,7 +1345,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic);
* *
* Call to unpause after SDL_PauseHaptic(). * Call to unpause after SDL_PauseHaptic().
* *
* \param haptic the SDL_Haptic device to unpause * \param haptic the SDL_Haptic device to unpause.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1356,7 +1358,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic);
/** /**
* Stop all the currently playing effects on a haptic device. * Stop all the currently playing effects on a haptic device.
* *
* \param haptic the SDL_Haptic device to stop * \param haptic the SDL_Haptic device to stop.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1370,7 +1372,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic);
/** /**
* Check whether rumble is supported on a haptic device. * Check whether rumble is supported on a haptic device.
* *
* \param haptic haptic device to check for rumble support * \param haptic haptic device to check for rumble support.
* \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1382,7 +1384,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *hapti
/** /**
* Initialize a haptic device for simple rumble playback. * Initialize a haptic device for simple rumble playback.
* *
* \param haptic the haptic device to initialize for simple rumble playback * \param haptic the haptic device to initialize for simple rumble playback.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1397,9 +1399,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic);
/** /**
* Run a simple rumble effect on a haptic device. * Run a simple rumble effect on a haptic device.
* *
* \param haptic the haptic device to play the rumble effect on * \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 strength strength of the rumble to play as a 0-1 float value.
* \param length length of the rumble to play in milliseconds * \param length length of the rumble to play in milliseconds.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1413,7 +1415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float s
/** /**
* Stop the simple rumble on a haptic device. * Stop the simple rumble on a haptic device.
* *
* \param haptic the haptic device to stop the rumble effect on * \param haptic the haptic device to stop the rumble effect on.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

90
include/SDL3/SDL_hidapi.h
View File

@@ -225,9 +225,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
* or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS * or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS
* can be set to "0" to enumerate all HID devices. * can be set to "0" to enumerate all HID devices.
* *
* \param vendor_id The Vendor ID (VID) of the types of device to open, or 0 * \param vendor_id the Vendor ID (VID) of the types of device to open, or 0
* to match any vendor. * to match any vendor.
* \param product_id The Product ID (PID) of the types of device to open, or 0 * \param product_id the Product ID (PID) of the types of device to open, or 0
* to match any product. * to match any product.
* \returns a pointer to a linked list of type SDL_hid_device_info, containing * \returns a pointer to a linked list of type SDL_hid_device_info, containing
* information about the HID devices attached to the system, or NULL * information about the HID devices attached to the system, or NULL
@@ -245,7 +245,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned sho
* *
* This function frees a linked list created by SDL_hid_enumerate(). * This function frees a linked list created by SDL_hid_enumerate().
* *
* \param devs Pointer to a list of struct_device returned from * \param devs pointer to a list of struct_device returned from
* SDL_hid_enumerate(). * SDL_hid_enumerate().
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -259,9 +259,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d
* If `serial_number` is NULL, the first device with the specified VID and PID * If `serial_number` is NULL, the first device with the specified VID and PID
* is opened. * is opened.
* *
* \param vendor_id The Vendor ID (VID) of the device to open. * \param vendor_id the Vendor ID (VID) of the device to open.
* \param product_id The Product ID (PID) of the device to open. * \param product_id the Product ID (PID) of the device to open.
* \param serial_number The Serial Number of the device to open (Optionally * \param serial_number the Serial Number of the device to open (Optionally
* NULL). * NULL).
* \returns a pointer to a SDL_hid_device object on success or NULL on * \returns a pointer to a SDL_hid_device object on success or NULL on
* failure. * failure.
@@ -276,7 +276,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_
* The path name be determined by calling SDL_hid_enumerate(), or a * The path name be determined by calling SDL_hid_enumerate(), or a
* platform-specific path name can be used (eg: /dev/hidraw0 on Linux). * platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
* *
* \param path The path name of the device to open * \param path the path name of the device to open.
* \returns a pointer to a SDL_hid_device object on success or NULL on * \returns a pointer to a SDL_hid_device object on success or NULL on
* failure. * failure.
* *
@@ -300,10 +300,10 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path)
* exists. If it does not, it will send the data through the Control Endpoint * exists. If it does not, it will send the data through the Control Endpoint
* (Endpoint 0). * (Endpoint 0).
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param data The data to send, including the report number as the first * \param data the data to send, including the report number as the first
* byte. * byte.
* \param length The length in bytes of the data to send. * \param length the length in bytes of the data to send.
* \returns the actual number of bytes written and -1 on error. * \returns the actual number of bytes written and -1 on error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -317,9 +317,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne
* The first byte will contain the Report number if the device uses numbered * The first byte will contain the Report number if the device uses numbered
* reports. * reports.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into. * \param data a buffer to put the read data into.
* \param length The number of bytes to read. For devices with multiple * \param length the number of bytes to read. For devices with multiple
* reports, make sure to read an extra byte for the report * reports, make sure to read an extra byte for the report
* number. * number.
* \param milliseconds timeout in milliseconds or -1 for blocking wait. * \param milliseconds timeout in milliseconds or -1 for blocking wait.
@@ -338,9 +338,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign
* The first byte will contain the Report number if the device uses numbered * The first byte will contain the Report number if the device uses numbered
* reports. * reports.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into. * \param data a buffer to put the read data into.
* \param length The number of bytes to read. For devices with multiple * \param length the number of bytes to read. For devices with multiple
* reports, make sure to read an extra byte for the report * reports, make sure to read an extra byte for the report
* number. * number.
* \returns the actual number of bytes read and -1 on error. If no packet was * \returns the actual number of bytes read and -1 on error. If no packet was
@@ -360,7 +360,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char
* *
* Nonblocking can be turned on and off at any time. * Nonblocking can be turned on and off at any time.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param nonblock enable or not the nonblocking reads - 1 to enable * \param nonblock enable or not the nonblocking reads - 1 to enable
* nonblocking - 0 to disable nonblocking. * nonblocking - 0 to disable nonblocking.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
@@ -383,10 +383,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int
* devices which do not use numbered reports), followed by the report data (16 * devices which do not use numbered reports), followed by the report data (16
* bytes). In this example, the length passed in would be 17. * bytes). In this example, the length passed in would be 17.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param data The data to send, including the report number as the first * \param data the data to send, including the report number as the first
* byte. * byte.
* \param length The length in bytes of the data to send, including the report * \param length the length in bytes of the data to send, including the report
* number. * number.
* \returns the actual number of bytes written and -1 on error. * \returns the actual number of bytes written and -1 on error.
* *
@@ -402,12 +402,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev,
* first byte will still contain the Report ID, and the report data will start * first byte will still contain the Report ID, and the report data will start
* in data[1]. * in data[1].
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into, including the Report ID. * \param data a buffer to put the read data into, including the Report ID.
* Set the first byte of `data` to the Report ID of the report to * Set the first byte of `data` to the Report ID of the report to
* be read, or set it to zero if your device does not use numbered * be read, or set it to zero if your device does not use numbered
* reports. * reports.
* \param length The number of bytes to read, including an extra byte for the * \param length the number of bytes to read, including an extra byte for the
* report ID. The buffer can be longer than the actual report. * report ID. The buffer can be longer than the actual report.
* \returns the number of bytes read plus one for the report ID (which is * \returns the number of bytes read plus one for the report ID (which is
* still in the first byte), or -1 on error. * still in the first byte), or -1 on error.
@@ -424,12 +424,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev,
* first byte will still contain the Report ID, and the report data will start * first byte will still contain the Report ID, and the report data will start
* in data[1]. * in data[1].
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into, including the Report ID. * \param data a buffer to put the read data into, including the Report ID.
* Set the first byte of `data` to the Report ID of the report to * Set the first byte of `data` to the Report ID of the report to
* be read, or set it to zero if your device does not use numbered * be read, or set it to zero if your device does not use numbered
* reports. * reports.
* \param length The number of bytes to read, including an extra byte for the * \param length the number of bytes to read, including an extra byte for the
* report ID. The buffer can be longer than the actual report. * report ID. The buffer can be longer than the actual report.
* \returns the number of bytes read plus one for the report ID (which is * \returns the number of bytes read plus one for the report ID (which is
* still in the first byte), or -1 on error. * still in the first byte), or -1 on error.
@@ -441,7 +441,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, un
/** /**
* Close a HID device. * Close a HID device.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -452,9 +452,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev);
/** /**
* Get The Manufacturer String from a HID device. * Get The Manufacturer String from a HID device.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into. * \param string a wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -465,9 +465,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *
/** /**
* Get The Product String from a HID device. * Get The Product String from a HID device.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into. * \param string a wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -478,9 +478,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev,
/** /**
* Get The Serial Number String from a HID device. * Get The Serial Number String from a HID device.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into. * \param string a wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -491,10 +491,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device
/** /**
* Get a string from a HID device, based on its string index. * Get a string from a HID device, based on its string index.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param string_index The index of the string to get. * \param string_index the index of the string to get.
* \param string A wide string buffer to put the data into. * \param string a wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t. * \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -505,7 +505,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev,
/** /**
* Get the device info from a HID device. * Get the device info from a HID device.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \returns a pointer to the SDL_hid_device_info for this hid_device, or NULL * \returns a pointer to the SDL_hid_device_info for this hid_device, or NULL
* in the case of failure; call SDL_GetError() for more information. * in the case of failure; call SDL_GetError() for more information.
* This struct is valid until the device is closed with * This struct is valid until the device is closed with
@@ -521,9 +521,9 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi
* User has to provide a preallocated buffer where descriptor will be copied * User has to provide a preallocated buffer where descriptor will be copied
* to. The recommended size for a preallocated buffer is 4096 bytes. * to. The recommended size for a preallocated buffer is 4096 bytes.
* *
* \param dev A device handle returned from SDL_hid_open(). * \param dev a device handle returned from SDL_hid_open().
* \param buf The buffer to copy descriptor into. * \param buf the buffer to copy descriptor into.
* \param buf_size The size of the buffer in bytes. * \param buf_size the size of the buffer in bytes.
* \returns the number of bytes actually copied, or -1 on error; call * \returns the number of bytes actually copied, or -1 on error; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -534,7 +534,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *de
/** /**
* Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers.
* *
* \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */

42
include/SDL3/SDL_hints.h
View File

@@ -3755,9 +3755,9 @@ typedef enum SDL_HintPriority
* value. Hints will replace existing hints of their priority and lower. * value. Hints will replace existing hints of their priority and lower.
* Environment variables are considered to have override priority. * Environment variables are considered to have override priority.
* *
* \param name the hint to set * \param name the hint to set.
* \param value the value of the hint variable * \param value the value of the hint variable.
* \param priority the SDL_HintPriority level for the hint * \param priority the SDL_HintPriority level for the hint.
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -3777,8 +3777,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
* variable that takes precedence. You can use SDL_SetHintWithPriority() to * variable that takes precedence. You can use SDL_SetHintWithPriority() to
* set the hint with override priority instead. * set the hint with override priority instead.
* *
* \param name the hint to set * \param name the hint to set.
* \param value the value of the hint variable * \param value the value of the hint variable.
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -3797,7 +3797,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
* the environment isn't set. Callbacks will be called normally with this * the environment isn't set. Callbacks will be called normally with this
* change. * change.
* *
* \param name the hint to set * \param name the hint to set.
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -3825,7 +3825,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param name the hint to query * \param name the hint to query.
* \returns the string value of a hint or NULL if the hint isn't set. * \returns the string value of a hint or NULL if the hint isn't set.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -3838,8 +3838,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
/** /**
* Get the boolean value of a hint variable. * Get the boolean value of a hint variable.
* *
* \param name the name of the hint to get the boolean value from * \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 * \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 * \returns the boolean value of a hint or the provided default value if the
* hint does not exist. * hint does not exist.
* *
@@ -3853,10 +3853,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo
/** /**
* 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 userdata what was passed as `userdata` to SDL_AddHintCallback().
* \param name what was passed as `name` to SDL_AddHintCallback() * \param name what was passed as `name` to SDL_AddHintCallback().
* \param oldValue the previous hint value * \param oldValue the previous hint value.
* \param newValue the new value hint is to be set to * \param newValue the new value hint is to be set to.
* *
* \since This datatype is available since SDL 3.0.0. * \since This datatype is available since SDL 3.0.0.
*/ */
@@ -3865,10 +3865,10 @@ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const
/** /**
* Add a function to watch a particular hint. * Add a function to watch a particular hint.
* *
* \param name the hint to watch * \param name the hint to watch.
* \param callback An SDL_HintCallback function that will be called when the * \param callback an SDL_HintCallback function that will be called when the
* hint value changes * hint value changes.
* \param userdata a pointer to pass to the callback function * \param userdata a pointer to pass to the callback function.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -3886,10 +3886,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddHintCallback(const char *name,
/** /**
* Remove a function watching a particular hint. * Remove a function watching a particular hint.
* *
* \param name the hint being watched * \param name the hint being watched.
* \param callback An SDL_HintCallback function that will be called when the * \param callback an SDL_HintCallback function that will be called when the
* hint value changes * hint value changes.
* \param userdata a pointer being passed to the callback function * \param userdata a pointer being passed to the callback function.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

2
include/SDL3/SDL_init.h
View File

@@ -105,7 +105,7 @@ typedef Uint32 SDL_InitFlags;
* call SDL_Quit() to force shutdown). If a subsystem is already loaded then * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
* this call will increase the ref-count and return. * this call will increase the ref-count and return.
* *
* \param flags subsystem initialization flags * \param flags subsystem initialization flags.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

172
include/SDL3/SDL_iostream.h
View File

@@ -221,7 +221,7 @@ typedef struct SDL_IOStream SDL_IOStream;
* the filesystem. If SDL used some other method to access the filesystem, * the filesystem. If SDL used some other method to access the filesystem,
* this property will not be set. * this property will not be set.
* *
* \param file a UTF-8 string representing the filename to open * \param file a UTF-8 string representing the filename to open.
* \param mode an ASCII string representing the mode to be used for opening * \param mode an ASCII string representing the mode to be used for opening
* the file. * the file.
* \returns a pointer to the SDL_IOStream structure that is created, or NULL * \returns a pointer to the SDL_IOStream structure that is created, or NULL
@@ -256,8 +256,8 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromFile(const char *file, const
* buffer, you should use SDL_IOFromConstMem() with a read-only buffer of * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of
* memory instead. * memory instead.
* *
* \param mem a pointer to a buffer to feed an SDL_IOStream stream * \param mem a pointer to a buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes * \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure, or NULL if it fails; * \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -289,8 +289,8 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromMem(void *mem, size_t size);
* If you need to write to a memory buffer, you should use SDL_IOFromMem() * If you need to write to a memory buffer, you should use SDL_IOFromMem()
* with a writable buffer of memory instead. * with a writable buffer of memory instead.
* *
* \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes * \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure, or NULL if it fails; * \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -351,8 +351,8 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void);
* This function makes a copy of `iface` and the caller does not need to keep * This function makes a copy of `iface` and the caller does not need to keep
* this data around after this call. * this data around after this call.
* *
* \param iface The function pointers that implement this SDL_IOStream. * \param iface the function pointers that implement this SDL_IOStream.
* \param userdata The app-controlled pointer that is passed to iface's * \param userdata the app-controlled pointer that is passed to iface's
* functions when called. * functions when called.
* \returns a pointer to the allocated memory on success, or NULL on failure; * \returns a pointer to the allocated memory on success, or NULL on failure;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
@@ -377,7 +377,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_OpenIO(const SDL_IOStreamInterface
* Note that if this fails to flush the stream to disk, this function reports * Note that if this fails to flush the stream to disk, this function reports
* an error, but the SDL_IOStream is still invalid once this function returns. * an error, but the SDL_IOStream is still invalid once this function returns.
* *
* \param context SDL_IOStream structure to close * \param context SDL_IOStream structure to close.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -390,7 +390,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CloseIO(SDL_IOStream *context);
/** /**
* Get the properties associated with an SDL_IOStream. * Get the properties associated with an SDL_IOStream.
* *
* \param context a pointer to an SDL_IOStream structure * \param context a pointer to an SDL_IOStream structure.
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -425,7 +425,7 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context);
/** /**
* Use this function to get the size of the data stream in an SDL_IOStream. * Use this function to get the size of the data stream in an SDL_IOStream.
* *
* \param context the SDL_IOStream to get the size of the data stream from * \param context the SDL_IOStream to get the size of the data stream from.
* \returns the size of the data stream in the SDL_IOStream on success or a * \returns the size of the data stream in the SDL_IOStream on success or a
* negative error code on failure; call SDL_GetError() for more * negative error code on failure; call SDL_GetError() for more
* information. * information.
@@ -447,11 +447,11 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context);
* *
* If this stream can not seek, it will return -1. * If this stream can not seek, it will return -1.
* *
* \param context a pointer to an SDL_IOStream structure * \param context a pointer to an SDL_IOStream structure.
* \param offset an offset in bytes, relative to `whence` location; can be * \param offset an offset in bytes, relative to `whence` location; can be
* negative * negative.
* \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`,
* `SDL_IO_SEEK_END` * `SDL_IO_SEEK_END`.
* \returns the final offset in the data stream after the seek or a negative * \returns the final offset in the data stream after the seek or a negative
* error code on failure; call SDL_GetError() for more information. * error code on failure; call SDL_GetError() for more information.
* *
@@ -469,7 +469,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs
* simplify application development. * simplify application development.
* *
* \param context an SDL_IOStream data stream object from which to get the * \param context an SDL_IOStream data stream object from which to get the
* current offset * current offset.
* \returns the current offset in the stream, or -1 if the information can not * \returns the current offset in the stream, or -1 if the information can not
* be determined. * be determined.
* *
@@ -488,8 +488,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
* determine if there was an error or all data was read, call * determine if there was an error or all data was read, call
* SDL_GetIOStatus(). * SDL_GetIOStatus().
* *
* \param context a pointer to an SDL_IOStream structure * \param context a pointer to an SDL_IOStream structure.
* \param ptr a pointer to a buffer to read data into * \param ptr a pointer to a buffer to read data into.
* \param size the number of bytes to read from the data source. * \param size the number of bytes to read from the data source.
* \returns the number of bytes read, or 0 on end of file or other error. * \returns the number of bytes read, or 0 on end of file or other error.
* *
@@ -514,9 +514,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr,
* recoverable, such as a non-blocking write that can simply be retried later, * recoverable, such as a non-blocking write that can simply be retried later,
* or a fatal error. * or a fatal error.
* *
* \param context a pointer to an SDL_IOStream structure * \param context a pointer to an SDL_IOStream structure.
* \param ptr a pointer to a buffer containing data to write * \param ptr a pointer to a buffer containing data to write.
* \param size the number of bytes to write * \param size the number of bytes to write.
* \returns the number of bytes written, which will be less than `size` on * \returns the number of bytes written, which will be less than `size` on
* error; call SDL_GetError() for more information. * error; call SDL_GetError() for more information.
* *
@@ -534,10 +534,10 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void
* *
* This function does formatted printing to the stream. * This function does formatted printing to the stream.
* *
* \param context a pointer to an SDL_IOStream structure * \param context a pointer to an SDL_IOStream structure.
* \param fmt a printf() style format string * \param fmt a printf() style format string.
* \param ... additional parameters matching % tokens in the `fmt` string, if * \param ... additional parameters matching % tokens in the `fmt` string, if
* any * any.
* \returns the number of bytes written, or 0 on error; call SDL_GetError() * \returns the number of bytes written, or 0 on error; call SDL_GetError()
* for more information. * for more information.
* *
@@ -553,9 +553,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT
* *
* This function does formatted printing to the stream. * This function does formatted printing to the stream.
* *
* \param context a pointer to an SDL_IOStream structure * \param context a pointer to an SDL_IOStream structure.
* \param fmt a printf() style format string * \param fmt a printf() style format string.
* \param ap a variable argument list * \param ap a variable argument list.
* \returns the number of bytes written, or 0 on error; call SDL_GetError() * \returns the number of bytes written, or 0 on error; call SDL_GetError()
* for more information. * for more information.
* *
@@ -575,10 +575,10 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN
* *
* The data should be freed with SDL_free(). * The data should be freed with SDL_free().
* *
* \param src the SDL_IOStream to read all available data from * \param src the SDL_IOStream to read all available data from.
* \param datasize if not NULL, will store the number of bytes read * \param datasize if not NULL, will store the number of bytes read.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error * even in the case of an error.
* \returns the data, or NULL if there was an error. * \returns the data, or NULL if there was an error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -596,8 +596,8 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *dat
* *
* The data should be freed with SDL_free(). * The data should be freed with SDL_free().
* *
* \param file the path to read all available data from * \param file the path to read all available data from.
* \param datasize if not NULL, will store the number of bytes read * \param datasize if not NULL, will store the number of bytes read.
* \returns the data, or NULL if there was an error. * \returns the data, or NULL if there was an error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -616,8 +616,8 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasiz
/** /**
* Use this function to read a byte from an SDL_IOStream. * Use this function to read a byte from an SDL_IOStream.
* *
* \param src the SDL_IOStream to read from * \param src the SDL_IOStream to read from.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
* for more information. * for more information.
* *
@@ -628,8 +628,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value)
/** /**
* Use this function to read a signed byte from an SDL_IOStream. * Use this function to read a signed byte from an SDL_IOStream.
* *
* \param src the SDL_IOStream to read from * \param src the SDL_IOStream to read from.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
* for more information. * for more information.
* *
@@ -644,8 +644,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value)
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -660,8 +660,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -676,8 +676,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -692,8 +692,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -708,8 +708,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -724,8 +724,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -740,8 +740,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -756,8 +756,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -772,8 +772,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -788,8 +788,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -804,8 +804,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -820,8 +820,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va
* SDL byteswaps the data only if necessary, so the data returned will be in * SDL byteswaps the data only if necessary, so the data returned will be in
* the native byte order. * the native byte order.
* *
* \param src the stream from which to read data * \param src the stream from which to read data.
* \param value a pointer filled in with the data read * \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -840,8 +840,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va
/** /**
* Use this function to write a byte to an SDL_IOStream. * Use this function to write a byte to an SDL_IOStream.
* *
* \param dst the SDL_IOStream to write to * \param dst the SDL_IOStream to write to.
* \param value the byte value to write * \param value the byte value to write.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -852,8 +852,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value)
/** /**
* Use this function to write a signed byte to an SDL_IOStream. * Use this function to write a signed byte to an SDL_IOStream.
* *
* \param dst the SDL_IOStream to write to * \param dst the SDL_IOStream to write to.
* \param value the byte value to write * \param value the byte value to write.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -869,8 +869,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value)
* specifies native format, and the data written will be in little-endian * specifies native format, and the data written will be in little-endian
* format. * format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -886,8 +886,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va
* specifies native format, and the data written will be in little-endian * specifies native format, and the data written will be in little-endian
* format. * format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -902,8 +902,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va
* SDL byteswaps the data only if necessary, so the application always * SDL byteswaps the data only if necessary, so the application always
* specifies native format, and the data written will be in big-endian format. * specifies native format, and the data written will be in big-endian format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -918,8 +918,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va
* SDL byteswaps the data only if necessary, so the application always * SDL byteswaps the data only if necessary, so the application always
* specifies native format, and the data written will be in big-endian format. * specifies native format, and the data written will be in big-endian format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -935,8 +935,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va
* specifies native format, and the data written will be in little-endian * specifies native format, and the data written will be in little-endian
* format. * format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -952,8 +952,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va
* specifies native format, and the data written will be in little-endian * specifies native format, and the data written will be in little-endian
* format. * format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -968,8 +968,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va
* SDL byteswaps the data only if necessary, so the application always * SDL byteswaps the data only if necessary, so the application always
* specifies native format, and the data written will be in big-endian format. * specifies native format, and the data written will be in big-endian format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -984,8 +984,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va
* SDL byteswaps the data only if necessary, so the application always * SDL byteswaps the data only if necessary, so the application always
* specifies native format, and the data written will be in big-endian format. * specifies native format, and the data written will be in big-endian format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1001,8 +1001,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va
* specifies native format, and the data written will be in little-endian * specifies native format, and the data written will be in little-endian
* format. * format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1018,8 +1018,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va
* specifies native format, and the data written will be in little-endian * specifies native format, and the data written will be in little-endian
* format. * format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1034,8 +1034,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va
* SDL byteswaps the data only if necessary, so the application always * SDL byteswaps the data only if necessary, so the application always
* specifies native format, and the data written will be in big-endian format. * specifies native format, and the data written will be in big-endian format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1050,8 +1050,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va
* SDL byteswaps the data only if necessary, so the application always * SDL byteswaps the data only if necessary, so the application always
* specifies native format, and the data written will be in big-endian format. * specifies native format, and the data written will be in big-endian format.
* *
* \param dst the stream to which data will be written * \param dst the stream to which data will be written.
* \param value the data to be written, in native format * \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

184
include/SDL3/SDL_joystick.h
View File

@@ -210,7 +210,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
/** /**
* Get a list of currently connected joysticks. * Get a list of currently connected joysticks.
* *
* \param count a pointer filled in with the number of joysticks returned * \param count a pointer filled in with the number of joysticks returned.
* \returns a 0 terminated array of joystick instance IDs which should be * \returns a 0 terminated array of joystick instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details. * more details.
@@ -229,7 +229,7 @@ extern SDL_DECLSPEC SDL_JoystickID *SDLCALL SDL_GetJoysticks(int *count);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the name of the selected joystick. If no name can be found, this * \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
@@ -247,7 +247,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickInstanceName(SDL_Joystick
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the path of the selected joystick. If no path can be found, this * \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
@@ -263,8 +263,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickInstancePath(SDL_Joystick
* *
* This can be called before any joysticks are opened. * This can be called before any joysticks are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the player index of a joystick, or -1 if it's not available * \returns the player index of a joystick, or -1 if it's not available.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -278,7 +278,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickInstancePlayerIndex(SDL_JoystickI
* *
* This can be called before any joysticks are opened. * This can be called before any joysticks are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the GUID of the selected joystick. If called with an invalid * \returns the GUID of the selected joystick. If called with an invalid
* instance_id, this function returns a zero GUID. * instance_id, this function returns a zero GUID.
* *
@@ -295,7 +295,7 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickInstanceGUID(SDL_Joy
* This can be called before any joysticks are opened. If the vendor ID isn't * This can be called before any joysticks are opened. If the vendor ID isn't
* available this function returns 0. * available this function returns 0.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the USB vendor ID of the selected joystick. If called with an * \returns the USB vendor ID of the selected joystick. If called with an
* invalid instance_id, this function returns 0. * invalid instance_id, this function returns 0.
* *
@@ -312,7 +312,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceVendor(SDL_JoystickID
* This can be called before any joysticks are opened. If the product ID isn't * This can be called before any joysticks are opened. If the product ID isn't
* available this function returns 0. * available this function returns 0.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the USB product ID of the selected joystick. If called with an * \returns the USB product ID of the selected joystick. If called with an
* invalid instance_id, this function returns 0. * invalid instance_id, this function returns 0.
* *
@@ -329,7 +329,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceProduct(SDL_JoystickID
* This can be called before any joysticks are opened. If the product version * This can be called before any joysticks are opened. If the product version
* isn't available this function returns 0. * isn't available this function returns 0.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the product version of the selected joystick. If called with an * \returns the product version of the selected joystick. If called with an
* invalid instance_id, this function returns 0. * invalid instance_id, this function returns 0.
* *
@@ -345,7 +345,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceProductVersion(SDL_Joy
* *
* This can be called before any joysticks are opened. * This can be called before any joysticks are opened.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns the SDL_JoystickType of the selected joystick. If called with an * \returns the SDL_JoystickType of the selected joystick. If called with an
* invalid instance_id, this function returns * invalid instance_id, this function returns
* `SDL_JOYSTICK_TYPE_UNKNOWN`. * `SDL_JOYSTICK_TYPE_UNKNOWN`.
@@ -363,7 +363,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickInstanceType(SDL_Joy
* The joystick subsystem must be initialized before a joystick can be opened * The joystick subsystem must be initialized before a joystick can be opened
* for use. * for use.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns a joystick identifier or NULL if an error occurred; call * \returns a joystick identifier or NULL if an error occurred; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -376,7 +376,7 @@ extern SDL_DECLSPEC SDL_Joystick *SDLCALL SDL_OpenJoystick(SDL_JoystickID instan
/** /**
* Get the SDL_Joystick associated with an instance ID, if it has been opened. * Get the SDL_Joystick associated with an instance ID, if it has been opened.
* *
* \param instance_id the instance ID to get the SDL_Joystick for * \param instance_id the instance ID to get the SDL_Joystick for.
* \returns an SDL_Joystick on success or NULL on failure or if it hasn't been * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been
* opened yet; call SDL_GetError() for more information. * opened yet; call SDL_GetError() for more information.
* *
@@ -387,7 +387,7 @@ extern SDL_DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromInstanceID(SDL_Joys
/** /**
* Get 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 * \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() * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
* for more information. * for more information.
* *
@@ -469,7 +469,7 @@ typedef struct SDL_VirtualJoystickDesc
/** /**
* Attach a new virtual joystick. * Attach a new virtual joystick.
* *
* \param desc Joystick description * \param desc joystick description.
* \returns the joystick instance ID, or 0 if an error occurred; call * \returns the joystick instance ID, or 0 if an error occurred; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -483,7 +483,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V
* Detach a virtual joystick. * Detach a virtual joystick.
* *
* \param instance_id the joystick instance ID, previously returned from * \param instance_id the joystick instance ID, previously returned from
* SDL_AttachVirtualJoystick() * SDL_AttachVirtualJoystick().
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -496,7 +496,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instanc
/** /**
* Query whether or not a joystick is virtual. * Query whether or not a joystick is virtual.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID.
* \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -598,12 +598,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick
* update. * update.
* \param finger the index of the finger on the touchpad to set. * \param finger the index of the finger on the touchpad to set.
* \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the * \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the
* finger is released * finger is released.
* \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1,
* with the origin in the upper left * with the origin in the upper left.
* \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1,
* with the origin in the upper left * with the origin in the upper left.
* \param pressure the pressure of the finger * \param pressure the pressure of the finger.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -623,9 +623,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joy
* \param joystick the virtual joystick on which to set state. * \param joystick the virtual joystick on which to set state.
* \param type the type of the sensor on the virtual joystick to update. * \param type the type of the sensor on the virtual joystick to update.
* \param sensor_timestamp a 64-bit timestamp in nanoseconds associated with * \param sensor_timestamp a 64-bit timestamp in nanoseconds associated with
* the sensor reading * the sensor reading.
* \param data the data associated with the sensor reading * \param data the data associated with the sensor reading.
* \param num_values the number of values pointed to by `data` * \param num_values the number of values pointed to by `data`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -649,7 +649,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *
* - `SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this joystick has * - `SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this joystick has
* simple trigger rumble * simple trigger rumble
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -671,7 +671,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the name of the selected joystick. If no name can be found, this * \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
@@ -686,7 +686,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickName(SDL_Joystick *joysti
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the path of the selected joystick. If no path can be found, this * \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
@@ -702,7 +702,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickPath(SDL_Joystick *joysti
* For XInput controllers this returns the XInput user index. Many joysticks * For XInput controllers this returns the XInput user index. Many joysticks
* will not be able to supply this information. * will not be able to supply this information.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the player index, or -1 if it's not available. * \returns the player index, or -1 if it's not available.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -714,8 +714,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic
/** /**
* Set the player index of an opened joystick. * Set the player index of an opened joystick.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \param player_index Player index to assign to this joystick, or -1 to clear * \param player_index player index to assign to this joystick, or -1 to clear
* the player index and turn off player LEDs. * the player index and turn off player LEDs.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@@ -731,7 +731,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystic
* *
* This function requires an open joystick. * This function requires an open joystick.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the GUID of the given joystick. If called on an invalid index, * \returns the GUID of the given joystick. If called on an invalid index,
* this function returns a zero GUID; call SDL_GetError() for more * this function returns a zero GUID; call SDL_GetError() for more
* information. * information.
@@ -748,7 +748,7 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *j
* *
* If the vendor ID isn't available this function returns 0. * If the vendor ID isn't available this function returns 0.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -762,7 +762,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick)
* *
* If the product ID isn't available this function returns 0. * If the product ID isn't available this function returns 0.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the USB product ID of the selected joystick, or 0 if unavailable. * \returns the USB product ID of the selected joystick, or 0 if unavailable.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -776,7 +776,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick
* *
* If the product version isn't available this function returns 0. * If the product version isn't available this function returns 0.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the product version of the selected joystick, or 0 if unavailable. * \returns the product version of the selected joystick, or 0 if unavailable.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -790,7 +790,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j
* *
* If the firmware version isn't available this function returns 0. * If the firmware version isn't available this function returns 0.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the firmware version of the selected joystick, or 0 if * \returns the firmware version of the selected joystick, or 0 if
* unavailable. * unavailable.
* *
@@ -805,7 +805,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the serial number of the selected joystick, or NULL if * \returns the serial number of the selected joystick, or NULL if
* unavailable. * unavailable.
* *
@@ -816,7 +816,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy
/** /**
* Get the type of an opened joystick. * Get the type of an opened joystick.
* *
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick() * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the SDL_JoystickType of the selected joystick. * \returns the SDL_JoystickType of the selected joystick.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -830,9 +830,9 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j
* *
* You should supply at least 33 bytes for pszGUID. * You should supply at least 33 bytes for pszGUID.
* *
* \param guid the SDL_JoystickGUID you wish to convert to string * \param guid the SDL_JoystickGUID you wish to convert to string.
* \param pszGUID buffer in which to write the ASCII string * \param pszGUID buffer in which to write the ASCII string.
* \param cbGUID the size of pszGUID * \param cbGUID the size of pszGUID.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -851,7 +851,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickGUIDString(SDL_JoystickGUID guid,
* an invalid GUID, the function will silently succeed, but the GUID generated * an invalid GUID, the function will silently succeed, but the GUID generated
* will not be useful. * will not be useful.
* *
* \param pchGUID string containing an ASCII representation of a GUID * \param pchGUID string containing an ASCII representation of a GUID.
* \returns a SDL_JoystickGUID structure. * \returns a SDL_JoystickGUID structure.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -863,15 +863,15 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUIDFromString(const
/** /**
* Get the device information encoded in a SDL_JoystickGUID structure. * Get the device information encoded in a SDL_JoystickGUID structure.
* *
* \param guid the SDL_JoystickGUID you wish to get info about * \param guid the SDL_JoystickGUID you wish to get info about.
* \param vendor A pointer filled in with the device VID, or 0 if not * \param vendor a pointer filled in with the device VID, or 0 if not
* available * available.
* \param product A pointer filled in with the device PID, or 0 if not * \param product a pointer filled in with the device PID, or 0 if not
* available * available.
* \param version A pointer filled in with the device version, or 0 if not * \param version a pointer filled in with the device version, or 0 if not
* available * available.
* \param crc16 A pointer filled in with a CRC used to distinguish different * \param crc16 a pointer filled in with a CRC used to distinguish different
* products with the same VID/PID, or 0 if not available * products with the same VID/PID, or 0 if not available.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -882,7 +882,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid,
/** /**
* Get the status of a specified joystick. * Get the status of a specified joystick.
* *
* \param joystick the joystick to query * \param joystick the joystick to query.
* \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -893,7 +893,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystic
/** /**
* Get the instance ID of an opened joystick. * Get the instance ID of an opened joystick.
* *
* \param joystick an SDL_Joystick structure containing joystick information * \param joystick an SDL_Joystick structure containing joystick information.
* \returns the instance ID of the specified joystick on success or 0 on * \returns the instance ID of the specified joystick on success or 0 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -908,7 +908,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickInstanceID(SDL_Joystic
* separate buttons or a POV hat, and not axes, but all of this is up to the * separate buttons or a POV hat, and not axes, but all of this is up to the
* device and platform. * device and platform.
* *
* \param joystick an SDL_Joystick structure containing joystick information * \param joystick an SDL_Joystick structure containing joystick information.
* \returns the number of axis controls/number of axes on success or a * \returns the number of axis controls/number of axes on success or a
* negative error code on failure; call SDL_GetError() for more * negative error code on failure; call SDL_GetError() for more
* information. * information.
@@ -930,7 +930,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick);
* *
* Most joysticks do not have trackballs. * Most joysticks do not have trackballs.
* *
* \param joystick an SDL_Joystick structure containing joystick information * \param joystick an SDL_Joystick structure containing joystick information.
* \returns the number of trackballs on success or a negative error code on * \returns the number of trackballs on success or a negative error code on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -946,7 +946,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(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 * \param joystick an SDL_Joystick structure containing joystick information.
* \returns the number of POV hats on success or a negative error code on * \returns the number of POV hats on success or a negative error code on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -962,7 +962,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(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 * \param joystick an SDL_Joystick structure containing joystick information.
* \returns the number of buttons on success or a negative error code on * \returns the number of buttons on success or a negative error code on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -982,7 +982,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick
* yourself and check the state of the joystick when you want joystick * yourself and check the state of the joystick when you want joystick
* information. * information.
* *
* \param enabled whether to process joystick events or not * \param enabled whether to process joystick events or not.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1030,8 +1030,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void);
* 32767) representing the current position of the axis. It may be necessary * 32767) representing the current position of the axis. It may be necessary
* to impose certain tolerances on these values to account for jitter. * to impose certain tolerances on these values to account for jitter.
* *
* \param joystick an SDL_Joystick structure containing joystick information * \param joystick an SDL_Joystick structure containing joystick information.
* \param axis the axis to query; the axis indices start at index 0 * \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 * \returns a 16-bit signed integer representing the current position of the
* axis or 0 on failure; call SDL_GetError() for more information. * axis or 0 on failure; call SDL_GetError() for more information.
* *
@@ -1048,9 +1048,9 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i
* *
* The axis indices start at index 0. * The axis indices start at index 0.
* *
* \param joystick an SDL_Joystick structure containing joystick information * \param joystick an SDL_Joystick structure containing joystick information.
* \param axis the axis to query; the axis indices start at index 0 * \param axis the axis to query; the axis indices start at index 0.
* \param state Upon return, the initial value is supplied here. * \param state upon return, the initial value is supplied here.
* \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. * \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1065,10 +1065,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic
* *
* Most joysticks do not have trackballs. * Most joysticks do not have trackballs.
* *
* \param joystick the SDL_Joystick to query * \param joystick the SDL_Joystick to query.
* \param ball the ball index to query; ball indices start at index 0 * \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 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 * \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 * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1083,8 +1083,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int
* *
* The returned value will be one of the `SDL_HAT_*` values. * The returned value will be one of the `SDL_HAT_*` values.
* *
* \param joystick an SDL_Joystick structure containing joystick information * \param joystick an SDL_Joystick structure containing joystick information.
* \param hat the hat index to get the state from; indices start at index 0 * \param hat the hat index to get the state from; indices start at index 0.
* \returns the current hat position. * \returns the current hat position.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1106,9 +1106,9 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int
/** /**
* Get the current state of a button on a joystick. * Get the current state of a button on a joystick.
* *
* \param joystick an SDL_Joystick structure containing joystick information * \param joystick an SDL_Joystick structure containing joystick information.
* \param button the button index to get the state from; indices start at * \param button the button index to get the state from; indices start at
* index 0 * index 0.
* \returns 1 if the specified button is pressed, 0 otherwise. * \returns 1 if the specified button is pressed, 0 otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -1126,13 +1126,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick,
* This function requires you to process SDL events or call * This function requires you to process SDL events or call
* SDL_UpdateJoysticks() to update rumble state. * SDL_UpdateJoysticks() to update rumble state.
* *
* \param joystick The joystick to vibrate * \param joystick the joystick to vibrate.
* \param low_frequency_rumble The intensity of the low frequency (left) * \param low_frequency_rumble the intensity of the low frequency (left)
* rumble motor, from 0 to 0xFFFF * rumble motor, from 0 to 0xFFFF.
* \param high_frequency_rumble The intensity of the high frequency (right) * \param high_frequency_rumble the intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF * rumble motor, from 0 to 0xFFFF.
* \param duration_ms The duration of the rumble effect, in milliseconds * \param duration_ms the duration of the rumble effect, in milliseconds.
* \returns 0, or -1 if rumble isn't supported on this joystick * \returns 0, or -1 if rumble isn't supported on this joystick.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -1152,12 +1152,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint1
* This function requires you to process SDL events or call * This function requires you to process SDL events or call
* SDL_UpdateJoysticks() to update rumble state. * SDL_UpdateJoysticks() to update rumble state.
* *
* \param joystick The joystick to vibrate * \param joystick the joystick to vibrate.
* \param left_rumble The intensity of the left trigger rumble motor, from 0 * \param left_rumble the intensity of the left trigger rumble motor, from 0
* to 0xFFFF * to 0xFFFF.
* \param right_rumble The intensity of the right trigger rumble motor, from 0 * \param right_rumble the intensity of the right trigger rumble motor, from 0
* to 0xFFFF * to 0xFFFF.
* \param duration_ms The duration of the rumble effect, in milliseconds * \param duration_ms the duration of the rumble effect, in milliseconds.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1176,10 +1176,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystic
* For joysticks with a single color LED, the maximum of the RGB values will * For joysticks with a single color LED, the maximum of the RGB values will
* be used as the LED brightness. * be used as the LED brightness.
* *
* \param joystick The joystick to update * \param joystick the joystick to update.
* \param red The intensity of the red LED * \param red the intensity of the red LED.
* \param green The intensity of the green LED * \param green the intensity of the green LED.
* \param blue The intensity of the blue LED * \param blue the intensity of the blue LED.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1190,9 +1190,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8
/** /**
* Send a joystick specific effect packet. * Send a joystick specific effect packet.
* *
* \param joystick The joystick to affect * \param joystick the joystick to affect.
* \param data The data to send to the joystick * \param data the data to send to the joystick.
* \param size The size of the data to send to the joystick * \param size the size of the data to send to the joystick.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1203,7 +1203,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, c
/** /**
* Close a joystick previously opened with SDL_OpenJoystick(). * Close a joystick previously opened with SDL_OpenJoystick().
* *
* \param joystick The joystick device to close * \param joystick the joystick device to close.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1214,7 +1214,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick);
/** /**
* Get the connection state of a joystick. * Get the connection state of a joystick.
* *
* \param joystick The joystick to query * \param joystick the joystick to query.
* \returns the connection state on success or * \returns the connection state on success or
* `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError()
* for more information. * for more information.
@@ -1232,7 +1232,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio
* not uncommon for older batteries to lose stored power much faster than it * not uncommon for older batteries to lose stored power much faster than it
* reports, or completely drain when reporting it has 20 percent left, etc. * reports, or completely drain when reporting it has 20 percent left, etc.
* *
* \param joystick The joystick to query * \param joystick the joystick to query.
* \param percent a pointer filled in with the percentage of battery life * \param percent a pointer filled in with the percentage of battery life
* left, between 0 and 100, or NULL to ignore. This will be * left, between 0 and 100, or NULL to ignore. This will be
* filled in with -1 we can't determine a value or there is no * filled in with -1 we can't determine a value or there is no

26
include/SDL3/SDL_keyboard.h
View File

@@ -92,7 +92,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
* power buttons, etc. You should wait for input from a device before you * power buttons, etc. You should wait for input from a device before you
* consider it actively in use. * consider it actively in use.
* *
* \param count a pointer filled in with the number of keyboards returned * \param count a pointer filled in with the number of keyboards returned.
* \returns a 0 terminated array of keyboards instance IDs which should be * \returns a 0 terminated array of keyboards instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details. * more details.
@@ -111,7 +111,7 @@ extern SDL_DECLSPEC SDL_KeyboardID *SDLCALL SDL_GetKeyboards(int *count);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the keyboard instance ID * \param instance_id the keyboard instance ID.
* \returns the name of the selected keyboard, or NULL on failure; call * \returns the name of the selected keyboard, or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -151,7 +151,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
* Note: This function doesn't take into account whether shift has been * Note: This function doesn't take into account whether shift has been
* pressed or not. * pressed or not.
* *
* \param numkeys if non-NULL, receives the length of the returned array * \param numkeys if non-NULL, receives the length of the returned array.
* \returns a pointer to an array of key states. * \returns a pointer to an array of key states.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -196,7 +196,7 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
* This does not change the keyboard state, only the key modifier flags that * This does not change the keyboard state, only the key modifier flags that
* SDL reports. * SDL reports.
* *
* \param modstate the desired SDL_Keymod for the keyboard * \param modstate the desired SDL_Keymod for the keyboard.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -210,7 +210,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
* *
* See SDL_Keycode for details. * See SDL_Keycode for details.
* *
* \param scancode the desired SDL_Scancode to query * \param scancode the desired SDL_Scancode to query.
* \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -226,7 +226,7 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetDefaultKeyFromScancode(SDL_Scanco
* *
* See SDL_Keycode for details. * See SDL_Keycode for details.
* *
* \param scancode the desired SDL_Scancode to query * \param scancode the desired SDL_Scancode to query.
* \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -242,7 +242,7 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan
* *
* See SDL_Scancode for details. * See SDL_Scancode for details.
* *
* \param key the desired SDL_Keycode to query * \param key the desired SDL_Keycode to query.
* \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -268,7 +268,7 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key)
* unsuitable for creating a stable cross-platform two-way mapping between * unsuitable for creating a stable cross-platform two-way mapping between
* strings and scancodes. * strings and scancodes.
* *
* \param scancode the desired SDL_Scancode to query * \param scancode the desired SDL_Scancode to query.
* \returns a pointer to the name for the scancode. If the scancode doesn't * \returns a pointer to the name for the scancode. If the scancode doesn't
* have a name this function returns an empty string (""). * have a name this function returns an empty string ("").
* *
@@ -282,7 +282,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancod
/** /**
* Get a scancode from a human-readable name. * Get a scancode from a human-readable name.
* *
* \param name the human-readable scancode name * \param name the human-readable scancode name.
* \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
* recognized; call SDL_GetError() for more information. * recognized; call SDL_GetError() for more information.
* *
@@ -301,7 +301,7 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param key the desired SDL_Keycode to query * \param key the desired SDL_Keycode to query.
* \returns a pointer to a UTF-8 string that stays valid at least until the * \returns a pointer to a UTF-8 string that stays valid at least until the
* next call to this function. If you need it around any longer, you * next call to this function. If you need it around any longer, you
* must copy it. If the key doesn't have a name, this function * must copy it. If the key doesn't have a name, this function
@@ -318,7 +318,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
/** /**
* Get a key code from a human-readable name. * Get a key code from a human-readable name.
* *
* \param name the human-readable key name * \param name the human-readable key name.
* \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -396,7 +396,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ClearComposition(void);
* any feedback. * any feedback.
* *
* \param rect the SDL_Rect structure representing the rectangle to receive * \param rect the SDL_Rect structure representing the rectangle to receive
* text (ignored if NULL) * text (ignored if NULL).
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -422,7 +422,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
/** /**
* Check whether the screen keyboard is shown for given window. * Check whether the screen keyboard is shown for given window.
* *
* \param window the window for which screen keyboard should be queried * \param window the window for which screen keyboard should be queried.
* \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

8
include/SDL3/SDL_loadso.h
View File

@@ -55,7 +55,7 @@ extern "C" {
/** /**
* Dynamically load a shared object. * Dynamically load a shared object.
* *
* \param sofile a system-dependent name of the object file * \param sofile a system-dependent name of the object file.
* \returns an opaque pointer to the object handle or NULL if there was an * \returns an opaque pointer to the object handle or NULL if there was an
* error; call SDL_GetError() for more information. * error; call SDL_GetError() for more information.
* *
@@ -81,8 +81,8 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
* *
* If the requested function doesn't exist, NULL is returned. * If the requested function doesn't exist, NULL is returned.
* *
* \param handle a valid shared object handle returned by SDL_LoadObject() * \param handle a valid shared object handle returned by SDL_LoadObject().
* \param name the name of the function to look up * \param name the name of the function to look up.
* \returns a pointer to the function or NULL if there was an error; call * \returns a pointer to the function or NULL if there was an error; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -95,7 +95,7 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, c
/** /**
* Unload a shared object from memory. * Unload a shared object from memory.
* *
* \param handle a valid shared object handle returned by SDL_LoadObject() * \param handle a valid shared object handle returned by SDL_LoadObject().
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

83
include/SDL3/SDL_log.h
View File

@@ -110,7 +110,7 @@ typedef enum SDL_LogPriority
/** /**
* Set the priority of all log categories. * Set the priority of all log categories.
* *
* \param priority the SDL_LogPriority to assign * \param priority the SDL_LogPriority to assign.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -122,8 +122,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
/** /**
* Set the priority of a particular log category. * Set the priority of a particular log category.
* *
* \param category the category to assign a priority to * \param category the category to assign a priority to.
* \param priority the SDL_LogPriority to assign * \param priority the SDL_LogPriority to assign.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -137,8 +137,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category,
/** /**
* Get the priority of a particular log category. * Get the priority of a particular log category.
* *
* \param category the category to query * \param category the category to query.
* \returns the SDL_LogPriority for the requested category * \returns the SDL_LogPriority for the requested category.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -161,9 +161,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
/** /**
* Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
* *
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the `fmt` string, if * \param ... additional parameters matching % tokens in the `fmt` string, if
* any * any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -181,10 +181,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm
/** /**
* Log a message with SDL_LOG_PRIORITY_VERBOSE. * Log a message with SDL_LOG_PRIORITY_VERBOSE.
* *
* \param category the category of the message * \param category the category of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string, * \param ... additional parameters matching % tokens in the **fmt** string,
* if any * if any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -202,10 +202,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_
/** /**
* Log a message with SDL_LOG_PRIORITY_DEBUG. * Log a message with SDL_LOG_PRIORITY_DEBUG.
* *
* \param category the category of the message * \param category the category of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string, * \param ... additional parameters matching % tokens in the **fmt** string,
* if any * if any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -223,10 +223,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST
/** /**
* Log a message with SDL_LOG_PRIORITY_INFO. * Log a message with SDL_LOG_PRIORITY_INFO.
* *
* \param category the category of the message * \param category the category of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string, * \param ... additional parameters matching % tokens in the **fmt** string,
* if any * if any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -244,10 +244,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR
/** /**
* Log a message with SDL_LOG_PRIORITY_WARN. * Log a message with SDL_LOG_PRIORITY_WARN.
* *
* \param category the category of the message * \param category the category of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string, * \param ... additional parameters matching % tokens in the **fmt** string,
* if any * if any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -265,10 +265,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR
/** /**
* Log a message with SDL_LOG_PRIORITY_ERROR. * Log a message with SDL_LOG_PRIORITY_ERROR.
* *
* \param category the category of the message * \param category the category of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string, * \param ... additional parameters matching % tokens in the **fmt** string,
* if any * if any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -286,10 +286,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST
/** /**
* Log a message with SDL_LOG_PRIORITY_CRITICAL. * Log a message with SDL_LOG_PRIORITY_CRITICAL.
* *
* \param category the category of the message * \param category the category of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string, * \param ... additional parameters matching % tokens in the **fmt** string,
* if any * if any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -307,11 +307,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT
/** /**
* Log a message with the specified category and priority. * Log a message with the specified category and priority.
* *
* \param category the category of the message * \param category the category of the message.
* \param priority the priority of the message * \param priority the priority of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string, * \param ... additional parameters matching % tokens in the **fmt** string,
* if any * if any.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -331,10 +331,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category,
/** /**
* Log a message with the specified category and priority. * Log a message with the specified category and priority.
* *
* \param category the category of the message * \param category the category of the message.
* \param priority the priority of the message * \param priority the priority of the message.
* \param fmt a printf() style message format string * \param fmt a printf() style message format string.
* \param ap a variable argument list * \param ap a variable argument list.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -356,10 +356,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category,
* *
* This function is called by SDL when there is new text to be logged. * This function is called by SDL when there is new text to be logged.
* *
* \param userdata what was passed as `userdata` to SDL_SetLogOutputFunction() * \param userdata what was passed as `userdata` to
* \param category the category of the message * SDL_SetLogOutputFunction().
* \param priority the priority of the message * \param category the category of the message.
* \param message the message being output * \param priority the priority of the message.
* \param message the message being output.
* *
* \since This datatype is available since SDL 3.0.0. * \since This datatype is available since SDL 3.0.0.
*/ */
@@ -369,9 +370,9 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_
* Get the current log output function. * Get the current log output function.
* *
* \param callback an SDL_LogOutputFunction filled in with the current log * \param callback an SDL_LogOutputFunction filled in with the current log
* callback * callback.
* \param userdata a pointer filled in with the pointer that is passed to * \param userdata a pointer filled in with the pointer that is passed to
* `callback` * `callback`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -382,8 +383,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction
/** /**
* Replace the default log output function with one of your own. * Replace the default log output function with one of your own.
* *
* \param callback an SDL_LogOutputFunction to call instead of the default * \param callback an SDL_LogOutputFunction to call instead of the default.
* \param userdata a pointer that is passed to `callback` * \param userdata a pointer that is passed to `callback`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

32
include/SDL3/SDL_main.h
View File

@@ -287,8 +287,8 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
* *
* \param appstate a place where the app can optionally store a pointer for * \param appstate a place where the app can optionally store a pointer for
* future use. * future use.
* \param argc The standard ANSI C main's argc; number of elements in `argv` * \param argc the standard ANSI C main's argc; number of elements in `argv`.
* \param argv The standard ANSI C main's argv; array of command line * \param argv the standard ANSI C main's argv; array of command line
* arguments. * arguments.
* \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
* terminate with success, SDL_APP_CONTINUE to continue. * terminate with success, SDL_APP_CONTINUE to continue.
@@ -506,17 +506,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void);
* using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do * using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do
* *not* need SDL_SetMainReady(). * *not* need SDL_SetMainReady().
* *
* \param argc The argc parameter from the application's main() function, or 0 * \param argc the argc parameter from the application's main() function, or 0
* if the platform's main-equivalent has no argc * if the platform's main-equivalent has no argc.
* \param argv The argv parameter from the application's main() function, or * \param argv the argv parameter from the application's main() function, or
* NULL if the platform's main-equivalent has no argv * NULL if the platform's main-equivalent has no argv.
* \param mainFunction Your SDL app's C-style main(). NOT the function you're * \param mainFunction your SDL app's C-style main(). NOT the function you're
* calling this from! Its name doesn't matter; it doesn't * calling this from! Its name doesn't matter; it doesn't
* literally have to be `main`. * literally have to be `main`.
* \param reserved should be NULL (reserved for future use, will probably be * \param reserved should be NULL (reserved for future use, will probably be
* platform-specific then) * platform-specific then).
* \returns the return value from mainFunction: 0 on success, -1 on failure; * \returns the return value from mainFunction: 0 on success, -1 on failure;
* SDL_GetError() might have more information on the failure * SDL_GetError() might have more information on the failure.
* *
* \threadsafety Generally this is called once, near startup, from the * \threadsafety Generally this is called once, near startup, from the
* process's initial thread. * process's initial thread.
@@ -537,13 +537,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char* argv[], SDL_main_func
* header-only library, and you should not call this directly unless you * header-only library, and you should not call this directly unless you
* _really_ know what you're doing. * _really_ know what you're doing.
* *
* \param argc standard Unix main argc * \param argc standard Unix main argc.
* \param argv standard Unix main argv * \param argv standard Unix main argv.
* \param appinit The application's SDL_AppInit function * \param appinit the application's SDL_AppInit function.
* \param appiter The application's SDL_AppIterate function * \param appiter the application's SDL_AppIterate function.
* \param appevent The application's SDL_AppEvent function * \param appevent the application's SDL_AppEvent function.
* \param appquit The application's SDL_AppQuit function * \param appquit the application's SDL_AppQuit function.
* \returns standard Unix main return value * \returns standard Unix main return value.
* *
* \threadsafety It is not safe to call this anywhere except as the only * \threadsafety It is not safe to call this anywhere except as the only
* function call in SDL_main. * function call in SDL_main.

13
include/SDL3/SDL_messagebox.h
View File

@@ -151,8 +151,9 @@ typedef struct SDL_MessageBoxData
* to stderr if you can. * to stderr if you can.
* *
* \param messageboxdata the SDL_MessageBoxData structure with title, text and * \param messageboxdata the SDL_MessageBoxData structure with title, text and
* other options * other options.
* \param buttonid the pointer to which user id of hit button should be copied * \param buttonid the pointer to which user id of hit button should be
* copied.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -191,10 +192,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *mes
* concern, check the return value from this function and fall back to writing * concern, check the return value from this function and fall back to writing
* to stderr if you can. * to stderr if you can.
* *
* \param flags an SDL_MessageBoxFlags value * \param flags an SDL_MessageBoxFlags value.
* \param title UTF-8 title text * \param title uTF-8 title text.
* \param message UTF-8 message text * \param message uTF-8 message text.
* \param window the parent window, or NULL for no parent * \param window the parent window, or NULL for no parent.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

10
include/SDL3/SDL_metal.h
View File

@@ -58,8 +58,8 @@ typedef void *SDL_MetalView;
* The returned handle can be casted directly to a NSView or UIView. To access * The returned handle can be casted directly to a NSView or UIView. To access
* the backing CAMetalLayer, call SDL_Metal_GetLayer(). * the backing CAMetalLayer, call SDL_Metal_GetLayer().
* *
* \param window the window * \param window the window.
* \returns handle NSView or UIView * \returns handle NSView or UIView.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -74,7 +74,7 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * wind
* This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
* called after SDL_CreateWindow. * called after SDL_CreateWindow.
* *
* \param view the SDL_MetalView object * \param view the SDL_MetalView object.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -85,8 +85,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
/** /**
* Get a pointer to the backing CAMetalLayer for the given view. * Get a pointer to the backing CAMetalLayer for the given view.
* *
* \param view the SDL_MetalView object * \param view the SDL_MetalView object.
* \returns a pointer * \returns a pointer.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */

2
include/SDL3/SDL_misc.h
View File

@@ -60,7 +60,7 @@ extern "C" {
* All this to say: this function can be useful, but you should definitely * All this to say: this function can be useful, but you should definitely
* test it on every platform you target. * test it on every platform you target.
* *
* \param url A valid URL/URI to open. Use `file:///full/path/to/file` for * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for
* local files, if supported. * local files, if supported.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.

50
include/SDL3/SDL_mouse.h
View File

@@ -135,7 +135,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
* You should wait for input from a device before you consider it actively in * You should wait for input from a device before you consider it actively in
* use. * use.
* *
* \param count a pointer filled in with the number of mice returned * \param count a pointer filled in with the number of mice returned.
* \returns a 0 terminated array of mouse instance IDs which should be freed * \returns a 0 terminated array of mouse instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more * with SDL_free(), or NULL on error; call SDL_GetError() for more
* details. * details.
@@ -154,7 +154,7 @@ extern SDL_DECLSPEC SDL_MouseID *SDLCALL SDL_GetMice(int *count);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the mouse instance ID * \param instance_id the mouse instance ID.
* \returns the name of the selected mouse, or NULL on failure; call * \returns the name of the selected mouse, or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -183,9 +183,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
* either `x` or `y`. * either `x` or `y`.
* *
* \param x the x coordinate of the mouse cursor position relative to the * \param x the x coordinate of the mouse cursor position relative to the
* focus window * focus window.
* \param y the y coordinate of the mouse cursor position relative to the * \param y the y coordinate of the mouse cursor position relative to the
* focus window * focus window.
* \returns a 32-bit button bitmask of the current button state. * \returns a 32-bit button bitmask of the current button state.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -212,9 +212,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, flo
* reason to use this function, you probably want SDL_GetMouseState() instead. * reason to use this function, you probably want SDL_GetMouseState() instead.
* *
* \param x filled in with the current X coord relative to the desktop; can be * \param x filled in with the current X coord relative to the desktop; can be
* NULL * NULL.
* \param y filled in with the current Y coord relative to the desktop; can be * \param y filled in with the current Y coord relative to the desktop; can be
* NULL * NULL.
* \returns the current button state as a bitmask which can be tested using * \returns the current button state as a bitmask which can be tested using
* the SDL_BUTTON(X) macros. * the SDL_BUTTON(X) macros.
* *
@@ -234,8 +234,8 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *
* mouse deltas since the last call to SDL_GetRelativeMouseState() or since * mouse deltas since the last call to SDL_GetRelativeMouseState() or since
* event initialization. You can pass NULL for either `x` or `y`. * event initialization. You can pass NULL for either `x` or `y`.
* *
* \param x a pointer filled with the last recorded x coordinate of the mouse * \param x a pointer filled with the last recorded x coordinate of the mouse.
* \param y a pointer filled with the last recorded y coordinate of the mouse * \param y a pointer filled with the last recorded y coordinate of the mouse.
* \returns a 32-bit button bitmask of the relative button state. * \returns a 32-bit button bitmask of the relative button state.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -255,9 +255,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float
* mouse when used over Microsoft Remote Desktop. * mouse when used over Microsoft Remote Desktop.
* *
* \param window the window to move the mouse into, or NULL for the current * \param window the window to move the mouse into, or NULL for the current
* mouse focus * mouse focus.
* \param x the x coordinate within the window * \param x the x coordinate within the window.
* \param y the y coordinate within the window * \param y the y coordinate within the window.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -277,8 +277,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
* Note that this function will appear to succeed, but not actually move the * Note that this function will appear to succeed, but not actually move the
* mouse when used over Microsoft Remote Desktop. * mouse when used over Microsoft Remote Desktop.
* *
* \param x the x coordinate * \param x the x coordinate.
* \param y the y coordinate * \param y the y coordinate.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -388,14 +388,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
* Also, SDL_CreateSystemCursor() is available, which provides several * Also, SDL_CreateSystemCursor() is available, which provides several
* readily-available system cursors to pick from. * readily-available system cursors to pick from.
* *
* \param data the color value for each pixel of the cursor * \param data the color value for each pixel of the cursor.
* \param mask the mask value for each pixel of the cursor * \param mask the mask value for each pixel of the cursor.
* \param w the width of the cursor * \param w the width of the cursor.
* \param h the height of the cursor * \param h the height of the cursor.
* \param hot_x the x-axis offset from the left of the cursor image to the * \param hot_x the x-axis offset from the left of the cursor image to the
* mouse x position, in the range of 0 to `w` - 1 * mouse x position, in the range of 0 to `w` - 1.
* \param hot_y the y-axis offset from the top of the cursor image to the * \param hot_y the y-axis offset from the top of the cursor image to the
* mouse y position, in the range of 0 to `h` - 1 * mouse y position, in the range of 0 to `h` - 1.
* \returns a new cursor with the specified parameters on success or NULL on * \returns a new cursor with the specified parameters on success or NULL on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -414,9 +414,9 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
/** /**
* Create a color cursor. * Create a color cursor.
* *
* \param surface an SDL_Surface structure representing the cursor image * \param surface an SDL_Surface structure representing the cursor image.
* \param hot_x the x position of the cursor hot spot * \param hot_x the x position of the cursor hot spot.
* \param hot_y the y position of the cursor hot spot * \param hot_y the y position of the cursor hot spot.
* \returns the new cursor on success or NULL on failure; call SDL_GetError() * \returns the new cursor on success or NULL on failure; call SDL_GetError()
* for more information. * for more information.
* *
@@ -434,7 +434,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surfa
/** /**
* Create a system cursor. * Create a system cursor.
* *
* \param id an SDL_SystemCursor enum value * \param id an SDL_SystemCursor enum value.
* \returns a cursor on success or NULL on failure; call SDL_GetError() for * \returns a cursor on success or NULL on failure; call SDL_GetError() for
* more information. * more information.
* *
@@ -452,7 +452,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor
* the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
* this is desired for any reason. * this is desired for any reason.
* *
* \param cursor a cursor to make active * \param cursor a cursor to make active.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -494,7 +494,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
* Use this function to free cursor resources created with SDL_CreateCursor(), * Use this function to free cursor resources created with SDL_CreateCursor(),
* SDL_CreateColorCursor() or SDL_CreateSystemCursor(). * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
* *
* \param cursor the cursor to free * \param cursor the cursor to free.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

54
include/SDL3/SDL_mutex.h
View File

@@ -181,7 +181,7 @@ extern SDL_DECLSPEC SDL_Mutex *SDLCALL SDL_CreateMutex(void);
* having locked nothing. If the mutex is valid, this function will always * having locked nothing. If the mutex is valid, this function will always
* block until it can lock the mutex, and return with it locked. * block until it can lock the mutex, and return with it locked.
* *
* \param mutex the mutex to lock * \param mutex the mutex to lock.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -204,8 +204,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut
* either lock the mutex and return 0, or return SDL_MUTEX_TIMEOUT and lock * either lock the mutex and return 0, or return SDL_MUTEX_TIMEOUT and lock
* nothing. * nothing.
* *
* \param mutex the mutex to try to lock * \param mutex the mutex to try to lock.
* \returns 0 or `SDL_MUTEX_TIMEDOUT` * \returns 0 or `SDL_MUTEX_TIMEDOUT`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -242,7 +242,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m
* to destroy a locked mutex, and may result in undefined behavior depending * to destroy a locked mutex, and may result in undefined behavior depending
* on the platform. * on the platform.
* *
* \param mutex the mutex to destroy * \param mutex the mutex to destroy.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -360,7 +360,7 @@ extern SDL_DECLSPEC SDL_RWLock *SDLCALL SDL_CreateRWLock(void);
* having locked nothing. If the rwlock is valid, this function will always * having locked nothing. If the rwlock is valid, this function will always
* block until it can lock the mutex, and return with it locked. * block until it can lock the mutex, and return with it locked.
* *
* \param rwlock the read/write lock to lock * \param rwlock the read/write lock to lock.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -391,7 +391,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD
* having locked nothing. If the rwlock is valid, this function will always * having locked nothing. If the rwlock is valid, this function will always
* block until it can lock the mutex, and return with it locked. * block until it can lock the mutex, and return with it locked.
* *
* \param rwlock the read/write lock to lock * \param rwlock the read/write lock to lock.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -418,8 +418,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD
* always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT * always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT
* and lock nothing. * and lock nothing.
* *
* \param rwlock the rwlock to try to lock * \param rwlock the rwlock to try to lock.
* \returns 0 or `SDL_RWLOCK_TIMEDOUT` * \returns 0 or `SDL_RWLOCK_TIMEDOUT`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -451,8 +451,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock)
* always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT * always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT
* and lock nothing. * and lock nothing.
* *
* \param rwlock the rwlock to try to lock * \param rwlock the rwlock to try to lock.
* \returns 0 or `SDL_RWLOCK_TIMEDOUT` * \returns 0 or `SDL_RWLOCK_TIMEDOUT`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -496,7 +496,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS
* is not safe to attempt to destroy a locked rwlock, and may result in * is not safe to attempt to destroy a locked rwlock, and may result in
* undefined behavior depending on the platform. * undefined behavior depending on the platform.
* *
* \param rwlock the rwlock to destroy * \param rwlock the rwlock to destroy.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -537,7 +537,7 @@ typedef struct SDL_Semaphore SDL_Semaphore;
* is 0. Each post operation will atomically increment the semaphore value and * is 0. Each post operation will atomically increment the semaphore value and
* wake waiting threads and allow them to retry the wait operation. * wake waiting threads and allow them to retry the wait operation.
* *
* \param initial_value the starting value of the semaphore * \param initial_value the starting value of the semaphore.
* \returns a new semaphore or NULL on failure; call SDL_GetError() for more * \returns a new semaphore or NULL on failure; call SDL_GetError() for more
* information. * information.
* *
@@ -558,7 +558,7 @@ extern SDL_DECLSPEC SDL_Semaphore *SDLCALL SDL_CreateSemaphore(Uint32 initial_va
* It is not safe to destroy a semaphore if there are threads currently * It is not safe to destroy a semaphore if there are threads currently
* waiting on it. * waiting on it.
* *
* \param sem the semaphore to destroy * \param sem the semaphore to destroy.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -577,7 +577,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem);
* This function is the equivalent of calling SDL_WaitSemaphoreTimeout() with * This function is the equivalent of calling SDL_WaitSemaphoreTimeout() with
* a time length of -1. * a time length of -1.
* *
* \param sem the semaphore wait on * \param sem the semaphore wait on.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -597,7 +597,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem);
* the semaphore doesn't have a positive value, the function immediately * the semaphore doesn't have a positive value, the function immediately
* returns SDL_MUTEX_TIMEDOUT. * returns SDL_MUTEX_TIMEDOUT.
* *
* \param sem the semaphore to wait on * \param sem the semaphore to wait on.
* \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
* block, or a negative error code on failure; call SDL_GetError() * block, or a negative error code on failure; call SDL_GetError()
* for more information. * for more information.
@@ -618,8 +618,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem);
* signal or error, or the specified time has elapsed. If the call is * signal or error, or the specified time has elapsed. If the call is
* successful it will atomically decrement the semaphore value. * successful it will atomically decrement the semaphore value.
* *
* \param sem the semaphore to wait on * \param sem the semaphore to wait on.
* \param timeoutMS the length of the timeout, in milliseconds * \param timeoutMS the length of the timeout, in milliseconds.
* \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
* succeed in the allotted time, or a negative error code on failure; * succeed in the allotted time, or a negative error code on failure;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
@@ -635,7 +635,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sin
/** /**
* Atomically increment a semaphore's value and wake waiting threads. * Atomically increment a semaphore's value and wake waiting threads.
* *
* \param sem the semaphore to increment * \param sem the semaphore to increment.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -650,7 +650,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PostSemaphore(SDL_Semaphore *sem);
/** /**
* Get the current value of a semaphore. * Get the current value of a semaphore.
* *
* \param sem the semaphore to query * \param sem the semaphore to query.
* \returns the current value of the semaphore. * \returns the current value of the semaphore.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -699,7 +699,7 @@ extern SDL_DECLSPEC SDL_Condition *SDLCALL SDL_CreateCondition(void);
/** /**
* Destroy a condition variable. * Destroy a condition variable.
* *
* \param cond the condition variable to destroy * \param cond the condition variable to destroy.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -710,7 +710,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond);
/** /**
* Restart one of the threads that are waiting on the condition variable. * Restart one of the threads that are waiting on the condition variable.
* *
* \param cond the condition variable to signal * \param cond the condition variable to signal.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -727,7 +727,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SignalCondition(SDL_Condition *cond);
/** /**
* Restart all threads that are waiting on the condition variable. * Restart all threads that are waiting on the condition variable.
* *
* \param cond the condition variable to signal * \param cond the condition variable to signal.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -756,8 +756,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BroadcastCondition(SDL_Condition *cond);
* This function is the equivalent of calling SDL_WaitConditionTimeout() with * This function is the equivalent of calling SDL_WaitConditionTimeout() with
* a time length of -1. * a time length of -1.
* *
* \param cond the condition variable to wait on * \param cond the condition variable to wait on.
* \param mutex the mutex used to coordinate thread access * \param mutex the mutex used to coordinate thread access.
* \returns 0 when it is signaled or a negative error code on failure; call * \returns 0 when it is signaled or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -784,10 +784,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex
* recursively (more than once) is not supported and leads to undefined * recursively (more than once) is not supported and leads to undefined
* behavior. * behavior.
* *
* \param cond the condition variable to wait on * \param cond the condition variable to wait on.
* \param mutex the mutex used to coordinate thread access * \param mutex the mutex used to coordinate thread access.
* \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait
* indefinitely * indefinitely.
* \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
* the condition is not signaled in the allotted time, or a negative * the condition is not signaled in the allotted time, or a negative
* error code on failure; call SDL_GetError() for more information. * error code on failure; call SDL_GetError() for more information.

32
include/SDL3/SDL_pen.h
View File

@@ -154,7 +154,7 @@ typedef enum SDL_PenSubtype
* throughout a session. To track pens across sessions (program restart), use * throughout a session. To track pens across sessions (program restart), use
* SDL_GUID . * SDL_GUID .
* *
* \param count The number of pens in the array (number of array elements * \param count the number of pens in the array (number of array elements
* minus 1, i.e., not counting the terminator 0). * minus 1, i.e., not counting the terminator 0).
* \returns a 0 terminated array of SDL_PenID values, or NULL on error. The * \returns a 0 terminated array of SDL_PenID values, or NULL on error. The
* array must be freed with SDL_free(). On a NULL return, * array must be freed with SDL_free(). On a NULL return,
@@ -170,12 +170,12 @@ extern SDL_DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
* If the pen is detached (cf. SDL_PenConnected), this operation may return * If the pen is detached (cf. SDL_PenConnected), this operation may return
* default values. * default values.
* *
* \param instance_id The pen to query. * \param instance_id the pen to query.
* \param x Out-mode parameter for pen x coordinate. May be NULL. * \param x out-mode parameter for pen x coordinate. May be NULL.
* \param y Out-mode parameter for pen y coordinate. May be NULL. * \param y out-mode parameter for pen y coordinate. May be NULL.
* \param axes Out-mode parameter for axis information. May be null. The axes * \param axes out-mode parameter for axis information. May be null. The axes
* are in the same order as SDL_PenAxis. * are in the same order as SDL_PenAxis.
* \param num_axes Maximum number of axes to write to "axes". * \param num_axes maximum number of axes to write to "axes".
* \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK * \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK
* etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of * etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of
* SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see * SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see
@@ -188,7 +188,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float
/** /**
* Retrieves an SDL_PenID for the given SDL_GUID. * Retrieves an SDL_PenID for the given SDL_GUID.
* *
* \param guid A pen GUID. * \param guid a pen GUID.
* \returns a valid SDL_PenID, or SDL_PEN_INVALID if there is no matching * \returns a valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
* SDL_PenID. * SDL_PenID.
* *
@@ -199,7 +199,7 @@ extern SDL_DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
/** /**
* Retrieves the SDL_GUID for a given SDL_PenID. * Retrieves the SDL_GUID for a given SDL_PenID.
* *
* \param instance_id The pen to query. * \param instance_id the pen to query.
* \returns the corresponding pen GUID; persistent across multiple sessions. * \returns the corresponding pen GUID; persistent across multiple sessions.
* If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID. * If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
* *
@@ -213,7 +213,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
* If a pen is detached, it will not show up for SDL_GetPens(). Other * If a pen is detached, it will not show up for SDL_GetPens(). Other
* operations will still be available but may return default values. * operations will still be available but may return default values.
* *
* \param instance_id A pen ID. * \param instance_id a pen ID.
* \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
* attached, or SDL_FALSE otherwise. * attached, or SDL_FALSE otherwise.
* *
@@ -226,14 +226,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id The pen to query. * \param instance_id the pen to query.
* \returns a string that contains the name of the pen, intended for human * \returns a string that contains the name of the pen, intended for human
* consumption. The string might or might not be localised, depending * consumption. The string might or might not be localised, depending
* on platform settings. It is not guaranteed to be unique; use * on platform settings. It is not guaranteed to be unique; use
* SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer * SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
* is managed by the SDL pen subsystem and must not be deallocated. * is managed by the SDL pen subsystem and must not be deallocated.
* The pointer remains valid until SDL is shut down. Returns NULL on * The pointer remains valid until SDL is shut down. Returns NULL on
* error (cf. SDL_GetError()) * error (cf. SDL_GetError()).
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -254,10 +254,10 @@ typedef struct SDL_PenCapabilityInfo
/** /**
* Retrieves capability flags for a given SDL_PenID. * Retrieves capability flags for a given SDL_PenID.
* *
* \param instance_id The pen to query. * \param instance_id the pen to query.
* \param capabilities Detail information about pen capabilities, such as the * \param capabilities detail information about pen capabilities, such as the
* number of buttons * number of buttons.
* \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -266,7 +266,7 @@ extern SDL_DECLSPEC SDL_PenCapabilityFlags SDLCALL SDL_GetPenCapabilities(SDL_Pe
/** /**
* Retrieves the pen type for a given SDL_PenID. * Retrieves the pen type for a given SDL_PenID.
* *
* \param instance_id The pen to query. * \param instance_id the pen to query.
* \returns the corresponding pen type (cf. SDL_PenSubtype) or 0 on error. * \returns the corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
* Note that the pen type does not dictate whether the pen tip is * Note that the pen type does not dictate whether the pen tip is
* SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen * SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen

88
include/SDL3/SDL_pixels.h
View File

@@ -760,7 +760,7 @@ typedef struct SDL_PixelFormat
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param format the pixel format to query * \param format the pixel format to query.
* \returns the human readable name of the specified pixel format or * \returns the human readable name of the specified pixel format or
* `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized. * `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
* *
@@ -771,12 +771,12 @@ extern SDL_DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(SDL_PixelFormatEn
/** /**
* Convert one of the enumerated pixel formats to a bpp value and RGBA masks. * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
* *
* \param format one of the SDL_PixelFormatEnum values * \param format one of the SDL_PixelFormatEnum values.
* \param bpp a bits per pixel value; usually 15, 16, or 32 * \param bpp a bits per pixel value; usually 15, 16, or 32.
* \param Rmask a pointer filled in with the red mask for the format * \param Rmask a pointer filled in with the red mask for the format.
* \param Gmask a pointer filled in with the green mask for the format * \param Gmask a pointer filled in with the green mask for the format.
* \param Bmask a pointer filled in with the blue mask for the format * \param Bmask a pointer filled in with the blue mask for the format.
* \param Amask a pointer filled in with the alpha mask for the format * \param Amask a pointer filled in with the alpha mask for the format.
* \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
* possible; call SDL_GetError() for more information. * possible; call SDL_GetError() for more information.
* *
@@ -797,11 +797,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormatEnum(SDL_PixelFor
* This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
* possible. * possible.
* *
* \param bpp a bits per pixel value; usually 15, 16, or 32 * \param bpp a bits per pixel value; usually 15, 16, or 32.
* \param Rmask the red mask for the format * \param Rmask the red mask for the format.
* \param Gmask the green mask for the format * \param Gmask the green mask for the format.
* \param Bmask the blue mask for the format * \param Bmask the blue mask for the format.
* \param Amask the alpha mask for the format * \param Amask the alpha mask for the format.
* \returns the SDL_PixelFormatEnum value corresponding to the format masks, * \returns the SDL_PixelFormatEnum value corresponding to the format masks,
* or SDL_PIXELFORMAT_UNKNOWN if there isn't a match. * or SDL_PIXELFORMAT_UNKNOWN if there isn't a match.
* *
@@ -822,7 +822,7 @@ extern SDL_DECLSPEC SDL_PixelFormatEnum SDLCALL SDL_GetPixelFormatEnumForMasks(i
* allocated), and hence should not be modified, especially the palette. Weird * allocated), and hence should not be modified, especially the palette. Weird
* errors such as `Blit combination not supported` may occur. * errors such as `Blit combination not supported` may occur.
* *
* \param pixel_format one of the SDL_PixelFormatEnum values * \param pixel_format one of the SDL_PixelFormatEnum values.
* \returns the new SDL_PixelFormat structure or NULL on failure; call * \returns the new SDL_PixelFormat structure or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -836,7 +836,7 @@ extern SDL_DECLSPEC SDL_PixelFormat * SDLCALL SDL_CreatePixelFormat(SDL_PixelFor
/** /**
* Free an SDL_PixelFormat structure allocated by SDL_CreatePixelFormat(). * Free an SDL_PixelFormat structure allocated by SDL_CreatePixelFormat().
* *
* \param format the SDL_PixelFormat structure to free * \param format the SDL_PixelFormat structure to free.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -849,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPixelFormat(SDL_PixelFormat *format)
* *
* The palette entries are initialized to white. * The palette entries are initialized to white.
* *
* \param ncolors represents the number of color entries in the color palette * \param ncolors represents the number of color entries in the color palette.
* \returns a new SDL_Palette structure on success or NULL on failure (e.g. if * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
* there wasn't enough memory); call SDL_GetError() for more * there wasn't enough memory); call SDL_GetError() for more
* information. * information.
@@ -865,8 +865,8 @@ extern SDL_DECLSPEC SDL_Palette *SDLCALL SDL_CreatePalette(int ncolors);
/** /**
* Set the palette for a pixel format structure. * Set the palette for a pixel format structure.
* *
* \param format the SDL_PixelFormat structure that will use the palette * \param format the SDL_PixelFormat structure that will use the palette.
* \param palette the SDL_Palette structure that will be used * \param palette the SDL_Palette structure that will be used.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -878,10 +878,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * form
/** /**
* Set a range of colors in a palette. * Set a range of colors in a palette.
* *
* \param palette the SDL_Palette structure to modify * \param palette the SDL_Palette structure to modify.
* \param colors an array of SDL_Color structures to copy into the palette * \param colors an array of SDL_Color structures to copy into the palette.
* \param firstcolor the index of the first palette entry to modify * \param firstcolor the index of the first palette entry to modify.
* \param ncolors the number of entries to modify * \param ncolors the number of entries to modify.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -894,7 +894,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
/** /**
* Free a palette created with SDL_CreatePalette(). * Free a palette created with SDL_CreatePalette().
* *
* \param palette the SDL_Palette structure to be freed * \param palette the SDL_Palette structure to be freed.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -920,11 +920,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette * palette);
* format the return value can be assigned to a Uint16, and similarly a Uint8 * format the return value can be assigned to a Uint16, and similarly a Uint8
* for an 8-bpp format). * for an 8-bpp format).
* *
* \param format an SDL_PixelFormat structure describing the pixel format * \param format an SDL_PixelFormat structure describing the pixel format.
* \param r the red component of the pixel in the range 0-255 * \param r the red component of the pixel in the range 0-255.
* \param g the green component of the pixel in the range 0-255 * \param g the green component of the pixel in the range 0-255.
* \param b the blue component of the pixel in the range 0-255 * \param b the blue component of the pixel in the range 0-255.
* \returns a pixel value * \returns a pixel value.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -954,12 +954,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
* for an 8-bpp format). * for an 8-bpp format).
* *
* \param format an SDL_PixelFormat structure describing the format of the * \param format an SDL_PixelFormat structure describing the format of the
* pixel * pixel.
* \param r the red component of the pixel in the range 0-255 * \param r the red component of the pixel in the range 0-255.
* \param g the green component of the pixel in the range 0-255 * \param g the green component of the pixel in the range 0-255.
* \param b the blue component of the pixel in the range 0-255 * \param b the blue component of the pixel in the range 0-255.
* \param a the alpha component of the pixel in the range 0-255 * \param a the alpha component of the pixel in the range 0-255.
* \returns a pixel value * \returns a pixel value.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -979,12 +979,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
* (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
* 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
* *
* \param pixel a pixel value * \param pixel a pixel value.
* \param format an SDL_PixelFormat structure describing the format of the * \param format an SDL_PixelFormat structure describing the format of the
* pixel * pixel.
* \param r a pointer filled in with the red component * \param r a pointer filled in with the red component.
* \param g a pointer filled in with the green component * \param g a pointer filled in with the green component.
* \param b a pointer filled in with the blue component * \param b a pointer filled in with the blue component.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1007,13 +1007,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
* If the surface has no alpha component, the alpha will be returned as 0xff * If the surface has no alpha component, the alpha will be returned as 0xff
* (100% opaque). * (100% opaque).
* *
* \param pixel a pixel value * \param pixel a pixel value.
* \param format an SDL_PixelFormat structure describing the format of the * \param format an SDL_PixelFormat structure describing the format of the
* pixel * pixel.
* \param r a pointer filled in with the red component * \param r a pointer filled in with the red component.
* \param g a pointer filled in with the green component * \param g a pointer filled in with the green component.
* \param b a pointer filled in with the blue component * \param b a pointer filled in with the blue component.
* \param a a pointer filled in with the alpha component * \param a a pointer filled in with the alpha component.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

98
include/SDL3/SDL_properties.h
View File

@@ -97,8 +97,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
* SDL_SetPropertyWithCleanup()), which will not be copied. Any property that * SDL_SetPropertyWithCleanup()), which will not be copied. Any property that
* already exists on `dst` will be overwritten. * already exists on `dst` will be overwritten.
* *
* \param src the properties to copy * \param src the properties to copy.
* \param dst the destination properties * \param dst the destination properties.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -120,7 +120,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Pro
* or want to guarantee that properties being queried aren't freed in another * or want to guarantee that properties being queried aren't freed in another
* thread. * thread.
* *
* \param props the properties to lock * \param props the properties to lock.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -135,7 +135,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
/** /**
* Unlock a set of properties. * Unlock a set of properties.
* *
* \param props the properties to unlock * \param props the properties to unlock.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -181,12 +181,12 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value)
* instead, as those functions will handle cleanup on your behalf. This * instead, as those functions will handle cleanup on your behalf. This
* function is only for more complex, custom data. * function is only for more complex, custom data.
* *
* \param props the properties to modify * \param props the properties to modify.
* \param name the name of the property to modify * \param name the name of the property to modify.
* \param value the new value of the property, or NULL to delete the property * \param value the new value of the property, or NULL to delete the property.
* \param cleanup the function to call when this property is deleted, or NULL * \param cleanup the function to call when this property is deleted, or NULL
* if no cleanup is necessary * if no cleanup is necessary.
* \param userdata a pointer that is passed to the cleanup function * \param userdata a pointer that is passed to the cleanup function.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -203,9 +203,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID prop
/** /**
* Set a property on a set of properties. * Set a property on a set of properties.
* *
* \param props the properties to modify * \param props the properties to modify.
* \param name the name of the property to modify * \param name the name of the property to modify.
* \param value the new value of the property, or NULL to delete the property * \param value the new value of the property, or NULL to delete the property.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -229,9 +229,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const ch
* This function makes a copy of the string; the caller does not have to * This function makes a copy of the string; the caller does not have to
* preserve the data after this call completes. * preserve the data after this call completes.
* *
* \param props the properties to modify * \param props the properties to modify.
* \param name the name of the property to modify * \param name the name of the property to modify.
* \param value the new value of the property, or NULL to delete the property * \param value the new value of the property, or NULL to delete the property.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -246,9 +246,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, co
/** /**
* Set an integer property on a set of properties. * Set an integer property on a set of properties.
* *
* \param props the properties to modify * \param props the properties to modify.
* \param name the name of the property to modify * \param name the name of the property to modify.
* \param value the new value of the property * \param value the new value of the property.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -263,9 +263,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, co
/** /**
* Set a floating point property on a set of properties. * Set a floating point property on a set of properties.
* *
* \param props the properties to modify * \param props the properties to modify.
* \param name the name of the property to modify * \param name the name of the property to modify.
* \param value the new value of the property * \param value the new value of the property.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -280,9 +280,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, con
/** /**
* Set a boolean property on a set of properties. * Set a boolean property on a set of properties.
* *
* \param props the properties to modify * \param props the properties to modify.
* \param name the name of the property to modify * \param name the name of the property to modify.
* \param value the new value of the property * \param value the new value of the property.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -297,8 +297,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, c
/** /**
* Return whether a property exists in a set of properties. * Return whether a property exists in a set of properties.
* *
* \param props the properties to query * \param props the properties to query.
* \param name the name of the property to query * \param name the name of the property to query.
* \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't. * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -312,8 +312,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con
/** /**
* Get the type of a property on a set of properties. * Get the type of a property on a set of properties.
* *
* \param props the properties to query * \param props the properties to query.
* \param name the name of the property to query * \param name the name of the property to query.
* \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is
* not set. * not set.
* *
@@ -333,9 +333,9 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI
* "SDL.internal.". These should be considered read-only and should not be * "SDL.internal.". These should be considered read-only and should not be
* modified by applications. * modified by applications.
* *
* \param props the properties to query * \param props the properties to query.
* \param name the name of the property to query * \param name the name of the property to query.
* \param default_value the default value of the property * \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or * \returns the value of the property, or `default_value` if it is not set or
* not a pointer property. * not a pointer property.
* *
@@ -362,9 +362,9 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param props the properties to query * \param props the properties to query.
* \param name the name of the property to query * \param name the name of the property to query.
* \param default_value the default value of the property * \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or * \returns the value of the property, or `default_value` if it is not set or
* not a string property. * not a string property.
* *
@@ -384,9 +384,9 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID p
* You can use SDL_GetPropertyType() to query whether the property exists and * You can use SDL_GetPropertyType() to query whether the property exists and
* is a number property. * is a number property.
* *
* \param props the properties to query * \param props the properties to query.
* \param name the name of the property to query * \param name the name of the property to query.
* \param default_value the default value of the property * \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or * \returns the value of the property, or `default_value` if it is not set or
* not a number property. * not a number property.
* *
@@ -406,9 +406,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props,
* You can use SDL_GetPropertyType() to query whether the property exists and * You can use SDL_GetPropertyType() to query whether the property exists and
* is a floating point property. * is a floating point property.
* *
* \param props the properties to query * \param props the properties to query.
* \param name the name of the property to query * \param name the name of the property to query.
* \param default_value the default value of the property * \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or * \returns the value of the property, or `default_value` if it is not set or
* not a float property. * not a float property.
* *
@@ -428,9 +428,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c
* You can use SDL_GetPropertyType() to query whether the property exists and * You can use SDL_GetPropertyType() to query whether the property exists and
* is a boolean property. * is a boolean property.
* *
* \param props the properties to query * \param props the properties to query.
* \param name the name of the property to query * \param name the name of the property to query.
* \param default_value the default value of the property * \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or * \returns the value of the property, or `default_value` if it is not set or
* not a float property. * not a float property.
* *
@@ -447,8 +447,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID pro
/** /**
* Clear a property on a set of properties. * Clear a property on a set of properties.
* *
* \param props the properties to modify * \param props the properties to modify.
* \param name the name of the property to clear * \param name the name of the property to clear.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -483,9 +483,9 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop
* The callback function is called for each property on the set of properties. * The callback function is called for each property on the set of properties.
* The properties are locked during enumeration. * The properties are locked during enumeration.
* *
* \param props the properties to query * \param props the properties to query.
* \param callback the function to call for each property * \param callback the function to call for each property.
* \param userdata a pointer that is passed to `callback` * \param userdata a pointer that is passed to `callback`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -501,7 +501,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props,
* All properties are deleted and their cleanup functions will be called, if * All properties are deleted and their cleanup functions will be called, if
* any. * any.
* *
* \param props the properties to destroy * \param props the properties to destroy.
* *
* \threadsafety This function should not be called while these properties are * \threadsafety This function should not be called while these properties are
* locked or other threads might be setting or getting values * locked or other threads might be setting or getting values

68
include/SDL3/SDL_rect.h
View File

@@ -192,8 +192,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
* *
* If either pointer is NULL the function will return SDL_FALSE. * If either pointer is NULL the function will return SDL_FALSE.
* *
* \param A an SDL_Rect structure representing the first rectangle * \param A an SDL_Rect structure representing the first rectangle.
* \param B an SDL_Rect structure representing the second rectangle * \param B an SDL_Rect structure representing the second rectangle.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -210,10 +210,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect * A,
* *
* If `result` is NULL then this function will return SDL_FALSE. * If `result` is NULL then this function will return SDL_FALSE.
* *
* \param A an SDL_Rect structure representing the first rectangle * \param A an SDL_Rect structure representing the first rectangle.
* \param B an SDL_Rect structure representing the second rectangle * \param B an SDL_Rect structure representing the second rectangle.
* \param result an SDL_Rect structure filled in with the intersection of * \param result an SDL_Rect structure filled in with the intersection of
* rectangles `A` and `B` * rectangles `A` and `B`.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -227,10 +227,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect * A,
/** /**
* Calculate the union of two rectangles. * Calculate the union of two rectangles.
* *
* \param A an SDL_Rect structure representing the first rectangle * \param A an SDL_Rect structure representing the first rectangle.
* \param B an SDL_Rect structure representing the second rectangle * \param B an SDL_Rect structure representing the second rectangle.
* \param result an SDL_Rect structure filled in with the union of rectangles * \param result an SDL_Rect structure filled in with the union of rectangles
* `A` and `B` * `A` and `B`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -247,11 +247,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnion(const SDL_Rect * A,
* considered. * considered.
* *
* \param points an array of SDL_Point structures representing points to be * \param points an array of SDL_Point structures representing points to be
* enclosed * enclosed.
* \param count the number of structures in the `points` array * \param count the number of structures in the `points` array.
* \param clip an SDL_Rect used for clipping or NULL to enclose all points * \param clip an SDL_Rect used for clipping or NULL to enclose all points.
* \param result an SDL_Rect structure filled in with the minimal enclosing * \param result an SDL_Rect structure filled in with the minimal enclosing
* rectangle * rectangle.
* \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
* points were outside of the clipping rectangle. * points were outside of the clipping rectangle.
* *
@@ -271,11 +271,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point
* both ends will be clipped to the boundary of the rectangle and the new * both ends will be clipped to the boundary of the rectangle and the new
* coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
* *
* \param rect an SDL_Rect structure representing the rectangle to intersect * \param rect an SDL_Rect structure representing the rectangle to intersect.
* \param X1 a pointer to the starting X-coordinate of the line * \param X1 a pointer to the starting X-coordinate of the line.
* \param Y1 a pointer to the starting Y-coordinate of the line * \param Y1 a pointer to the starting Y-coordinate of the line.
* \param X2 a pointer to the ending X-coordinate of the line * \param X2 a pointer to the ending X-coordinate of the line.
* \param Y2 a pointer to the ending Y-coordinate of the line * \param Y2 a pointer to the ending Y-coordinate of the line.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -408,8 +408,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec
* *
* If either pointer is NULL the function will return SDL_FALSE. * If either pointer is NULL the function will return SDL_FALSE.
* *
* \param A an SDL_FRect structure representing the first rectangle * \param A an SDL_FRect structure representing the first rectangle.
* \param B an SDL_FRect structure representing the second rectangle * \param B an SDL_FRect structure representing the second rectangle.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -424,10 +424,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRec
* *
* If `result` is NULL then this function will return SDL_FALSE. * If `result` is NULL then this function will return SDL_FALSE.
* *
* \param A an SDL_FRect structure representing the first rectangle * \param A an SDL_FRect structure representing the first rectangle.
* \param B an SDL_FRect structure representing the second rectangle * \param B an SDL_FRect structure representing the second rectangle.
* \param result an SDL_FRect structure filled in with the intersection of * \param result an SDL_FRect structure filled in with the intersection of
* rectangles `A` and `B` * rectangles `A` and `B`.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -441,10 +441,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec
/** /**
* Calculate the union of two rectangles with float precision. * Calculate the union of two rectangles with float precision.
* *
* \param A an SDL_FRect structure representing the first rectangle * \param A an SDL_FRect structure representing the first rectangle.
* \param B an SDL_FRect structure representing the second rectangle * \param B an SDL_FRect structure representing the second rectangle.
* \param result an SDL_FRect structure filled in with the union of rectangles * \param result an SDL_FRect structure filled in with the union of rectangles
* `A` and `B` * `A` and `B`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -462,11 +462,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A,
* considered. * considered.
* *
* \param points an array of SDL_FPoint structures representing points to be * \param points an array of SDL_FPoint structures representing points to be
* enclosed * enclosed.
* \param count the number of structures in the `points` array * \param count the number of structures in the `points` array.
* \param clip an SDL_FRect used for clipping or NULL to enclose all points * \param clip an SDL_FRect used for clipping or NULL to enclose all points.
* \param result an SDL_FRect structure filled in with the minimal enclosing * \param result an SDL_FRect structure filled in with the minimal enclosing
* rectangle * rectangle.
* \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
* points were outside of the clipping rectangle. * points were outside of the clipping rectangle.
* *
@@ -487,11 +487,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F
* both ends will be clipped to the boundary of the rectangle and the new * both ends will be clipped to the boundary of the rectangle and the new
* coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
* *
* \param rect an SDL_FRect structure representing the rectangle to intersect * \param rect an SDL_FRect structure representing the rectangle to intersect.
* \param X1 a pointer to the starting X-coordinate of the line * \param X1 a pointer to the starting X-coordinate of the line.
* \param Y1 a pointer to the starting Y-coordinate of the line * \param Y1 a pointer to the starting Y-coordinate of the line.
* \param X2 a pointer to the ending X-coordinate of the line * \param X2 a pointer to the ending X-coordinate of the line.
* \param Y2 a pointer to the ending Y-coordinate of the line * \param Y2 a pointer to the ending Y-coordinate of the line.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

470
include/SDL3/SDL_render.h
View File

File diff suppressed because it is too large Load Diff

36
include/SDL3/SDL_sensor.h
View File

@@ -146,7 +146,7 @@ typedef enum SDL_SensorType
/** /**
* Get a list of currently connected sensors. * Get a list of currently connected sensors.
* *
* \param count a pointer filled in with the number of sensors returned * \param count a pointer filled in with the number of sensors returned.
* \returns a 0 terminated array of sensor instance IDs which should be freed * \returns a 0 terminated array of sensor instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more * with SDL_free(), or NULL on error; call SDL_GetError() for more
* details. * details.
@@ -160,8 +160,8 @@ extern SDL_DECLSPEC SDL_SensorID *SDLCALL SDL_GetSensors(int *count);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id the sensor instance ID * \param instance_id the sensor instance ID.
* \returns the sensor name, or NULL if `instance_id` is not valid * \returns the sensor name, or NULL if `instance_id` is not valid.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -170,9 +170,9 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetSensorInstanceName(SDL_SensorID i
/** /**
* Get the type of a sensor. * Get the type of a sensor.
* *
* \param instance_id the sensor instance ID * \param instance_id the sensor instance ID.
* \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is
* not valid * not valid.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -181,9 +181,9 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorInstanceType(SDL_SensorI
/** /**
* Get the platform dependent type of a sensor. * Get the platform dependent type of a sensor.
* *
* \param instance_id the sensor instance ID * \param instance_id the sensor instance ID.
* \returns the sensor platform dependent type, or -1 if `instance_id` is not * \returns the sensor platform dependent type, or -1 if `instance_id` is not
* valid * valid.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -192,7 +192,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorInstanceNonPortableType(SDL_SensorI
/** /**
* Open a sensor for use. * Open a sensor for use.
* *
* \param instance_id the sensor instance ID * \param instance_id the sensor instance ID.
* \returns an SDL_Sensor sensor object, or NULL if an error occurred. * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -202,7 +202,7 @@ extern SDL_DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(SDL_SensorID instance_id)
/** /**
* Return the SDL_Sensor associated with an instance ID. * Return the SDL_Sensor associated with an instance ID.
* *
* \param instance_id the sensor instance ID * \param instance_id the sensor instance ID.
* \returns an SDL_Sensor object. * \returns an SDL_Sensor object.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -212,7 +212,7 @@ extern SDL_DECLSPEC SDL_Sensor *SDLCALL SDL_GetSensorFromInstanceID(SDL_SensorID
/** /**
* Get the properties associated with a sensor. * Get the properties associated with a sensor.
* *
* \param sensor The SDL_Sensor object * \param sensor the SDL_Sensor object.
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -228,7 +228,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param sensor The SDL_Sensor object * \param sensor the SDL_Sensor object.
* \returns the sensor name, or NULL if `sensor` is NULL. * \returns the sensor name, or NULL if `sensor` is NULL.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -238,7 +238,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetSensorName(SDL_Sensor *sensor);
/** /**
* Get the type of a sensor. * Get the type of a sensor.
* *
* \param sensor The SDL_Sensor object to inspect * \param sensor the SDL_Sensor object to inspect.
* \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
* NULL. * NULL.
* *
@@ -249,7 +249,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor)
/** /**
* Get the platform dependent type of a sensor. * Get the platform dependent type of a sensor.
* *
* \param sensor The SDL_Sensor object to inspect * \param sensor the SDL_Sensor object to inspect.
* \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -259,7 +259,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor)
/** /**
* Get the instance ID of a sensor. * Get the instance ID of a sensor.
* *
* \param sensor The SDL_Sensor object to inspect * \param sensor the SDL_Sensor object to inspect.
* \returns the sensor instance ID, or 0 if `sensor` is NULL. * \returns the sensor instance ID, or 0 if `sensor` is NULL.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -271,9 +271,9 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorInstanceID(SDL_Sensor *sen
* *
* The number of values and interpretation of the data is sensor dependent. * The number of values and interpretation of the data is sensor dependent.
* *
* \param sensor The SDL_Sensor object to query * \param sensor the SDL_Sensor object to query.
* \param data A pointer filled with the current sensor state * \param data a pointer filled with the current sensor state.
* \param num_values The number of values to write to data * \param num_values the number of values to write to data.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -284,7 +284,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *dat
/** /**
* Close a sensor previously opened with SDL_OpenSensor(). * Close a sensor previously opened with SDL_OpenSensor().
* *
* \param sensor The SDL_Sensor object to close * \param sensor the SDL_Sensor object to close.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */

242
include/SDL3/SDL_stdinc.h
View File

@@ -509,10 +509,10 @@ typedef void (SDLCALL *SDL_free_func)(void *mem);
* runtime's `malloc` functions behind the scenes! Different platforms and * runtime's `malloc` functions behind the scenes! Different platforms and
* build configurations might do any number of unexpected things. * build configurations might do any number of unexpected things.
* *
* \param malloc_func filled with malloc function * \param malloc_func filled with malloc function.
* \param calloc_func filled with calloc function * \param calloc_func filled with calloc function.
* \param realloc_func filled with realloc function * \param realloc_func filled with realloc function.
* \param free_func filled with free function * \param free_func filled with free function.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -526,10 +526,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func
/** /**
* Get the current set of SDL memory functions. * Get the current set of SDL memory functions.
* *
* \param malloc_func filled with malloc function * \param malloc_func filled with malloc function.
* \param calloc_func filled with calloc function * \param calloc_func filled with calloc function.
* \param realloc_func filled with realloc function * \param realloc_func filled with realloc function.
* \param free_func filled with free function * \param free_func filled with free function.
* *
* \threadsafety This does not hold a lock, so do not call this in the * \threadsafety This does not hold a lock, so do not call this in the
* unlikely event of a background thread calling * unlikely event of a background thread calling
@@ -555,10 +555,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_
* If used, usually this needs to be the first call made into the SDL library, * If used, usually this needs to be the first call made into the SDL library,
* if not the very first thing done at program startup time. * if not the very first thing done at program startup time.
* *
* \param malloc_func custom malloc function * \param malloc_func custom malloc function.
* \param calloc_func custom calloc function * \param calloc_func custom calloc function.
* \param realloc_func custom realloc function * \param realloc_func custom realloc function.
* \param free_func custom free function * \param free_func custom free function.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -588,9 +588,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_fu
* The memory returned by this function must be freed with SDL_aligned_free(), * The memory returned by this function must be freed with SDL_aligned_free(),
* and _not_ SDL_free. * and _not_ SDL_free.
* *
* \param alignment the alignment requested * \param alignment the alignment requested.
* \param size the size to allocate * \param size the size to allocate.
* \returns a pointer to the aligned memory * \returns a pointer to the aligned memory.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -619,7 +619,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem);
/** /**
* Get the number of outstanding (unfreed) allocations. * Get the number of outstanding (unfreed) allocations.
* *
* \returns the number of allocations * \returns the number of allocations.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -940,8 +940,8 @@ extern SDL_DECLSPEC wchar_t *SDLCALL SDL_wcsnstr(const wchar_t *haystack, const
* character; it does not care if the string is well-formed UTF-16 (or UTF-32, * character; it does not care if the string is well-formed UTF-16 (or UTF-32,
* depending on your platform's wchar_t size), or uses valid Unicode values. * depending on your platform's wchar_t size), or uses valid Unicode values.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -970,9 +970,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *s
* null-terminator character before this count), they will be considered * null-terminator character before this count), they will be considered
* equal. * equal.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \param maxlen The maximum number of wchar_t to compare. * \param maxlen the maximum number of wchar_t to compare.
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -1001,8 +1001,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *
* CHARACTER), which is to say two strings of random bits may turn out to * CHARACTER), which is to say two strings of random bits may turn out to
* match if they convert to the same amount of replacement characters. * match if they convert to the same amount of replacement characters.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -1042,9 +1042,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_
* null-terminator character before this number of bytes), they will be * null-terminator character before this number of bytes), they will be
* considered equal. * considered equal.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \param maxlen The maximum number of wchar_t values to compare. * \param maxlen the maximum number of wchar_t values to compare.
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -1076,7 +1076,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strrev(char *str);
* malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their * malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their
* uppercase equivalents in-place, returning the original `str` pointer. * uppercase equivalents in-place, returning the original `str` pointer.
* *
* \param str The string to convert in-place. Can not be NULL. * \param str the string to convert in-place. Can not be NULL.
* \returns the `str` pointer passed into this function. * \returns the `str` pointer passed into this function.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -1097,7 +1097,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strupr(char *str);
* malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their * malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their
* lowercase equivalents in-place, returning the original `str` pointer. * lowercase equivalents in-place, returning the original `str` pointer.
* *
* \param str The string to convert in-place. Can not be NULL. * \param str the string to convert in-place. Can not be NULL.
* \returns the `str` pointer passed into this function. * \returns the `str` pointer passed into this function.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@@ -1140,8 +1140,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp);
* null-terminating character. Also due to the nature of UTF-8, this can be * null-terminating character. Also due to the nature of UTF-8, this can be
* used with SDL_qsort() to put strings in (roughly) alphabetical order. * used with SDL_qsort() to put strings in (roughly) alphabetical order.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -1169,9 +1169,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2);
* match to this number of bytes (or both have matched to a null-terminator * match to this number of bytes (or both have matched to a null-terminator
* character before this number of bytes), they will be considered equal. * character before this number of bytes), they will be considered equal.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \param maxlen The maximum number of _bytes_ to compare. * \param maxlen the maximum number of _bytes_ to compare.
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -1198,8 +1198,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2,
* CHARACTER), which is to say two strings of random bits may turn out to * CHARACTER), which is to say two strings of random bits may turn out to
* match if they convert to the same amount of replacement characters. * match if they convert to the same amount of replacement characters.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -1237,9 +1237,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str
* match to this number of bytes (or both have matched to a null-terminator * match to this number of bytes (or both have matched to a null-terminator
* character before this number of bytes), they will be considered equal. * character before this number of bytes), they will be considered equal.
* *
* \param str1 The first string to compare. NULL is not permitted! * \param str1 the first string to compare. NULL is not permitted!
* \param str2 The second string to compare. NULL is not permitted! * \param str2 the second string to compare. NULL is not permitted!
* \param maxlen The maximum number of bytes to compare. * \param maxlen the maximum number of bytes to compare.
* \returns less than zero if str1 is "less than" str2, greater than zero if * \returns less than zero if str1 is "less than" str2, greater than zero if
* str1 is "greater than" str2, and zero if the strings match * str1 is "greater than" str2, and zero if the strings match
* exactly. * exactly.
@@ -1283,8 +1283,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STR
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value * \param x floating point value.
* \returns arc cosine of `x`, in radians * \returns arc cosine of `x`, in radians.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1314,7 +1314,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x);
* updated. * updated.
* *
* \param x floating point value. * \param x floating point value.
* \returns arc cosine of `x`, in radians * \returns arc cosine of `x`, in radians.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1438,7 +1438,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x);
* updated. * updated.
* *
* \param x floating point value. * \param x floating point value.
* \returns arc tangent of of `x` in radians, or 0 if `x = 0` * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1471,7 +1471,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param y floating point value of the numerator (y coordinate) * \param y floating point value of the numerator (y coordinate).
* \param x floating point value of the denominator (x coordinate). * \param x floating point value of the denominator (x coordinate).
* \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
* `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`. * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
@@ -1507,7 +1507,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param y floating point value of the numerator (y coordinate) * \param y floating point value of the numerator (y coordinate).
* \param x floating point value of the denominator (x coordinate). * \param x floating point value of the denominator (x coordinate).
* \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
* `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`. * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
@@ -1535,8 +1535,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_ceilf for single-precision floats. * SDL_ceilf for single-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \returns the ceiling of `x` * \returns the ceiling of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1563,8 +1563,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_ceil for double-precision floats. * SDL_ceil for double-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \returns the ceiling of `x` * \returns the ceiling of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1590,9 +1590,10 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_copysignf for single-precision floats. * SDL_copysignf for single-precision floats.
* *
* \param x floating point value to use as the magnitude * \param x floating point value to use as the magnitude.
* \param y floating point value to use as the sign * \param y floating point value to use as the sign.
* \returns the floating point value with the sign of y and the magnitude of x * \returns the floating point value with the sign of y and the magnitude of
* x.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1615,9 +1616,10 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_copysign for double-precision floats. * SDL_copysign for double-precision floats.
* *
* \param x floating point value to use as the magnitude * \param x floating point value to use as the magnitude.
* \param y floating point value to use as the sign * \param y floating point value to use as the sign.
* \returns the floating point value with the sign of y and the magnitude of x * \returns the floating point value with the sign of y and the magnitude of
* x.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1643,8 +1645,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value, in radians * \param x floating point value, in radians.
* \returns cosine of `x` * \returns cosine of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1671,8 +1673,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value, in radians * \param x floating point value, in radians.
* \returns cosine of `x` * \returns cosine of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1704,8 +1706,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value * \param x floating point value.
* \returns value of `e^x` * \returns value of `e^x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1736,8 +1738,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value * \param x floating point value.
* \returns value of `e^x` * \returns value of `e^x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1758,8 +1760,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_copysignf for single-precision floats. * SDL_copysignf for single-precision floats.
* *
* \param x floating point value to use as the magnitude * \param x floating point value to use as the magnitude.
* \returns the absolute value of `x` * \returns the absolute value of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1779,8 +1781,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_copysignf for double-precision floats. * SDL_copysignf for double-precision floats.
* *
* \param x floating point value to use as the magnitude * \param x floating point value to use as the magnitude.
* \returns the absolute value of `x` * \returns the absolute value of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1803,8 +1805,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_floorf for single-precision floats. * SDL_floorf for single-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \returns the floor of `x` * \returns the floor of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1831,8 +1833,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_floorf for double-precision floats. * SDL_floorf for double-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \returns the floor of `x` * \returns the floor of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1859,8 +1861,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_truncf for single-precision floats. * SDL_truncf for single-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \returns `x` truncated to an integer * \returns `x` truncated to an integer.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1888,8 +1890,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_truncf for double-precision floats. * SDL_truncf for double-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \returns `x` truncated to an integer * \returns `x` truncated to an integer.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1916,9 +1918,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_fmodf for single-precision floats. * SDL_fmodf for single-precision floats.
* *
* \param x the numerator * \param x the numerator.
* \param y the denominator. Must not be 0. * \param y the denominator. Must not be 0.
* \returns the remainder of `x / y` * \returns the remainder of `x / y`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1946,9 +1948,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_fmod for single-precision floats. * SDL_fmod for single-precision floats.
* *
* \param x the numerator * \param x the numerator.
* \param y the denominator. Must not be 0. * \param y the denominator. Must not be 0.
* \returns the remainder of `x / y` * \returns the remainder of `x / y`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -1982,7 +1984,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y);
* updated. * updated.
* *
* \param x floating point value. Must be greater than 0. * \param x floating point value. Must be greater than 0.
* \returns the natural logarithm of `x` * \returns the natural logarithm of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2012,7 +2014,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x);
* updated. * updated.
* *
* \param x floating point value. Must be greater than 0. * \param x floating point value. Must be greater than 0.
* \returns the natural logarithm of `x` * \returns the natural logarithm of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2041,7 +2043,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x);
* updated. * updated.
* *
* \param x floating point value. Must be greater than 0. * \param x floating point value. Must be greater than 0.
* \returns the logarithm of `x` * \returns the logarithm of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2071,7 +2073,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x);
* updated. * updated.
* *
* \param x floating point value. Must be greater than 0. * \param x floating point value. Must be greater than 0.
* \returns the logarithm of `x` * \returns the logarithm of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2089,9 +2091,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_modff for single-precision floats. * SDL_modff for single-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \param y output pointer to store the integer part of `x` * \param y output pointer to store the integer part of `x`.
* \returns the fractional part of `x` * \returns the fractional part of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2109,9 +2111,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_modf for double-precision floats. * SDL_modf for double-precision floats.
* *
* \param x floating point value * \param x floating point value.
* \param y output pointer to store the integer part of `x` * \param y output pointer to store the integer part of `x`.
* \returns the fractional part of `x` * \returns the fractional part of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2141,9 +2143,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x the base * \param x the base.
* \param y the exponent * \param y the exponent.
* \returns `x` raised to the power `y` * \returns `x` raised to the power `y`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2173,9 +2175,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x the base * \param x the base.
* \param y the exponent * \param y the exponent.
* \returns `x` raised to the power `y` * \returns `x` raised to the power `y`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2201,8 +2203,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y);
* SDL_roundf for single-precision floats. To get the result as an integer * SDL_roundf for single-precision floats. To get the result as an integer
* type, use SDL_lround. * type, use SDL_lround.
* *
* \param x floating point value * \param x floating point value.
* \returns the nearest integer to `x` * \returns the nearest integer to `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2230,8 +2232,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x);
* SDL_roundf for single-precision floats. To get the result as an integer * SDL_roundf for single-precision floats. To get the result as an integer
* type, use SDL_lroundf. * type, use SDL_lroundf.
* *
* \param x floating point value * \param x floating point value.
* \returns the nearest integer to `x` * \returns the nearest integer to `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2259,8 +2261,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x);
* SDL_lround for single-precision floats. To get the result as a * SDL_lround for single-precision floats. To get the result as a
* floating-point type, use SDL_round. * floating-point type, use SDL_round.
* *
* \param x floating point value * \param x floating point value.
* \returns the nearest integer to `x` * \returns the nearest integer to `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2288,8 +2290,8 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x);
* SDL_lroundf for double-precision floats. To get the result as a * SDL_lroundf for double-precision floats. To get the result as a
* floating-point type, use SDL_roundf, * floating-point type, use SDL_roundf,
* *
* \param x floating point value * \param x floating point value.
* \returns the nearest integer to `x` * \returns the nearest integer to `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2315,9 +2317,9 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x);
* This function operates on double-precision floating point values, use * This function operates on double-precision floating point values, use
* SDL_scalbnf for single-precision floats. * SDL_scalbnf for single-precision floats.
* *
* \param x floating point value to be scaled * \param x floating point value to be scaled.
* \param n integer exponent * \param n integer exponent.
* \returns `x * 2^n` * \returns `x * 2^n`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2340,9 +2342,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
* This function operates on single-precision floating point values, use * This function operates on single-precision floating point values, use
* SDL_scalbn for double-precision floats. * SDL_scalbn for double-precision floats.
* *
* \param x floating point value to be scaled * \param x floating point value to be scaled.
* \param n integer exponent * \param n integer exponent.
* \returns `x * 2^n` * \returns `x * 2^n`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2368,8 +2370,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value, in radians * \param x floating point value, in radians.
* \returns sine of `x` * \returns sine of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2396,8 +2398,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value, in radians * \param x floating point value, in radians.
* \returns sine of `x` * \returns sine of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2425,7 +2427,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x);
* updated. * updated.
* *
* \param x floating point value. Must be greater than or equal to 0. * \param x floating point value. Must be greater than or equal to 0.
* \returns square root of `x` * \returns square root of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2451,7 +2453,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x);
* updated. * updated.
* *
* \param x floating point value. Must be greater than or equal to 0. * \param x floating point value. Must be greater than or equal to 0.
* \returns square root of `x` * \returns square root of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2476,8 +2478,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value, in radians * \param x floating point value, in radians.
* \returns tangent of `x` * \returns tangent of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2506,8 +2508,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x);
* the same input on different machines or operating systems, or if SDL is * the same input on different machines or operating systems, or if SDL is
* updated. * updated.
* *
* \param x floating point value, in radians * \param x floating point value, in radians.
* \returns tangent of `x` * \returns tangent of `x`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@@ -2641,8 +2643,8 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size);
* *
* Otherwise store `a * b` via ret and return 0. * Otherwise store `a * b` via ret and return 0.
* *
* \param a the multiplicand * \param a the multiplicand.
* \param b the multiplier * \param b the multiplier.
* \param ret on non-overflow output, stores the multiplication result. May * \param ret on non-overflow output, stores the multiplication result. May
* not be NULL. * not be NULL.
* \returns -1 on overflow, 0 if result doesn't overflow. * \returns -1 on overflow, 0 if result doesn't overflow.

80
include/SDL3/SDL_storage.h
View File

@@ -101,8 +101,8 @@ typedef struct SDL_Storage SDL_Storage;
/** /**
* Opens up a read-only container for the application's filesystem. * Opens up a read-only container for the application's filesystem.
* *
* \param override a path to override the backend's default title root * \param override a path to override the backend's default title root.
* \param props a property list that may contain backend-specific information * \param props a property list that may contain backend-specific information.
* \returns a title storage container on success or NULL on failure; call * \returns a title storage container on success or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -123,9 +123,9 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenTitleStorage(const char *overri
* This allows the backend to properly batch file operations and flush them * This allows the backend to properly batch file operations and flush them
* when the container has been closed; ensuring safe and optimal save I/O. * when the container has been closed; ensuring safe and optimal save I/O.
* *
* \param org the name of your organization * \param org the name of your organization.
* \param app the name of your application * \param app the name of your application.
* \param props a property list that may contain backend-specific information * \param props a property list that may contain backend-specific information.
* \returns a user storage container on success or NULL on failure; call * \returns a user storage container on success or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -149,7 +149,7 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenUserStorage(const char *org, co
* SDL_OpenUserStorage() for access to user data. * SDL_OpenUserStorage() for access to user data.
* *
* \param path the base path prepended to all storage paths, or NULL for no * \param path the base path prepended to all storage paths, or NULL for no
* base path * base path.
* \returns a filesystem storage container on success or NULL on failure; call * \returns a filesystem storage container on success or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -173,8 +173,8 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenFileStorage(const char *path);
* should use the built-in implementations in SDL, like SDL_OpenTitleStorage() * should use the built-in implementations in SDL, like SDL_OpenTitleStorage()
* or SDL_OpenUserStorage(). * or SDL_OpenUserStorage().
* *
* \param iface the function table to be used by this container * \param iface the function table to be used by this container.
* \param userdata the pointer that will be passed to the store interface * \param userdata the pointer that will be passed to the store interface.
* \returns a storage container on success or NULL on failure; call * \returns a storage container on success or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -192,7 +192,7 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenStorage(const SDL_StorageInterf
/** /**
* Closes and frees a storage container. * Closes and frees a storage container.
* *
* \param storage a storage container to close * \param storage a storage container to close.
* \returns 0 if the container was freed with no errors, a negative value * \returns 0 if the container was freed with no errors, a negative value
* otherwise; call SDL_GetError() for more information. Even if the * otherwise; call SDL_GetError() for more information. Even if the
* function returns an error, the container data will be freed; the * function returns an error, the container data will be freed; the
@@ -214,8 +214,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_CloseStorage(SDL_Storage *storage);
* SDL_TRUE - however, it is not recommended to spinwait on this call, as the * SDL_TRUE - however, it is not recommended to spinwait on this call, as the
* backend may depend on a synchronous message loop. * backend may depend on a synchronous message loop.
* *
* \param storage a storage container to query * \param storage a storage container to query.
* \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -224,9 +224,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
/** /**
* Query the size of a file within a storage container. * Query the size of a file within a storage container.
* *
* \param storage a storage container to query * \param storage a storage container to query.
* \param path the relative path of the file to query * \param path the relative path of the file to query.
* \param length a pointer to be filled with the file's length * \param length a pointer to be filled with the file's length.
* \returns 0 if the file could be queried, a negative value otherwise; call * \returns 0 if the file could be queried, a negative value otherwise; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -241,10 +241,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, con
* Synchronously read a file from a storage container into a client-provided * Synchronously read a file from a storage container into a client-provided
* buffer. * buffer.
* *
* \param storage a storage container to read from * \param storage a storage container to read from.
* \param path the relative path of the file to read * \param path the relative path of the file to read.
* \param destination a client-provided buffer to read the file into * \param destination a client-provided buffer to read the file into.
* \param length the length of the destination buffer * \param length the length of the destination buffer.
* \returns 0 if the file was read, a negative value otherwise; call * \returns 0 if the file was read, a negative value otherwise; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -259,10 +259,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const
/** /**
* Synchronously write a file from client memory into a storage container. * Synchronously write a file from client memory into a storage container.
* *
* \param storage a storage container to write to * \param storage a storage container to write to.
* \param path the relative path of the file to write * \param path the relative path of the file to write.
* \param source a client-provided buffer to write from * \param source a client-provided buffer to write from.
* \param length the length of the source buffer * \param length the length of the source buffer.
* \returns 0 if the file was written, a negative value otherwise; call * \returns 0 if the file was written, a negative value otherwise; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -277,8 +277,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const
/** /**
* Create a directory in a writable storage container. * Create a directory in a writable storage container.
* *
* \param storage a storage container * \param storage a storage container.
* \param path the path of the directory to create * \param path the path of the directory to create.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -295,10 +295,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage,
* callback, called once for each directory entry, until all results have been * callback, called once for each directory entry, until all results have been
* provided or the callback returns <= 0. * provided or the callback returns <= 0.
* *
* \param storage a storage container * \param storage a storage container.
* \param path the path of the directory to enumerate * \param path the path of the directory to enumerate.
* \param callback a function that is called for each entry in the directory * \param callback a function that is called for each entry in the directory.
* \param userdata a pointer that is passed to `callback` * \param userdata a pointer that is passed to `callback`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -311,8 +311,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *stora
/** /**
* Remove a file or an empty directory in a writable storage container. * Remove a file or an empty directory in a writable storage container.
* *
* \param storage a storage container * \param storage a storage container.
* \param path the path of the directory to enumerate * \param path the path of the directory to enumerate.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -325,9 +325,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, cons
/** /**
* Rename a file or directory in a writable storage container. * Rename a file or directory in a writable storage container.
* *
* \param storage a storage container * \param storage a storage container.
* \param oldpath the old path * \param oldpath the old path.
* \param newpath the new path * \param newpath the new path.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -340,10 +340,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, cons
/** /**
* Get information about a filesystem path in a storage container. * Get information about a filesystem path in a storage container.
* *
* \param storage a storage container * \param storage a storage container.
* \param path the path to query * \param path the path to query.
* \param info a pointer filled in with information about the path, or NULL to * \param info a pointer filled in with information about the path, or NULL to
* check for the existence of a file * check for the existence of a file.
* \returns 0 on success or a negative error code if the file doesn't exist, * \returns 0 on success or a negative error code if the file doesn't exist,
* or another failure; call SDL_GetError() for more information. * or another failure; call SDL_GetError() for more information.
* *
@@ -356,8 +356,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, con
/** /**
* Queries the remaining space in a storage container. * Queries the remaining space in a storage container.
* *
* \param storage a storage container to query * \param storage a storage container to query.
* \returns the amount of remaining space, in bytes * \returns the amount of remaining space, in bytes.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -385,8 +385,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto
* *
* You must free the returned pointer with SDL_free() when done with it. * You must free the returned pointer with SDL_free() when done with it.
* *
* \param storage a storage container * \param storage a storage container.
* \param path the path of the directory to enumerate * \param path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be * \param pattern the pattern that files in the directory must match. Can be
* NULL. * NULL.
* \param flags `SDL_GLOB_*` bitflags that affect this search. * \param flags `SDL_GLOB_*` bitflags that affect this search.

251
include/SDL3/SDL_surface.h
View File

@@ -145,8 +145,8 @@ typedef struct SDL_Surface
/** /**
* Allocate a new RGB surface with a specific pixel format. * Allocate a new RGB surface with a specific pixel format.
* *
* \param width the width of the surface * \param width the width of the surface.
* \param height the height of the surface * \param height the height of the surface.
* \param format the SDL_PixelFormatEnum for the new surface's pixel format. * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
* \returns the new SDL_Surface structure that is created or NULL if it fails; * \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
@@ -171,10 +171,10 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height
* You may pass NULL for pixels and 0 for pitch to create a surface that you * You may pass NULL for pixels and 0 for pitch to create a surface that you
* will fill in with valid values later. * will fill in with valid values later.
* *
* \param pixels a pointer to existing pixel data * \param pixels a pointer to existing pixel data.
* \param width the width of the surface * \param width the width of the surface.
* \param height the height of the surface * \param height the height of the surface.
* \param pitch the number of bytes between each row, including padding * \param pitch the number of bytes between each row, including padding.
* \param format the SDL_PixelFormatEnum for the new surface's pixel format. * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
* \returns the new SDL_Surface structure that is created or NULL if it fails; * \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
@@ -225,7 +225,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface);
* where N is a floating point scale factor applied in linear space, and * where N is a floating point scale factor applied in linear space, and
* "none", which disables tone mapping. This defaults to "chrome". * "none", which disables tone mapping. This defaults to "chrome".
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -247,8 +247,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac
* Setting the colorspace doesn't change the pixels, only how they are * Setting the colorspace doesn't change the pixels, only how they are
* interpreted in color operations. * interpreted in color operations.
* *
* \param surface the SDL_Surface structure to update * \param surface the SDL_Surface structure to update.
* \param colorspace an SDL_ColorSpace value describing the surface colorspace * \param colorspace an SDL_ColorSpace value describing the surface
* colorspace.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -263,9 +264,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, S
* formats, SDL_COLORSPACE_HDR10 for 10-bit formats, SDL_COLORSPACE_SRGB for * formats, SDL_COLORSPACE_HDR10 for 10-bit formats, SDL_COLORSPACE_SRGB for
* other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures. * other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures.
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \param colorspace a pointer filled in with an SDL_ColorSpace value * \param colorspace a pointer filled in with an SDL_ColorSpace value
* describing the surface colorspace * describing the surface colorspace.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -278,8 +279,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorspace(SDL_Surface *surface, S
* *
* A single palette can be shared with many surfaces. * A single palette can be shared with many surfaces.
* *
* \param surface the SDL_Surface structure to update * \param surface the SDL_Surface structure to update.
* \param palette the SDL_Palette structure to use * \param palette the SDL_Palette structure to use.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -299,7 +300,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_
* 0, then you can read and write to the surface at any time, and the pixel * 0, then you can read and write to the surface at any time, and the pixel
* format of the surface will not change. * format of the surface will not change.
* *
* \param surface the SDL_Surface structure to be locked * \param surface the SDL_Surface structure to be locked.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -313,7 +314,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
/** /**
* Release a surface after directly accessing the pixels. * Release a surface after directly accessing the pixels.
* *
* \param surface the SDL_Surface structure to be unlocked * \param surface the SDL_Surface structure to be unlocked.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -327,9 +328,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
* The new surface should be freed with SDL_DestroySurface(). Not doing so * The new surface should be freed with SDL_DestroySurface(). Not doing so
* will result in a memory leak. * will result in a memory leak.
* *
* \param src the data stream for the surface * \param src the data stream for the surface.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error * even in the case of an error.
* \returns a pointer to a new SDL_Surface structure or NULL if there was an * \returns a pointer to a new SDL_Surface structure or NULL if there was an
* error; call SDL_GetError() for more information. * error; call SDL_GetError() for more information.
* *
@@ -347,7 +348,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_b
* The new surface should be freed with SDL_DestroySurface(). Not doing so * The new surface should be freed with SDL_DestroySurface(). Not doing so
* will result in a memory leak. * will result in a memory leak.
* *
* \param file the BMP file to load * \param file the BMP file to load.
* \returns a pointer to a new SDL_Surface structure or NULL if there was an * \returns a pointer to a new SDL_Surface structure or NULL if there was an
* error; call SDL_GetError() for more information. * error; call SDL_GetError() for more information.
* *
@@ -368,10 +369,10 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP(const char *file);
* surface before they are saved. YUV and paletted 1-bit and 4-bit formats are * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
* not supported. * not supported.
* *
* \param surface the SDL_Surface structure containing the image to be saved * \param surface the SDL_Surface structure containing the image to be saved.
* \param dst a data stream to save to * \param dst a data stream to save to.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning, * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning,
* even in the case of an error * even in the case of an error.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -391,8 +392,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStrea
* surface before they are saved. YUV and paletted 1-bit and 4-bit formats are * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
* not supported. * not supported.
* *
* \param surface the SDL_Surface structure containing the image to be saved * \param surface the SDL_Surface structure containing the image to be saved.
* \param file a file to save to * \param file a file to save to.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -409,8 +410,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *fi
* If RLE is enabled, color key and alpha blending blits are much faster, but * If RLE is enabled, color key and alpha blending blits are much faster, but
* the surface must be locked before directly accessing the pixels. * the surface must be locked before directly accessing the pixels.
* *
* \param surface the SDL_Surface structure to optimize * \param surface the SDL_Surface structure to optimize.
* \param flag 0 to disable, non-zero to enable RLE acceleration * \param flag 0 to disable, non-zero to enable RLE acceleration.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -427,7 +428,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, int flag
* *
* It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -449,9 +450,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
* RLE acceleration can substantially speed up blitting of images with large * RLE acceleration can substantially speed up blitting of images with large
* horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details. * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
* *
* \param surface the SDL_Surface structure to update * \param surface the SDL_Surface structure to update.
* \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key.
* \param key the transparent pixel * \param key the transparent pixel.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -467,7 +468,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, int
* *
* It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -485,8 +486,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface
* *
* If the surface doesn't have color key enabled this function returns -1. * If the surface doesn't have color key enabled this function returns -1.
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \param key a pointer filled in with the transparent pixel * \param key a pointer filled in with the transparent pixel.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -506,10 +507,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uin
* *
* `srcC = srcC * (color / 255)` * `srcC = srcC * (color / 255)`
* *
* \param surface the SDL_Surface structure to update * \param surface the SDL_Surface structure to update.
* \param r the red color value multiplied into blit operations * \param r the red color value multiplied into blit operations.
* \param g the green color value multiplied into blit operations * \param g the green color value multiplied into blit operations.
* \param b the blue color value multiplied into blit operations * \param b the blue color value multiplied into blit operations.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -524,10 +525,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uin
/** /**
* Get the additional color value multiplied into blit operations. * Get the additional color value multiplied into blit operations.
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \param r a pointer filled in with the current red color value * \param r a pointer filled in with the current red color value.
* \param g a pointer filled in with the current green color value * \param g a pointer filled in with the current green color value.
* \param b a pointer filled in with the current blue color value * \param b a pointer filled in with the current blue color value.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -546,8 +547,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uin
* *
* `srcA = srcA * (alpha / 255)` * `srcA = srcA * (alpha / 255)`
* *
* \param surface the SDL_Surface structure to update * \param surface the SDL_Surface structure to update.
* \param alpha the alpha value multiplied into blit operations * \param alpha the alpha value multiplied into blit operations.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -561,8 +562,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uin
/** /**
* Get the additional alpha value used in blit operations. * Get the additional alpha value used in blit operations.
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \param alpha a pointer filled in with the current alpha value * \param alpha a pointer filled in with the current alpha value.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -580,8 +581,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uin
* existing data, the blendmode of the SOURCE surface should be set to * existing data, the blendmode of the SOURCE surface should be set to
* `SDL_BLENDMODE_NONE`. * `SDL_BLENDMODE_NONE`.
* *
* \param surface the SDL_Surface structure to update * \param surface the SDL_Surface structure to update.
* \param blendMode the SDL_BlendMode to use for blit blending * \param blendMode the SDL_BlendMode to use for blit blending.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -594,8 +595,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SD
/** /**
* Get the blend mode used for blit operations. * Get the blend mode used for blit operations.
* *
* \param surface the SDL_Surface structure to query * \param surface the SDL_Surface structure to query.
* \param blendMode a pointer filled in with the current SDL_BlendMode * \param blendMode a pointer filled in with the current SDL_BlendMode.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -614,9 +615,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SD
* Note that blits are automatically clipped to the edges of the source and * Note that blits are automatically clipped to the edges of the source and
* destination surfaces. * destination surfaces.
* *
* \param surface the SDL_Surface structure to be clipped * \param surface the SDL_Surface structure to be clipped.
* \param rect the SDL_Rect structure representing the clipping rectangle, or * \param rect the SDL_Rect structure representing the clipping rectangle, or
* NULL to disable clipping * NULL to disable clipping.
* \returns SDL_TRUE if the rectangle intersects the surface, otherwise * \returns SDL_TRUE if the rectangle intersects the surface, otherwise
* SDL_FALSE and blits will be completely clipped. * SDL_FALSE and blits will be completely clipped.
* *
@@ -633,9 +634,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface
* rectangle is drawn into. * rectangle is drawn into.
* *
* \param surface the SDL_Surface structure representing the surface to be * \param surface the SDL_Surface structure representing the surface to be
* clipped * clipped.
* \param rect an SDL_Rect structure filled in with the clipping rectangle for * \param rect an SDL_Rect structure filled in with the clipping rectangle for
* the surface * the surface.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -648,8 +649,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL
/** /**
* Flip a surface vertically or horizontally. * Flip a surface vertically or horizontally.
* *
* \param surface the surface to flip * \param surface the surface to flip.
* \param flip the direction to flip * \param flip the direction to flip.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -680,9 +681,9 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface *surfa
* surface. The new, optimized surface can then be used as the source for * surface. The new, optimized surface can then be used as the source for
* future blits, making them faster. * future blits, making them faster.
* *
* \param surface the existing SDL_Surface structure to convert * \param surface the existing SDL_Surface structure to convert.
* \param format the SDL_PixelFormat structure that the new surface is * \param format the SDL_PixelFormat structure that the new surface is
* optimized for * optimized for.
* \returns the new SDL_Surface structure that is created or NULL if it fails; * \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -703,8 +704,8 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface(SDL_Surface *surface
* it might be easier to call but it doesn't have access to palette * it might be easier to call but it doesn't have access to palette
* information for the destination surface, in case that would be important. * information for the destination surface, in case that would be important.
* *
* \param surface the existing SDL_Surface structure to convert * \param surface the existing SDL_Surface structure to convert.
* \param pixel_format the new pixel format * \param pixel_format the new pixel format.
* \returns the new SDL_Surface structure that is created or NULL if it fails; * \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -724,10 +725,10 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat(SDL_Surface *s
* and returns the new surface. This will perform any pixel format and * and returns the new surface. This will perform any pixel format and
* colorspace conversion needed. * colorspace conversion needed.
* *
* \param surface the existing SDL_Surface structure to convert * \param surface the existing SDL_Surface structure to convert.
* \param pixel_format the new pixel format * \param pixel_format the new pixel format.
* \param colorspace the new colorspace * \param colorspace the new colorspace.
* \param props an SDL_PropertiesID with additional color properties, or 0 * \param props an SDL_PropertiesID with additional color properties, or 0.
* \returns the new SDL_Surface structure that is created or NULL if it fails; * \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
@@ -742,14 +743,14 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormatAndColorspace(S
/** /**
* Copy a block of pixels of one format to another format. * Copy a block of pixels of one format to another format.
* *
* \param width the width of the block to copy, in pixels * \param width the width of the block to copy, in pixels.
* \param height the height of the block to copy, in pixels * \param height the height of the block to copy, in pixels.
* \param src_format an SDL_PixelFormatEnum value of the `src` pixels format * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
* \param src a pointer to the source pixels * \param src a pointer to the source pixels.
* \param src_pitch the pitch of the source pixels, in bytes * \param src_pitch the pitch of the source pixels, in bytes.
* \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
* \param dst a pointer to be filled in with new pixel data * \param dst a pointer to be filled in with new pixel data.
* \param dst_pitch the pitch of the destination pixels, in bytes * \param dst_pitch the pitch of the destination pixels, in bytes.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -763,22 +764,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_Pix
* Copy a block of pixels of one format and colorspace to another format and * Copy a block of pixels of one format and colorspace to another format and
* colorspace. * colorspace.
* *
* \param width the width of the block to copy, in pixels * \param width the width of the block to copy, in pixels.
* \param height the height of the block to copy, in pixels * \param height the height of the block to copy, in pixels.
* \param src_format an SDL_PixelFormatEnum value of the `src` pixels format * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
* \param src_colorspace an SDL_ColorSpace value describing the colorspace of * \param src_colorspace an SDL_ColorSpace value describing the colorspace of
* the `src` pixels * the `src` pixels.
* \param src_properties an SDL_PropertiesID with additional source color * \param src_properties an SDL_PropertiesID with additional source color
* properties, or 0 * properties, or 0.
* \param src a pointer to the source pixels * \param src a pointer to the source pixels.
* \param src_pitch the pitch of the source pixels, in bytes * \param src_pitch the pitch of the source pixels, in bytes.
* \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
* \param dst_colorspace an SDL_ColorSpace value describing the colorspace of * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of
* the `dst` pixels * the `dst` pixels.
* \param dst_properties an SDL_PropertiesID with additional destination color * \param dst_properties an SDL_PropertiesID with additional destination color
* properties, or 0 * properties, or 0.
* \param dst a pointer to be filled in with new pixel data * \param dst a pointer to be filled in with new pixel data.
* \param dst_pitch the pitch of the destination pixels, in bytes * \param dst_pitch the pitch of the destination pixels, in bytes.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -795,14 +796,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int he
* *
* This function is currently only implemented for SDL_PIXELFORMAT_ARGB8888. * This function is currently only implemented for SDL_PIXELFORMAT_ARGB8888.
* *
* \param width the width of the block to convert, in pixels * \param width the width of the block to convert, in pixels.
* \param height the height of the block to convert, in pixels * \param height the height of the block to convert, in pixels.
* \param src_format an SDL_PixelFormatEnum value of the `src` pixels format * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
* \param src a pointer to the source pixels * \param src a pointer to the source pixels.
* \param src_pitch the pitch of the source pixels, in bytes * \param src_pitch the pitch of the source pixels, in bytes.
* \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
* \param dst a pointer to be filled in with premultiplied pixel data * \param dst a pointer to be filled in with premultiplied pixel data.
* \param dst_pitch the pitch of the destination pixels, in bytes * \param dst_pitch the pitch of the destination pixels, in bytes.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -822,10 +823,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_
* SDL_SetSurfaceClipRect()), then this function will fill based on the * SDL_SetSurfaceClipRect()), then this function will fill based on the
* intersection of the clip rectangle and `rect`. * intersection of the clip rectangle and `rect`.
* *
* \param dst the SDL_Surface structure that is the drawing target * \param dst the SDL_Surface structure that is the drawing target.
* \param rect the SDL_Rect structure representing the rectangle to fill, or * \param rect the SDL_Rect structure representing the rectangle to fill, or
* NULL to fill the entire surface * NULL to fill the entire surface.
* \param color the color to fill with * \param color the color to fill with.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -847,10 +848,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_
* SDL_SetSurfaceClipRect()), then this function will fill based on the * SDL_SetSurfaceClipRect()), then this function will fill based on the
* intersection of the clip rectangle and `rect`. * intersection of the clip rectangle and `rect`.
* *
* \param dst the SDL_Surface structure that is the drawing target * \param dst the SDL_Surface structure that is the drawing target.
* \param rects an array of SDL_Rects representing the rectangles to fill. * \param rects an array of SDL_Rects representing the rectangles to fill.
* \param count the number of rectangles in the array * \param count the number of rectangles in the array.
* \param color the color to fill with * \param color the color to fill with.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -913,10 +914,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL
* source color key. * source color key.
* ``` * ```
* *
* \param src the SDL_Surface structure to be copied from * \param src the SDL_Surface structure to be copied from.
* \param srcrect the SDL_Rect structure representing the rectangle to be * \param srcrect the SDL_Rect structure representing the rectangle to be
* copied, or NULL to copy the entire surface * copied, or NULL to copy the entire surface.
* \param dst the SDL_Surface structure that is the blit target * \param dst the SDL_Surface structure that is the blit target.
* \param dstrect the SDL_Rect structure representing the x and y position in * \param dstrect the SDL_Rect structure representing the x and y position in
* the destination surface. On input the width and height are * the destination surface. On input the width and height are
* ignored (taken from srcrect), and on output this is filled * ignored (taken from srcrect), and on output this is filled
@@ -940,12 +941,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect
* This is a semi-private blit function and it performs low-level surface * This is a semi-private blit function and it performs low-level surface
* blitting, assuming the input rectangles have already been clipped. * blitting, assuming the input rectangles have already been clipped.
* *
* \param src the SDL_Surface structure to be copied from * \param src the SDL_Surface structure to be copied from.
* \param srcrect the SDL_Rect structure representing the rectangle to be * \param srcrect the SDL_Rect structure representing the rectangle to be
* copied, or NULL to copy the entire surface * copied, or NULL to copy the entire surface.
* \param dst the SDL_Surface structure that is the blit target * \param dst the SDL_Surface structure that is the blit target.
* \param dstrect the SDL_Rect structure representing the target rectangle in * \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface * the destination surface.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -965,13 +966,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const
* Using SDL_SCALEMODE_NEAREST: fast, low quality. Using SDL_SCALEMODE_LINEAR: * Using SDL_SCALEMODE_NEAREST: fast, low quality. Using SDL_SCALEMODE_LINEAR:
* bilinear scaling, slower, better quality, only 32BPP. * bilinear scaling, slower, better quality, only 32BPP.
* *
* \param src the SDL_Surface structure to be copied from * \param src the SDL_Surface structure to be copied from.
* \param srcrect the SDL_Rect structure representing the rectangle to be * \param srcrect the SDL_Rect structure representing the rectangle to be
* copied * copied.
* \param dst the SDL_Surface structure that is the blit target * \param dst the SDL_Surface structure that is the blit target.
* \param dstrect the SDL_Rect structure representing the target rectangle in * \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface * the destination surface.
* \param scaleMode scale algorithm to be used * \param scaleMode scale algorithm to be used.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -985,14 +986,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, const SDL_Rect
* Perform a scaled blit to a destination surface, which may be of a different * Perform a scaled blit to a destination surface, which may be of a different
* format. * format.
* *
* \param src the SDL_Surface structure to be copied from * \param src the SDL_Surface structure to be copied from.
* \param srcrect the SDL_Rect structure representing the rectangle to be * \param srcrect the SDL_Rect structure representing the rectangle to be
* copied * copied.
* \param dst the SDL_Surface structure that is the blit target * \param dst the SDL_Surface structure that is the blit target.
* \param dstrect the SDL_Rect structure representing the target rectangle in * \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface, filled with the actual rectangle * the destination surface, filled with the actual rectangle
* used after clipping * used after clipping.
* \param scaleMode the SDL_ScaleMode to be used * \param scaleMode the SDL_ScaleMode to be used.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1012,13 +1013,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SD
* This is a semi-private function and it performs low-level surface blitting, * This is a semi-private function and it performs low-level surface blitting,
* assuming the input rectangles have already been clipped. * assuming the input rectangles have already been clipped.
* *
* \param src the SDL_Surface structure to be copied from * \param src the SDL_Surface structure to be copied from.
* \param srcrect the SDL_Rect structure representing the rectangle to be * \param srcrect the SDL_Rect structure representing the rectangle to be
* copied * copied.
* \param dst the SDL_Surface structure that is the blit target * \param dst the SDL_Surface structure that is the blit target.
* \param dstrect the SDL_Rect structure representing the target rectangle in * \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface * the destination surface.
* \param scaleMode scale algorithm to be used * \param scaleMode scale algorithm to be used.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1041,17 +1042,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src,
* Like SDL_GetRGBA, this uses the entire 0..255 range when converting color * Like SDL_GetRGBA, this uses the entire 0..255 range when converting color
* components from pixel formats with less than 8 bits per RGB component. * components from pixel formats with less than 8 bits per RGB component.
* *
* \param surface the surface to read * \param surface the surface to read.
* \param x the horizontal coordinate, 0 <= x < width * \param x the horizontal coordinate, 0 <= x < width.
* \param y the vertical coordinate, 0 <= y < height * \param y the vertical coordinate, 0 <= y < height.
* \param r a pointer filled in with the red channel, 0-255, or NULL to ignore * \param r a pointer filled in with the red channel, 0-255, or NULL to ignore
* this channel * this channel.
* \param g a pointer filled in with the green channel, 0-255, or NULL to * \param g a pointer filled in with the green channel, 0-255, or NULL to
* ignore this channel * ignore this channel.
* \param b a pointer filled in with the blue channel, 0-255, or NULL to * \param b a pointer filled in with the blue channel, 0-255, or NULL to
* ignore this channel * ignore this channel.
* \param a a pointer filled in with the alpha channel, 0-255, or NULL to * \param a a pointer filled in with the alpha channel, 0-255, or NULL to
* ignore this channel * ignore this channel.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

52
include/SDL3/SDL_system.h
View File

@@ -80,8 +80,8 @@ typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
* message should continue to be processed, or SDL_FALSE to prevent further * message should continue to be processed, or SDL_FALSE to prevent further
* processing. * processing.
* *
* \param callback The SDL_WindowsMessageHook function to call. * \param callback the SDL_WindowsMessageHook function to call.
* \param userdata a pointer to pass to every iteration of `callback` * \param userdata a pointer to pass to every iteration of `callback`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -100,7 +100,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo
* The returned adapter index can be passed to `IDirect3D9::CreateDevice` and * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
* controls on which monitor a full screen application will appear. * controls on which monitor a full screen application will appear.
* *
* \param displayID the instance of the display to query * \param displayID the instance of the display to query.
* \returns the D3D9 adapter index on success or a negative error code on * \returns the D3D9 adapter index on success or a negative error code on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -119,9 +119,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex(SDL_DisplayID displ
* `EnumOutputs` respectively to get the objects required to create a DX10 or * `EnumOutputs` respectively to get the objects required to create a DX10 or
* DX11 device and swap chain. * DX11 device and swap chain.
* *
* \param displayID the instance of the display to query * \param displayID the instance of the display to query.
* \param adapterIndex a pointer to be filled in with the adapter index * \param adapterIndex a pointer to be filled in with the adapter index.
* \param outputIndex a pointer to be filled in with the output index * \param outputIndex a pointer to be filled in with the output index.
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
* for more information. * for more information.
* *
@@ -145,8 +145,8 @@ typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
* should continue to be processed, or SDL_FALSE to prevent further * should continue to be processed, or SDL_FALSE to prevent further
* processing. * processing.
* *
* \param callback The SDL_X11EventHook function to call. * \param callback the SDL_X11EventHook function to call.
* \param userdata a pointer to pass to every iteration of `callback` * \param userdata a pointer to pass to every iteration of `callback`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -161,7 +161,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback,
* This uses setpriority() if possible, and RealtimeKit if available. * This uses setpriority() if possible, and RealtimeKit if available.
* *
* \param threadID the Unix thread ID to change priority of. * \param threadID the Unix thread ID to change priority of.
* \param priority The new, Unix-specific, priority value. * \param priority the new, Unix-specific, priority value.
* \returns 0 on success, or -1 on error. * \returns 0 on success, or -1 on error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -173,10 +173,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int
* *
* This uses setpriority() if possible, and RealtimeKit if available. * This uses setpriority() if possible, and RealtimeKit if available.
* *
* \param threadID The Unix thread ID to change priority of. * \param threadID the Unix thread ID to change priority of.
* \param sdlPriority The new SDL_ThreadPriority value. * \param sdlPriority the new SDL_ThreadPriority value.
* \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR, * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR,
* SCHED_OTHER, etc...) * SCHED_OTHER, etc...).
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -234,9 +234,9 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
* *
* https://wiki.libsdl.org/SDL3/README/main-functions * https://wiki.libsdl.org/SDL3/README/main-functions
* *
* \param window the window for which the animation callback should be set * \param window the window for which the animation callback should be set.
* \param interval the number of frames after which **callback** will be * \param interval the number of frames after which **callback** will be
* called * called.
* \param callback the function to call for every frame. * \param callback the function to call for every frame.
* \param callbackParam a pointer that is passed to `callback`. * \param callbackParam a pointer that is passed to `callback`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
@@ -253,7 +253,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_iOSSetAnimationCallback(SDL_Window * window,
* *
* This function is only available on Apple iOS. * This function is only available on Apple iOS.
* *
* \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -475,9 +475,9 @@ typedef void (SDLCALL *SDL_AndroidRequestPermissionCallback)(void *userdata, con
* like memory running out. Normally there will be a yes or no to the request * like memory running out. Normally there will be a yes or no to the request
* through the callback. * through the callback.
* *
* \param permission The permission to request. * \param permission the permission to request.
* \param cb The callback to trigger when the request has a response. * \param cb the callback to trigger when the request has a response.
* \param userdata An app-controlled pointer that is passed to the callback. * \param userdata an app-controlled pointer that is passed to the callback.
* \returns zero if the request was submitted, -1 if there was an error * \returns zero if the request was submitted, -1 if there was an error
* submitting. The result of the request is only ever reported * submitting. The result of the request is only ever reported
* through the callback, not this return value. * through the callback, not this return value.
@@ -502,11 +502,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AndroidRequestPermission(const char *permiss
* *
* https://developer.android.com/reference/android/view/Gravity * https://developer.android.com/reference/android/view/Gravity
* *
* \param message text message to be shown * \param message text message to be shown.
* \param duration 0=short, 1=long * \param duration 0=short, 1=long.
* \param gravity where the notification should appear on the screen. * \param gravity where the notification should appear on the screen.
* \param xoffset set this parameter only when gravity >=0 * \param xoffset set this parameter only when gravity >=0.
* \param yoffset set this parameter only when gravity >=0 * \param yoffset set this parameter only when gravity >=0.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -521,8 +521,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int du
* *
* Override "boolean onUnhandledMessage(Message msg)" to handle the message. * Override "boolean onUnhandledMessage(Message msg)" to handle the message.
* *
* \param command user command that must be greater or equal to 0x8000 * \param command user command that must be greater or equal to 0x8000.
* \param param user parameter * \param param user parameter.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -600,7 +600,7 @@ typedef enum SDL_WinRT_DeviceFamily
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param pathType the type of path to retrieve, one of SDL_WinRT_Path * \param pathType the type of path to retrieve, one of SDL_WinRT_Path.
* \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
* the path is not available for any reason; call SDL_GetError() for * the path is not available for any reason; call SDL_GetError() for
* more information. * more information.

26
include/SDL3/SDL_thread.h
View File

@@ -107,7 +107,7 @@ typedef enum SDL_ThreadPriority {
/** /**
* The function passed to SDL_CreateThread() as the new thread's entry point. * The function passed to SDL_CreateThread() as the new thread's entry point.
* *
* \param data what was passed as `data` to SDL_CreateThread() * \param data what was passed as `data` to SDL_CreateThread().
* \returns a value that can be reported through SDL_WaitThread(). * \returns a value that can be reported through SDL_WaitThread().
* *
* \since This datatype is available since SDL 3.0.0. * \since This datatype is available since SDL 3.0.0.
@@ -173,9 +173,9 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
* Usually, apps should just call this function the same way on every platform * Usually, apps should just call this function the same way on every platform
* and let the macros hide the details. * and let the macros hide the details.
* *
* \param fn the SDL_ThreadFunction function to call in the new thread * \param fn the SDL_ThreadFunction function to call in the new thread.
* \param name the name of the thread * \param name the name of the thread.
* \param data a pointer that is passed to `fn` * \param data a pointer that is passed to `fn`.
* \returns an opaque pointer to the new thread object on success, NULL if the * \returns an opaque pointer to the new thread object on success, NULL if the
* new thread could not be created; call SDL_GetError() for more * new thread could not be created; call SDL_GetError() for more
* information. * information.
@@ -241,7 +241,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn,
* Usually, apps should just call this function the same way on every platform * Usually, apps should just call this function the same way on every platform
* and let the macros hide the details. * and let the macros hide the details.
* *
* \param props the properties to use * \param props the properties to use.
* \returns an opaque pointer to the new thread object on success, NULL if the * \returns an opaque pointer to the new thread object on success, NULL if the
* new thread could not be created; call SDL_GetError() for more * new thread could not be created; call SDL_GetError() for more
* information. * information.
@@ -333,7 +333,7 @@ extern SDL_DECLSPEC SDL_Thread *SDLCALL SDL_CreateThreadWithPropertiesRuntime(SD
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param thread the thread to query * \param thread the thread to query.
* \returns a pointer to a UTF-8 string that names the specified thread, or * \returns a pointer to a UTF-8 string that names the specified thread, or
* NULL if it doesn't have a name. * NULL if it doesn't have a name.
* *
@@ -366,7 +366,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void);
* If SDL is running on a platform that does not support threads the return * If SDL is running on a platform that does not support threads the return
* value will always be zero. * value will always be zero.
* *
* \param thread the thread to query * \param thread the thread to query.
* \returns the ID of the specified thread, or the ID of the current thread if * \returns the ID of the specified thread, or the ID of the current thread if
* `thread` is NULL. * `thread` is NULL.
* *
@@ -383,7 +383,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
* promote the thread to a higher priority) at all, and some require you to be * promote the thread to a higher priority) at all, and some require you to be
* an administrator account. Be prepared for this to fail. * an administrator account. Be prepared for this to fail.
* *
* \param priority the SDL_ThreadPriority to set * \param priority the SDL_ThreadPriority to set.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -414,7 +414,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priorit
* afterward. * afterward.
* *
* \param thread the SDL_Thread pointer that was returned from the * \param thread the SDL_Thread pointer that was returned from the
* SDL_CreateThread() call that started this thread * SDL_CreateThread() call that started this thread.
* \param status pointer to an integer that will receive the value returned * \param status pointer to an integer that will receive the value returned
* from the thread function by its 'return', or NULL to not * from the thread function by its 'return', or NULL to not
* receive such value back. * receive such value back.
@@ -453,7 +453,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status
* It is safe to pass NULL to this function; it is a no-op. * It is safe to pass NULL to this function; it is a no-op.
* *
* \param thread the SDL_Thread pointer that was returned from the * \param thread the SDL_Thread pointer that was returned from the
* SDL_CreateThread() call that started this thread * SDL_CreateThread() call that started this thread.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -480,7 +480,7 @@ extern SDL_DECLSPEC SDL_TLSID SDLCALL SDL_CreateTLS(void);
/** /**
* Get the current thread's value associated with a thread local storage ID. * Get the current thread's value associated with a thread local storage ID.
* *
* \param id the thread local storage ID * \param id the thread local storage ID.
* \returns the value associated with the ID for the current thread or NULL if * \returns the value associated with the ID for the current thread or NULL if
* no value has been set; call SDL_GetError() for more information. * no value has been set; call SDL_GetError() for more information.
* *
@@ -513,8 +513,8 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value);
* `destructor` can be NULL; it is assumed that `value` does not need to be * `destructor` can be NULL; it is assumed that `value` does not need to be
* cleaned up if so. * cleaned up if so.
* *
* \param id the thread local storage ID * \param id the thread local storage ID.
* \param value the value to associate with the ID for the current thread * \param value the value to associate with the ID for the current thread.
* \param destructor a function called when the thread exits, to free the * \param destructor a function called when the thread exits, to free the
* value. Can be NULL. * value. Can be NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call

44
include/SDL3/SDL_time.h
View File

@@ -92,9 +92,9 @@ typedef enum SDL_TimeFormat
* preference outside of your program. * preference outside of your program.
* *
* \param dateFormat a pointer to the SDL_DateFormat to hold the returned date * \param dateFormat a pointer to the SDL_DateFormat to hold the returned date
* format, may be NULL * format, may be NULL.
* \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time
* format, may be NULL * format, may be NULL.
* \returns 0 on success or -1 on error; call SDL_GetError() for more * \returns 0 on success or -1 on error; call SDL_GetError() for more
* information. * information.
* *
@@ -106,7 +106,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat
* Gets the current value of the system realtime clock in nanoseconds since * Gets the current value of the system realtime clock in nanoseconds since
* Jan 1, 1970 in Universal Coordinated Time (UTC). * Jan 1, 1970 in Universal Coordinated Time (UTC).
* *
* \param ticks the SDL_Time to hold the returned tick count * \param ticks the SDL_Time to hold the returned tick count.
* \returns 0 on success or -1 on error; call SDL_GetError() for more * \returns 0 on success or -1 on error; call SDL_GetError() for more
* information. * information.
* *
@@ -118,11 +118,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
* Converts an SDL_Time in nanoseconds since the epoch to a calendar time in * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in
* the SDL_DateTime format. * the SDL_DateTime format.
* *
* \param ticks the SDL_Time to be converted * \param ticks the SDL_Time to be converted.
* \param dt the resulting SDL_DateTime * \param dt the resulting SDL_DateTime.
* \param localTime the resulting SDL_DateTime will be expressed in local time * \param localTime the resulting SDL_DateTime will be expressed in local time
* if true, otherwise it will be in Universal Coordinated * if true, otherwise it will be in Universal Coordinated
* Time (UTC) * Time (UTC).
* \returns 0 on success or -1 on error; call SDL_GetError() for more * \returns 0 on success or -1 on error; call SDL_GetError() for more
* information. * information.
* *
@@ -136,8 +136,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime
* This function ignores the day_of_week member of the SDL_DateTime struct, so * This function ignores the day_of_week member of the SDL_DateTime struct, so
* it may remain unset. * it may remain unset.
* *
* \param dt the source SDL_DateTime * \param dt the source SDL_DateTime.
* \param ticks the resulting SDL_Time * \param ticks the resulting SDL_Time.
* \returns 0 on success or -1 on error; call SDL_GetError() for more * \returns 0 on success or -1 on error; call SDL_GetError() for more
* information. * information.
* *
@@ -151,11 +151,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_T
* *
* This function fills in the two 32-bit values of the FILETIME structure. * This function fills in the two 32-bit values of the FILETIME structure.
* *
* \param ticks the time to convert * \param ticks the time to convert.
* \param dwLowDateTime a pointer filled in with the low portion of the * \param dwLowDateTime a pointer filled in with the low portion of the
* Windows FILETIME value * Windows FILETIME value.
* \param dwHighDateTime a pointer filled in with the high portion of the * \param dwHighDateTime a pointer filled in with the high portion of the
* Windows FILETIME value * Windows FILETIME value.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -168,9 +168,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow
* This function takes the two 32-bit values of the FILETIME structure as * This function takes the two 32-bit values of the FILETIME structure as
* parameters. * parameters.
* *
* \param dwLowDateTime the low portion of the Windows FILETIME value * \param dwLowDateTime the low portion of the Windows FILETIME value.
* \param dwHighDateTime the high portion of the Windows FILETIME value * \param dwHighDateTime the high portion of the Windows FILETIME value.
* \returns the converted SDL time * \returns the converted SDL time.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -179,8 +179,8 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U
/** /**
* Get the number of days in a month for a given year. * Get the number of days in a month for a given year.
* *
* \param year the year * \param year the year.
* \param month the month [1-12] * \param month the month [1-12].
* \returns the number of days in the requested month, otherwise -1; call * \returns the number of days in the requested month, otherwise -1; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -191,9 +191,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
/** /**
* Get the day of year for a calendar date. * Get the day of year for a calendar date.
* *
* \param year the year component of the date * \param year the year component of the date.
* \param month the month component of the date * \param month the month component of the date.
* \param day the day component of the date * \param day the day component of the date.
* \returns the day of year [0-365] if the date is valid, otherwise -1; call * \returns the day of year [0-365] if the date is valid, otherwise -1; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -204,9 +204,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
/** /**
* Get the day of week for a calendar date. * Get the day of week for a calendar date.
* *
* \param year the year component of the date * \param year the year component of the date.
* \param month the month component of the date * \param month the month component of the date.
* \param day the day component of the date * \param day the day component of the date.
* \returns a value between 0 and 6 (0 being Sunday) if the date is valid, * \returns a value between 0 and 6 (0 being Sunday) if the date is valid,
* otherwise -1; call SDL_GetError() for more information. * otherwise -1; call SDL_GetError() for more information.
* *

22
include/SDL3/SDL_timer.h
View File

@@ -105,7 +105,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
* waits at least the specified time, but possibly longer due to OS * waits at least the specified time, but possibly longer due to OS
* scheduling. * scheduling.
* *
* \param ms the number of milliseconds to delay * \param ms the number of milliseconds to delay.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -118,7 +118,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
* waits at least the specified time, but possibly longer due to OS * waits at least the specified time, but possibly longer due to OS
* scheduling. * scheduling.
* *
* \param ns the number of nanoseconds to delay * \param ns the number of nanoseconds to delay.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -141,7 +141,7 @@ typedef Uint32 SDL_TimerID;
* *
* \param userdata an arbitrary pointer provided by the app through * \param userdata an arbitrary pointer provided by the app through
* SDL_AddTimer, for its own use. * SDL_AddTimer, for its own use.
* \param timerID the current timer being processed * \param timerID the current timer being processed.
* \param interval the current callback time interval. * \param interval the current callback time interval.
* \returns the new callback time interval, or 0 to disable further runs of * \returns the new callback time interval, or 0 to disable further runs of
* the callback. * the callback.
@@ -178,10 +178,10 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID,
* time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
* callback needs to adjust for variances. * callback needs to adjust for variances.
* *
* \param interval the timer delay, in milliseconds, passed to `callback` * \param interval the timer delay, in milliseconds, passed to `callback`.
* \param callback the SDL_TimerCallback function to call when the specified * \param callback the SDL_TimerCallback function to call when the specified
* `interval` elapses * `interval` elapses.
* \param userdata a pointer that is passed to `callback` * \param userdata a pointer that is passed to `callback`.
* \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
* information. * information.
* *
@@ -204,7 +204,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerC
* *
* \param userdata an arbitrary pointer provided by the app through * \param userdata an arbitrary pointer provided by the app through
* SDL_AddTimer, for its own use. * SDL_AddTimer, for its own use.
* \param timerID the current timer being processed * \param timerID the current timer being processed.
* \param interval the current callback time interval. * \param interval the current callback time interval.
* \returns the new callback time interval, or 0 to disable further runs of * \returns the new callback time interval, or 0 to disable further runs of
* the callback. * the callback.
@@ -241,10 +241,10 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI
* time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
* callback needs to adjust for variances. * callback needs to adjust for variances.
* *
* \param interval the timer delay, in nanoseconds, passed to `callback` * \param interval the timer delay, in nanoseconds, passed to `callback`.
* \param callback the SDL_TimerCallback function to call when the specified * \param callback the SDL_TimerCallback function to call when the specified
* `interval` elapses * `interval` elapses.
* \param userdata a pointer that is passed to `callback` * \param userdata a pointer that is passed to `callback`.
* \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
* information. * information.
* *
@@ -260,7 +260,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi
/** /**
* Remove a timer created with SDL_AddTimer(). * Remove a timer created with SDL_AddTimer().
* *
* \param id the ID of the timer to remove * \param id the ID of the timer to remove.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

6
include/SDL3/SDL_touch.h
View File

@@ -109,8 +109,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touch
/** /**
* Get the type of the given touch device. * Get the type of the given touch device.
* *
* \param touchID the ID of a touch device * \param touchID the ID of a touch device.
* \returns touch device type * \returns touch device type.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -119,7 +119,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch
/** /**
* Get a list of active fingers for a given touch device. * Get a list of active fingers for a given touch device.
* *
* \param touchID the ID of a touch device * \param touchID the ID of a touch device.
* \param count a pointer filled in with the number of fingers returned, can * \param count a pointer filled in with the number of fingers returned, can
* be NULL. * be NULL.
* \returns a NULL terminated array of SDL_Finger pointers which should be * \returns a NULL terminated array of SDL_Finger pointers which should be

340
include/SDL3/SDL_video.h
View File

@@ -344,7 +344,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param index the index of a video driver * \param index the index of a video driver.
* \returns the name of the video driver with the given **index**. * \returns the name of the video driver with the given **index**.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -375,7 +375,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
/** /**
* Get the current system theme. * Get the current system theme.
* *
* \returns the current system theme, light, dark, or unknown * \returns the current system theme, light, dark, or unknown.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@@ -384,7 +384,7 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
/** /**
* Get a list of currently connected displays. * Get a list of currently connected displays.
* *
* \param count a pointer filled in with the number of displays returned * \param count a pointer filled in with the number of displays returned.
* \returns a 0 terminated array of display instance IDs which should be freed * \returns a 0 terminated array of display instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more * with SDL_free(), or NULL on error; call SDL_GetError() for more
* details. * details.
@@ -431,7 +431,7 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void);
* coordinate transformations needed to conform to the requested display * coordinate transformations needed to conform to the requested display
* orientation. * orientation.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -452,7 +452,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \returns the name of a display or NULL on failure; call SDL_GetError() for * \returns the name of a display or NULL on failure; call SDL_GetError() for
* more information. * more information.
* *
@@ -467,8 +467,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetDisplayName(SDL_DisplayID display
* *
* The primary display is always located at (0,0). * The primary display is always located at (0,0).
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \param rect the SDL_Rect structure filled in with the display bounds * \param rect the SDL_Rect structure filled in with the display bounds.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -491,8 +491,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SD
* so these are good guidelines for the maximum space available to a * so these are good guidelines for the maximum space available to a
* non-fullscreen window. * non-fullscreen window.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \param rect the SDL_Rect structure filled in with the display bounds * \param rect the SDL_Rect structure filled in with the display bounds.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -506,7 +506,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID display
/** /**
* Get the orientation of a display when it is unrotated. * Get the orientation of a display when it is unrotated.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \returns the SDL_DisplayOrientation enum value of the display, or * \returns the SDL_DisplayOrientation enum value of the display, or
* `SDL_ORIENTATION_UNKNOWN` if it isn't available. * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
* *
@@ -519,7 +519,7 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat
/** /**
* Get the orientation of a display. * Get the orientation of a display.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \returns the SDL_DisplayOrientation enum value of the display, or * \returns the SDL_DisplayOrientation enum value of the display, or
* `SDL_ORIENTATION_UNKNOWN` if it isn't available. * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
* *
@@ -537,7 +537,7 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat
* display scale, which means that the user expects UI elements to be twice as * display scale, which means that the user expects UI elements to be twice as
* big on this display, to aid in readability. * big on this display, to aid in readability.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \returns the content scale of the display, or 0.0f on error; call * \returns the content scale of the display, or 0.0f on error; call
* SDL_GetError() for more details. * SDL_GetError() for more details.
* *
@@ -559,8 +559,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
* - refresh rate -> highest to lowest * - refresh rate -> highest to lowest
* - pixel density -> lowest to highest * - pixel density -> lowest to highest
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \param count a pointer filled in with the number of display modes returned * \param count a pointer filled in with the number of display modes returned.
* \returns a NULL terminated array of display mode pointers which should be * \returns a NULL terminated array of display mode pointers which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details. * more details.
@@ -581,13 +581,13 @@ extern SDL_DECLSPEC const SDL_DisplayMode **SDLCALL SDL_GetFullscreenDisplayMode
* and finally checking the refresh rate. If all the available modes are too * and finally checking the refresh rate. If all the available modes are too
* small, then NULL is returned. * small, then NULL is returned.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \param w the width in pixels of the desired display mode * \param w the width in pixels of the desired display mode.
* \param h the height in pixels of the desired display mode * \param h the height in pixels of the desired display mode.
* \param refresh_rate the refresh rate of the desired display mode, or 0.0f * \param refresh_rate the refresh rate of the desired display mode, or 0.0f
* for the desktop refresh rate * for the desktop refresh rate.
* \param include_high_density_modes Boolean to include high density modes in * \param include_high_density_modes boolean to include high density modes in
* the search * the search.
* \returns a pointer to the closest display mode equal to or larger than the * \returns a pointer to the closest display mode equal to or larger than the
* desired mode, or NULL on error; call SDL_GetError() for more * desired mode, or NULL on error; call SDL_GetError() for more
* information. * information.
@@ -607,7 +607,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetClosestFullscreenDispl
* function will return the previous native display mode, and not the current * function will return the previous native display mode, and not the current
* display mode. * display mode.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \returns a pointer to the desktop display mode or NULL on error; call * \returns a pointer to the desktop display mode or NULL on error; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -626,7 +626,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetDesktopDisplayMode(SDL
* function will return the current display mode, and not the previous native * function will return the current display mode, and not the previous native
* display mode. * display mode.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query.
* \returns a pointer to the desktop display mode or NULL on error; call * \returns a pointer to the desktop display mode or NULL on error; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -640,7 +640,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetCurrentDisplayMode(SDL
/** /**
* Get the display containing a point. * Get the display containing a point.
* *
* \param point the point to query * \param point the point to query.
* \returns the instance ID of the display containing the point or 0 on * \returns the instance ID of the display containing the point or 0 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
@@ -654,7 +654,7 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point
/** /**
* Get the display primarily containing a rect. * Get the display primarily containing a rect.
* *
* \param rect the rect to query * \param rect the rect to query.
* \returns the instance ID of the display entirely containing the rect or * \returns the instance ID of the display entirely containing the rect or
* closest to the center of the rect on success or 0 on failure; call * closest to the center of the rect on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@@ -669,7 +669,7 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect *
/** /**
* Get the display associated with a window. * Get the display associated with a window.
* *
* \param window the window to query * \param window the window to query.
* \returns the instance ID of the display containing the center of the window * \returns the instance ID of the display containing the center of the window
* on success or 0 on failure; call SDL_GetError() for more * on success or 0 on failure; call SDL_GetError() for more
* information. * information.
@@ -688,7 +688,7 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *wi
* 1920x1080 and it has a high density back buffer of 3840x2160 pixels, it * 1920x1080 and it has a high density back buffer of 3840x2160 pixels, it
* would have a pixel density of 2.0. * would have a pixel density of 2.0.
* *
* \param window the window to query * \param window the window to query.
* \returns the pixel density or 0.0f on failure; call SDL_GetError() for more * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more
* information. * information.
* *
@@ -712,7 +712,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window);
* updated when that setting is changed, or the window moves to a display with * updated when that setting is changed, or the window moves to a display with
* a different scale setting. * a different scale setting.
* *
* \param window the window to query * \param window the window to query.
* \returns the display scale, or 0.0f on failure; call SDL_GetError() for * \returns the display scale, or 0.0f on failure; call SDL_GetError() for
* more information. * more information.
* *
@@ -737,7 +737,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window);
* SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new
* mode dimensions. * mode dimensions.
* *
* \param window the window to affect * \param window the window to affect.
* \param mode a pointer to the display mode to use, which can be NULL for * \param mode a pointer to the display mode to use, which can be NULL for
* borderless fullscreen desktop mode, or one of the fullscreen * borderless fullscreen desktop mode, or one of the fullscreen
* modes returned by SDL_GetFullscreenDisplayModes() to set an * modes returned by SDL_GetFullscreenDisplayModes() to set an
@@ -756,9 +756,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window,
/** /**
* Query the display mode to use when a window is visible at fullscreen. * Query the display mode to use when a window is visible at fullscreen.
* *
* \param window the window to query * \param window the window to query.
* \returns a pointer to the exclusive fullscreen mode to use or NULL for * \returns a pointer to the exclusive fullscreen mode to use or NULL for
* borderless fullscreen desktop mode * borderless fullscreen desktop mode.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -772,8 +772,8 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetWindowFullscreenMode(S
* *
* Data returned should be freed with SDL_free. * Data returned should be freed with SDL_free.
* *
* \param window the window to query * \param window the window to query.
* \param size the size of the ICC profile * \param size the size of the ICC profile.
* \returns the raw ICC profile data on success or NULL on failure; call * \returns the raw ICC profile data on success or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -784,7 +784,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, si
/** /**
* Get the pixel format associated with the window. * Get the pixel format associated with the window.
* *
* \param window the window to query * \param window the window to query.
* \returns the pixel format of the window on success or * \returns the pixel format of the window on success or
* SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more
* information. * information.
@@ -841,10 +841,10 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
* loader or link to a dynamic library version. This limitation may be removed * loader or link to a dynamic library version. This limitation may be removed
* in a future version of SDL. * in a future version of SDL.
* *
* \param title the title of the window, in UTF-8 encoding * \param title the title of the window, in UTF-8 encoding.
* \param w the width of the window * \param w the width of the window.
* \param h the height of the window * \param h the height of the window.
* \param flags 0, or one or more SDL_WindowFlags OR'd together * \param flags 0, or one or more SDL_WindowFlags OR'd together.
* \returns the window that was created or NULL on failure; call * \returns the window that was created or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -890,13 +890,13 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int
* If the parent window is destroyed, any child popup windows will be * If the parent window is destroyed, any child popup windows will be
* recursively destroyed as well. * recursively destroyed as well.
* *
* \param parent the parent of the window, must not be NULL * \param parent the parent of the window, must not be NULL.
* \param offset_x the x position of the popup window relative to the origin * \param offset_x the x position of the popup window relative to the origin
* of the parent * of the parent.
* \param offset_y the y position of the popup window relative to the origin * \param offset_y the y position of the popup window relative to the origin
* of the parent window * of the parent window.
* \param w the width of the window * \param w the width of the window.
* \param h the height of the window * \param h the height of the window.
* \param flags SDL_WINDOW_TOOLTIP or SDL_WINDOW_POPUP_MENU, and zero or more * \param flags SDL_WINDOW_TOOLTIP or SDL_WINDOW_POPUP_MENU, and zero or more
* additional SDL_WindowFlags OR'd together. * additional SDL_WindowFlags OR'd together.
* \returns the window that was created or NULL on failure; call * \returns the window that was created or NULL on failure; call
@@ -1015,7 +1015,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent
* set to true, then create the renderer, then show the window with * set to true, then create the renderer, then show the window with
* SDL_ShowWindow(). * SDL_ShowWindow().
* *
* \param props the properties to use * \param props the properties to use.
* \returns the window that was created or NULL on failure; call * \returns the window that was created or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1067,7 +1067,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithProperties(SDL_Prope
* The numeric ID is what SDL_WindowEvent references, and is necessary to map * The numeric ID is what SDL_WindowEvent references, and is necessary to map
* these events to specific SDL_Window objects. * these events to specific SDL_Window objects.
* *
* \param window the window to query * \param window the window to query.
* \returns the ID of the window on success or 0 on failure; call * \returns the ID of the window on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1083,7 +1083,7 @@ extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window);
* The numeric ID is what SDL_WindowEvent references, and is necessary to map * The numeric ID is what SDL_WindowEvent references, and is necessary to map
* these events to specific SDL_Window objects. * these events to specific SDL_Window objects.
* *
* \param id the ID of the window * \param id the ID of the window.
* \returns the window associated with `id` or NULL if it doesn't exist; call * \returns the window associated with `id` or NULL if it doesn't exist; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1096,7 +1096,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_GetWindowFromID(SDL_WindowID id);
/** /**
* Get parent of a window. * Get parent of a window.
* *
* \param window the window to query * \param window the window to query.
* \returns the parent of the window on success or NULL if the window has no * \returns the parent of the window on success or NULL if the window has no
* parent. * parent.
* *
@@ -1204,7 +1204,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
* - `SDL_PROP_WINDOW_X11_WINDOW_NUMBER`: the X11 Window associated with the * - `SDL_PROP_WINDOW_X11_WINDOW_NUMBER`: the X11 Window associated with the
* window * window
* *
* \param window the window to query * \param window the window to query.
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1250,8 +1250,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window
/** /**
* Get the window flags. * Get the window flags.
* *
* \param window the window to query * \param window the window to query.
* \returns a mask of the SDL_WindowFlags associated with `window` * \returns a mask of the SDL_WindowFlags associated with `window`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -1270,8 +1270,8 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo
* *
* This string is expected to be in UTF-8 encoding. * This string is expected to be in UTF-8 encoding.
* *
* \param window the window to change * \param window the window to change.
* \param title the desired window title in UTF-8 format * \param title the desired window title in UTF-8 format.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1286,7 +1286,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const cha
* *
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param window the window to query * \param window the window to query.
* \returns the title of the window in UTF-8 format or "" if there is no * \returns the title of the window in UTF-8 format or "" if there is no
* title. * title.
* *
@@ -1299,8 +1299,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window *window);
/** /**
* Set the icon for a window. * Set the icon for a window.
* *
* \param window the window to change * \param window the window to change.
* \param icon an SDL_Surface structure containing the icon for the window * \param icon an SDL_Surface structure containing the icon for the window.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1333,11 +1333,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surfac
* Additionally, as this is just a request, it can be denied by the windowing * Additionally, as this is just a request, it can be denied by the windowing
* system. * system.
* *
* \param window the window to reposition * \param window the window to reposition.
* \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
* `SDL_WINDOWPOS_UNDEFINED` * `SDL_WINDOWPOS_UNDEFINED`.
* \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
* `SDL_WINDOWPOS_UNDEFINED` * `SDL_WINDOWPOS_UNDEFINED`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1357,9 +1357,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x,
* If you do not need the value for one of the positions a NULL may be passed * If you do not need the value for one of the positions a NULL may be passed
* in the `x` or `y` parameter. * in the `x` or `y` parameter.
* *
* \param window the window to query * \param window the window to query.
* \param x a pointer filled in with the x position of the window, may be NULL * \param x a pointer filled in with the x position of the window, may be
* \param y a pointer filled in with the y position of the window, may be NULL * NULL.
* \param y a pointer filled in with the y position of the window, may be
* NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1391,9 +1393,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x
* content area to remain within the usable desktop bounds). Additionally, as * content area to remain within the usable desktop bounds). Additionally, as
* this is just a request, it can be denied by the windowing system. * this is just a request, it can be denied by the windowing system.
* *
* \param window the window to change * \param window the window to change.
* \param w the width of the window, must be > 0 * \param w the width of the window, must be > 0.
* \param h the height of the window, must be > 0 * \param h the height of the window, must be > 0.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1412,9 +1414,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int
* window is on a high pixel density display. Use SDL_GetWindowSizeInPixels() * window is on a high pixel density display. Use SDL_GetWindowSizeInPixels()
* or SDL_GetRenderOutputSize() to get the real client area size in pixels. * or SDL_GetRenderOutputSize() to get the real client area size in pixels.
* *
* \param window the window to query the width and height from * \param window the window to query the width and height from.
* \param w a pointer filled in with the width of the window, may be NULL * \param w a pointer filled in with the width of the window, may be NULL.
* \param h a pointer filled in with the height of the window, may be NULL * \param h a pointer filled in with the height of the window, may be NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1450,11 +1452,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, in
* Additionally, as this is just a request, it can be denied by the windowing * Additionally, as this is just a request, it can be denied by the windowing
* system. * system.
* *
* \param window the window to change * \param window the window to change.
* \param min_aspect the minimum aspect ratio of the window, or 0.0f for no * \param min_aspect the minimum aspect ratio of the window, or 0.0f for no
* limit * limit.
* \param max_aspect the maximum aspect ratio of the window, or 0.0f for no * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no
* limit * limit.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1468,11 +1470,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, flo
/** /**
* Get the size of a window's client area. * Get the size of a window's client area.
* *
* \param window the window to query the width and height from * \param window the window to query the width and height from.
* \param min_aspect a pointer filled in with the minimum aspect ratio of the * \param min_aspect a pointer filled in with the minimum aspect ratio of the
* window, may be NULL * window, may be NULL.
* \param max_aspect a pointer filled in with the maximum aspect ratio of the * \param max_aspect a pointer filled in with the maximum aspect ratio of the
* window, may be NULL * window, may be NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1498,15 +1500,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, flo
* This function also returns -1 if getting the information is not supported. * This function also returns -1 if getting the information is not supported.
* *
* \param window the window to query the size values of the border * \param window the window to query the size values of the border
* (decorations) from * (decorations) from.
* \param top pointer to variable for storing the size of the top border; NULL * \param top pointer to variable for storing the size of the top border; NULL
* is permitted * is permitted.
* \param left pointer to variable for storing the size of the left border; * \param left pointer to variable for storing the size of the left border;
* NULL is permitted * NULL is permitted.
* \param bottom pointer to variable for storing the size of the bottom * \param bottom pointer to variable for storing the size of the bottom
* border; NULL is permitted * border; NULL is permitted.
* \param right pointer to variable for storing the size of the right border; * \param right pointer to variable for storing the size of the right border;
* NULL is permitted * NULL is permitted.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1519,10 +1521,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int
/** /**
* Get the size of a window's client area, in pixels. * Get the size of a window's client area, in pixels.
* *
* \param window the window from which the drawable size should be queried * \param window the window from which the drawable size should be queried.
* \param w a pointer to variable for storing the width in pixels, may be NULL * \param w a pointer to variable for storing the width in pixels, may be
* NULL.
* \param h a pointer to variable for storing the height in pixels, may be * \param h a pointer to variable for storing the height in pixels, may be
* NULL * NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1536,9 +1539,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, in
/** /**
* Set the minimum size of a window's client area. * Set the minimum size of a window's client area.
* *
* \param window the window to change * \param window the window to change.
* \param min_w the minimum width of the window, or 0 for no limit * \param min_w the minimum width of the window, or 0 for no limit.
* \param min_h the minimum height of the window, or 0 for no limit * \param min_h the minimum height of the window, or 0 for no limit.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1552,11 +1555,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int
/** /**
* Get the minimum size of a window's client area. * Get the minimum size of a window's client area.
* *
* \param window the window to query * \param window the window to query.
* \param w a pointer filled in with the minimum width of the window, may be * \param w a pointer filled in with the minimum width of the window, may be
* NULL * NULL.
* \param h a pointer filled in with the minimum height of the window, may be * \param h a pointer filled in with the minimum height of the window, may be
* NULL * NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1570,9 +1573,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int
/** /**
* Set the maximum size of a window's client area. * Set the maximum size of a window's client area.
* *
* \param window the window to change * \param window the window to change.
* \param max_w the maximum width of the window, or 0 for no limit * \param max_w the maximum width of the window, or 0 for no limit.
* \param max_h the maximum height of the window, or 0 for no limit * \param max_h the maximum height of the window, or 0 for no limit.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1586,11 +1589,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int
/** /**
* Get the maximum size of a window's client area. * Get the maximum size of a window's client area.
* *
* \param window the window to query * \param window the window to query.
* \param w a pointer filled in with the maximum width of the window, may be * \param w a pointer filled in with the maximum width of the window, may be
* NULL * NULL.
* \param h a pointer filled in with the maximum height of the window, may be * \param h a pointer filled in with the maximum height of the window, may be
* NULL * NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1610,8 +1613,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int
* *
* You can't change the border state of a fullscreen window. * You can't change the border state of a fullscreen window.
* *
* \param window the window of which to change the border state * \param window the window of which to change the border state.
* \param bordered SDL_FALSE to remove border, SDL_TRUE to add border * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1630,8 +1633,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bo
* *
* You can't change the resizable state of a fullscreen window. * You can't change the resizable state of a fullscreen window.
* *
* \param window the window of which to change the resizable state * \param window the window of which to change the resizable state.
* \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1647,9 +1650,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_b
* This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This
* will bring the window to the front and keep the window above the rest. * will bring the window to the front and keep the window above the rest.
* *
* \param window The window of which to change the always on top state * \param window the window of which to change the always on top state.
* \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to
* disable * disable.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1662,7 +1665,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, SDL
/** /**
* Show a window. * Show a window.
* *
* \param window the window to show * \param window the window to show.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1676,7 +1679,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ShowWindow(SDL_Window *window);
/** /**
* Hide a window. * Hide a window.
* *
* \param window the window to hide * \param window the window to hide.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1689,7 +1692,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_HideWindow(SDL_Window *window);
/** /**
* Raise a window above other windows and set the input focus. * Raise a window above other windows and set the input focus.
* *
* \param window the window to raise * \param window the window to raise.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1717,7 +1720,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RaiseWindow(SDL_Window *window);
* manager. Win32 and macOS enforce the constraints when maximizing, while X11 * manager. Win32 and macOS enforce the constraints when maximizing, while X11
* and Wayland window managers may vary. * and Wayland window managers may vary.
* *
* \param window the window to maximize * \param window the window to maximize.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1741,7 +1744,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window);
* emitted. Note that, as this is just a request, the windowing system can * emitted. Note that, as this is just a request, the windowing system can
* deny the state change. * deny the state change.
* *
* \param window the window to minimize * \param window the window to minimize.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1766,7 +1769,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_MinimizeWindow(SDL_Window *window);
* emitted. Note that, as this is just a request, the windowing system can * emitted. Note that, as this is just a request, the windowing system can
* deny the state change. * deny the state change.
* *
* \param window the window to restore * \param window the window to restore.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1794,8 +1797,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window);
* SDL_EVENT_WINDOW_LEAVE_FULLSCREEN event will be emitted. Note that, as this * SDL_EVENT_WINDOW_LEAVE_FULLSCREEN event will be emitted. Note that, as this
* is just a request, it can be denied by the windowing system. * is just a request, it can be denied by the windowing system.
* *
* \param window the window to change * \param window the window to change.
* \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed mode * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed
* mode.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1820,7 +1824,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_
* On windowing systems where changes are immediate, this does nothing. * On windowing systems where changes are immediate, this does nothing.
* *
* \param window the window for which to wait for the pending state to be * \param window the window for which to wait for the pending state to be
* applied * applied.
* \returns 0 on success, a positive value if the operation timed out before * \returns 0 on success, a positive value if the operation timed out before
* the window was in the requested state, or a negative error code on * the window was in the requested state, or a negative error code on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
@@ -1840,7 +1844,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SyncWindow(SDL_Window *window);
/** /**
* Return whether the window has a surface associated with it. * Return whether the window has a surface associated with it.
* *
* \param window the window to query * \param window the window to query.
* \returns SDL_TRUE if there is a surface associated with the window, or * \returns SDL_TRUE if there is a surface associated with the window, or
* SDL_FALSE otherwise. * SDL_FALSE otherwise.
* *
@@ -1864,7 +1868,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window);
* *
* This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`. * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`.
* *
* \param window the window to query * \param window the window to query.
* \returns the surface associated with the window, or NULL on failure; call * \returns the surface associated with the window, or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1907,7 +1911,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, in
/** /**
* Get VSync for the window surface. * Get VSync for the window surface.
* *
* \param window the window to query * \param window the window to query.
* \param vsync an int filled with the current vertical refresh sync interval. * \param vsync an int filled with the current vertical refresh sync interval.
* See SDL_SetWindowSurfaceVSync() for the meaning of the value. * See SDL_SetWindowSurfaceVSync() for the meaning of the value.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
@@ -1927,7 +1931,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, in
* *
* This function is equivalent to the SDL 1.2 API SDL_Flip(). * This function is equivalent to the SDL 1.2 API SDL_Flip().
* *
* \param window the window to update * \param window the window to update.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1951,10 +1955,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window *window);
* update more of the screen (or all of the screen!), depending on what method * update more of the screen (or all of the screen!), depending on what method
* SDL uses to send pixels to the system. * SDL uses to send pixels to the system.
* *
* \param window the window to update * \param window the window to update.
* \param rects an array of SDL_Rect structures representing areas of the * \param rects an array of SDL_Rect structures representing areas of the
* surface to copy, in pixels * surface to copy, in pixels.
* \param numrects the number of rectangles * \param numrects the number of rectangles.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1968,7 +1972,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window,
/** /**
* Destroy the surface associated with the window. * Destroy the surface associated with the window.
* *
* \param window the window to update * \param window the window to update.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -1998,8 +2002,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_DestroyWindowSurface(SDL_Window *window);
* If the caller enables a grab while another window is currently grabbed, the * If the caller enables a grab while another window is currently grabbed, the
* other window loses its grab in favor of the caller's window. * other window loses its grab in favor of the caller's window.
* *
* \param window The window for which the keyboard grab mode should be set. * \param window the window for which the keyboard grab mode should be set.
* \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release. * \param grabbed this is SDL_TRUE to grab keyboard, and SDL_FALSE to release.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2015,8 +2019,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SD
* *
* Mouse grab confines the mouse cursor to the window. * Mouse grab confines the mouse cursor to the window.
* *
* \param window The window for which the mouse grab mode should be set. * \param window the window for which the mouse grab mode should be set.
* \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release. * \param grabbed this is SDL_TRUE to grab mouse, and SDL_FALSE to release.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2030,7 +2034,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_b
/** /**
* Get a window's keyboard grab mode. * Get a window's keyboard grab mode.
* *
* \param window the window to query * \param window the window to query.
* \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -2042,7 +2046,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *windo
/** /**
* Get a window's mouse grab mode. * Get a window's mouse grab mode.
* *
* \param window the window to query * \param window the window to query.
* \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -2069,8 +2073,8 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_GetGrabbedWindow(void);
* Note that this does NOT grab the cursor, it only defines the area a cursor * Note that this does NOT grab the cursor, it only defines the area a cursor
* is restricted to when the window has mouse focus. * is restricted to when the window has mouse focus.
* *
* \param window The window that will be associated with the barrier. * \param window the window that will be associated with the barrier.
* \param rect A rectangle area in window-relative coordinates. If NULL the * \param rect a rectangle area in window-relative coordinates. If NULL the
* barrier for the specified window will be destroyed. * barrier for the specified window will be destroyed.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@@ -2085,7 +2089,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const
/** /**
* Get the mouse confinement rectangle of a window. * Get the mouse confinement rectangle of a window.
* *
* \param window The window to query * \param window the window to query.
* \returns a pointer to the mouse confinement rectangle of a window, or NULL * \returns a pointer to the mouse confinement rectangle of a window, or NULL
* if there isn't one. * if there isn't one.
* *
@@ -2103,8 +2107,8 @@ extern SDL_DECLSPEC const SDL_Rect *SDLCALL SDL_GetWindowMouseRect(SDL_Window *w
* *
* This function also returns -1 if setting the opacity isn't supported. * This function also returns -1 if setting the opacity isn't supported.
* *
* \param window the window which will be made transparent or opaque * \param window the window which will be made transparent or opaque.
* \param opacity the opacity value (0.0f - transparent, 1.0f - opaque) * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque).
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2124,8 +2128,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float o
* *
* This function also returns -1 if an invalid window was provided. * This function also returns -1 if an invalid window was provided.
* *
* \param window the window to get the current opacity value from * \param window the window to get the current opacity value from.
* \param out_opacity the float filled in (0.0f - transparent, 1.0f - opaque) * \param out_opacity the float filled in (0.0f - transparent, 1.0f - opaque).
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2145,8 +2149,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window *window, float *
* Setting a window as modal to a parent that is a descendent of the modal * Setting a window as modal to a parent that is a descendent of the modal
* window results in undefined behavior. * window results in undefined behavior.
* *
* \param modal_window the window that should be set modal * \param modal_window the window that should be set modal.
* \param parent_window the parent window for the modal window * \param parent_window the parent window for the modal window.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2161,7 +2165,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window *modal_window,
* this with caution, as you might give focus to a window that is completely * this with caution, as you might give focus to a window that is completely
* obscured by other windows. * obscured by other windows.
* *
* \param window the window that should get the input focus * \param window the window that should get the input focus.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2174,9 +2178,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window *window);
/** /**
* Set whether the window may have input focus. * Set whether the window may have input focus.
* *
* \param window the window to set focusable state * \param window the window to set focusable state.
* \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow * \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow
* input focus * input focus.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2196,11 +2200,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_b
* On platforms or desktops where this is unsupported, this function does * On platforms or desktops where this is unsupported, this function does
* nothing. * nothing.
* *
* \param window the window for which the menu will be displayed * \param window the window for which the menu will be displayed.
* \param x the x coordinate of the menu, relative to the origin (top-left) of * \param x the x coordinate of the menu, relative to the origin (top-left) of
* the client area * the client area.
* \param y the y coordinate of the menu, relative to the origin (top-left) of * \param y the y coordinate of the menu, relative to the origin (top-left) of
* the client area * the client area.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2232,9 +2236,9 @@ typedef enum SDL_HitTestResult
/** /**
* Callback used for hit-testing. * Callback used for hit-testing.
* *
* \param win the SDL_Window where hit-testing was set on * \param win the SDL_Window where hit-testing was set on.
* \param area an SDL_Point which should be hit-tested * \param area an SDL_Point which should be hit-tested.
* \param data what was passed as `callback_data` to SDL_SetWindowHitTest() * \param data what was passed as `callback_data` to SDL_SetWindowHitTest().
* \returns an SDL_HitTestResult value. * \returns an SDL_HitTestResult value.
* *
* \sa SDL_SetWindowHitTest * \sa SDL_SetWindowHitTest
@@ -2275,9 +2279,9 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
* can fire at any time, you should try to keep your callback efficient, * can fire at any time, you should try to keep your callback efficient,
* devoid of allocations, etc. * devoid of allocations, etc.
* *
* \param window the window to set hit-testing on * \param window the window to set hit-testing on.
* \param callback the function to call when doing a hit-test * \param callback the function to call when doing a hit-test.
* \param callback_data an app-defined void pointer passed to **callback** * \param callback_data an app-defined void pointer passed to **callback**.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2299,9 +2303,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_Hit
* *
* The window must have been created with the SDL_WINDOW_TRANSPARENT flag. * The window must have been created with the SDL_WINDOW_TRANSPARENT flag.
* *
* \param window the window * \param window the window.
* \param shape the surface representing the shape of the window, or NULL to * \param shape the surface representing the shape of the window, or NULL to
* remove any current shape * remove any current shape.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2312,8 +2316,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surfa
/** /**
* Request a window to demand attention from the user. * Request a window to demand attention from the user.
* *
* \param window the window to be flashed * \param window the window to be flashed.
* \param operation the operation to perform * \param operation the operation to perform.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2330,7 +2334,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOpe
* If `window` is NULL, this function will return immediately after setting * If `window` is NULL, this function will return immediately after setting
* the SDL error message to "Invalid window". See SDL_GetError(). * the SDL error message to "Invalid window". See SDL_GetError().
* *
* \param window the window to destroy * \param window the window to destroy.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@@ -2407,7 +2411,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_DisableScreenSaver(void);
* program from the dynamic library using SDL_GL_GetProcAddress(). * program from the dynamic library using SDL_GL_GetProcAddress().
* *
* \param path the platform dependent OpenGL library name, or NULL to open the * \param path the platform dependent OpenGL library name, or NULL to open the
* default OpenGL library * default OpenGL library.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2459,7 +2463,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
* code. This will ensure the proper calling convention is followed on * code. This will ensure the proper calling convention is followed on
* platforms where this matters (Win32) thereby avoiding stack corruption. * platforms where this matters (Win32) thereby avoiding stack corruption.
* *
* \param proc the name of an OpenGL function * \param proc the name of an OpenGL function.
* \returns a pointer to the named OpenGL function. The returned pointer * \returns a pointer to the named OpenGL function. The returned pointer
* should be cast to the appropriate function signature. * should be cast to the appropriate function signature.
* *
@@ -2478,7 +2482,7 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char
* points for EGL functions. This is useful to provide to an EGL API and * points for EGL functions. This is useful to provide to an EGL API and
* extension loader. * extension loader.
* *
* \param proc the name of an EGL function * \param proc the name of an EGL function.
* \returns a pointer to the named EGL function. The returned pointer should * \returns a pointer to the named EGL function. The returned pointer should
* be cast to the appropriate function signature. * be cast to the appropriate function signature.
* *
@@ -2511,7 +2515,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
* context and save that information somewhere instead of calling the function * context and save that information somewhere instead of calling the function
* every time you need to know. * every time you need to know.
* *
* \param extension the name of the extension to check * \param extension the name of the extension to check.
* \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -2536,8 +2540,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
* SDL_GL_GetAttribute() to check the values after creating the OpenGL * SDL_GL_GetAttribute() to check the values after creating the OpenGL
* context, since the values obtained can differ from the requested ones. * context, since the values obtained can differ from the requested ones.
* *
* \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to
* \param value the desired value for the attribute * set.
* \param value the desired value for the attribute.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2551,8 +2556,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
/** /**
* Get the actual value for an attribute from the current context. * Get the actual value for an attribute from the current context.
* *
* \param attr an SDL_GLattr enum value specifying the OpenGL attribute to get * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to
* \param value a pointer filled in with the current value of `attr` * get.
* \param value a pointer filled in with the current value of `attr`.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2574,7 +2580,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value)
* *
* SDL_GLContext is an alias for `void *`. It's opaque to the application. * SDL_GLContext is an alias for `void *`. It's opaque to the application.
* *
* \param window the window to associate with the context * \param window the window to associate with the context.
* \returns the OpenGL context associated with `window` or NULL on error; call * \returns the OpenGL context associated with `window` or NULL on error; call
* SDL_GetError() for more details. * SDL_GetError() for more details.
* *
@@ -2590,8 +2596,8 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo
* *
* The context must have been created with a compatible window. * The context must have been created with a compatible window.
* *
* \param window the window to associate with the context * \param window the window to associate with the context.
* \param context the OpenGL context to associate with the window * \param context the OpenGL context to associate with the window.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2646,7 +2652,7 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentEGLConfig(void);
/** /**
* Get the EGL surface associated with the window. * Get the EGL surface associated with the window.
* *
* \param window the window to query * \param window the window to query.
* \returns the EGLSurface pointer associated with the window, or NULL on * \returns the EGLSurface pointer associated with the window, or NULL on
* failure. * failure.
* *
@@ -2667,11 +2673,11 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowEGLSurface(SDL_Windo
* *
* NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes. * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes.
* *
* \param platformAttribCallback Callback for attributes to pass to * \param platformAttribCallback callback for attributes to pass to
* eglGetPlatformDisplay. * eglGetPlatformDisplay.
* \param surfaceAttribCallback Callback for attributes to pass to * \param surfaceAttribCallback callback for attributes to pass to
* eglCreateSurface. * eglCreateSurface.
* \param contextAttribCallback Callback for attributes to pass to * \param contextAttribCallback callback for attributes to pass to
* eglCreateContext. * eglCreateContext.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -2699,7 +2705,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetEGLAttributeCallbacks(SDL_EGLAttribA
* https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync
* *
* \param interval 0 for immediate updates, 1 for updates synchronized with * \param interval 0 for immediate updates, 1 for updates synchronized with
* the vertical retrace, -1 for adaptive vsync * the vertical retrace, -1 for adaptive vsync.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2715,10 +2721,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
* If the system can't determine the swap interval, or there isn't a valid * If the system can't determine the swap interval, or there isn't a valid
* current context, this function will set *interval to 0 as a safe default. * current context, this function will set *interval to 0 as a safe default.
* *
* \param interval Output interval value. 0 if there is no vertical retrace * \param interval output interval value. 0 if there is no vertical retrace
* synchronization, 1 if the buffer swap is synchronized with * synchronization, 1 if the buffer swap is synchronized with
* the vertical retrace, and -1 if late swaps happen * the vertical retrace, and -1 if late swaps happen
* immediately instead of waiting for the next retrace * immediately instead of waiting for the next retrace.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2738,7 +2744,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(int *interval);
* glBindFramebuffer(), this is the default and you won't have to do anything * glBindFramebuffer(), this is the default and you won't have to do anything
* extra. * extra.
* *
* \param window the window to change * \param window the window to change.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -2749,7 +2755,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_SwapWindow(SDL_Window *window);
/** /**
* Delete an OpenGL context. * Delete an OpenGL context.
* *
* \param context the OpenGL context to be deleted * \param context the OpenGL context to be deleted.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

18
include/SDL3/SDL_vulkan.h
View File

@@ -93,7 +93,7 @@ struct VkAllocationCallbacks;
* supported. Either do not link to the Vulkan loader or link to a dynamic * supported. Either do not link to the Vulkan loader or link to a dynamic
* library version. * library version.
* *
* \param path The platform dependent Vulkan loader library name or NULL * \param path the platform dependent Vulkan loader library name or NULL.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@@ -166,12 +166,12 @@ extern SDL_DECLSPEC char const* const* SDLCALL SDL_Vulkan_GetInstanceExtensions(
* If `allocator` is NULL, Vulkan will use the system default allocator. This * If `allocator` is NULL, Vulkan will use the system default allocator. This
* argument is passed directly to Vulkan and isn't used by SDL itself. * argument is passed directly to Vulkan and isn't used by SDL itself.
* *
* \param window The window to which to attach the Vulkan surface * \param window the window to which to attach the Vulkan surface.
* \param instance The Vulkan instance handle * \param instance the Vulkan instance handle.
* \param allocator A VkAllocationCallbacks struct, which lets the app set the * \param allocator a VkAllocationCallbacks struct, which lets the app set the
* allocator that creates the surface. Can be NULL. * allocator that creates the surface. Can be NULL.
* \param surface A pointer to a VkSurfaceKHR handle to output the newly * \param surface a pointer to a VkSurfaceKHR handle to output the newly
* created surface * created surface.
* \returns SDL_TRUE on success, SDL_FALSE on error. * \returns SDL_TRUE on success, SDL_FALSE on error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@@ -197,9 +197,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window
* If `allocator` is NULL, Vulkan will use the system default allocator. This * If `allocator` is NULL, Vulkan will use the system default allocator. This
* argument is passed directly to Vulkan and isn't used by SDL itself. * argument is passed directly to Vulkan and isn't used by SDL itself.
* *
* \param instance The Vulkan instance handle * \param instance the Vulkan instance handle.
* \param surface VkSurfaceKHR handle to destroy * \param surface vkSurfaceKHR handle to destroy.
* \param allocator A VkAllocationCallbacks struct, which lets the app set the * \param allocator a VkAllocationCallbacks struct, which lets the app set the
* allocator that destroys the surface. Can be NULL. * allocator that destroys the surface. Can be NULL.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.