eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-31 08:57:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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
No known key found for this signature in database
GPG key ID: FA148B892AB48044
44 changed files with 1699 additions and 1686 deletions
Download patch file Download diff file Expand all files Collapse all files

28
include/SDL3/SDL_assert.h
View file

@ -234,11 +234,11 @@ typedef struct SDL_AssertData
*
* Use the SDL_assert* macros instead.
*
* \param data assert data structure
* \param func function name
* \param file file name
* \param line line number
* \returns assert state
* \param data assert data structure.
* \param func function name.
* \param file file name.
* \param line line number.
* \returns assert state.
*
* \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!
* 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.
*/
@ -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!
* 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.
*/
@ -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!
* 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.
*/
@ -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!
* 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.
*/
@ -426,8 +426,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* A callback that fires when an SDL assertion fails.
*
* \param data a pointer to the SDL_AssertData structure corresponding to the
* current assertion
* \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
* current assertion.
* \param userdata what was passed as `userdata` to SDL_SetAssertionHandler().
* \returns an SDL_AssertState value indicating how to handle the failure.
*
* \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()!
*
* \param handler the SDL_AssertionHandler function to call when an assertion
* fails or NULL for the default handler
* \param userdata a pointer that is passed to `handler`
* fails or NULL for the default handler.
* \param userdata a pointer that is passed to `handler`.
*
* \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.
*
* \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.
*
* \since This function is available since SDL 3.0.0.

36
include/SDL3/SDL_atomic.h
View file

@ -87,7 +87,7 @@ typedef int SDL_SpinLock;
* ***Please note that spinlocks are dangerous if you don't know what you're
* 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
* 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
* 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.
*
@ -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
* 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.
*
@ -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
* it!***
*
* \param a a pointer to an SDL_AtomicInt variable to be modified
* \param oldval the old value
* \param newval the new value
* \param a a pointer to an SDL_AtomicInt variable to be modified.
* \param oldval the old value.
* \param newval the new value.
* \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
*
* \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
* it!***
*
* \param a a pointer to an SDL_AtomicInt variable to be modified
* \param v the desired value
* \param a a pointer to an SDL_AtomicInt variable to be modified.
* \param v the desired value.
* \returns the previous value of the atomic variable.
*
* \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
* 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.
*
* \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
* it!***
*
* \param a a pointer to an SDL_AtomicInt variable to be modified
* \param v the desired value to add
* \param a a pointer to an SDL_AtomicInt variable to be modified.
* \param v the desired value to add.
* \returns the previous value of the atomic variable.
*
* \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.
* \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.
*
@ -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
* it!***
*
* \param a a pointer to a pointer
* \param oldval the old pointer value
* \param newval the new pointer value
* \param a a pointer to a pointer.
* \param oldval the old pointer value.
* \param newval the new pointer value.
* \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
*
* \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
* it!***
*
* \param a a pointer to a pointer
* \param v the desired pointer value
* \param a a pointer to a pointer.
* \param v the desired pointer value.
* \returns the previous value of the pointer.
*
* \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
* it!***
*
* \param a a pointer to a pointer
* \param a a pointer to a pointer.
* \returns the current value of a pointer.
*
* \threadsafety It is safe to call this function from any thread.

160
include/SDL3/SDL_audio.h
View file

