diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index caf5eac5a..9d11c9d32 100644 --- a/include/SDL3/SDL_assert.h +++ b/include/SDL3/SDL_assert.h @@ -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. diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h index 5bf0cf9aa..90594b5ef 100644 --- a/include/SDL3/SDL_atomic.h +++ b/include/SDL3/SDL_atomic.h @@ -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. diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index 08ec2928f..162b0d7a1 100644 --- a/include/SDL3/SDL_audio.h +++ b/include/SDL3/SDL_audio.h @@ -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. * diff --git a/include/SDL3/SDL_bits.h b/include/SDL3/SDL_bits.h index 6547a96c3..72be08272 100644 --- a/include/SDL3/SDL_bits.h +++ b/include/SDL3/SDL_bits.h @@ -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. diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h index 05c3562de..159924b4d 100644 --- a/include/SDL3/SDL_blendmode.h +++ b/include/SDL3/SDL_blendmode.h @@ -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. * diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h index 25d7a32d0..11eab4327 100644 --- a/include/SDL3/SDL_camera.h +++ b/include/SDL3/SDL_camera.h @@ -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. diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h index 44987bb45..073c309d0 100644 --- a/include/SDL3/SDL_clipboard.h +++ b/include/SDL3/SDL_clipboard.h @@ -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. * diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h index e1b518721..99a6a112e 100644 --- a/include/SDL3/SDL_dialog.h +++ b/include/SDL3/SDL_dialog.h @@ -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. diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h index e8438c936..fced53c02 100644 --- a/include/SDL3/SDL_error.h +++ b/include/SDL3/SDL_error.h @@ -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. * diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h index 3488cd05a..5f56d2353 100644 --- a/include/SDL3/SDL_events.h +++ b/include/SDL3/SDL_events.h @@ -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. * diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h index eb198e83b..c3bda170f 100644 --- a/include/SDL3/SDL_filesystem.h +++ b/include/SDL3/SDL_filesystem.h @@ -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. diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h index fb0fd7691..9ab90092f 100644 --- a/include/SDL3/SDL_gamepad.h +++ b/include/SDL3/SDL_gamepad.h @@ -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. * diff --git a/include/SDL3/SDL_guid.h b/include/SDL3/SDL_guid.h index 267b1ef16..b7fdab57c 100644 --- a/include/SDL3/SDL_guid.h +++ b/include/SDL3/SDL_guid.h @@ -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. diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h index 5c23ab417..9624e311a 100644 --- a/include/SDL3/SDL_haptic.h +++ b/include/SDL3/SDL_haptic.h @@ -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. * diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h index 107ac8050..cd84402a5 100644 --- a/include/SDL3/SDL_hidapi.h +++ b/include/SDL3/SDL_hidapi.h @@ -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. */ diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h index 69d01f388..17a4f3ee6 100644 --- a/include/SDL3/SDL_hints.h +++ b/include/SDL3/SDL_hints.h @@ -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. * diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h index 2ef7288ff..18d5d8956 100644 --- a/include/SDL3/SDL_init.h +++ b/include/SDL3/SDL_init.h @@ -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. * diff --git a/include/SDL3/SDL_iostream.h b/include/SDL3/SDL_iostream.h index 8f2bff8de..4da921445 100644 --- a/include/SDL3/SDL_iostream.h +++ b/include/SDL3/SDL_iostream.h @@ -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. * diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h index 125d1c0a3..c4e713c7c 100644 --- a/include/SDL3/SDL_joystick.h +++ b/include/SDL3/SDL_joystick.h @@ -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 diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h index 791d96ae2..c84eb7838 100644 --- a/include/SDL3/SDL_keyboard.h +++ b/include/SDL3/SDL_keyboard.h @@ -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. diff --git a/include/SDL3/SDL_loadso.h b/include/SDL3/SDL_loadso.h index e0a34bbb4..097437eb0 100644 --- a/include/SDL3/SDL_loadso.h +++ b/include/SDL3/SDL_loadso.h @@ -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. * diff --git a/include/SDL3/SDL_log.h b/include/SDL3/SDL_log.h index f0bc355a1..6d7c6d626 100644 --- a/include/SDL3/SDL_log.h +++ b/include/SDL3/SDL_log.h @@ -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. * diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h index 35aae3bf4..e293cc505 100644 --- a/include/SDL3/SDL_main.h +++ b/include/SDL3/SDL_main.h @@ -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. diff --git a/include/SDL3/SDL_messagebox.h b/include/SDL3/SDL_messagebox.h index fc75db263..6aa385371 100644 --- a/include/SDL3/SDL_messagebox.h +++ b/include/SDL3/SDL_messagebox.h @@ -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. * diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h index 5c4be9dc5..4e987086b 100644 --- a/include/SDL3/SDL_metal.h +++ b/include/SDL3/SDL_metal.h @@ -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. */ diff --git a/include/SDL3/SDL_misc.h b/include/SDL3/SDL_misc.h index 250a0a5ec..09dec9e06 100644 --- a/include/SDL3/SDL_misc.h +++ b/include/SDL3/SDL_misc.h @@ -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. diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h index 14ad506a4..1de4ad8e4 100644 --- a/include/SDL3/SDL_mouse.h +++ b/include/SDL3/SDL_mouse.h @@ -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. * diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h index 5723d3994..e26034055 100644 --- a/include/SDL3/SDL_mutex.h +++ b/include/SDL3/SDL_mutex.h @@ -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. diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h index ead0cf06f..58031564f 100644 --- a/include/SDL3/SDL_pen.h +++ b/include/SDL3/SDL_pen.h @@ -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 diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h index 2b814c0c9..c19f09213 100644 --- a/include/SDL3/SDL_pixels.h +++ b/include/SDL3/SDL_pixels.h @@ -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. * diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h index fc8c4cf52..fef5725c1 100644 --- a/include/SDL3/SDL_properties.h +++ b/include/SDL3/SDL_properties.h @@ -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 diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h index 46e2a8c3f..f0616c02e 100644 --- a/include/SDL3/SDL_rect.h +++ b/include/SDL3/SDL_rect.h @@ -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. diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index 012756cd4..870df7463 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -157,7 +157,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * The returned string follows the SDL_GetStringRule. * * \param index the index of the rendering driver; the value ranges from 0 to - * SDL_GetNumRenderDrivers() - 1 + * SDL_GetNumRenderDrivers() - 1. * \returns the name of the rendering driver at the requested index, or NULL * if an invalid index was specified. * @@ -170,13 +170,13 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetRenderDriver(int index); /** * Create a window and default renderer. * - * \param title the title of the window, in UTF-8 encoding - * \param width the width of the window - * \param height the height of the window + * \param title the title of the window, in UTF-8 encoding. + * \param width the width of the window. + * \param height the height of the window. * \param window_flags the flags used to create the window (see - * SDL_CreateWindow()) - * \param window a pointer filled with the window, or NULL on error - * \param renderer a pointer filled with the renderer, or NULL on error + * SDL_CreateWindow()). + * \param window a pointer filled with the window, or NULL on error. + * \param renderer a pointer filled with the renderer, or NULL on error. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -200,9 +200,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(const char *title, i * can call SDL_SetRenderLogicalPresentation() to change the content size and * scaling options. * - * \param window the window where rendering is displayed + * \param window the window where rendering is displayed. * \param name the name of the rendering driver to initialize, or NULL to - * initialize the first one supporting the requested flags + * initialize the first one supporting the requested flags. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * @@ -254,7 +254,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * - `SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER`: the * queue family index used for presentation. * - * \param props the properties to use + * \param props the properties to use. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * @@ -289,7 +289,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_ * SDL_Window as the final destination and not an SDL_Surface. * * \param surface the SDL_Surface structure representing the surface where - * rendering is done + * rendering is done. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * @@ -302,7 +302,7 @@ extern SDL_DECLSPEC SDL_Renderer *SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface /** * Get the renderer associated with a window. * - * \param window the window to query + * \param window the window to query. * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * @@ -313,7 +313,7 @@ extern SDL_DECLSPEC SDL_Renderer *SDLCALL SDL_GetRenderer(SDL_Window *window); /** * Get the window associated with a renderer. * - * \param renderer the renderer to query + * \param renderer the renderer to query. * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * @@ -326,7 +326,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *render * * The returned string follows the SDL_GetStringRule. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns the name of the selected renderer, or NULL if the renderer is * invalid. * @@ -408,7 +408,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetRendererName(SDL_Renderer *render * swapchain images, or potential frames in flight, used by the Vulkan * renderer * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * @@ -449,9 +449,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * This returns the true output size in pixels, ignoring any render targets or * logical size and presentation. * - * \param renderer the rendering context - * \param w a pointer filled in with the width in pixels - * \param h a pointer filled in with the height in pixels + * \param renderer the rendering context. + * \param w a pointer filled in with the width in pixels. + * \param h a pointer filled in with the height in pixels. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -469,9 +469,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, * logical size, otherwise it will return the value of * SDL_GetRenderOutputSize(). * - * \param renderer the rendering context - * \param w a pointer filled in with the current width - * \param h a pointer filled in with the current height + * \param renderer the rendering context. + * \param w a pointer filled in with the current width. + * \param h a pointer filled in with the current height. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -484,11 +484,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *ren /** * Create a texture for a rendering context. * - * \param renderer the rendering context - * \param format one of the enumerated values in SDL_PixelFormatEnum - * \param access one of the enumerated values in SDL_TextureAccess - * \param w the width of the texture in pixels - * \param h the height of the texture in pixels + * \param renderer the rendering context. + * \param format one of the enumerated values in SDL_PixelFormatEnum. + * \param access one of the enumerated values in SDL_TextureAccess. + * \param w the width of the texture in pixels. + * \param h the height of the texture in pixels. * \returns a pointer to the created texture or NULL if no rendering context * was active, the format was unsupported, or the width or height * were out of range; call SDL_GetError() for more information. @@ -515,9 +515,9 @@ extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_CreateTexture(SDL_Renderer *rendere * format of the surface, and can be queried using the * SDL_PROP_TEXTURE_FORMAT_NUMBER property. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param surface the SDL_Surface structure containing pixel data used to fill - * the texture + * the texture. * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * @@ -623,8 +623,8 @@ extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Render * VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL associated with the texture, if * you want to wrap an existing texture. * - * \param renderer the rendering context - * \param props the properties to use + * \param renderer the rendering context. + * \param props the properties to use. * \returns a pointer to the created texture or NULL if no rendering context * was active, the format was unsupported, or the width or height * were out of range; call SDL_GetError() for more information. @@ -753,7 +753,7 @@ extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureWithProperties(SDL_Ren * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the * texture * - * \param texture the texture to query + * \param texture the texture to query. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * @@ -794,7 +794,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Textur /** * Get the renderer that created an SDL_Texture. * - * \param texture the texture to query + * \param texture the texture to query. * \returns a pointer to the SDL_Renderer that created the texture, or NULL on * failure; call SDL_GetError() for more information. * @@ -807,7 +807,7 @@ extern SDL_DECLSPEC SDL_Renderer *SDLCALL SDL_GetRendererFromTexture(SDL_Texture /** * Get the size of a texture, as floating point values. * - * \param texture the texture to query + * \param texture the texture to query. * \param w a pointer filled in with the width of the texture in pixels. This * argument can be NULL if you don't need this information. * \param h a pointer filled in with the height of the texture in pixels. This @@ -831,10 +831,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float * * Color modulation is not always supported by the renderer; it will return -1 * if color modulation is not supported. * - * \param texture the texture to update - * \param r the red color value multiplied into copy operations - * \param g the green color value multiplied into copy operations - * \param b the blue color value multiplied into copy operations + * \param texture the texture to update. + * \param r the red color value multiplied into copy operations. + * \param g the green color value multiplied into copy operations. + * \param b the blue color value multiplied into copy operations. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -859,10 +859,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uin * Color modulation is not always supported by the renderer; it will return -1 * if color modulation is not supported. * - * \param texture the texture to update - * \param r the red color value multiplied into copy operations - * \param g the green color value multiplied into copy operations - * \param b the blue color value multiplied into copy operations + * \param texture the texture to update. + * \param r the red color value multiplied into copy operations. + * \param g the green color value multiplied into copy operations. + * \param b the blue color value multiplied into copy operations. * \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_SetTextureColorModFloat(SDL_Texture *texture /** * Get the additional color value multiplied into render copy operations. * - * \param texture the texture 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 texture the texture 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. * @@ -896,10 +896,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uin /** * Get the additional color value multiplied into render copy operations. * - * \param texture the texture 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 texture the texture 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. * @@ -922,8 +922,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture * Alpha modulation is not always supported by the renderer; it will return -1 * if alpha modulation is not supported. * - * \param texture the texture to update - * \param alpha the source alpha value multiplied into copy operations + * \param texture the texture to update. + * \param alpha the source alpha value multiplied into copy operations. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -946,8 +946,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uin * Alpha modulation is not always supported by the renderer; it will return -1 * if alpha modulation is not supported. * - * \param texture the texture to update - * \param alpha the source alpha value multiplied into copy operations + * \param texture the texture to update. + * \param alpha the source alpha value multiplied into copy operations. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -962,8 +962,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture /** * Get the additional alpha value multiplied into render copy operations. * - * \param texture the texture to query - * \param alpha a pointer filled in with the current alpha value + * \param texture the texture 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. * @@ -978,8 +978,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uin /** * Get the additional alpha value multiplied into render copy operations. * - * \param texture the texture to query - * \param alpha a pointer filled in with the current alpha value + * \param texture the texture 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. * @@ -997,8 +997,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture * If the blend mode is not supported, the closest supported mode is chosen * and this function returns -1. * - * \param texture the texture to update - * \param blendMode the SDL_BlendMode to use for texture blending + * \param texture the texture to update. + * \param blendMode the SDL_BlendMode to use for texture blending. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1011,8 +1011,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SD /** * Get the blend mode used for texture copy operations. * - * \param texture the texture to query - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \param texture the texture 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. * @@ -1029,7 +1029,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SD * * If the scale mode is not supported, the closest supported mode is chosen. * - * \param texture The texture to update. + * \param texture the texture to update. * \param scaleMode the SDL_ScaleMode to use for texture scaling. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. @@ -1068,12 +1068,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SD * While this function will work with streaming textures, for optimization * reasons you may not get the pixels back if you lock the texture afterward. * - * \param texture the texture to update + * \param texture the texture to update. * \param rect an SDL_Rect structure representing the area to update, or NULL - * to update the entire texture - * \param pixels the raw pixel data in the format of the texture + * to update the entire texture. + * \param pixels the raw pixel data in the format of the texture. * \param pitch the number of bytes in a row of pixel data, including padding - * between lines + * between lines. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1094,18 +1094,18 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SD * block of Y and U/V planes in the proper order, but this function is * available if your pixel data is not contiguous. * - * \param texture the texture to update + * \param texture the texture to update. * \param rect a pointer to the rectangle of pixels to update, or NULL to - * update the entire texture - * \param Yplane the raw pixel data for the Y plane + * update the entire texture. + * \param Yplane the raw pixel data for the Y plane. * \param Ypitch the number of bytes between rows of pixel data for the Y - * plane - * \param Uplane the raw pixel data for the U plane + * plane. + * \param Uplane the raw pixel data for the U plane. * \param Upitch the number of bytes between rows of pixel data for the U - * plane - * \param Vplane the raw pixel data for the V plane + * plane. + * \param Vplane the raw pixel data for the V plane. * \param Vpitch the number of bytes between rows of pixel data for the V - * plane + * plane. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1127,7 +1127,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * block of NV12/21 planes in the proper order, but this function is available * if your pixel data is not contiguous. * - * \param texture the texture to update + * \param texture the texture to update. * \param rect a pointer to the rectangle of pixels to update, or NULL to * update the entire texture. * \param Yplane the raw pixel data for the Y plane. @@ -1161,13 +1161,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * changes. * * \param texture the texture to lock for access, which was created with - * `SDL_TEXTUREACCESS_STREAMING` + * `SDL_TEXTUREACCESS_STREAMING`. * \param rect an SDL_Rect structure representing the area to lock for access; - * NULL to lock the entire texture + * NULL to lock the entire texture. * \param pixels this is filled in with a pointer to the locked pixels, - * appropriately offset by the locked area + * appropriately offset by the locked area. * \param pitch this is filled in with the pitch of the locked pixels; the - * pitch is the length of one row in bytes + * pitch is the length of one row in bytes. * \returns 0 on success or a negative error code if the texture is not valid * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call * SDL_GetError() for more information. @@ -1200,11 +1200,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture *texture, * or SDL_DestroyTexture(). The caller should not free it. * * \param texture the texture to lock for access, which must be created with - * `SDL_TEXTUREACCESS_STREAMING` + * `SDL_TEXTUREACCESS_STREAMING`. * \param rect a pointer to the rectangle to lock for access. If the rect is - * NULL, the entire texture will be locked + * NULL, the entire texture will be locked. * \param surface this is filled in with an SDL surface representing the - * locked area + * locked area. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1228,7 +1228,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, * Which is to say: locking and immediately unlocking a texture can result in * corrupted textures, depending on the renderer in use. * - * \param texture a texture locked by SDL_LockTexture() + * \param texture a texture locked by SDL_LockTexture(). * * \since This function is available since SDL 3.0.0. * @@ -1243,7 +1243,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * To stop rendering to a texture and render to the window again, call this * function with a NULL `texture`. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param texture the targeted texture, which must be created with the * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the * window instead of a texture. @@ -1262,7 +1262,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_ * The default render target is the window for which the renderer was created, * and is reported a NULL here. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * * \since This function is available since SDL 3.0.0. @@ -1285,11 +1285,11 @@ extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *rende * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). * - * \param renderer the rendering context - * \param w the width of the logical resolution - * \param h the height of the logical resolution - * \param mode the presentation mode used - * \param scale_mode the scale mode used + * \param renderer the rendering context. + * \param w the width of the logical resolution. + * \param h the height of the logical resolution. + * \param mode the presentation mode used. + * \param scale_mode the scale mode used. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1306,11 +1306,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *r * This function gets the width and height of the logical rendering output, or * the output size in pixels if a logical resolution is not enabled. * - * \param renderer the rendering context - * \param w an int to be filled with the width - * \param h an int to be filled with the height - * \param mode a pointer filled in with the presentation mode - * \param scale_mode a pointer filled in with the scale mode + * \param renderer the rendering context. + * \param w an int to be filled with the width. + * \param h an int to be filled with the height. + * \param mode a pointer filled in with the presentation mode. + * \param scale_mode a pointer filled in with the scale mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1323,11 +1323,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *r /** * Get a point in render coordinates when given a point in window coordinates. * - * \param renderer the rendering context - * \param window_x the x coordinate in window coordinates - * \param window_y the y coordinate in window coordinates - * \param x a pointer filled with the x coordinate in render coordinates - * \param y a pointer filled with the y coordinate in render coordinates + * \param renderer the rendering context. + * \param window_x the x coordinate in window coordinates. + * \param window_y the y coordinate in window coordinates. + * \param x a pointer filled with the x coordinate in render coordinates. + * \param y a pointer filled with the y coordinate in render coordinates. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1341,13 +1341,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *re /** * Get a point in window coordinates when given a point in render coordinates. * - * \param renderer the rendering context - * \param x the x coordinate in render coordinates - * \param y the y coordinate in render coordinates + * \param renderer the rendering context. + * \param x the x coordinate in render coordinates. + * \param y the y coordinate in render coordinates. * \param window_x a pointer filled with the x coordinate in window - * coordinates + * coordinates. * \param window_y a pointer filled with the y coordinate in window - * coordinates + * coordinates. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1366,8 +1366,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *rend * * Once converted, the coordinates may be outside the rendering area. * - * \param renderer the rendering context - * \param event the event to modify + * \param renderer the rendering context. + * \param event the event to modify. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1380,9 +1380,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer /** * Set the drawing area for rendering on the current target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the drawing area, or NULL - * to set the viewport to the entire target + * to set the viewport to the entire target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1396,8 +1396,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, co /** * Get the drawing area for the current target. * - * \param renderer the rendering context - * \param rect an SDL_Rect structure filled in with the current drawing area + * \param renderer the rendering context. + * \param rect an SDL_Rect structure filled in with the current drawing area. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1415,9 +1415,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SD * whether you should restore a specific rectangle or NULL. Note that the * viewport is always reset when changing rendering targets. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns SDL_TRUE if the viewport was set to a specific rectangle, or - * SDL_FALSE if it was set to NULL (the entire target) + * SDL_FALSE if it was set to NULL (the entire target). * * \since This function is available since SDL 3.0.0. * @@ -1429,9 +1429,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *rendere /** * Set the clip rectangle for rendering on the specified target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the clip area, relative to - * the viewport, or NULL to disable clipping + * the viewport, or NULL to disable clipping. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1445,9 +1445,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, co /** * Get the clip rectangle for the current target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current clipping area - * or an empty rectangle if clipping is disabled + * or an empty rectangle if clipping is disabled. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1461,7 +1461,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SD /** * Get whether clipping is enabled on the given renderer. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call * SDL_GetError() for more information. * @@ -1483,9 +1483,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *rendere * will be handled using the appropriate quality hints. For best results use * integer scaling factors. * - * \param renderer the rendering context - * \param scaleX the horizontal scaling factor - * \param scaleY the vertical scaling factor + * \param renderer the rendering context. + * \param scaleX the horizontal scaling factor. + * \param scaleY the vertical scaling factor. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1498,9 +1498,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float /** * Get the drawing scale for the current target. * - * \param renderer the rendering context - * \param scaleX a pointer filled in with the horizontal scaling factor - * \param scaleY a pointer filled in with the vertical scaling factor + * \param renderer the rendering context. + * \param scaleX a pointer filled in with the horizontal scaling factor. + * \param scaleY a pointer filled in with the vertical scaling factor. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1516,13 +1516,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float * Set the color for drawing or filling rectangles, lines, and points, and for * SDL_RenderClear(). * - * \param renderer the rendering context - * \param r the red value used to draw on the rendering target - * \param g the green value used to draw on the rendering target - * \param b the blue value used to draw on the rendering target + * \param renderer the rendering context. + * \param r the red value used to draw on the rendering target. + * \param g the green value used to draw on the rendering target. + * \param b the blue value used to draw on the rendering target. * \param a the alpha value used to draw on the rendering target; usually * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to - * specify how the alpha channel is used + * specify how the alpha channel is used. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1539,13 +1539,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, U * Set the color for drawing or filling rectangles, lines, and points, and for * SDL_RenderClear(). * - * \param renderer the rendering context - * \param r the red value used to draw on the rendering target - * \param g the green value used to draw on the rendering target - * \param b the blue value used to draw on the rendering target + * \param renderer the rendering context. + * \param r the red value used to draw on the rendering target. + * \param g the green value used to draw on the rendering target. + * \param b the blue value used to draw on the rendering target. * \param a the alpha value used to draw on the rendering target. Use * SDL_SetRenderDrawBlendMode to specify how the alpha channel is - * used + * used. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1559,15 +1559,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *render /** * Get the color used for drawing operations (Rect, Line and Clear). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param r a pointer filled in with the red value used to draw on the - * rendering target + * rendering target. * \param g a pointer filled in with the green value used to draw on the - * rendering target + * rendering target. * \param b a pointer filled in with the blue value used to draw on the - * rendering target + * rendering target. * \param a a pointer filled in with the alpha value used to draw on the - * rendering target; usually `SDL_ALPHA_OPAQUE` (255) + * rendering target; usually `SDL_ALPHA_OPAQUE` (255). * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1581,15 +1581,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, U /** * Get the color used for drawing operations (Rect, Line and Clear). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param r a pointer filled in with the red value used to draw on the - * rendering target + * rendering target. * \param g a pointer filled in with the green value used to draw on the - * rendering target + * rendering target. * \param b a pointer filled in with the blue value used to draw on the - * rendering target + * rendering target. * \param a a pointer filled in with the alpha value used to draw on the - * rendering target + * rendering target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1611,8 +1611,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *render * The color scale does not affect the alpha channel, only the color * brightness. * - * \param renderer the rendering context - * \param scale the color scale value + * \param renderer the rendering context. + * \param scale the color scale value. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1625,8 +1625,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, /** * Get the color scale used for render operations. * - * \param renderer the rendering context - * \param scale a pointer filled in with the current color scale value + * \param renderer the rendering context. + * \param scale a pointer filled in with the current color scale value. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1641,8 +1641,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, * * If the blend mode is not supported, the closest supported mode is chosen. * - * \param renderer the rendering context - * \param blendMode the SDL_BlendMode to use for blending + * \param renderer the rendering context. + * \param blendMode the SDL_BlendMode to use for blending. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1655,8 +1655,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *rendere /** * Get the blend mode used for drawing operations. * - * \param renderer the rendering context - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \param renderer the rendering context. + * \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. * @@ -1674,7 +1674,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *rendere * the rendering target to current renderer draw color, so make sure to invoke * SDL_SetRenderDrawColor() when needed. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1687,10 +1687,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer *renderer); /** * Draw a point on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw a point. - * \param x The x coordinate of the point. - * \param y The y coordinate of the point. - * \returns 0 on success, or -1 on error + * \param renderer the renderer which should draw a point. + * \param x the x coordinate of the point. + * \param y the y coordinate of the point. + * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 3.0.0. * @@ -1701,9 +1701,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, /** * Draw multiple points on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw multiple points. - * \param points The points to draw - * \param count The number of points to draw + * \param renderer the renderer which should draw multiple points. + * \param points the points to draw. + * \param count the number of points to draw. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1716,12 +1716,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const S /** * Draw a line on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw a line. - * \param x1 The x coordinate of the start point. - * \param y1 The y coordinate of the start point. - * \param x2 The x coordinate of the end point. - * \param y2 The y coordinate of the end point. - * \returns 0 on success, or -1 on error + * \param renderer the renderer which should draw a line. + * \param x1 the x coordinate of the start point. + * \param y1 the y coordinate of the start point. + * \param x2 the x coordinate of the end point. + * \param y2 the y coordinate of the end point. + * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 3.0.0. * @@ -1733,9 +1733,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, * Draw a series of connected lines on the current rendering target at * subpixel precision. * - * \param renderer The renderer which should draw multiple lines. - * \param points The points along the lines - * \param count The number of points, drawing count-1 lines + * \param renderer the renderer which should draw multiple lines. + * \param points the points along the lines. + * \param count the number of points, drawing count-1 lines. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1748,10 +1748,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SD /** * Draw a rectangle on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw a rectangle. - * \param rect A pointer to the destination rectangle, or NULL to outline the + * \param renderer the renderer which should draw a rectangle. + * \param rect a pointer to the destination rectangle, or NULL to outline the * entire rendering target. - * \returns 0 on success, or -1 on error + * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 3.0.0. * @@ -1763,9 +1763,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL * Draw some number of rectangles on the current rendering target at subpixel * precision. * - * \param renderer The renderer which should draw multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. + * \param renderer the renderer which should draw multiple rectangles. + * \param rects a pointer to an array of destination rectangles. + * \param count the number of rectangles. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1779,10 +1779,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SD * Fill a rectangle on the current rendering target with the drawing color at * subpixel precision. * - * \param renderer The renderer which should fill a rectangle. - * \param rect A pointer to the destination rectangle, or NULL for the entire + * \param renderer the renderer which should fill a rectangle. + * \param rect a pointer to the destination rectangle, or NULL for the entire * rendering target. - * \returns 0 on success, or -1 on error + * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 3.0.0. * @@ -1794,9 +1794,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const * Fill some number of rectangles on the current rendering target with the * drawing color at subpixel precision. * - * \param renderer The renderer which should fill multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. + * \param renderer the renderer which should fill multiple rectangles. + * \param rects a pointer to an array of destination rectangles. + * \param count the number of rectangles. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1810,13 +1810,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, cons * Copy a portion of the texture to the current rendering target at subpixel * precision. * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the + * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns 0 on success, or -1 on error + * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 3.0.0. * @@ -1828,19 +1828,19 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Te * Copy a portion of the source texture to the current rendering target, with * rotation and flipping, at subpixel precision. * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the + * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \param angle An angle in degrees that indicates the rotation that will be - * applied to dstrect, rotating it in a clockwise direction - * \param center A pointer to a point indicating the point around which + * \param angle an angle in degrees that indicates the rotation that will be + * applied to dstrect, rotating it in a clockwise direction. + * \param center a pointer to a point indicating the point around which * dstrect will be rotated (if NULL, rotation will be done * around dstrect.w/2, dstrect.h/2). - * \param flip An SDL_FlipMode value stating which flipping actions should be - * performed on the texture + * \param flip an SDL_FlipMode value stating which flipping actions should be + * performed on the texture. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1858,15 +1858,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, * vertex array Color and alpha modulation is done per vertex * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored). * - * \param renderer The rendering context. + * \param renderer the rendering context. * \param texture (optional) The SDL texture to use. - * \param vertices Vertices. - * \param num_vertices Number of vertices. + * \param vertices vertices. + * \param num_vertices number of vertices. * \param indices (optional) An array of integer indices into the 'vertices' * array, if NULL all vertices will be rendered in sequential * order. - * \param num_indices Number of indices. - * \returns 0 on success, or -1 if the operation is not supported + * \param num_indices number of indices. + * \returns 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 3.0.0. * @@ -1882,19 +1882,19 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * vertex arrays Color and alpha modulation is done per vertex * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored). * - * \param renderer The rendering context. + * \param renderer the rendering context. * \param texture (optional) The SDL texture to use. - * \param xy Vertex positions - * \param xy_stride Byte size to move from one element to the next element - * \param color Vertex colors (as SDL_Color) - * \param color_stride Byte size to move from one element to the next element - * \param uv Vertex normalized texture coordinates - * \param uv_stride Byte size to move from one element to the next element - * \param num_vertices Number of vertices. + * \param xy vertex positions. + * \param xy_stride byte size to move from one element to the next element. + * \param color vertex colors (as SDL_Color). + * \param color_stride byte size to move from one element to the next element. + * \param uv vertex normalized texture coordinates. + * \param uv_stride byte size to move from one element to the next element. + * \param num_vertices number of vertices. * \param indices (optional) An array of indices into the 'vertices' arrays, * if NULL all vertices will be rendered in sequential order. - * \param num_indices Number of indices. - * \param size_indices Index size: 1 (byte), 2 (short), 4 (int) + * \param num_indices number of indices. + * \param size_indices index size: 1 (byte), 2 (short), 4 (int). * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1915,19 +1915,19 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, * vertex arrays Color and alpha modulation is done per vertex * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored). * - * \param renderer The rendering context. + * \param renderer the rendering context. * \param texture (optional) The SDL texture to use. - * \param xy Vertex positions - * \param xy_stride Byte size to move from one element to the next element - * \param color Vertex colors (as SDL_FColor) - * \param color_stride Byte size to move from one element to the next element - * \param uv Vertex normalized texture coordinates - * \param uv_stride Byte size to move from one element to the next element - * \param num_vertices Number of vertices. + * \param xy vertex positions. + * \param xy_stride byte size to move from one element to the next element. + * \param color vertex colors (as SDL_FColor). + * \param color_stride byte size to move from one element to the next element. + * \param uv vertex normalized texture coordinates. + * \param uv_stride byte size to move from one element to the next element. + * \param num_vertices number of vertices. * \param indices (optional) An array of indices into the 'vertices' arrays, * if NULL all vertices will be rendered in sequential order. - * \param num_indices Number of indices. - * \param size_indices Index size: 1 (byte), 2 (short), 4 (int) + * \param num_indices number of indices. + * \param size_indices index size: 1 (byte), 2 (short), 4 (int). * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1953,9 +1953,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderGeometryRawFloat(SDL_Renderer *rendere * frequently. If you're using this on the main rendering target, it should be * called after rendering and before SDL_RenderPresent(). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the area in pixels relative - * to the to current viewport, or NULL for the entire viewport + * to the to current viewport, or NULL for the entire viewport. * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. * @@ -1982,7 +1982,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * starting each new frame's drawing, even if you plan to overwrite every * pixel. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -2010,7 +2010,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * Passing NULL or an otherwise invalid texture will set the SDL error message * to "Invalid texture". * - * \param texture the texture to destroy + * \param texture the texture to destroy. * * \since This function is available since SDL 3.0.0. * @@ -2025,7 +2025,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * If `renderer` is NULL, this function will return immediately after setting * the SDL error message to "Invalid renderer". See SDL_GetError(). * - * \param renderer the rendering context + * \param renderer the rendering context. * * \since This function is available since SDL 3.0.0. * @@ -2056,7 +2056,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * OpenGL state that can confuse things; you should use your best judgement * and be prepared to make changes if specific state needs to be protected. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -2070,9 +2070,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * This function returns `void *`, so SDL doesn't have to include Metal's * headers, but it can be safely cast to a `CAMetalLayer *`. * - * \param renderer The renderer to query + * \param renderer the renderer to query. * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a - * Metal renderer + * Metal renderer. * * \since This function is available since SDL 3.0.0. * @@ -2091,7 +2091,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *renderer * doesn't apply to command encoders for render targets, just the window's * backbuffer. Check your return values! * - * \param renderer The renderer to query + * \param renderer the renderer to query. * \returns an `id` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * @@ -2115,13 +2115,13 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer * SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER will give you the * maximum number of semaphores you'll need. * - * \param renderer the rendering context - * \param wait_stage_mask the VkPipelineStageFlags for the wait + * \param renderer the rendering context. + * \param wait_stage_mask the VkPipelineStageFlags for the wait. * \param wait_semaphore a VkSempahore to wait on before rendering the current - * frame, or 0 if not needed + * frame, or 0 if not needed. * \param signal_semaphore a VkSempahore that SDL will signal when rendering * for the current frame is complete, or 0 if not - * needed + * needed. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -2144,7 +2144,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *rend * supported by every driver, so you should check the return value to see * whether the requested setting is supported. * - * \param renderer The renderer to toggle. + * \param renderer the renderer to toggle. * \param vsync the vertical refresh sync interval. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. @@ -2161,7 +2161,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int v /** * Get VSync of the given renderer. * - * \param renderer The renderer to toggle + * \param renderer the renderer to toggle. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetRenderVSync() for the meaning of the value. * \returns 0 on success or a negative error code on failure; call diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h index 94593432c..13dcd424b 100644 --- a/include/SDL3/SDL_sensor.h +++ b/include/SDL3/SDL_sensor.h @@ -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. */ diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index 20fd49ce9..3d509cbd7 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -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. diff --git a/include/SDL3/SDL_storage.h b/include/SDL3/SDL_storage.h index 3f99f9dea..c98c5201a 100644 --- a/include/SDL3/SDL_storage.h +++ b/include/SDL3/SDL_storage.h @@ -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. diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h index 9e95bf3df..5df03c465 100644 --- a/include/SDL3/SDL_surface.h +++ b/include/SDL3/SDL_surface.h @@ -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. * diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index 5a5e0bcf0..c7c0ad421 100644 --- a/include/SDL3/SDL_system.h +++ b/include/SDL3/SDL_system.h @@ -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. diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h index 5414d311a..f15a0f105 100644 --- a/include/SDL3/SDL_thread.h +++ b/include/SDL3/SDL_thread.h @@ -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 diff --git a/include/SDL3/SDL_time.h b/include/SDL3/SDL_time.h index 2860de3f4..d8b75ca92 100644 --- a/include/SDL3/SDL_time.h +++ b/include/SDL3/SDL_time.h @@ -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. * diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h index 0a6060279..c127da1fd 100644 --- a/include/SDL3/SDL_timer.h +++ b/include/SDL3/SDL_timer.h @@ -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. * diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h index df9a7b720..c619012a5 100644 --- a/include/SDL3/SDL_touch.h +++ b/include/SDL3/SDL_touch.h @@ -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 diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index ff6ba9b88..9be8b007d 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -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. * diff --git a/include/SDL3/SDL_vulkan.h b/include/SDL3/SDL_vulkan.h index 3e70846ee..86c57751d 100644 --- a/include/SDL3/SDL_vulkan.h +++ b/include/SDL3/SDL_vulkan.h @@ -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.