Mirrors_Framework/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2026-05-28 11:57:24 +08:00
Code Issues Actions 7 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
include/SDL3/SDL_assert.h
+14 -14
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.
include/SDL3/SDL_atomic.h
+18 -18
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.
include/SDL3/SDL_audio.h
+80 -80
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.
* *
include/SDL3/SDL_bits.h
+2 -2
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.
include/SDL3/SDL_blendmode.h
+6 -6
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.
* *
include/SDL3/SDL_camera.h
+14 -14
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.
include/SDL3/SDL_clipboard.h
+16 -16
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.
* *
include/SDL3/SDL_dialog.h
+21 -21
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.
include/SDL3/SDL_error.h
+4 -4
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.
* *
include/SDL3/SDL_events.h
+27 -27
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.
* *
include/SDL3/SDL_filesystem.h
+13 -13
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.
include/SDL3/SDL_gamepad.h
+110 -110
View File
File diff suppressed because it is too large Load Diff
include/SDL3/SDL_guid.h
+4 -4
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.
include/SDL3/SDL_haptic.h
+44 -42
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.
* *
include/SDL3/SDL_hidapi.h
+45 -45
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.
*/ */
include/SDL3/SDL_hints.h
+21 -21
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.
* *
include/SDL3/SDL_init.h
+1 -1
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.
* *
include/SDL3/SDL_iostream.h
+86 -86
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.
* *
include/SDL3/SDL_joystick.h
+92 -92
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
include/SDL3/SDL_keyboard.h
+13 -13
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.
include/SDL3/SDL_loadso.h
+4 -4
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.
* *
include/SDL3/SDL_log.h
+42 -41
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.
* *
include/SDL3/SDL_main.h
+16 -16
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.
include/SDL3/SDL_messagebox.h
+7 -6
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.
* *
include/SDL3/SDL_metal.h
+5 -5
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.
*/ */
include/SDL3/SDL_misc.h
+1 -1
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.
include/SDL3/SDL_mouse.h
+25 -25
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.
* *
include/SDL3/SDL_mutex.h
+27 -27
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.
include/SDL3/SDL_pen.h
+16 -16
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
include/SDL3/SDL_pixels.h
+44 -44
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.
* *
include/SDL3/SDL_properties.h
+49 -49
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
include/SDL3/SDL_rect.h
+34 -34
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.
include/SDL3/SDL_render.h
+235 -235
View File
File diff suppressed because it is too large Load Diff
include/SDL3/SDL_sensor.h
+18 -18
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.
*/ */
include/SDL3/SDL_stdinc.h
+122 -120
View File
File diff suppressed because it is too large Load Diff
include/SDL3/SDL_storage.h
+40 -40
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.
include/SDL3/SDL_surface.h
+126 -125
View File
File diff suppressed because it is too large Load Diff
include/SDL3/SDL_system.h
+26 -26
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.
include/SDL3/SDL_thread.h
+13 -13
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
include/SDL3/SDL_time.h
+22 -22
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.
* *
include/SDL3/SDL_timer.h
+11 -11
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.
* *
include/SDL3/SDL_touch.h
+3 -3
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
include/SDL3/SDL_video.h
+173 -167
View File
File diff suppressed because it is too large Load Diff
include/SDL3/SDL_vulkan.h
+9 -9
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.