@ -141,8 +141,8 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
*
* \param x an SDL_AudioFormat value
* \returns data size in bits
* \param x an SDL_AudioFormat value.
* \returns data size in bits.
*
* \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.
*
* \param x an SDL_AudioFormat value
* \returns data size in bytes
* \param x an SDL_AudioFormat value.
* \returns data size in bytes.
*
* \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.
*
* \param x an SDL_AudioFormat value
* \param x an SDL_AudioFormat value.
* \returns non-zero if format is floating point, zero otherwise.
*
* \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.
*
* \param x an SDL_AudioFormat value
* \param x an SDL_AudioFormat value.
* \returns non-zero if format is bigendian, zero otherwise.
*
* \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.
*
* \param x an SDL_AudioFormat value
* \param x an SDL_AudioFormat value.
* \returns non-zero if format is littleendian, zero otherwise.
*
* \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.
*
* \param x an SDL_AudioFormat value
* \param x an SDL_AudioFormat value.
* \returns non-zero if format is signed, zero otherwise.
*
* \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.
*
* \param x an SDL_AudioFormat value
* \param x an SDL_AudioFormat value.
* \returns non-zero if format is integer, zero otherwise.
*
* \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.
*
* \param x an SDL_AudioFormat value
* \param x an SDL_AudioFormat value.
* \returns non-zero if format is unsigned, zero otherwise.
*
* \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.
*
* \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
* 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.
*
* \param devid the instance ID of the device to query.
* \param spec On return, will be filled with device details.
* \param sample_frames Pointer to store device buffer size, in sample frames.
* \param spec on return, will be filled with device details.
* \param sample_frames pointer to store device buffer size, in sample frames.
* Can be NULL.
* \returns 0 on success or a negative error code on failure; call
* 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
* 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
* 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
* 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
* 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
* 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.
*
* \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.
*
* \param devid an audio device id previously returned by
* SDL_OpenAudioDevice()
* SDL_OpenAudioDevice().
*
* \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 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
* 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.
*
* \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.
*
@ -819,8 +819,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
/**
* Create a new audio stream.
*
* \param src_spec The format details of the input audio
* \param dst_spec The format details of the output audio
* \param src_spec the format details of the input audio.
* \param dst_spec the format details of the output audio.
* \returns a new audio stream on success, or NULL on failure.
*
* \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.
*
* \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
* 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.
*
* \param stream the SDL_AudioStream to query.
* \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 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.
* \returns 0 on success, or -1 on error.
*
* \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
* file is still queued, and everything will still play back correctly.
*
* \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 stream the stream the format is being changed.
* \param src_spec the new format of the audio input; if NULL, it is not
* 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.
* \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.
*
* \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
* 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
* changed to create various effects.
*
* \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 stream the stream the frequency ratio is being changed.
* \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
* and 100.
* \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
* Get call would just dequeue the previously-converted data.
*
* \param stream The stream the audio data is being added to
* \param buf A pointer to the audio data to add
* \param len The number of bytes to write to the stream
* \param stream the stream the audio data is being added to.
* \param buf a pointer to the audio data to add.
* \param len the number of bytes to write to the stream.
* \returns 0 on success or a negative error code on failure; call
* 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
* to the stream and requesting the output just copied the converted data.
*
* \param stream The stream the audio is being requested from
* \param buf A buffer to fill with audio data
* \param len The maximum number of bytes to fill
* \returns the number of bytes read from the stream, or -1 on error
* \param stream the stream the audio is being requested from.
* \param buf a buffer to fill with audio data.
* \param len the maximum number of bytes to fill.
* \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
* 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
* clamped.
*
* \param stream The audio stream to query
* \param stream the audio stream to query.
* \returns the number of converted/resampled bytes available.
*
* \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
* clamped.
*
* \param stream The audio stream to query
* \param stream the audio stream to query.
* \returns the number of bytes queued.
*
* \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
* 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
* 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
* 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
* 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
* 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
* 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
* 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
* 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
* 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
* 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.
*
* \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
* 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
* if this callback does nothing.
*
* \param stream The SDL audio stream associated with this callback.
* \param additional_amount The amount of data, in bytes, that is needed right
* \param stream the SDL audio stream associated with this callback.
* \param additional_amount the amount of data, in bytes, that is needed right
* now.
* \param total_amount The total amount of data requested, in bytes, that is
* \param total_amount the total amount of data requested, in bytes, that is
* requested or available.
* \param userdata An opaque pointer provided by the app for their personal
* \param userdata an opaque pointer provided by the app for their personal
* use.
*
* \threadsafety This callbacks may run from any thread, so if you need to
@ -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,
* 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.
*
@ -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
* SDL_AUDIO_DEVICE_DEFAULT_CAPTURE.
* \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
* which case the app will need to call SDL_PutAudioStreamData
* 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.
* \returns an audio stream on success, ready to use. NULL on error; call
* 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.
*
* \param devid The ID of an opened audio device.
* \param callback A callback function to be called. Can be NULL.
* \param userdata App-controlled pointer passed to callback. Can be NULL.
* \param devid the ID of an opened audio device.
* \param callback a callback function to be called. 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
* information.
*
@ -1549,15 +1549,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID de
* SDL_LoadWAV("sample.wav", &spec, &buf, &len);
* ```
*
* \param src The data source for the WAVE data
* \param closeio If SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error
* \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
* data's format details on successful return
* \param audio_buf A pointer filled with the audio data, allocated by the
* function
* \param audio_len A pointer filled with the length of the audio data buffer
* in bytes
* \param src the data source for the WAVE data.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error.
* \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
* data's format details on successful return.
* \param audio_buf a pointer filled with the audio data, allocated by the
* function.
* \param audio_len a pointer filled with the length of the audio data buffer
* in bytes.
* \returns 0 on success. `audio_buf` will be filled with a pointer to an
* allocated buffer containing the audio data, and `audio_len` is
* filled with the length of that audio buffer in bytes.
@ -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);
* ```
*
* \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 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
* 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.
* \param audio_len A pointer filled with the length of the audio data buffer
* in bytes
* \param audio_len a pointer filled with the length of the audio data buffer
* in bytes.
* \returns 0 on success. `audio_buf` will be filled with a pointer to an
* allocated buffer containing the audio data, and `audio_len` is
* filled with the length of that audio buffer in bytes.
@ -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
* stream with a volume adjustment.
*
* \param dst the destination for the mixed audio
* \param src the source audio buffer to be mixed
* \param dst the destination for the mixed audio.
* \param src the source audio buffer to be mixed.
* \param format the SDL_AudioFormat structure representing the desired audio
* format
* \param len the length of the audio buffer in bytes
* format.
* \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
* audio volume
* audio volume.
* \returns 0 on success or a negative error code on failure; call
* 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
* convert multiple times.
*
* \param src_spec The format details of the input audio
* \param src_data The audio data to be converted
* \param src_len The len of src_data
* \param dst_spec The format details of the output audio
* \param dst_data Will be filled with a pointer to converted audio data,
* \param src_spec the format details of the input audio.
* \param src_data the audio data to be converted.
* \param src_len the len of src_data.
* \param dst_spec the format details of the output audio.
* \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
* 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
* SDL_GetError() for more information.
*

4
include/SDL3/SDL_bits.h
View file

@ -60,7 +60,7 @@ extern __inline int _SDL_bsr_watcom(Uint32);
* embedded in the calling program and the linker and dynamic loader will not
* 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.
*
* \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
* 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.
*
* \threadsafety It is safe to call this function from any thread.

12
include/SDL3/SDL_blendmode.h
View file

@ -168,18 +168,18 @@ typedef enum SDL_BlendFactor
* case.
*
* \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
* blue components of the destination pixels
* blue components of the destination pixels.
* \param colorOperation the SDL_BlendOperation used to combine the red,
* green, and blue components of the source and
* destination pixels
* destination pixels.
* \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
* the destination pixels
* the destination pixels.
* \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
* operations.
*

28
include/SDL3/SDL_camera.h
View file

@ -137,7 +137,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
* The returned string follows the SDL_GetStringRule.
*
* \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
* an invalid index was specified.
*
@ -232,7 +232,7 @@ extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraDeviceSupportedFormats(
*
* 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
* 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
* 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.
*
* \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
* immediately, but it might come seconds, minutes, or hours later!
*
* \param instance_id the camera device instance ID
* \param spec The desired format for data the device will provide. Can be
* \param instance_id the camera device instance ID.
* \param spec the desired format for data the device will provide. Can be
* NULL.
* \returns device, or NULL on failure; call SDL_GetError() for more
* 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
* 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,
* 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.
*
* \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
* 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.
*
* \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
* 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()
* occasionally until it returns non-zero.
*
* \param camera opened camera device
* \param spec The SDL_CameraSpec to be initialized by this function.
* \param camera opened camera device.
* \param spec the SDL_CameraSpec to be initialized by this function.
* \returns 0 on success or a negative error code on failure; call
* 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()
* 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
* error. Can be NULL.
* \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;
* assume the surface is freed and the pointer is invalid.
*
* \param camera opened camera device
* \param frame The video frame surface to release.
* \param camera opened camera device.
* \param frame the video frame surface to release.
* \returns 0 on success or a negative error code on failure; call
* 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
* device.
*
* \param camera opened camera device
* \param camera opened camera device.
*
* \threadsafety It is safe to call this function from any thread, but no
* thread may reference `device` once this function is called.

32
include/SDL3/SDL_clipboard.h
View file

@ -45,7 +45,7 @@ extern "C" {
/**
* Put UTF-8 text into the clipboard.
*
* \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
* 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.
*
* \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
* 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
* cleared in SDL_Quit().
*
* \param userdata A pointer to provided user data
* \param mime_type The requested mime-type
* \param size A pointer filled in with the length of the returned data
* \param userdata a pointer to provided user data.
* \param mime_type the requested mime-type.
* \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
* 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
@ -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
* 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.
*
@ -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
* document)
*
* \param callback A function pointer to the function that provides the
* clipboard data
* \param cleanup A function pointer to the function that cleans up the
* clipboard data
* \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 num_mime_types The number of mime-types in the mime_types list
* \param callback a function pointer to the function that provides the
* clipboard data.
* \param cleanup a function pointer to the function that cleans up the
* clipboard data.
* \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 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
* 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
* guaranteed to be null terminated.
*
* \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 mime_type the mime type to read from the clipboard.
* \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()
* for more information. Caller must call SDL_free() on the returned
* 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.
*
* \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
* type, SDL_FALSE if it does not.
*

42
include/SDL3/SDL_dialog.h
View file

@ -82,9 +82,9 @@ typedef struct SDL_DialogFileFilter
* no filter was selected or if the platform or method doesn't support
* fetching the selected filter.
*
* \param userdata An app-provided pointer, for the callback's use.
* \param filelist The file(s) chosen by the user.
* \param filter Index of the selected filter.
* \param userdata an app-provided pointer, for the callback's use.
* \param filelist the file(s) chosen by the user.
* \param filter index of the selected filter.
*
* \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
* 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
* error occurs. The first argument is a null-terminated list
* 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
* chosen, or -1 if the platform does not support detecting
* 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.
* \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.
* \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
* it may allow the user to ignore the filters.
* \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 nfilters the number of filters. Ignored if filters is NULL.
* \param default_location the default folder or file to start the dialog at.
* 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.
*
* \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
* 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
* error occurs. The first argument is a null-terminated list
* 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
* chosen, or -1 if the platform does not support detecting
* 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.
* \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.
* \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
* it may allow the user to ignore the filters.
* \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 nfilters the number of filters. Ignored if filters is NULL.
* \param default_location the default folder or file to start the dialog at.
* May be NULL. Not all platforms support this option.
*
* \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
* 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
* error occurs. The first argument is a null-terminated list
* 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
* is the userdata pointer passed to the function. The third
* 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.
* \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.
* \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.
* \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.
*
* \since This function is available since SDL 3.0.0.

8
include/SDL3/SDL_error.h
View file

@ -53,9 +53,9 @@ extern "C" {
* }
* ```
*
* \param fmt a printf()-style message format string
* \param fmt a printf()-style message format string.
* \param ... additional parameters matching % tokens in the `fmt` string, if
* any
* any.
* \returns always -1.
*
* \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.
*
* \returns -1
* \returns -1.
*
* \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.
*
* \returns 0
* \returns 0.
*
* \since This function is available since SDL 3.0.0.
*

54
include/SDL3/SDL_events.h
View file

@ -958,7 +958,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
* If you need to check for a range of event types, use SDL_HasEvents()
* 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
* 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.
*
* \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
* SDL_EventType for details
* SDL_EventType for details.
* \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
* 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
* 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.
*
@ -1028,9 +1028,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
* on the main thread immediately before the flush call.
*
* \param minType the low end of event type to be cleared, inclusive; see
* SDL_EventType for details
* SDL_EventType for details.
* \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.
*
@ -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
* the queue, or NULL
* the queue, or NULL.
* \returns SDL_TRUE if this got an event or SDL_FALSE if there are none
* 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.
*
* \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
* 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.
*
* \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
* available event
* available event.
* \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed
* 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
* 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
* code on failure; call SDL_GetError() for more information. A
* 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.
*
* \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
* SDL_AddEventWatch, etc
* \param event the event that triggered the callback
* SDL_AddEventWatch, etc.
* \param event the event that triggered the callback.
* \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.
*
@ -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
* not.
*
* \param filter An SDL_EventFilter function to call when an event happens
* \param userdata a pointer that is passed to `filter`
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`.
*
* \threadsafety SDL may call the filter callback at any time from any thread;
* the application is responsible for locking resources the
@ -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
* 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
* be stored here
* be stored here.
* \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.
@ -1271,7 +1271,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter,
* through SDL_PeepEvents().
*
* \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
* 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
* delete the corresponding callback.
*
* \param filter the function originally passed to SDL_AddEventWatch()
* \param userdata the pointer originally passed to SDL_AddEventWatch()
* \param filter the function originally passed to SDL_AddEventWatch().
* \param userdata the pointer originally passed to SDL_AddEventWatch().
*
* \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
* supplied filter until this function returns.
*
* \param filter the SDL_EventFilter function to call when an event happens
* \param userdata a pointer that is passed to `filter`
* \param filter the SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`.
*
* \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.
*
* \param type the type of event; see SDL_EventType for details
* \param enabled whether to process the event or not
* \param type the type of event; see SDL_EventType for details.
* \param enabled whether to process the event or not.
*
* \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.
*
* \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.
*
* \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
* 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
* 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
* 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
* SDL_GetError() for more information.
*

26
include/SDL3/SDL_filesystem.h
View file

@ -127,8 +127,8 @@ extern SDL_DECLSPEC char *SDLCALL SDL_GetBasePath(void);
* The pointer returned is owned by the caller. Please call SDL_free() on the
* pointer when done with it.
*
* \param org the name of your organization
* \param app the name of your application
* \param org the name of your organization.
* \param app the name of your application.
* \returns a UTF-8 string of the user directory in platform-dependent
* notation. NULL if there's a problem (creating directory failed,
* etc.).
@ -232,7 +232,7 @@ typedef enum SDL_Folder
*
* 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
* folder, or NULL if an error happened.
*
@ -277,7 +277,7 @@ typedef Uint32 SDL_GlobFlags;
/**
* 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
* 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
* provided or the callback returns <= 0.
*
* \param path the path of the directory to enumerate
* \param callback a function that is called for each entry in the directory
* \param userdata a pointer that is passed to `callback`
* \param path the path of the directory to enumerate.
* \param callback a function that is called for each entry in the directory.
* \param userdata a pointer that is passed to `callback`.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \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
* SDL_GetError() for more information.
*
@ -322,8 +322,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RemovePath(const char *path);
/**
* Rename a file or directory.
*
* \param oldpath the old path
* \param newpath the new path
* \param oldpath the old path.
* \param newpath the new path.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \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
* 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,
* 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.
*
* \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
* NULL.
* \param flags `SDL_GLOB_*` bitflags that affect this search.

220
include/SDL3/SDL_gamepad.h
View file

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

8
include/SDL3/SDL_guid.h
View file

@ -68,9 +68,9 @@ typedef struct SDL_GUID {
*
* You should supply at least 33 bytes for pszGUID.
*
* \param guid the SDL_GUID you wish to convert to string
* \param pszGUID buffer in which to write the ASCII string
* \param cbGUID the size of pszGUID
* \param guid the SDL_GUID you wish to convert to string.
* \param pszGUID buffer in which to write the ASCII string.
* \param cbGUID the size of pszGUID.
* \returns 0 on success or a negative error code on failure; call
* 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
* 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.
*
* \since This function is available since SDL 3.0.0.

86
include/SDL3/SDL_haptic.h
View file

@ -932,7 +932,8 @@ typedef Uint32 SDL_HapticID;
/**
* Get a list of currently connected haptic devices.
*
* \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
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
@ -950,7 +951,7 @@ extern SDL_DECLSPEC SDL_HapticID *SDLCALL SDL_GetHaptics(int *count);
*
* 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,
* this function returns NULL; call SDL_GetError() for more
* 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()
* 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
* 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.
*
* \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
* 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.
*
* \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
* 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.
*
* \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,
* this function returns NULL; call SDL_GetError() for more
* information.
@ -1053,7 +1054,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHapticFromMouse(void);
/**
* 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.
*
* \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
* 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;
* 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().
*
* \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.
*
@ -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
* 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
* 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.
*
* \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
* or a negative error code on failure; call SDL_GetError() for more
* 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.
*
* \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
* 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
* 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;
* 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.
*
* \param haptic the SDL_Haptic device to query
* \param effect the desired effect to query
* \param haptic the SDL_Haptic device to query.
* \param effect the desired effect to query.
* \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.
@ -1175,9 +1176,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti
/**
* 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
* the effect to create
* the effect to create.
* \returns the ID of the effect on success or a negative error code on
* failure; call SDL_GetError() for more information.
*
@ -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
* running SDL_UpdateHapticEffect().
*
* \param haptic the SDL_Haptic device that has the effect
* \param effect the identifier of the effect to update
* \param haptic the SDL_Haptic device that has the effect.
* \param effect the identifier of the effect to update.
* \param data an SDL_HapticEffect structure containing the new effect
* properties to use
* properties to use.
* \returns 0 on success or a negative error code on failure; call
* 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`
* instead.
*
* \param haptic the SDL_Haptic device to run the effect on
* \param effect the ID of the haptic effect to run
* \param haptic the SDL_Haptic device to run the effect on.
* \param effect the ID of the haptic effect to run.
* \param iterations the number of iterations to run the effect; use
* `SDL_HAPTIC_INFINITY` to repeat forever
* `SDL_HAPTIC_INFINITY` to repeat forever.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param haptic the SDL_Haptic device to stop the effect on
* \param effect the ID of the haptic effect to stop
* \param haptic the SDL_Haptic device to stop the effect on.
* \param effect the ID of the haptic effect to stop.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -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
* destroyed when the device is closed.
*
* \param haptic the SDL_Haptic device to destroy the effect on
* \param effect the ID of the haptic effect to destroy
* \param haptic the SDL_Haptic device to destroy the effect on.
* \param effect the ID of the haptic effect to destroy.
*
* \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.
*
* \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 haptic the SDL_Haptic device to query for the effect status on.
* \param effect the ID of the haptic effect to query its status.
* \returns 0 if it isn't playing, 1 if it is playing, or a negative error
* code on failure; call SDL_GetError() for more information.
*
@ -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
* maximum.
*
* \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 haptic the SDL_Haptic device to set the gain on.
* \param gain value to set the gain to, should be between 0 and 100 (0 -
* 100).
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -1308,8 +1310,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain);
*
* Device must support the SDL_HAPTIC_AUTOCENTER feature.
*
* \param haptic the SDL_Haptic device to set autocentering on
* \param autocenter value to set autocenter to (0-100)
* \param haptic the SDL_Haptic device to set autocentering on.
* \param autocenter value to set autocenter to (0-100).
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -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
* 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
* 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().
*
* \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
* 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.
*
* \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
* 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.
*
* \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.
*
* \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.
*
* \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
* 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.
*
* \param haptic the haptic device to play the rumble effect on
* \param strength strength of the rumble to play as a 0-1 float value
* \param length length of the rumble to play in milliseconds
* \param haptic the haptic device to play the rumble effect on.
* \param strength strength of the rumble to play as a 0-1 float value.
* \param length length of the rumble to play in milliseconds.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -1413,7 +1415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float s
/**
* 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
* SDL_GetError() for more information.
*

90
include/SDL3/SDL_hidapi.h
View file

@ -225,9 +225,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
* or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS
* 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.
* \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.
* \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
@ -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().
*
* \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().
*
* \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
* is opened.
*
* \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 serial_number The Serial Number of the device to open (Optionally
* \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 serial_number the Serial Number of the device to open (Optionally
* NULL).
* \returns a pointer to a SDL_hid_device object on success or NULL on
* 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
* 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
* 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
* (Endpoint 0).
*
* \param dev A device handle returned from SDL_hid_open().
* \param data The data to send, including the report number as the first
* \param dev a device handle returned from SDL_hid_open().
* \param data the data to send, including the report number as the first
* 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.
*
* \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
* reports.
*
* \param dev A device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into.
* \param length The number of bytes to read. For devices with multiple
* \param dev a device handle returned from SDL_hid_open().
* \param data a buffer to put the read data into.
* \param length the number of bytes to read. For devices with multiple
* reports, make sure to read an extra byte for the report
* number.
* \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
* reports.
*
* \param dev A device handle returned from SDL_hid_open().
* \param data A buffer to put the read data into.
* \param length The number of bytes to read. For devices with multiple
* \param dev a device handle returned from SDL_hid_open().
* \param data a buffer to put the read data into.
* \param length the number of bytes to read. For devices with multiple
* reports, make sure to read an extra byte for the report
* number.
* \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.
*
* \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
* nonblocking - 0 to disable nonblocking.
* \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
* bytes). In this example, the length passed in would be 17.
*
* \param dev A device handle returned from SDL_hid_open().
* \param data The data to send, including the report number as the first
* \param dev a device handle returned from SDL_hid_open().
* \param data the data to send, including the report number as the first
* 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.
* \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
* in data[1].
*
* \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 dev a device handle returned from SDL_hid_open().
* \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
* be read, or set it to zero if your device does not use numbered
* 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.
* \returns the number of bytes read plus one for the report ID (which is
* 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
* in data[1].
*
* \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 dev a device handle returned from SDL_hid_open().
* \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
* be read, or set it to zero if your device does not use numbered
* 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.
* \returns the number of bytes read plus one for the report ID (which is
* 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.
*
* \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
* 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.
*
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \param dev a device handle returned from SDL_hid_open().
* \param string a wide string buffer to put the data into.
* \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \param dev a device handle returned from SDL_hid_open().
* \param string a wide string buffer to put the data into.
* \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \param dev a device handle returned from SDL_hid_open().
* \param string a wide string buffer to put the data into.
* \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param dev A device handle returned from SDL_hid_open().
* \param string_index The index of the string to get.
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \param dev a device handle returned from SDL_hid_open().
* \param string_index the index of the string to get.
* \param string a wide string buffer to put the data into.
* \param maxlen the length of the buffer in multiples of wchar_t.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \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
* in the case of failure; call SDL_GetError() for more information.
* 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
* to. The recommended size for a preallocated buffer is 4096 bytes.
*
* \param dev A device handle returned from SDL_hid_open().
* \param buf The buffer to copy descriptor into.
* \param buf_size The size of the buffer in bytes.
* \param dev a device handle returned from SDL_hid_open().
* \param buf the buffer to copy descriptor into.
* \param buf_size the size of the buffer in bytes.
* \returns the number of bytes actually copied, or -1 on error; call
* 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.
*
* \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.
*/

42
include/SDL3/SDL_hints.h
View file

@ -3755,9 +3755,9 @@ typedef enum SDL_HintPriority
* value. Hints will replace existing hints of their priority and lower.
* Environment variables are considered to have override priority.
*
* \param name the hint to set
* \param value the value of the hint variable
* \param priority the SDL_HintPriority level for the hint
* \param name the hint to set.
* \param value the value of the hint variable.
* \param priority the SDL_HintPriority level for the hint.
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
*
* \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
* set the hint with override priority instead.
*
* \param name the hint to set
* \param value the value of the hint variable
* \param name the hint to set.
* \param value the value of the hint variable.
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
*
* \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
* change.
*
* \param name the hint to set
* \param name the hint to set.
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
*
* \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.
*
* \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.
*
* \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.
*
* \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 name the name of the hint to get the boolean value from.
* \param default_value the value to return if the hint does not exist.
* \returns the boolean value of a hint or the provided default value if the
* hint does not exist.
*
@ -3853,10 +3853,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo
/**
* Type definition of the hint callback function.
*
* \param userdata what was passed as `userdata` to SDL_AddHintCallback()
* \param name what was passed as `name` to SDL_AddHintCallback()
* \param oldValue the previous hint value
* \param newValue the new value hint is to be set to
* \param userdata what was passed as `userdata` to SDL_AddHintCallback().
* \param name what was passed as `name` to SDL_AddHintCallback().
* \param oldValue the previous hint value.
* \param newValue the new value hint is to be set to.
*
* \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.
*
* \param name the hint to watch
* \param callback An SDL_HintCallback function that will be called when the
* hint value changes
* \param userdata a pointer to pass to the callback function
* \param name the hint to watch.
* \param callback an SDL_HintCallback function that will be called when the
* hint value changes.
* \param userdata a pointer to pass to the callback function.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param name the hint being watched
* \param callback An SDL_HintCallback function that will be called when the
* hint value changes
* \param userdata a pointer being passed to the callback function
* \param name the hint being watched.
* \param callback an SDL_HintCallback function that will be called when the
* hint value changes.
* \param userdata a pointer being passed to the callback function.
*
* \since This function is available since SDL 3.0.0.
*

2
include/SDL3/SDL_init.h
View file

@ -105,7 +105,7 @@ typedef Uint32 SDL_InitFlags;
* call SDL_Quit() to force shutdown). If a subsystem is already loaded then
* 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
* SDL_GetError() for more information.
*

172
include/SDL3/SDL_iostream.h
View file

@ -221,7 +221,7 @@ typedef struct SDL_IOStream SDL_IOStream;
* the filesystem. If SDL used some other method to access the filesystem,
* 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
* the file.
* \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
* memory instead.
*
* \param mem a pointer to a buffer to feed an SDL_IOStream stream
* \param size the buffer size, in bytes
* \param mem a pointer to a buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
* 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()
* with a writable buffer of memory instead.
*
* \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream
* \param size the buffer size, in bytes
* \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
* 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 data around after this call.
*
* \param iface The function pointers that implement this SDL_IOStream.
* \param userdata The app-controlled pointer that is passed to iface's
* \param iface the function pointers that implement this SDL_IOStream.
* \param userdata the app-controlled pointer that is passed to iface's
* functions when called.
* \returns a pointer to the allocated memory on success, or NULL on failure;
* 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
* 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
* 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.
*
* \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
* 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.
*
* \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
* negative error code on failure; call SDL_GetError() for more
* 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.
*
* \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
* negative
* negative.
* \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
* 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.
*
* \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
* 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
* SDL_GetIOStatus().
*
* \param context a pointer to an SDL_IOStream structure
* \param ptr a pointer to a buffer to read data into
* \param context a pointer to an SDL_IOStream structure.
* \param ptr a pointer to a buffer to read data into.
* \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.
*
@ -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,
* or a fatal error.
*
* \param context a pointer to an SDL_IOStream structure
* \param ptr a pointer to a buffer containing data to write
* \param size the number of bytes to write
* \param context a pointer to an SDL_IOStream structure.
* \param ptr a pointer to a buffer containing data to write.
* \param size the number of bytes to write.
* \returns the number of bytes written, which will be less than `size` on
* 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.
*
* \param context a pointer to an SDL_IOStream structure
* \param fmt a printf() style format string
* \param context a pointer to an SDL_IOStream structure.
* \param fmt a printf() style format string.
* \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()
* 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.
*
* \param context a pointer to an SDL_IOStream structure
* \param fmt a printf() style format string
* \param ap a variable argument list
* \param context a pointer to an SDL_IOStream structure.
* \param fmt a printf() style format string.
* \param ap a variable argument list.
* \returns the number of bytes written, or 0 on error; call SDL_GetError()
* 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().
*
* \param src the SDL_IOStream to read all available data from
* \param datasize if not NULL, will store the number of bytes read
* \param src the SDL_IOStream to read all available data from.
* \param datasize if not NULL, will store the number of bytes read.
* \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.
*
* \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().
*
* \param file the path to read all available data from
* \param datasize if not NULL, will store the number of bytes read
* \param file the path to read all available data from.
* \param datasize if not NULL, will store the number of bytes read.
* \returns the data, or NULL if there was an error.
*
* \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.
*
* \param src the SDL_IOStream to read from
* \param value a pointer filled in with the data read
* \param src the SDL_IOStream to read from.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
* 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.
*
* \param src the SDL_IOStream to read from
* \param value a pointer filled in with the data read
* \param src the SDL_IOStream to read from.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* the native byte order.
*
* \param src the stream from which to read data
* \param value a pointer filled in with the data read
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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.
*
* \param dst the SDL_IOStream to write to
* \param value the byte value to write
* \param dst the SDL_IOStream to write to.
* \param value the byte value to write.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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.
*
* \param dst the SDL_IOStream to write to
* \param value the byte value to write
* \param dst the SDL_IOStream to write to.
* \param value the byte value to write.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* specifies native format, and the data written will be in big-endian format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* specifies native format, and the data written will be in big-endian format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* specifies native format, and the data written will be in big-endian format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* specifies native format, and the data written will be in big-endian format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* specifies native format, and the data written will be in big-endian format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* 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
* specifies native format, and the data written will be in big-endian format.
*
* \param dst the stream to which data will be written
* \param value the data to be written, in native format
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* SDL_GetError() for more information.
*

184
include/SDL3/SDL_joystick.h
View file

@ -210,7 +210,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
/**
* Get a list of currently connected joysticks.
*
* \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
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
@ -229,7 +229,7 @@ extern SDL_DECLSPEC SDL_JoystickID *SDLCALL SDL_GetJoysticks(int *count);
*
* 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
* 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.
*
* \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
* 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.
*
* \param instance_id the joystick instance ID
* \returns the player index of a joystick, or -1 if it's not available
* \param instance_id the joystick instance ID.
* \returns the player index of a joystick, or -1 if it's not available.
*
* \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.
*
* \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
* 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
* 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
* 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
* 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
* 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
* 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
* 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.
*
* \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
* invalid instance_id, this function returns
* `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
* 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
* 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.
*
* \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
* 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.
*
* \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()
* for more information.
*
@ -469,7 +469,7 @@ typedef struct SDL_VirtualJoystickDesc
/**
* 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
* SDL_GetError() for more information.
*
@ -483,7 +483,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V
* Detach a virtual joystick.
*
* \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
* 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.
*
* \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.
*
* \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.
* \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
* finger is released
* finger is released.
* \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,
* with the origin in the upper left
* \param pressure the pressure of the finger
* with the origin in the upper left.
* \param pressure the pressure of the finger.
* \returns 0 on success or a negative error code on failure; call
* 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 type the type of the sensor on the virtual joystick to update.
* \param sensor_timestamp a 64-bit timestamp in nanoseconds 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`
* the sensor reading.
* \param data the data associated with the sensor reading.
* \param num_values the number of values pointed to by `data`.
* \returns 0 on success or a negative error code on failure; call
* 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
* 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
* 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.
*
* \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
* 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.
*
* \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
* 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
* 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.
*
* \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.
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
* \param player_index Player index to assign to this joystick, or -1 to clear
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \param player_index player index to assign to this joystick, or -1 to clear
* the player index and turn off player LEDs.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \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,
* this function returns a zero GUID; call SDL_GetError() for more
* 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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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
* unavailable.
*
@ -805,7 +805,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *
*
* 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
* unavailable.
*
@ -816,7 +816,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy
/**
* 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.
*
* \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.
*
* \param guid the SDL_JoystickGUID you wish to convert to string
* \param pszGUID buffer in which to write the ASCII string
* \param cbGUID the size of pszGUID
* \param guid the SDL_JoystickGUID you wish to convert to string.
* \param pszGUID buffer in which to write the ASCII string.
* \param cbGUID the size of pszGUID.
* \returns 0 on success or a negative error code on failure; call
* 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
* 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.
*
* \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.
*
* \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
* available
* \param product A pointer filled in with the device PID, or 0 if not
* available
* \param version A pointer filled in with the device version, or 0 if not
* available
* \param crc16 A pointer filled in with a CRC used to distinguish different
* products with the same VID/PID, or 0 if not available
* \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
* available.
* \param product a pointer filled in with the device PID, or 0 if not
* available.
* \param version a pointer filled in with the device version, or 0 if not
* available.
* \param crc16 a pointer filled in with a CRC used to distinguish different
* products with the same VID/PID, or 0 if not available.
*
* \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.
*
* \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;
* 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.
*
* \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
* 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
* 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
* negative error code on failure; call SDL_GetError() for more
* information.
@ -930,7 +930,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick);
*
* 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
* 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.
*
* \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
* 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.
*
* \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
* 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
* 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.
*
@ -1030,8 +1030,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void);
* 32767) representing the current position of the axis. It may be necessary
* to impose certain tolerances on these values to account for jitter.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \param axis the axis to query; the axis indices start at index 0
* \param joystick an SDL_Joystick structure containing joystick information.
* \param axis the axis to query; the axis indices start at index 0.
* \returns a 16-bit signed integer representing the current position of the
* axis or 0 on failure; call SDL_GetError() for more information.
*
@ -1048,9 +1048,9 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i
*
* The axis indices start at index 0.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \param axis the axis to query; the axis indices start at index 0
* \param state Upon return, the initial value is supplied here.
* \param joystick an SDL_Joystick structure containing joystick information.
* \param axis the axis to query; the axis indices start at index 0.
* \param state upon return, the initial value is supplied here.
* \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.
@ -1065,10 +1065,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic
*
* Most joysticks do not have trackballs.
*
* \param joystick the SDL_Joystick to query
* \param ball the ball index to query; ball indices start at index 0
* \param dx stores the difference in the x axis position since the last poll
* \param dy stores the difference in the y axis position since the last poll
* \param joystick the SDL_Joystick to query.
* \param ball the ball index to query; ball indices start at index 0.
* \param dx stores the difference in the x axis position since the last poll.
* \param dy stores the difference in the y axis position since the last poll.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -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.
*
* \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 joystick an SDL_Joystick structure containing joystick information.
* \param hat the hat index to get the state from; indices start at index 0.
* \returns the current hat position.
*
* \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.
*
* \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
* index 0
* index 0.
* \returns 1 if the specified button is pressed, 0 otherwise.
*
* \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
* SDL_UpdateJoysticks() to update rumble state.
*
* \param joystick The joystick to vibrate
* \param low_frequency_rumble The intensity of the low frequency (left)
* rumble motor, from 0 to 0xFFFF
* \param high_frequency_rumble The intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
* \returns 0, or -1 if rumble isn't supported on this joystick
* \param joystick the joystick to vibrate.
* \param low_frequency_rumble the intensity of the low frequency (left)
* rumble motor, from 0 to 0xFFFF.
* \param high_frequency_rumble the intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF.
* \param duration_ms the duration of the rumble effect, in milliseconds.
* \returns 0, or -1 if rumble isn't supported on this joystick.
*
* \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
* SDL_UpdateJoysticks() to update rumble state.
*
* \param joystick The joystick to vibrate
* \param left_rumble The intensity of the left trigger rumble motor, from 0
* to 0xFFFF
* \param right_rumble The intensity of the right trigger rumble motor, from 0
* to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
* \param joystick the joystick to vibrate.
* \param left_rumble the intensity of the left trigger rumble motor, from 0
* to 0xFFFF.
* \param right_rumble the intensity of the right trigger rumble motor, from 0
* to 0xFFFF.
* \param duration_ms the duration of the rumble effect, in milliseconds.
* \returns 0 on success or a negative error code on failure; call
* 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
* be used as the LED brightness.
*
* \param joystick The joystick to update
* \param red The intensity of the red LED
* \param green The intensity of the green LED
* \param blue The intensity of the blue LED
* \param joystick the joystick to update.
* \param red the intensity of the red LED.
* \param green the intensity of the green LED.
* \param blue the intensity of the blue LED.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param joystick The joystick to affect
* \param data The data to send to the joystick
* \param size The size of the data to send to the joystick
* \param joystick the joystick to affect.
* \param data 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
* 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().
*
* \param joystick The joystick device to close
* \param joystick the joystick device to close.
*
* \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.
*
* \param joystick The joystick to query
* \param joystick the joystick to query.
* \returns the connection state on success or
* `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError()
* 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
* 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
* 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

26
include/SDL3/SDL_keyboard.h
View file

@ -92,7 +92,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
* power buttons, etc. You should wait for input from a device before you
* 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
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
@ -111,7 +111,7 @@ extern SDL_DECLSPEC SDL_KeyboardID *SDLCALL SDL_GetKeyboards(int *count);
*
* 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
* 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
* 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.
*
* \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
* 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.
*
@ -210,7 +210,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
*
* 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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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
* 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
* 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.
*
* \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
* 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.
*
* \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
* 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
@ -318,7 +318,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
/**
* 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
* SDL_GetError() for more information.
*
@ -396,7 +396,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ClearComposition(void);
* any feedback.
*
* \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
* 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.
*
* \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.
*
* \since This function is available since SDL 3.0.0.

8
include/SDL3/SDL_loadso.h
View file

@ -55,7 +55,7 @@ extern "C" {
/**
* Dynamically load a shared object.
*
* \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
* 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.
*
* \param handle a valid shared object handle returned by SDL_LoadObject()
* \param name the name of the function to look up
* \param handle a valid shared object handle returned by SDL_LoadObject().
* \param name the name of the function to look up.
* \returns a pointer to the function or NULL if there was an error; call
* 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.
*
* \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.
*

83
include/SDL3/SDL_log.h
View file

@ -110,7 +110,7 @@ typedef enum SDL_LogPriority
/**
* 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.
*
@ -122,8 +122,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
/**
* Set the priority of a particular log category.
*
* \param category the category to assign a priority to
* \param priority the SDL_LogPriority to assign
* \param category the category to assign a priority to.
* \param priority the SDL_LogPriority to assign.
*
* \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.
*
* \param category the category to query
* \returns the SDL_LogPriority for the requested category
* \param category the category to query.
* \returns the SDL_LogPriority for the requested category.
*
* \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.
*
* \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
* any
* any.
*
* \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.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param category the category of the message.
* \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
* if any.
*
* \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.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param category the category of the message.
* \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
* if any.
*
* \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.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param category the category of the message.
* \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
* if any.
*
* \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.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param category the category of the message.
* \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
* if any.
*
* \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.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param category the category of the message.
* \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
* if any.
*
* \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.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param category the category of the message.
* \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
* if any.
*
* \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.
*
* \param category the category of the message
* \param priority the priority of the message
* \param fmt a printf() style message format string
* \param category the category of the message.
* \param priority the priority of the message.
* \param fmt a printf() style message format string.
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
* if any.
*
* \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.
*
* \param category the category of the message
* \param priority the priority of the message
* \param fmt a printf() style message format string
* \param ap a variable argument list
* \param category the category of the message.
* \param priority the priority of the message.
* \param fmt a printf() style message format string.
* \param ap a variable argument list.
*
* \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.
*
* \param userdata what was passed as `userdata` to SDL_SetLogOutputFunction()
* \param category the category of the message
* \param priority the priority of the message
* \param message the message being output
* \param userdata what was passed as `userdata` to
* SDL_SetLogOutputFunction().
* \param category the category of the message.
* \param priority the priority of the message.
* \param message the message being output.
*
* \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.
*
* \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
* `callback`
* `callback`.
*
* \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.
*
* \param callback an SDL_LogOutputFunction to call instead of the default
* \param userdata a pointer that is passed to `callback`
* \param callback an SDL_LogOutputFunction to call instead of the default.
* \param userdata a pointer that is passed to `callback`.
*
* \since This function is available since SDL 3.0.0.
*

32
include/SDL3/SDL_main.h
View file

@ -287,8 +287,8 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
*
* \param appstate a place where the app can optionally store a pointer for
* future use.
* \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 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
* arguments.
* \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
* 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
* *not* need SDL_SetMainReady().
*
* \param argc The argc parameter from the application's main() function, or 0
* if the platform's main-equivalent has no argc
* \param argv The argv parameter from the application's main() function, or
* 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 argc the argc parameter from the application's main() function, or 0
* if the platform's main-equivalent has no argc.
* \param argv the argv parameter from the application's main() function, or
* NULL if the platform's main-equivalent has no argv.
* \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
* literally have to be `main`.
* \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;
* 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
* 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
* _really_ know what you're doing.
*
* \param argc standard Unix main argc
* \param argv standard Unix main argv
* \param appinit The application's SDL_AppInit function
* \param appiter The application's SDL_AppIterate function
* \param appevent The application's SDL_AppEvent function
* \param appquit The application's SDL_AppQuit function
* \returns standard Unix main return value
* \param argc standard Unix main argc.
* \param argv standard Unix main argv.
* \param appinit the application's SDL_AppInit function.
* \param appiter the application's SDL_AppIterate function.
* \param appevent the application's SDL_AppEvent function.
* \param appquit the application's SDL_AppQuit function.
* \returns standard Unix main return value.
*
* \threadsafety It is not safe to call this anywhere except as the only
* function call in SDL_main.

13
include/SDL3/SDL_messagebox.h
View file

@ -151,8 +151,9 @@ typedef struct SDL_MessageBoxData
* to stderr if you can.
*
* \param messageboxdata the SDL_MessageBoxData structure with title, text and
* other options
* \param buttonid the pointer to which user id of hit button should be copied
* other options.
* \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
* 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
* to stderr if you can.
*
* \param flags an SDL_MessageBoxFlags value
* \param title UTF-8 title text
* \param message UTF-8 message text
* \param window the parent window, or NULL for no parent
* \param flags an SDL_MessageBoxFlags value.
* \param title uTF-8 title text.
* \param message uTF-8 message text.
* \param window the parent window, or NULL for no parent.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*

10
include/SDL3/SDL_metal.h
View file

@ -58,8 +58,8 @@ typedef void *SDL_MetalView;
* The returned handle can be casted directly to a NSView or UIView. To access
* the backing CAMetalLayer, call SDL_Metal_GetLayer().
*
* \param window the window
* \returns handle NSView or UIView
* \param window the window.
* \returns handle NSView or UIView.
*
* \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
* 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.
*
@ -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.
*
* \param view the SDL_MetalView object
* \returns a pointer
* \param view the SDL_MetalView object.
* \returns a pointer.
*
* \since This function is available since SDL 3.0.0.
*/

2
include/SDL3/SDL_misc.h
View file

@ -60,7 +60,7 @@ extern "C" {
* All this to say: this function can be useful, but you should definitely
* 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.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.

50
include/SDL3/SDL_mouse.h
View file

@ -135,7 +135,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
* You should wait for input from a device before you consider it actively in
* 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
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
@ -154,7 +154,7 @@ extern SDL_DECLSPEC SDL_MouseID *SDLCALL SDL_GetMice(int *count);
*
* 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
* SDL_GetError() for more information.
*
@ -183,9 +183,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
* either `x` or `y`.
*
* \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
* focus window
* focus window.
* \returns a 32-bit button bitmask of the current button state.
*
* \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.
*
* \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
* NULL
* NULL.
* \returns the current button state as a bitmask which can be tested using
* 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
* 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 y a pointer filled with the last recorded y 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.
* \returns a 32-bit button bitmask of the relative button state.
*
* \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.
*
* \param window the window to move the mouse into, or NULL for the current
* mouse focus
* \param x the x coordinate within the window
* \param y the y coordinate within the window
* mouse focus.
* \param x the x coordinate within the window.
* \param y the y coordinate within the window.
*
* \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
* mouse when used over Microsoft Remote Desktop.
*
* \param x the x coordinate
* \param y the y coordinate
* \param x the x coordinate.
* \param y the y coordinate.
* \returns 0 on success or a negative error code on failure; call
* 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
* readily-available system cursors to pick from.
*
* \param data the color 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 h the height 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 w the width 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
* 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
* 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
* 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.
*
* \param surface an SDL_Surface structure representing the cursor image
* \param hot_x the x position of the cursor hot spot
* \param hot_y the y position of the cursor hot spot
* \param surface an SDL_Surface structure representing the cursor image.
* \param hot_x the x 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()
* for more information.
*
@ -434,7 +434,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surfa
/**
* 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
* 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
* 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
* 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(),
* 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.
*

54
include/SDL3/SDL_mutex.h
View file

@ -181,7 +181,7 @@ extern SDL_DECLSPEC SDL_Mutex *SDLCALL SDL_CreateMutex(void);
* having locked nothing. If the mutex is valid, this function will always
* 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.
*
@ -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
* nothing.
*
* \param mutex the mutex to try to lock
* \returns 0 or `SDL_MUTEX_TIMEDOUT`
* \param mutex the mutex to try to lock.
* \returns 0 or `SDL_MUTEX_TIMEDOUT`.
*
* \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
* 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.
*
@ -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
* 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.
*
@ -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
* 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.
*
@ -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
* and lock nothing.
*
* \param rwlock the rwlock to try to lock
* \returns 0 or `SDL_RWLOCK_TIMEDOUT`
* \param rwlock the rwlock to try to lock.
* \returns 0 or `SDL_RWLOCK_TIMEDOUT`.
*
* \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
* and lock nothing.
*
* \param rwlock the rwlock to try to lock
* \returns 0 or `SDL_RWLOCK_TIMEDOUT`
* \param rwlock the rwlock to try to lock.
* \returns 0 or `SDL_RWLOCK_TIMEDOUT`.
*
* \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
* 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.
*
@ -537,7 +537,7 @@ typedef struct SDL_Semaphore SDL_Semaphore;
* is 0. Each post operation will atomically increment the semaphore value and
* 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
* 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
* 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.
*
@ -577,7 +577,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem);
* This function is the equivalent of calling SDL_WaitSemaphoreTimeout() with
* 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
* 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
* 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
* block, or a negative error code on failure; call SDL_GetError()
* 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
* successful it will atomically decrement the semaphore value.
*
* \param sem the semaphore to wait on
* \param timeoutMS the length of the timeout, in milliseconds
* \param sem the semaphore to wait on.
* \param timeoutMS the length of the timeout, in milliseconds.
* \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;
* 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.
*
* \param sem the semaphore to increment
* \param sem the semaphore to increment.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param sem the semaphore to query
* \param sem the semaphore to query.
* \returns the current value of the semaphore.
*
* \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.
*
* \param cond the condition variable to destroy
* \param cond the condition variable to destroy.
*
* \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.
*
* \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
* 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.
*
* \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
* 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
* a time length of -1.
*
* \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access
* \param cond the condition variable to wait on.
* \param mutex the mutex used to coordinate thread access.
* \returns 0 when it is signaled or a negative error code on failure; call
* 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
* behavior.
*
* \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access
* \param cond the condition variable to wait on.
* \param mutex the mutex used to coordinate thread access.
* \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
* the condition is not signaled in the allotted time, or a negative
* error code on failure; call SDL_GetError() for more information.

32
include/SDL3/SDL_pen.h
View file

@ -154,7 +154,7 @@ typedef enum SDL_PenSubtype
* throughout a session. To track pens across sessions (program restart), use
* 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).
* \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,
@ -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
* default values.
*
* \param instance_id The pen to query.
* \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 axes Out-mode parameter for axis information. May be null. The axes
* \param instance_id the pen to query.
* \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 axes out-mode parameter for axis information. May be null. The axes
* 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
* etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of
* 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.
*
* \param guid A pen GUID.
* \param guid a pen GUID.
* \returns a valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
* 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.
*
* \param instance_id The pen to query.
* \param instance_id the pen to query.
* \returns the corresponding pen GUID; persistent across multiple sessions.
* 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
* 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
* 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.
*
* \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
* consumption. The string might or might not be localised, depending
* on platform settings. It is not guaranteed to be unique; use
* SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
* is managed by the SDL pen subsystem and must not be deallocated.
* 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.
*/
@ -254,10 +254,10 @@ typedef struct SDL_PenCapabilityInfo
/**
* Retrieves capability flags for a given SDL_PenID.
*
* \param instance_id The pen to query.
* \param capabilities Detail information about pen capabilities, such as the
* number of buttons
* \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES
* \param instance_id the pen to query.
* \param capabilities detail information about pen capabilities, such as the
* number of buttons.
* \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES.
*
* \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.
*
* \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.
* 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

88
include/SDL3/SDL_pixels.h
View file

@ -760,7 +760,7 @@ typedef struct SDL_PixelFormat
*
* 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
* `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.
*
* \param format one of the SDL_PixelFormatEnum values
* \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 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 Amask a pointer filled in with the alpha mask for the format
* \param format one of the SDL_PixelFormatEnum values.
* \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 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 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
* 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
* possible.
*
* \param bpp a bits per pixel value; usually 15, 16, or 32
* \param Rmask the red mask for the format
* \param Gmask the green mask for the format
* \param Bmask the blue mask for the format
* \param Amask the alpha mask for the format
* \param bpp a bits per pixel value; usually 15, 16, or 32.
* \param Rmask the red mask for the format.
* \param Gmask the green mask for the format.
* \param Bmask the blue mask for the format.
* \param Amask the alpha mask for the format.
* \returns the SDL_PixelFormatEnum value corresponding to the format masks,
* 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
* 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
* 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().
*
* \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.
*
@ -849,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPixelFormat(SDL_PixelFormat *format)
*
* 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
* there wasn't enough memory); call SDL_GetError() for more
* information.
@ -865,8 +865,8 @@ extern SDL_DECLSPEC SDL_Palette *SDLCALL SDL_CreatePalette(int ncolors);
/**
* Set the palette for a pixel format structure.
*
* \param format the SDL_PixelFormat structure that will use the palette
* \param palette the SDL_Palette structure that will be used
* \param format the SDL_PixelFormat structure that will use the palette.
* \param palette the SDL_Palette structure that will be used.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param palette the SDL_Palette structure to modify
* \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 ncolors the number of entries to modify
* \param palette the SDL_Palette structure to modify.
* \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 ncolors the number of entries to modify.
* \returns 0 on success or a negative error code on failure; call
* 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().
*
* \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.
*
@ -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
* for an 8-bpp 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 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
* \returns a pixel value
* \param format an SDL_PixelFormat structure describing the pixel format.
* \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 b the blue component of the pixel in the range 0-255.
* \returns a pixel value.
*
* \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).
*
* \param format an SDL_PixelFormat structure describing the format of the
* pixel
* \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 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
* \returns a pixel value
* pixel.
* \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 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.
* \returns a pixel value.
*
* \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,
* 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
* pixel
* \param r a pointer filled in with the red component
* \param g a pointer filled in with the green component
* \param b a pointer filled in with the blue component
* pixel.
* \param r a pointer filled in with the red component.
* \param g a pointer filled in with the green component.
* \param b a pointer filled in with the blue component.
*
* \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
* (100% opaque).
*
* \param pixel a pixel value
* \param pixel a pixel value.
* \param format an SDL_PixelFormat structure describing the format of the
* pixel
* \param r a pointer filled in with the red component
* \param g a pointer filled in with the green component
* \param b a pointer filled in with the blue component
* \param a a pointer filled in with the alpha component
* pixel.
* \param r a pointer filled in with the red component.
* \param g a pointer filled in with the green component.
* \param b a pointer filled in with the blue component.
* \param a a pointer filled in with the alpha component.
*
* \since This function is available since SDL 3.0.0.
*

98
include/SDL3/SDL_properties.h
View file

@ -97,8 +97,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
* SDL_SetPropertyWithCleanup()), which will not be copied. Any property that
* already exists on `dst` will be overwritten.
*
* \param src the properties to copy
* \param dst the destination properties
* \param src the properties to copy.
* \param dst the destination properties.
* \returns 0 on success or a negative error code on failure; call
* 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
* 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
* SDL_GetError() for more information.
*
@ -135,7 +135,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
/**
* 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.
*
@ -181,12 +181,12 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value)
* instead, as those functions will handle cleanup on your behalf. This
* function is only for more complex, custom data.
*
* \param props the properties 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 props the properties 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 cleanup the function to call when this property is deleted, or NULL
* if no cleanup is necessary
* \param userdata a pointer that is passed to the cleanup function
* if no cleanup is necessary.
* \param userdata a pointer that is passed to the cleanup function.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param props the properties 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 props the properties 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.
* \returns 0 on success or a negative error code on failure; call
* 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
* preserve the data after this call completes.
*
* \param props the properties 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 props the properties 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.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property
* \param props the properties to modify.
* \param name the name of the property to modify.
* \param value the new value of the property.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property
* \param props the properties to modify.
* \param name the name of the property to modify.
* \param value the new value of the property.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property
* \param props the properties to modify.
* \param name the name of the property to modify.
* \param value the new value of the property.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param props the properties to query
* \param name the name of the property to query
* \param props the properties 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.
*
* \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.
*
* \param props the properties to query
* \param name the name of the property to query
* \param props the properties 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
* 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
* modified by applications.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \param props the properties to query.
* \param name the name of the property to query.
* \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or
* 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.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \param props the properties to query.
* \param name the name of the property to query.
* \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or
* 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
* is a number property.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \param props the properties to query.
* \param name the name of the property to query.
* \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or
* 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
* is a floating point property.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \param props the properties to query.
* \param name the name of the property to query.
* \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or
* 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
* is a boolean property.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \param props the properties to query.
* \param name the name of the property to query.
* \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or
* 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.
*
* \param props the properties to modify
* \param name the name of the property to clear
* \param props the properties to modify.
* \param name the name of the property to clear.
* \returns 0 on success or a negative error code on failure; call
* 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 properties are locked during enumeration.
*
* \param props the properties to query
* \param callback the function to call for each property
* \param userdata a pointer that is passed to `callback`
* \param props the properties to query.
* \param callback the function to call for each property.
* \param userdata a pointer that is passed to `callback`.
* \returns 0 on success or a negative error code on failure; call
* 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
* any.
*
* \param props the properties to destroy
* \param props the properties to destroy.
*
* \threadsafety This function should not be called while these properties are
* locked or other threads might be setting or getting values

68
include/SDL3/SDL_rect.h
View file

@ -192,8 +192,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
*
* If either pointer is NULL the function will return SDL_FALSE.
*
* \param A an SDL_Rect structure representing the first rectangle
* \param B an SDL_Rect structure representing the second rectangle
* \param A an SDL_Rect structure representing the first rectangle.
* \param B an SDL_Rect structure representing the second rectangle.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
*
* \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.
*
* \param A an SDL_Rect structure representing the first rectangle
* \param B an SDL_Rect structure representing the second rectangle
* \param A an SDL_Rect structure representing the first rectangle.
* \param B an SDL_Rect structure representing the second rectangle.
* \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.
*
* \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.
*
* \param A an SDL_Rect structure representing the first rectangle
* \param B an SDL_Rect structure representing the second rectangle
* \param A an SDL_Rect structure representing the first rectangle.
* \param B an SDL_Rect structure representing the second rectangle.
* \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
* SDL_GetError() for more information.
*
@ -247,11 +247,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnion(const SDL_Rect * A,
* considered.
*
* \param points an array of SDL_Point structures representing points to be
* enclosed
* \param count the number of structures in the `points` array
* \param clip an SDL_Rect used for clipping or NULL to enclose all points
* enclosed.
* \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 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
* 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
* coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
*
* \param rect an SDL_Rect structure representing the rectangle to intersect
* \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 X2 a pointer to the ending X-coordinate of the line
* \param Y2 a pointer to the ending Y-coordinate of the line
* \param rect an SDL_Rect structure representing the rectangle to intersect.
* \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 X2 a pointer to the ending X-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.
*
* \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.
*
* \param A an SDL_FRect structure representing the first rectangle
* \param B an SDL_FRect structure representing the second rectangle
* \param A an SDL_FRect structure representing the first rectangle.
* \param B an SDL_FRect structure representing the second rectangle.
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
*
* \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.
*
* \param A an SDL_FRect structure representing the first rectangle
* \param B an SDL_FRect structure representing the second rectangle
* \param A an SDL_FRect structure representing the first rectangle.
* \param B an SDL_FRect structure representing the second rectangle.
* \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.
*
* \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.
*
* \param A an SDL_FRect structure representing the first rectangle
* \param B an SDL_FRect structure representing the second rectangle
* \param A an SDL_FRect structure representing the first rectangle.
* \param B an SDL_FRect structure representing the second rectangle.
* \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
* SDL_GetError() for more information.
*
@ -462,11 +462,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A,
* considered.
*
* \param points an array of SDL_FPoint structures representing points to be
* enclosed
* \param count the number of structures in the `points` array
* \param clip an SDL_FRect used for clipping or NULL to enclose all points
* enclosed.
* \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 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
* 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
* coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
*
* \param rect an SDL_FRect structure representing the rectangle to intersect
* \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 X2 a pointer to the ending X-coordinate of the line
* \param Y2 a pointer to the ending Y-coordinate of the line
* \param rect an SDL_FRect structure representing the rectangle to intersect.
* \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 X2 a pointer to the ending X-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.
*
* \since This function is available since SDL 3.0.0.

470
include/SDL3/SDL_render.h
View file

File diff suppressed because it is too large Load diff

36
include/SDL3/SDL_sensor.h
View file

@ -146,7 +146,7 @@ typedef enum SDL_SensorType
/**
* Get a list of currently connected sensors.
*
* \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
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
@ -160,8 +160,8 @@ extern SDL_DECLSPEC SDL_SensorID *SDLCALL SDL_GetSensors(int *count);
*
* The returned string follows the SDL_GetStringRule.
*
* \param instance_id the sensor instance ID
* \returns the sensor name, or NULL if `instance_id` is not valid
* \param instance_id the sensor instance ID.
* \returns the sensor name, or NULL if `instance_id` is not valid.
*
* \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.
*
* \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
* not valid
* not valid.
*
* \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.
*
* \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
* valid
* valid.
*
* \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.
*
* \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.
*
* \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.
*
* \param instance_id the sensor instance ID
* \param instance_id the sensor instance ID.
* \returns an SDL_Sensor object.
*
* \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.
*
* \param sensor The SDL_Sensor object
* \param sensor the SDL_Sensor object.
* \returns a valid property ID on success or 0 on failure; call
* 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.
*
* \param sensor The SDL_Sensor object
* \param sensor the SDL_Sensor object.
* \returns the sensor name, or NULL if `sensor` is NULL.
*
* \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.
*
* \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
* NULL.
*
@ -249,7 +249,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *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.
*
* \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.
*
* \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.
*
* \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.
*
* \param sensor The SDL_Sensor object to query
* \param data A pointer filled with the current sensor state
* \param num_values The number of values to write to data
* \param sensor the SDL_Sensor object to query.
* \param data a pointer filled with the current sensor state.
* \param num_values the number of values to write to data.
* \returns 0 on success or a negative error code on failure; call
* 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().
*
* \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.
*/

242
include/SDL3/SDL_stdinc.h
View file

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

80
include/SDL3/SDL_storage.h
View file

@ -101,8 +101,8 @@ typedef struct SDL_Storage SDL_Storage;
/**
* Opens up a read-only container for the application's filesystem.
*
* \param override a path to override the backend's default title root
* \param props a property list that may contain backend-specific information
* \param override a path to override the backend's default title root.
* \param props a property list that may contain backend-specific information.
* \returns a title storage container on success or NULL on failure; call
* 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
* when the container has been closed; ensuring safe and optimal save I/O.
*
* \param org the name of your organization
* \param app the name of your application
* \param props a property list that may contain backend-specific information
* \param org the name of your organization.
* \param app the name of your application.
* \param props a property list that may contain backend-specific information.
* \returns a user storage container on success or NULL on failure; call
* 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.
*
* \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
* 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()
* or SDL_OpenUserStorage().
*
* \param iface the function table to be used by this container
* \param userdata the pointer that will be passed to the store interface
* \param iface the function table to be used by this container.
* \param userdata the pointer that will be passed to the store interface.
* \returns a storage container on success or NULL on failure; call
* 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.
*
* \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
* otherwise; call SDL_GetError() for more information. Even if 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
* backend may depend on a synchronous message loop.
*
* \param storage a storage container to query
* \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise
* \param storage a storage container to query.
* \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise.
*
* \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.
*
* \param storage a storage container 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 storage a storage container to query.
* \param path the relative path of the file to query.
* \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
* 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
* buffer.
*
* \param storage a storage container to read from
* \param path the relative path of the file to read
* \param destination a client-provided buffer to read the file into
* \param length the length of the destination buffer
* \param storage a storage container to read from.
* \param path the relative path of the file to read.
* \param destination a client-provided buffer to read the file into.
* \param length the length of the destination buffer.
* \returns 0 if the file was read, a negative value otherwise; call
* 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.
*
* \param storage a storage container to write to
* \param path the relative path of the file to write
* \param source a client-provided buffer to write from
* \param length the length of the source buffer
* \param storage a storage container to write to.
* \param path the relative path of the file to write.
* \param source a client-provided buffer to write from.
* \param length the length of the source buffer.
* \returns 0 if the file was written, a negative value otherwise; call
* 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.
*
* \param storage a storage container
* \param path the path of the directory to create
* \param storage a storage container.
* \param path the path of the directory to create.
* \returns 0 on success or a negative error code on failure; call
* 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
* provided or the callback returns <= 0.
*
* \param storage a storage container
* \param path the path of the directory to enumerate
* \param callback a function that is called for each entry in the directory
* \param userdata a pointer that is passed to `callback`
* \param storage a storage container.
* \param path the path of the directory to enumerate.
* \param callback a function that is called for each entry in the directory.
* \param userdata a pointer that is passed to `callback`.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param storage a storage container
* \param path the path of the directory to enumerate
* \param storage a storage container.
* \param path the path of the directory to enumerate.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param storage a storage container
* \param oldpath the old path
* \param newpath the new path
* \param storage a storage container.
* \param oldpath the old path.
* \param newpath the new path.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param storage a storage container
* \param path the path to query
* \param storage a storage container.
* \param path the path to query.
* \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,
* 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.
*
* \param storage a storage container to query
* \returns the amount of remaining space, in bytes
* \param storage a storage container to query.
* \returns the amount of remaining space, in bytes.
*
* \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.
*
* \param storage a storage container
* \param path the path of the directory to enumerate
* \param storage a storage container.
* \param path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be
* NULL.
* \param flags `SDL_GLOB_*` bitflags that affect this search.

251
include/SDL3/SDL_surface.h
View file

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

52
include/SDL3/SDL_system.h
View file

@ -80,8 +80,8 @@ typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
* message should continue to be processed, or SDL_FALSE to prevent further
* processing.
*
* \param callback The SDL_WindowsMessageHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`
* \param callback the SDL_WindowsMessageHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`.
*
* \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
* 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
* 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
* DX11 device and swap chain.
*
* \param displayID the instance of the display to query
* \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 displayID the instance of the display to query.
* \param adapterIndex a pointer to be filled in with the adapter 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()
* 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
* processing.
*
* \param callback The SDL_X11EventHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`
* \param callback the SDL_X11EventHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`.
*
* \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.
*
* \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.
*
* \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.
*
* \param threadID The Unix thread ID to change priority of.
* \param sdlPriority The new SDL_ThreadPriority value.
* \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR,
* SCHED_OTHER, etc...)
* \param threadID the Unix thread ID to change priority of.
* \param sdlPriority the new SDL_ThreadPriority value.
* \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR,
* SCHED_OTHER, etc...).
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -234,9 +234,9 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
*
* 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
* called
* called.
* \param callback the function to call for every frame.
* \param callbackParam a pointer that is passed to `callback`.
* \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.
*
* \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.
*
@ -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
* through the callback.
*
* \param permission The permission to request.
* \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 permission the permission to request.
* \param cb the callback to trigger when the request has a response.
* \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
* submitting. The result of the request is only ever reported
* 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
*
* \param message text message to be shown
* \param duration 0=short, 1=long
* \param message text message to be shown.
* \param duration 0=short, 1=long.
* \param gravity where the notification should appear on the screen.
* \param xoffset set this parameter only when gravity >=0
* \param yoffset 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.
* \returns 0 on success or a negative error code on failure; call
* 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.
*
* \param command user command that must be greater or equal to 0x8000
* \param param user parameter
* \param command user command that must be greater or equal to 0x8000.
* \param param user parameter.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -600,7 +600,7 @@ typedef enum SDL_WinRT_DeviceFamily
*
* 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
* the path is not available for any reason; call SDL_GetError() for
* more information.

26
include/SDL3/SDL_thread.h
View file

@ -107,7 +107,7 @@ typedef enum SDL_ThreadPriority {
/**
* The function passed to SDL_CreateThread() as the new thread's entry point.
*
* \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().
*
* \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
* and let the macros hide the details.
*
* \param fn the SDL_ThreadFunction function to call in the new thread
* \param name the name of the thread
* \param data a pointer that is passed to `fn`
* \param fn the SDL_ThreadFunction function to call in the new thread.
* \param name the name of the thread.
* \param data a pointer that is passed to `fn`.
* \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
* 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
* 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
* new thread could not be created; call SDL_GetError() for more
* information.
@ -333,7 +333,7 @@ extern SDL_DECLSPEC SDL_Thread *SDLCALL SDL_CreateThreadWithPropertiesRuntime(SD
*
* 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
* 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
* 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
* `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
* 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
* SDL_GetError() for more information.
*
@ -414,7 +414,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priorit
* afterward.
*
* \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
* from the thread function by its 'return', or NULL to not
* 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.
*
* \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.
*
@ -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.
*
* \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
* 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
* cleaned up if so.
*
* \param id the thread local storage ID
* \param value the value to associate with the ID for the current thread
* \param id the thread local storage ID.
* \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
* value. Can be NULL.
* \returns 0 on success or a negative error code on failure; call

44
include/SDL3/SDL_time.h
View file

@ -92,9 +92,9 @@ typedef enum SDL_TimeFormat
* preference outside of your program.
*
* \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
* format, may be NULL
* format, may be NULL.
* \returns 0 on success or -1 on error; call SDL_GetError() for more
* 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
* 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
* 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
* the SDL_DateTime format.
*
* \param ticks the SDL_Time to be converted
* \param dt the resulting SDL_DateTime
* \param ticks the SDL_Time to be converted.
* \param dt the resulting SDL_DateTime.
* \param localTime the resulting SDL_DateTime will be expressed in local time
* 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
* 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
* it may remain unset.
*
* \param dt the source SDL_DateTime
* \param ticks the resulting SDL_Time
* \param dt the source SDL_DateTime.
* \param ticks the resulting SDL_Time.
* \returns 0 on success or -1 on error; call SDL_GetError() for more
* 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.
*
* \param ticks the time to convert
* \param ticks the time to convert.
* \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
* Windows FILETIME value
* Windows FILETIME value.
*
* \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
* parameters.
*
* \param dwLowDateTime the low portion of the Windows FILETIME value
* \param dwHighDateTime the high portion of the Windows FILETIME value
* \returns the converted SDL time
* \param dwLowDateTime the low portion of the Windows FILETIME value.
* \param dwHighDateTime the high portion of the Windows FILETIME value.
* \returns the converted SDL time.
*
* \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.
*
* \param year the year
* \param month the month [1-12]
* \param year the year.
* \param month the month [1-12].
* \returns the number of days in the requested month, otherwise -1; call
* 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.
*
* \param year the year component of the date
* \param month the month component of the date
* \param day the day component of the date
* \param year the year component of the date.
* \param month the month 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
* 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.
*
* \param year the year component of the date
* \param month the month component of the date
* \param day the day component of the date
* \param year the year component of the date.
* \param month the month 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,
* otherwise -1; call SDL_GetError() for more information.
*

22
include/SDL3/SDL_timer.h
View file

@ -105,7 +105,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
* waits at least the specified time, but possibly longer due to OS
* 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.
*/
@ -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
* 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.
*/
@ -141,7 +141,7 @@ typedef Uint32 SDL_TimerID;
*
* \param userdata an arbitrary pointer provided by the app through
* 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.
* \returns the new callback time interval, or 0 to disable further runs of
* 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
* 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
* `interval` elapses
* \param userdata a pointer that is passed to `callback`
* `interval` elapses.
* \param userdata a pointer that is passed to `callback`.
* \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
* 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
* 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.
* \returns the new callback time interval, or 0 to disable further runs of
* 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
* 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
* `interval` elapses
* \param userdata a pointer that is passed to `callback`
* `interval` elapses.
* \param userdata a pointer that is passed to `callback`.
* \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
* information.
*
@ -260,7 +260,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi
/**
* 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
* SDL_GetError() for more information.
*

6
include/SDL3/SDL_touch.h
View file

@ -109,8 +109,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touch
/**
* Get the type of the given touch device.
*
* \param touchID the ID of a touch device
* \returns touch device type
* \param touchID the ID of a touch device.
* \returns touch device type.
*
* \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.
*
* \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
* be NULL.
* \returns a NULL terminated array of SDL_Finger pointers which should be

340
include/SDL3/SDL_video.h
View file

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

18
include/SDL3/SDL_vulkan.h
View file

@ -93,7 +93,7 @@ struct VkAllocationCallbacks;
* supported. Either do not link to the Vulkan loader or link to a dynamic
* 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
* 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
* 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 instance The Vulkan instance handle
* \param allocator A VkAllocationCallbacks struct, which lets the app set the
* \param window the window to which to attach the Vulkan surface.
* \param instance the Vulkan instance handle.
* \param allocator a VkAllocationCallbacks struct, which lets the app set the
* allocator that creates the surface. Can be NULL.
* \param surface A pointer to a VkSurfaceKHR handle to output the newly
* created surface
* \param surface a pointer to a VkSurfaceKHR handle to output the newly
* created surface.
* \returns SDL_TRUE on success, SDL_FALSE on error.
*
* \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
* argument is passed directly to Vulkan and isn't used by SDL itself.
*
* \param instance The Vulkan instance handle
* \param surface VkSurfaceKHR handle to destroy
* \param allocator A VkAllocationCallbacks struct, which lets the app set the
* \param instance the Vulkan instance handle.
* \param surface vkSurfaceKHR handle to destroy.
* \param allocator a VkAllocationCallbacks struct, which lets the app set the
* allocator that destroys the surface. Can be NULL.
*
* \since This function is available since SDL 3.0.0.